Enelvon

ses
External Text v3.3.4 (Write your game in an organized manner -- even your database! Easily add translations!)

6 posts in this topic

Freebies_Enelvon_01A.png

Introduction
This script allows you to display text (as the Show Text event command) that is stored in external files. It will automatically wrap the text and divide it into as many messages as necessary, saving you the trouble of worrying about it yourself. The external files are extremely easy to configure, and support showing faces as well as all of the usual text codes. Displaying a block of text is as easy as a single-line script call!

Change Log

  • v1.0 (November 30th, 2012) - Initial release.
  • v1.1 (December 1st, 2012) - Fixed a bug with Battle Test not loading text.
  • v1.2 (December 1st, 2012) - Added nameboxes and the newline tag.
  • v1.3 (December 6th, 2012) - Fixed a bug with persistent colors.
  • v1.4 (December 6th, 2012) - Added an additional style for names.
  • v1.5 (December 7th, 2012) - Added the [FName] tag, made adding tags easier for scripters, fixed a bug with the namebox, added block text call.
  • v1.6 (December 10th, 2012) - Added in the ability to alter message window location and background.
  • v1.7 (December 11th, 2012) - Added the [get_text] calls and a text code for referencing $game_text
  • v1.8 (December 12th, 2012) - Added a fix for the choice window
  • v1.9 (June 1st, 2013) - Width calculation is now based solely on the font size of Window_Message, rather than the default size
  • v2.0 (June 1st, 2013) - Added scrolling text support
  • v2.1 (June 13th, 2013) - Added Unicode support
  • v2.2 (June 30th, 2013) - Fixed issue with EOL characters and get_text
  • v3.0 (Released May 23rd, 2015) - Small bugfixes, new ways to use block text, and prettier code!
  • v3.1 (May 24th, 2015) - Now allows multiple files, as well as subfolders for organization!
  • v3.2 (May 26th, 2015) - Allows you to override keys on a file-by-file basis!
  • v3.3 (June 30th, 2015) - Allows you to manage choices! Extractor plugin released!
  • v3.3.1 (July 5th, 2015) - Minor update to fix the way that \t interacts with escape characters.
  • v3.3.2 (July 5th, 2015) - Fix for 3.3.1.
  • v3.3.3 (July 5th, 2015) - Final fix for 3.3.1/3.3.2.
  • v3.3.4 (July 31st, 2015) - Fix for save error provided by Source.

Features

  • Use an organized directory tree of text files to hold all of your game text - your outline can become your game!
  • Simple to configure - takes far less time than trying out various combinations of words in order to find the perfect length for a line!

Note on Updating from v3.0 or below to v3.1 or higher
Your Text.txt file will still work, don't worry! Just make sure to move it to a new folder named Text inside of the Data folder. You can divide it up into whatever kind of organization you'd like now!

How to Use
This script is incredibly easy to use. There is little in-script configuration - all you really need to do is format your text file correctly and call the text from events when it is appropriate.

Setting up your Text File

This is actually extremely simple. The first thing you have to do is create a directory named Text inside of your Data directory. We'll be using this folder to store all of our text data - I would recommend using a program like Notepad++ instead of the default Windows Notepad when editing the text files, for the sake of formatting. Any text file that we place in this Text folder will be read and included in the game! You can also add subfolders to the Text directory -- everything that they contain will be used, too.

Inside of our text file, the first thing we'll want to do is define a block of text. We do that like this:


[Key] !Name!

Replace !Name! with whatever you would like the block to be named. You will use the name to call it in the game, so make it something you'll associate with the text.

If we want to add a face, we've got four options.

Option 1:
 

[Face] !Faceset!, !Index!

Here we replace !Faceset! with the name of the faceset image we're using and !Index! with the index of the face in the file, starting at 0.

Option 2
 

[AFace] !Index!

Here we replace !Index! with the index of an actor. Whatever face they have at the time the text is displayed (including any changes made through the Change Actor Graphic event command) will be shown.

Option 3:
 

[PFace] !Index!

