External Text v3.3.4 (Write your game in an organized manner! Translate with ease!)

 
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!)[code] 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: [code]$game_system.add_override(!Key1!, !Key2!)[/code] `!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: [code]$game_system.delete_override(!Key!)[/code] `!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:  [code]show_choices(!Key!)[/code]  !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![/spoiler][b]Sample Text.txt File - this can be used as-is in an empty project if you want to test the script[/b][spoiler][code=auto:0]# Introduction[Key] Intro 1[Face] Actor5, 7[Name] IsabelleSo 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] RalphNonsense! Chaaaaaarge!// End Introduction[/code]You would call these with these script calls: [code=auto:0]text("Intro 1")text("Intro 2")text("Intro 3")text("Intro 4")[/code]Version 1.5 introduces block text calls, which allow us to simplify that to this: [code=auto:0]block_text(/Intro \d+/i)[/code]or this [code=auto:0]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.

• 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.