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

Discussion in 'RGSS3 Scripts (RMVX Ace)' started by Enelvon, Dec 1, 2012.

    Tags:
  1. Enelvon

    Enelvon Slumbering Goddess Veteran

    Messages:
    240
    Likes Received:
    134
    Location:
    Dreamland
    First Language:
    English
    [​IMG]
     
    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!)
     `!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!)
     `!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!)
      !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
    Code:
    # 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
    You would call these with these script calls: 
    Code:
    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: 
    Code:
    block_text(/Intro \d+/i)
    or this 
    Code:
    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.
    
    [/SPOILER]
    
    [B]Script[/B]
    It's right over here on [URL="https://github.com/sesvxace/external-text"]GitHub![/URL]
    
    [B]Addons:[/B]
    [URL="https://github.com/sesvxace/external-text/tree/master/lib/addons/external-text-database"]Database[/URL] - Allows you to store all of your Database text in external files! Instructions are in the Header.
    [URL="https://github.com/sesvxace/external-text/tree/master/lib/addons/multi-lang"]MultiLang[/URL] - Adds support for multiple languages! Instructions are in the Header.
    [URL="https://github.com/sesvxace/external-text/blob/master/lib/addons/extractor/enelvon_external_text_extractor.rb"]Extractor[/URL] - this is a [URL="http://forums.rpgmakerweb.com/index.php?/topic/40752-demiurge-a-notes-manager-and-extensible-database/"]Demiurge[/URL] 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 [I]all[/I] 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 [I]always[/I] be careful.
    
    [B]Credit and Thanks[/B][LIST][*]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)
    [/LIST]
    [B]Author's Notes[/B]
    This script is made available under the terms of the MIT Expat license. View [URL="http://sesvxace.wordpress.com/license/"]this page[/URL] for more information.
     
    Last edited by a moderator: Aug 1, 2015
    #1
  2. Shaz

    Shaz Veteran Veteran

    Messages:
    37,355
    Likes Received:
    11,146
    Location:
    Australia
    First Language:
    English
    Primarily Uses:
    RMMV
    Nice script! This would be especially helpful for proofreading/editing, and translating games.

    And thank you for making it available for commercial use.

    Have you tested that this works in a compressed game? Fomar mentioned something to me a while ago (which I may be misrepresenting now) about issues with compressed (or encrypted?) games not being able to load external files. I used a different approach, so I didn't really discover what the issue was.
     
    Last edited by a moderator: Dec 1, 2012
    #2
    ShinGamix likes this.
  3. Enelvon

    Enelvon Slumbering Goddess Veteran

    Messages:
    240
    Likes Received:
    134
    Location:
    Dreamland
    First Language:
    English
    Yes, it works in encrypted games. The Text.txt file gets serialized into Text.rvdata2 when the game is run unencrypted, so the only requirement for it to work in an encrypted game is that you playtest before compressing/encrypting.
     
    Last edited by a moderator: Dec 1, 2012
    #3
    Shaz likes this.
  4. Leinkreig

    Leinkreig Veteran Veteran

    Messages:
    204
    Likes Received:
    2
    Location:
    Hull, England
    First Language:
    English
    Ohhhh wow.

    This is truly amazing! I really like how it's set up, and how simple it is to use. Plus, you've provided an easy-to-understand explanation on how to use it!

    Thanks a lot for sharing this, as it makes it much easier to not have to keep checking the messages and Show Text editor when you change font/font size!

    Definitely going to try it out.
     
    #4
  5. Enelvon

    Enelvon Slumbering Goddess Veteran

    Messages:
    240
    Likes Received:
    134
    Location:
    Dreamland
    First Language:
    English
    Good, good. I'm glad you like it. One thing I didn't mention in the OP, though it may be good to know, is that this doesn't modify any of the methods used for drawing text - which means that scripts like Mithran's Text Cache will work with it without issues.

    Edit: Updated to version 1.1. Please download the new one - I had previously overlooked loading text in Battle Tests, so the text(!Key!) command only caused crashing before now.

    Edit 2: I have no idea what happened to the formatting, but it's fixed now. I've also updated the script to version 1.2, which adds namebox functionality.
     
    Last edited by a moderator: Dec 2, 2012
    #5
    Acetonide likes this.
  6. Megablackdragon31

    Megablackdragon31 Veteran Veteran

    Messages:
    215
    Likes Received:
    35
    Location:
    Argentina
    First Language:
    Spanish
    Nice script miss Enelvon,thanks you very much.

    Excuse me for my bad English and Greetings from Argentina.
     
    #6
  7. Enelvon

    Enelvon Slumbering Goddess Veteran

    Messages:
    240
    Likes Received:
    134
    Location:
    Dreamland
    First Language:
    English
    I've updated the script to version 1.3 - this fixes an important issue with how it handles persistent text colors between pages.
     
    #7
    Acetonide likes this.
  8. Enelvon

    Enelvon Slumbering Goddess Veteran

    Messages:
    240
    Likes Received:
    134
    Location:
    Dreamland
    First Language:
    English
    Updated to v1.5. This includes an important bugfix for nameboxes and a few new features: a new tag, a new way to call text, and a quick way for scripters to add new tags.
     
    #8
  9. Yin

    Yin Veteran Veteran

    Messages:
    133
    Likes Received:
    50
    Location:
    NY
    First Language:
    English
    Primarily Uses:
    N/A
    Thank you for this, it is a very handy script!

    Any way to get the script call into a show choice box?
     
    #9
  10. Enelvon

    Enelvon Slumbering Goddess Veteran

    Messages:
    240
    Likes Received:
    134
    Location:
    Dreamland
    First Language:
    English
    That's something I've been considering, actually. At the moment the answer is no (especially as the choices box does not cleanly support multiple rows of text for a single choice), but I've got a couple of ideas in mind, and it may make an appearance in a future update.
     
    #10
  11. Yin

    Yin Veteran Veteran

    Messages:
    133
    Likes Received:
    50
    Location:
    NY
    First Language:
    English
    Primarily Uses:
    N/A
    That sounds great! Looking forward to future versions!
     
    #11
  12. Enelvon

    Enelvon Slumbering Goddess Veteran

    Messages:
    240
    Likes Received:
    134
    Location:
    Dreamland
    First Language:
    English
    Updated to v1.6 - this allows you to alter the position and background of the message window the way you could with a normal Show Text command by using the [Position] and tags. At this point I'm willing to take requests for new tags - but please, don't ask me about choices. I'm working on that, and they will make an appearance at some point.
     
    #12
  13. estriole

    estriole Veteran Veteran

    Messages:
    1,030
    Likes Received:
    334
    First Language:
    indonesian
    first of all... this is the greatest external text i ever seen. and really easy to use too.

    i have some suggestion.

    1)could you made escape code for fetching key in the text.

    example: \key[intro 1]

    will change into "intro 1" text.

    2)to use in script call. example

    a = get_key("intro 1")

    it will store "intro 1" text in variable a

    then it's up to developer to set the text files. if using that key for choice... don't use [FACE] or other.

    by adding number 1) feature

    you could use it in choices. and even for all database items. (using global escape codes script of course)

    by adding number 2) feature

    we could alter scripts that show text to use the key.

    Ex: modify Attack command text.

    if that achievable... we could make multiple language games more easily. just change the text files and viola you got yourself another language version of your game.
     
    Last edited by a moderator: Dec 11, 2012
    #13
  14. Enelvon

    Enelvon Slumbering Goddess Veteran

    Messages:
    240
    Likes Received:
    134
    Location:
    Dreamland
    First Language:
    English
    Those are good suggestions, estriole. I have added them to the script - v1.7 is now up. Please note that this script does not contain the ability to use text codes anywhere but the message window - you will still need a global text codes script to use them in the Database. I am sure there is at least one out there - if not, let me know and I *may* write one, though it will still be separate from this script, as the purpose of this script is to read and process data from the Text.txt file.
     
    #14
  15. Nicke

    Nicke Fortune seeker Veteran

    Messages:
    529
    Likes Received:
    500
    Location:
    Sweden
    First Language:
    Swedish
    Primarily Uses:
    RMMV
    Neat script. Just wanna point out on your latest release (1.7) you still have this in the code:



    Code:
    ($imported ||= {})["SES - External Text"] = 1.5
    
    Should probably state 1.7 right?
     
    Last edited by a moderator: Dec 12, 2012
    #15
  16. Enelvon

    Enelvon Slumbering Goddess Veteran

    Messages:
    240
    Likes Received:
    134
    Location:
    Dreamland
    First Language:
    English
    Ah, yes, thank you - I forgot to update the version number there. It shouldn't be a problem right now - as long as there's *something* there it will work - but it may be important for future versions, so I'll try to remember to update it in the future. Anyway, fixed now!
     
    #16
    Acetonide likes this.
  17. estriole

    estriole Veteran Veteran

    Messages:
    1,030
    Likes Received:
    334
    First Language:
    indonesian
    Hurray for Enelvon!!! thanks a lot for this update.

    now it's easy to translate a game from english to our own native language

    i made games for my toy store purchase bonus. and some of them didn't understand english. but some also complain when i use my 'native' language since it's not cool to use in games :D . so now i can just give them two Text.rvdata2 one english and one my native language. no more complaint :D

    edit: i forgot. i cannot encrypt the game it that's the case >.<.

    is there a way to switch the text database we use in game? like we have

    English.txt

    Indonesian.txt

    both of them will turn to:

    English.rvdata2

    Indonesian.rvdata2

    in data folder.

    default will use

    English.rvdata2

    then when we change the chosen language and use

    Indonesian.rvdata2

    in game

    edit2: for now i think i could distribute two encrypted files (since it's not too big anyway). but above function could be helpful for anyone who create multi language games :D .
     
    Last edited by a moderator: Dec 12, 2012
    #17
  18. Enelvon

    Enelvon Slumbering Goddess Veteran

    Messages:
    240
    Likes Received:
    134
    Location:
    Dreamland
    First Language:
    English
    You're welcome! I'm glad you like the script, and I hope the update proves helpful! Let me know if you find any problems, and I'll make sure to fix them right away.
     
    #18
  19. estriole

    estriole Veteran Veteran

    Messages:
    1,030
    Likes Received:
    334
    First Language:
    indonesian
    just want to let you know...

    the updates work perfectly if using raizen more choice script.

    a = get_text("Choice 1")

    @get_choices = [a,"No"]

    the width of the choice window will fit perfectly with the longest text including the one using the external window

    then i do some test using normal choice box. there's problem with counting the size of the text. (affect choice window width)

    ex:

    \t["Choice 1"]

    it will count \t["Choice 1"] width

    instead of what the text in choice 1 key width.

    so if i have "I want you to understand" in that key

    it will cutted to "I want you to" the rest is hidden outside the window.

    i also do some test by adding spaces after the

    \t["Choice 1"]

    in choice box

    the strange thing is... when i first talk to that choice. it will appear correctly (since it add some spaces)

    but after talking it again... it will gain those extra spaces. it's like it recognize the key content width. :D .

    but for me... it's ok as it is since i use raizen more choice script for my choice. thus i don't have that width problem.

    and after rereading your script... i found solution for my problem above (multi language). and i want to share it for any person creating multi language games like me :D .

    i just need to play test the game twice. using different language text files. then rename it to corresponding language (ex: English.rvdata2 and Indonesian.rvdata2)

    copy it to data folder.

    then i create this two method in module DataManager



    Code:
    def self.change_indonesian
    $game_text = load_data("Data/Indonesian.rvdata2")
    end
    def self.change_english
    $game_text = load_data("Data/English.rvdata2")
    end
    
    then whenever i want to change it to english language...

    script call

    DataManager.change_english

    then whenever i want to change it to indonesian language...

    script call

    DataManager.change_indonesian

    hope this help as temporary solution :D
     
    #19
  20. Enelvon

    Enelvon Slumbering Goddess Veteran

    Messages:
    240
    Likes Received:
    134
    Location:
    Dreamland
    First Language:
    English
    Mmmm, I'll admit I didn't test it in the choices window, though even if I had I might not have experienced issues, as I've modified a significant portion of the base scripts. When I get a chance, I'll run it in a fresh project and see if I can find a solution - I believe I know what the problem is, so it shouldn't be that hard.

    As far as the multiple languages thing goes, yes, that is one of the most effective ways to do it (in the short-term). I am considering writing an add-on that will allow easy swapping of languages, but again, that will have to wait until a little later.

    Edit: The MultiLang addon has been released! It allows multiple languages to be used with ease. Instructions are in its header. v1.8 of the main script has also been released - you will need it for MultiLang. It also causes the choice window to be properly sized when using the \t[key] text code.
     
    Last edited by a moderator: Dec 13, 2012
    #20
    Acetonide likes this.

Share This Page