For this, we replace !Index! with an index in the party (starting at 0). It will display the current face of whatever actor is in that slot of the party when the text is displayed.

Option 4:
 

[DFace] !Name!

This one requires some configuration in the script itself. Go to SES::ExternalText and find the Faces hash (which should be easy - it's the only thing in the module). Define a face inside of it with this format:
 

"Name" => ["Faceset", Index],

I think each part of that is self-explanatory - "Name" is a string that you will use in the !Name! spot of the tag to call the face, "Faceset" is the name of the faceset file, and Index is the index of the face in the faceset, starting at 0.

Additionally, please note the [FName] tag, added in 1.5. It allows you to display both a face and a name with one tag - it will display the given name and a face from the Faces hash in the same manner that [DFace] would.

As for text itself, we just write that out anywhere below a [Key] tag. Going down to a new line (by pressing enter) will only add a space to the text, not a new line, so you can use it for the sake of an easily readable file. Just be careful not to hit space and then enter, or you will have two spaces instead of one.

After you've defined your first text block, just add another [Key] tag and keep going! You can have as many as you want, and the order they're in doesn't affect anything, so feel free to organize things however you'd like! You can comment out lines by beginning them with either # or // (though these only work at the beginning of a line - leading spaces are okay, but not text, so you can still use them in dialogue) in order to divide the file into sections.

Note that you will still need to manually handle choices - due to the way those work, they would be difficult to effectively apply through a script. It could be done with labels, but... it's easy enough to create choices yourself. If there's enough demand for it I'll set up a system, but I think it's fine as is.

Version 1.2 also adds in the ability to have a name box. We do that like this:
 

[Name] !Name!

Just replace !Name! with the name you want to display - this will take text codes, so you can specify actors or party members with \n or \p, and color the names in different ways.

v1.2 added the [Line] tag for new lines, but that's now deprecated -- add new lines just by adding them in your text editor! It looks much cleaner. The [Line] tag still works, for the sake of backwards compatibility. [v3.3 Note: No longer deprecated for Choices]

1.6 gives us the [Position] and tags, which can be used to set the message window's position and background, respectively. We include these before the text, like we would for most tags. View the Header of the script for instructions on using these.

As of v1.7, you can use a text code to call text in any place that they can be used. This is only the message window by default, and I do not intend to add global text code functionality into this script, as I am sure there are others that do so. By using one of them, you can have all of your Database item names and descriptions come from Text.txt, allowing you to easily translate a game into multiple languages. Note that this code does not autowrap text. You can use it like this:
 

\t[!Key!]

!Key! is, of course, the key of the text you want to use.

Also in v1.7 are some script calls to get the text (but not the face/name/etc) from a particular key. Read the Header of the script for more information on this.

v3.3 has added the ability to manage choices with External Text. To set up choices, create a key like you would for normal text. Give it a default option with this tag:

 

[Default Choice] !Choice!

Set !Choice! to 0 to disable canceling, to a number from 1 through the number of choices that will be provided to have that option
serve as the default, or to the number of choices + 1 (e.g. 5 if there are 4 choices) to give cancel its own branch.

Next, we'll add our choices. Just type them! Each new line of text will act as a new choice. These will get wrapped in the choice box, so feel free to make them long! If you want to add manual line breaks in a choice, use the `[Line]` tag. You can have as many choices as you want -- you're not limited to four, like in default Ace.

You're done! Go to the Script Calls section to learn how to use your new choices.



Displaying Text


Displaying text is extremely easy. Place this in a Script event command, and you're set:
 

text(!Key!)

Remember those keys that we defined for our text? Well, this is where we use them. Replace !Key! with the key of a section text to display it. You can have as many text(!Key!) calls per Script command as you would like - they will display one after the other.

v1.5 added in the ability to display multiple sections of text with a single call. You can read more about that in the Header of the script or in the next section here, the Sample Text.txt File.

v3.0 has added an unsorted version of block_text, as requested -- call it with
 

block_text_us(!KeyPattern!)

As with block_text, !KeyPattern! can be a Regular Expression (recommended) or a String.

v3.2 adds the ability to override existing keys for a given save file! Use this script call:
 

$game_system.add_override(!Key1!, !Key2!)

`!Key1!` is the key that you want to override.
`!Key2!` is the key that contains the value that `!Key1!` should now reference.

You can remove overrides with this script call:
 

$game_system.delete_override(!Key!)

`!Key!` is the key whose override you want to delete.

You do not need to delete an override before replacing it. If you call add_override for a key that already has an override, the override will be replaced. Overrides are fully compatible with both MultiLang and Database.

v3.3 has added the `show_choices` method. Use it in a script call with this format:

 

show_choices(!Key!)

!Key! should be an External Text key that you've formatted for choices as described in the previous section. This call will display the choices -- but how do you branch for them? With conditional branches!

Just set up branches that will check the value of the designated ChoiceVariable (found in the SES::ExternalText module). If the player chooses the first choice, the result will be 1, the second choice will be 2, and so on. If you set it up to use a branch for cancel, the variable will be equal to the number you gave for said branch. Easy, right? Just put all of your processing in those conditional branches. You're done!



Sample Text.txt File - this can be used as-is in an empty project if you want to test the script

 

# Introduction
[Key] Intro 1
[Face] Actor5, 7
[Name] Isabelle
So some foolish heroes are approaching my land, hm? I'll just have to stomp them out!

[Key] Intro 2
[PFace] 0
[Name] \p[1]
So this is the evil empire of Cliche...

[Key] Intro 3
[AFace] 4
[Name] \n[4]
Boss, are you sure we should be here? It's dangerous.

[Key] Intro 4
[DFace] Ralph
[Name] Ralph
Nonsense! Chaaaaaarge!
// End Introduction

You would call these with these script calls:
 

text("Intro 1")
text("Intro 2")
text("Intro 3")
text("Intro 4")

Version 1.5 introduces block text calls, which allow us to simplify that to this:
 

block_text(/Intro \d+/i)

or this
 

block_text("Intro")

The first of those will display all text with a key matching the given Regular Expression. The second will display all text including the given string, making it a less accurate option - I would recommend learning the basics of Regular Expressions. They're not hard, and can be incredibly useful. Note that block_text will automatically sort the keys, so even if things are listed out of order in your text file they will display alphabetically in game - though I would recommend that you keep things organized.




Script
It's right over here on GitHub!

Addons:
Database - Allows you to store all of your Database text in external files! Instructions are in the Header.
MultiLang - Adds support for multiple languages! Instructions are in the Header.
Extractor - this is a Demiurge plugin rather than an RM script. Put it in your Demiurge plugins directory as a .rb file, run Demiurge, and load it into your game's plugins list. A new option will be added to the Tools menu -- "Extract Text for External Text". If you select this option, you will be able to automatically extract all of your game's text (from the Database, from Events, from Common Events, from Troops, and even from the Vocab module!) into neatly organized text files that are fully compatible with External Text. If you let it extract from events (map, common, and troop), it will automatically replace the Show Text commands with calls to External Text. It will also change Show Choices commands into External Text-style conditional branches. Everything will be done for you! Make sure to back up your Data folder before running this command, just in case. No problems have been discovered, even with large test projects, but you should always be careful.

Credit and Thanks

  • Enelvon (author)
  • Solistra (tester, giver-of-ideas-for-multiple-faceset-types [without her input, you would just have the [Face] and [DFace] tags. She's the one who convinced me to add in [AFace] and [PFace]. Bow down to her.], catcher of the # class Class commenting error)
  • ♥ SOURCE ♥ (sanity checked v3.0, provided fix in v3.3.4)
  • ♦SOURCE♦ (lovely banner image)

Author's Notes
This script is made available under the terms of the MIT Expat license. View this page for more information.

Edited by Enelvon

Share this post


Link to post
Share on other sites

v3.3 is out! You now have the ability to control choices through External Text.

Do you like the way External Text looks but are afraid to use it because your project is huge and already contains a lot of text? Fear not! The Extractor Demiurge plugin has been released! It will pull all of your game text out of your project, organize it, format it for External Text, and even update your game's events to use External Text calls so that you don't have to worry about a thing!

Using Choices


To set up choices, create a key like you would for normal text. Give it a default option with this tag:
 

[Default Choice] !Choice!

Set !Choice! to 0 to disable canceling, to a number from 1 through the number of choices that will be provided to have that option
serve as the default, or to the number of choices + 1 (e.g. 5 if there are 4 choices) to give cancel its own branch.

Next, we'll add our choices. Just type them! Each new line of text will act as a new choice. These will get wrapped in the choice box, so feel free to make them long! If you want to add manual line breaks in a choice, use the `[Line]` tag. You can have as many choices as you want -- you're not limited to four, like in default Ace.

To show these choices, you'll need to use the `show_choices` method. Use it in a script call with this format:
 

show_choices(!Key!)

!Key! should be an External Text key that you've formatted for choices as described in the previous section. This call will display the choices -- but how do you branch for them? With conditional branches!

Just set up branches that will check the value of the designated ChoiceVariable (found in the SES::ExternalText module). If the player chooses the first choice, the result will be 1, the second choice will be 2, and so on. If you set it up to use a branch for cancel, the variable will be equal to the number you gave for said branch. Easy, right? Just put all of your processing in those conditional branches. You're done!



Extractor

Extractor - this is a Demiurge plugin rather than an RM script. Put it in your Demiurge plugins directory as a .rb file, run Demiurge, and load it into your game's plugins list. A new option will be added to the Tools menu -- "Extract Text for External Text". If you select this option, you will be able to automatically extract all of your game's text (from the Database, from Events, from Common Events, from Troops, and even from the Vocab module!) into neatly organized text files that are fully compatible with External Text. If you let it extract from events (map, common, and troop), it will automatically replace the Show Text commands with calls to External Text. It will also change Show Choices commands into External Text-style conditional branches. Everything will be done for you! Make sure to back up your Data folder before running this command, just in case. No problems have been discovered, even with large test projects, but you should always be careful.

 

Edited by Enelvon

Share this post


Link to post
Share on other sites

Very nice job! I think I am going to use this.

 

One favor though: I don't have the time right now to get into it and understand how it works (it is a bit complicated). Could you make a video explaining it?

 

I think this would help a lot of people, that know only see text in your post. Pictures would be great too!

 

Keep up the good work!

Share this post


Link to post
Share on other sites

It sounds REALLY GREAT!

One fast question to make sure:

 

Can you change language in mid game? Including Database; scripts; text events etc.?

How does it exactly work?

thanasulas likes this

Share this post


Link to post
Share on other sites

Very nice job! I think I am going to use this.

 

One favor though: I don't have the time right now to get into it and understand how it works (it is a bit complicated). Could you make a video explaining it?

 

I think this would help a lot of people, that know only see text in your post. Pictures would be great too!

 

Keep up the good work!

 

I'm afraid that I don't have the time or skill to make a video, so I'm going to have to decline. It's honestly not that complicated once you start using it -- there's an example in one of the first post's spoiler tags, and most of it ends up being pretty intuitive. If you have specific problems I'd be happy to help, but a video guide just isn't something that I can accomodate right now.

 

It sounds REALLY GREAT!

One fast question to make sure:

 

Can you change language in mid game? Including Database; scripts; text events etc.?

How does it exactly work?

 

Absolutely! You can change the language as many times as you want mid-game if you're using the MultiLang addon. The addon provides a scene that allows the user to change the language to any of the other languages provided by the developer. Instructions are in the header!

 

Edit: Looks like the first post's formatting got messed up a bit, which hid the sample text. Fixed that -- it's now one of the three options in the main spoiler.

Edited by Enelvon

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!


Register a new account

Sign in

Already have an account? Sign in here.


Sign In Now

  • Recently Browsing   0 members

    No registered users viewing this page.