//=============================================================================
// VisuStella MZ - Message Core
// VisuMZ_1_MessageCore.js
//=============================================================================
var Imported = Imported || {};
Imported.VisuMZ_1_MessageCore = true;
var VisuMZ = VisuMZ || {};
VisuMZ.MessageCore = VisuMZ.MessageCore || {};
VisuMZ.MessageCore.version = 1.54;
//=============================================================================
/*:
* @target MZ
* @plugindesc [RPG Maker MZ] [Tier 1] [Version 1.54] [MessageCore]
* @author VisuStella
* @url http://www.yanfly.moe/wiki/Message_Core_VisuStella_MZ
* @orderAfter VisuMZ_0_CoreEngine
*
* @help
* ============================================================================
* Introduction
* ============================================================================
*
* The Message Core plugin extends and builds upon the message functionality of
* RPG Maker MZ and allows you, the game dev, to customize the workflow for
* your game's message system.
*
* Features include all (but not limited to) the following:
*
* * Control over general message settings.
* * Auto-Color key words and/or database entries.
* * Increases the text codes available to perform newer functions/effects.
* * Ability for you to implement custom Text Code actions.
* * Ability for you to implement custom Text code string replacements.
* * Invoke a macro system to speed up the dev process.
* * Add a Text Speed option to the Options menu.
* * Add the ever so useful Word Wrap to your message system.
* * Extend the choice selection process to your liking.
* * The ability to enable/disable as well as show/hide certain choices.
*
* ============================================================================
* Requirements
* ============================================================================
*
* This plugin is made for RPG Maker MZ. This will not work in other iterations
* of RPG Maker.
*
* ------ Tier 1 ------
*
* This plugin is a Tier 1 plugin. Place it under other plugins of lower tier
* value on your Plugin Manager list (ie: 0, 1, 2, 3, 4, 5). This is to ensure
* that your plugins will have the best compatibility with the rest of the
* VisuStella MZ library.
*
* ============================================================================
* Major Changes
* ============================================================================
*
* This plugin adds some new hard-coded features to RPG Maker MZ's functions.
* The following is a list of them.
*
* ---
*
* Dim Background Extension
*
* Before, when using the Dim Background as a part of a Show Text event, its
* size is only the same as the message window's width itself. This looked
* really ugly because it had hard edges cutting off while gradients are seen
* elsewhere. To make it look better, we extended the dimmed background to span
* the width of the screen instead.
*
* ---
*
* Extended Messages
*
* If you decide to expand the size of the message window to allow for more
* rows to be displayed, you can type in the data for them by chaining together
* Show Message events. They will take data from each other and display them in
* the same message window as long as there are enough rows.
*
* ---
*
* Extended Choice Lists
*
* Choice lists can be extended by just chaining one Choice List event after
* the other in succession along the same indentation. They do not extend if
* there is any event other than a Choice List option between them on the same
* indentation level.
*
* ---
*
* ============================================================================
* Text Language Information
* ============================================================================
*
* As of Message Core version 1.46, Text Language has been added.
*
* The "Text Language" feature allows your players to switch between different
* languages for your game to allow people from around the globe to enjoy what
* story you have to tell.
*
* Disclaimers: This is not an automatic translation tool. Translations made
* through the "Text Language" feature of the VisuStella MZ Message Core
* will require manual input by the game developer.
*
* As of Message Core version 1.53, we've decided to add support for TSV.
*
* This is because we have done our research and decided that CSV's are too
* restricted to use due to their default nature of wanting to use commas as
* separators. Thus, we've decided to switch to TSV where the default separator
* is a tab space, something that is almost never used in RPG Maker text.
*
* ---
*
* === How to Enable Switching ===
*
* Text Language is NOT enabled by default. Here's what you have to do:
*
* #1. Open up the Message Core's Plugin Parameters
* #2. Plugin Parameters > Text Language Settings > Enable Switching?
* #3. Change the "Enable Switching?" parameter setting to "true".
* #4. Adjust any other settings as needed.
* #5. Save the Plugin Parameter changes.
* #6. Save your game.
*
* Now, it's time to get the CSV/TSV file that will contain all of the text
* used to translate your game's script.
*
* #1. Play test your game. Make sure Play test mode is NOT disabled.
* #2. A popup will appear asking to create a language CSV/TSV file.
* #3. Click "OK" and let the plugin do its thing.
* #4. The project's /data/ folder will appear with Language.csv/tsv made.
* #5. The plugin will then ask you to restart your game.
*
* '''IMPORTANT!''' The separator used for the CSV file must be a semicolon (;)
* and not a comma (,) as to reduce the amount of punctuation conflicts. Keep
* this in mind as most CSV editors will default to comma (,) instead of the
* semicolon (;) for their separator.
*
* ---
*
* === How to Edit the Language CSV/TSV ===
*
* The Language CSV/TSV is structured as a normal CSV/TSV file would be, which
* also means it can be modified in programs like Microsoft Excel or Google
* Sheets. We recommend using either of those programs to modify the text.
*
* We do not recommend modifying the CSV/TSV file in programs like notepad
* directly due to the way certain things like commas (,) and tabs are handled
* and how easy it is to be error-prone.
*
* The table will appear something like this at first:
*
* Key English Chinese Japanese Korean
* Greeting Hello 你好 こんにちは 안녕하세요
* Farewell Good-bye 再见 さようなら 안녕히
* Wow Wow 哇 ワオ 와우
*
* The "Key" column refers to the reference key used to determine which lines
* will be inserted into the text. The columns with the languages will utilize
* the respective phrases for that language.
*
* You can remove columns containing languages that you aren't planning to
* translate for your game.
*
* ---
*
* === Things to Keep in Mind ===
*
* When adding text to the CSV/TSV file via the spreadsheet editor (Excel or
* Google Sheets), there's a few things to keep in mind.
*
* ---
*
* ==== How to Load the CSV/TSV in Google Sheets ====
*
* If you are using Google Sheets and wish to edit the CSV/TSV without it
* converting all the separators into commas, here's what you do:
*
* #1. Go to "https://sheets.google.com"
* #2. Create a "Blank spreadsheet"
* #3. File > Import > Upload > Select the CSV/TSV file that was created in
* your game project's /data/ folder. You may need to select "All Files"
* for file type if uploading a TSV.
* #4. For "Separator Type", if you are using CSV, change it to "Custom" and
* insert the Semicolon ";". Otherwise, if you are using TSV, select "tab"
* as your separator type.
* #5. Uncheck "Convert text to numbers, dates, and formulas"
*
* ==== How to Load the CSV/TSV in VS Code ===
*
* #1. Go to "https://code.visualstudio.com/"
* #2. Download and install it
* #3. Open up VS Code and go to View > Extensions
* #4. Search for an extension called "Edit CSV"
* #5. Load the CSV/TSV file into VS Code and view with the CSV Editor
* #6. Click the button that says "Edit CSV" in the upper right
*
* ==== Line Breaks ====
*
* When you want to insert line breaks into the translated phrases, use the
*
text code. This is best used for text that is to be transferred into
* the message window or help window.
*
* ==== Text Codes ====
*
* Text codes like \C[2] can be inserted normally. However, they only work in
* windows that support text codes, such as the message window or help window.
* Otherwise, the text codes will not transfer over properly.
*
* ==== Semicolons (CSV Only) ====
*
* Due to the nature of the CSV file, we used the semicolon (;) as the
* separator. As such, semicolons should not be used in the text entries.
* Though some sentences will work with the semicolon, not all of them will. If
* you do want to use a semicolon, use the text code instead.
*
* Example:
*
* "The pancakes were delicious they were fluffy and sweet."
*
* Other variations of the semicolon text code are and .
* The text code and variants only work with the Language CSV and
* are ignored otherwise when typed in a regular message box entry.
*
* ---
*
* ==== Macros and Language Switches ====
*
* For those using both text macros and text language switches, macros will be
* converted to text before language switches as it allows for better text
* transitions that way.
*
* ---
*
* === How to Use the Reference Keys ===
*
* Remember the "Key" column and the reference keys? Those are used to
* determine which lines will be inserted into the text for the message window
* and just about any other window. However, there's a specific way these keys
* must be used in order for them to work.
*
* The "text code" format works like this. Use any of the following:
*
* \tl{keyName}
* \translate{keyName}
* \loc{keyName}
* \locale{keyName}
* \localize{keyName}
*
* or for those coming from different translation plugins but want to switch
* over to the VisuStella MZ Message Core's translation system:
*
* ${keyName}
*
* For example, to use one of the default keys made with the Language CSV/TSV:
*
* \tl{Greeting}
*
* This will yield "Hello" in English, "你好" in Chinese, "こんにちは" in
* Japanese, and "안녕하세요" in Korean.
*
* Key names are not case sensitive and any trailing spaces will be removed
* from them in order to make sure the CSV/TSV table is stable to reference any
* translated text from.
*
* You can insert these language "text codes" into item names, skill names,
* etc. as well as system entries like for Attack, Defense, etc.
*
* ---
*
* === Naming Weapon Types, Armor Types, Equip Types, Item Categories ===
*
* You might have noticed that if you've decided to use \tl{keyName} for weapon
* or other database types, other parts of the game will error out. Don't
* worry, for these, you don't have to change the currently used database name.
* Go straight to the CSV/TSV and insert in a new key for that particular
* database name. For example, the equip type "Accessory" will use "Accessory"
* as the automatic key to look for a translated phrase. If there isn't any in
* the CSV/TSV file, then the default database text entry will be used.
*
* ---
*
* ============================================================================
* Available Text Codes
* ============================================================================
*
* The following are text codes that you may use with this plugin. Some of
* these are original text codes provided by RPG Maker MZ, while others are
* new text codes added through this plugin. You may even add your own text
* codes through the plugin parameters.
*
* === RPG Maker MZ Text Codes ===
*
* The following are text codes that come with RPG Maker MZ. These text codes
* cannot be edited through the Plugin Parameters.
*
* ---
*
* ------------------ -------------------------------------------------------
* Text Code Effect (Global)
* ------------------ -------------------------------------------------------
* \V[x] Replaced by the value of variable 'x'.
* \N[x] Replaced by the name of actor 'x'.
* \P[x] Replaced by the name of party member 'x'.
* \C[x] Draw the subsequent text with window skin color 'x'.
* \I[x] Draw icon 'x'.
*
* \PX[x] Moves text x position to 'x'.
* \PY[x] Moves text y position to 'y'.
*
* \G Replaced by the currency unit.
*
* \{ Increase the text font size by one step.
* \} Decrease the text font size by one step.
* \FS[x] Changes the text font size to 'x'.
*
* \\ Replaced by the backslash character.
*
* ---
*
* ------------------ -------------------------------------------------------
* Text Code Effect (Message Window Only)
* ------------------ -------------------------------------------------------
* \$ Opens the gold window.
* \. Waits a 1/4 second.
* \| Waits a full second.
* \! Waits for button input.
* \> Display remaining text on same line all at once.
* \< Cancel the effect that displays text all at once.
* \^ Do not wait for input after displaying text to move on.
*
* ---
*
* === Message Core Hard-Coded Text Codes ===
*
* The following text codes are hard-coded into VisuStella MZ Message Core's
* code. These text codes cannot be edited through the Plugin Parameters.
*
* ---
*
* ------------------ -------------------------------------------------------
* Text Code Effect (Global)
* ------------------ -------------------------------------------------------
* Makes subsequent text bold.
* Removes bold from subsequent text.
* Makes subsequent text italic.
* Removes italic from subsequent text.
*
* Makes subsequent text left-aligned. *Note1*
* Removes left-alignment for subsequent text.
* Makes subsequent text center-aligned. *Note1*
* Removes center-alignment for subsequent text.
* Makes subsequent text right-aligned. *Note1*
* Removes right-alignment for subsequent text.
*
* Note1: Use at line-start. Does not work with Word Wrap.
*
* ---
*
* ------------------ -------------------------------------------------------
* Text Code Effect (Global)
* ------------------ -------------------------------------------------------
*
* Text codes can't change text color for subsequent text.
* Removes Color Lock property.
*
* Enables Word Wrap for this window. *Note2*
* Disables Word Wrap for this window. *Note2*
*
Adds a line break. Requires Word Wrap enabled.
* Adds a line break. Requires Word Wrap enabled.
*
* Note2: Some windows cannot use Word Wrap such as the Choice Window.
* Word Wrap also cannot be used together with , , or and
* will disable itself if text alignment text codes are detected.
*
* ---
*
* ------------------ -------------------------------------------------------
* Text Code Effect (Global)
* ------------------ -------------------------------------------------------
*
* \picture Draws picture x (filename) at current text position.
* \CenterPicture Draws picture x (filename) centered at the window.
*
* While these text codes are available globally, they are best suited for use
* in the message window or any other window that does not change its contents.
* The reason being is because the picture drawn is drawn into the background
* of the window.
*
* Therefore, we do not recommend using this in windows that change contents
* often like Help Windows or Quest Descriptions. Instead, we recommend using
* icons instead.
*
* As of the version 1.53 update, the Help Window now supports both of these
* text codes. However, we still recommend using icons over using pictures as
* there will be loading delays.
*
* ---
*
* ------------------ -------------------------------------------------------
* Text Code Effect (Map Name)
* ------------------ -------------------------------------------------------
* Makes map name align to left side of screen.
* Makes map name align to horizontally center of screen.
* Makes map name align to right side of screen.
*
* Makes map name align to top of screen.
* Makes map name align to vertically middle of screen.
* Makes map name align to bottom of screen.
*
* Adjusts the horizontal position of map name by n.
* Adjusts the horizontal position of map name by n.
*
* Adjusts the vertical position of map name by n.
* Adjusts the vertical position of map name by n.
*
* Note: All of these text codes require VisuMZ_0_CoreEngine installed and its
* "Map Name Text Code" plugin parameter enabled.
*
* ---
*
* ------------------ -------------------------------------------------------
* Text Code Effect (Global)
* ------------------ -------------------------------------------------------
* Makes all text after this capitalized.
* Turns off other auto-text case modes.
* ie: "hello world" becomes "HELLO WORLD"
* Turns off auto text-casing effects.
*
* Makes the first letter of any word after a space to be
* capitalized. Other letters are left alone.
* Turns off other auto-text case modes.
* ie. "old mcDonald" becomes "Old McDonald"
* Turns off auto text-casing effects.
*
* Makes all text after this lowercase.
* Turns off other auto-text case modes.
* ie: "THE QUICK BROWN FOX" becomes "the quick brown fox"
* Turns off auto text-casing effects.
*
* Makes all text after this alternate between uppercase
* and lowercase. Turns off other auto-text case modes.
* ie: "Hello" becomes "HeLlO"
* Turns off auto text-casing effects.
*
* Makes all text after this randomize between uppercase
* and lowercase. Turns off other auto-text case modes.
* ie: "Wassup" becomes "waSsUP" or "WasSuP"
* Turns off auto text-casing effects.
*
* **Clarity:** In case you're wondering, the text codes , ,
* , , and all do the same thing and can be used
* interchangeably with each other. For example, you can do this:
* hello world and it would still accomplish the same effect, but
* you won't do that because you're not a monster of a developer.
*
* ---
*
* ------------------ -------------------------------------------------------
* Text Code Effect (Message Window Only)
* ------------------ -------------------------------------------------------
* \CommonEvent[x] Runs common event x when text code is reached.
* \Wait[x] Makes the message wait x frames before continuing.
*
* Ends the current message page at this line. This is
* used for messages when rows are at 5 or above and the
* message lines don't match the amount. This is used to
* prevent grabbing message windows from following message
* events. Any lines following in the same
* message event will be ignored.
*
* Resizes message window dimensions to fit text. *Note3*
* Resizes message window width to fit text. *Note3*
* Resizes message window height to fit text. *Note3*
*
* Resizes message window and positions it over actor x
* sprite's head. *Note3*
* Resizes message window and positions it over party
* member x sprite's head. *Note3*
* Map-Only. Resizes message window and positions it over
* the player sprite's head. *Note3*
* Map-Only. Resizes message window and positions it over
* event x sprite's head. *Note3*
* Battle-Only. Resizes message window and positions it
* over enemy x sprite's head. *Note3*
*
* Note3: Upon using these text codes, the message window's settings will be
* reset for the upcoming message. These effects do not work with Word Wrap.
*
* ---
*
* ---------------------------- ---------------------------------------------
* Text Code Effect (Battle Only)
* ---------------------------- ---------------------------------------------
* Replaces text code with the current target of
* an action in battle.
* Replaces text code with the currently active
* user in battle.
* Replaces text code with the current battle
* action's name with an icon in front.
* Replaces text code with the current battle
* action's name without an icon.
*
* If there is no battle, no target, no user, or no action, then the text code
* will just be replaced with no text.
*
* These text codes are NOT recommended to be used inside of Help Descriptions.
* They are best used with "Show Text" event commands.
*
* ---
*
* ----------------------------- ---------------------------------------------
* Text Code Effect (Choice Window Only)
* ----------------------------- ---------------------------------------------
* Choice is always shown.
* Choice shown if switch x is ON.
* Choice shown if the x switches are all ON.
* Choice shown if the x switches are all ON.
* Choice shown if any of x switches are ON.
*
* Choice is always hidden.
* Choice hidden if switch x is ON.
* Choice hidden if the x switches are all ON.
* Choice hidden if the x switches are all ON.
* Choice hidden if any of x switches are ON.
*
* Choice is always enabled.
* Choice enabled if switch x is ON.
* Choice enabled if the x switches are all ON.
* Choice enabled if the x switches are all ON.
* Choice enabled if any of x switches are ON.
*
* Choice is always disabled.
* Choice disabled if switch x is ON.
* Choice disabled if the x switches are all ON.
* Choice disabled if the x switches are all ON.
* Choice disabled if any of x switches are ON.
*
* Sets the minimum text area width to x.
* Applies to whole choice window.
* Sets the indent to x value. Applies to
* current choice selection only.
*
* Requires VisuMZ_0_CoreEngine! Sets background
* color of this choice to 'x' text color. This
* will be combined with a fading
* Requires VisuMZ_0_CoreEngine! Sets background
* color of this choice to 'x' to 'y' gradient
* text color.
* Requires VisuMZ_0_CoreEngine! Sets background
* color of this choice to '#rrggbb' color using
* hex color values.
* Requires VisuMZ_0_CoreEngine! Sets background
* color of this choice to '#rrggbb' gradient
* using hex color values.
*
* text Makes a help window appear and have it show
* 'text' in its contents. The help window will
* disappear if no text is displayed.
*
* Shuffles the order of all choices. Any cancel
* shortcuts other than "Branch" will be undone.
* Shuffles the order of all choices and only
* x number of them will appear. Any cancel
* shortcuts other than "Branch" will be undone.
* Hidden choices do not count towards x number.
*
* ---
*
* ----------------------------- ---------------------------------------------
* Text Code Background Effects (Choice Window Only)
* ----------------------------- ---------------------------------------------
*
* Creates a background image from img/pictures/
* stretched across the choice rectangle.
* Creates a background image from img/pictures/
* scaled to the lower left of choice rect.
* Creates a background image from img/pictures/
* scaled to the lower center of choice rect.
* Creates a background image from img/pictures/
* scaled to the lower right of choice rect.
* Creates a background image from img/pictures/
* scaled to the middle left of choice rect.
* Creates a background image from img/pictures/
* scaled to the center of choice rect.
* Creates a background image from img/pictures/
* scaled to the middle right of choice rect.
* Creates a background image from img/pictures/
* scaled to the upper left of choice rect.
* Creates a background image from img/pictures/
* scaled to the upper center of choice rect.
* Creates a background image from img/pictures/
* scaled to the upper right of choice rect.
*
* *Note:* For the text code variants, even if the background
* image is smaller than the choice contents, it will overscale to match its
* choice rectangle dimensions.
*
* *Note:* Using a background image will clear the dimmed background rectangle
* that is normally behind each selectable choice.
*
* *Note:* Each choice can only have one background image but can use a
* combination of one background and one foreground image.
*
* *Note:* Images in the background will appear behind the select cursor.
*
* ---
*
* ----------------------------- ---------------------------------------------
* Text Code Foreground Effects (Choice Window Only)
* ----------------------------- ---------------------------------------------
*
* Creates a foreground image from img/pictures/
* stretched across the choice rectangle.
* Creates a foreground image from img/pictures/
* scaled to the lower left of choice rect.
* Creates a foreground image from img/pictures/
* scaled to the lower center of choice rect.
* Creates a foreground image from img/pictures/
* scaled to the lower right of choice rect.
* Creates a foreground image from img/pictures/
* scaled to the middle left of choice rect.
* Creates a foreground image from img/pictures/
* scaled to the center of choice rect.
* Creates a foreground image from img/pictures/
* scaled to the middle right of choice rect.
* Creates a foreground image from img/pictures/
* scaled to the upper left of choice rect.
* Creates a foreground image from img/pictures/
* scaled to the upper center of choice rect.
* Creates a foreground image from img/pictures/
* scaled to the upper right of choice rect.
*
* *Note:* For the text code variants, unlike the background
* variant, the foreground image will not overscale past its original size.
* Instead, it will maintain its original size or be smaller, so long as it can
* be scaled to exist within the choice rectangle unless it is intended to be
* stretched by using the variant.
*
* *Note:* Text is then written on top of the foreground image.
*
* *Note:* Each choice can only have one foreground image but can use a
* combination of one background and one foreground image.
*
* *Note:* Images in the foreground will appear behind the select cursor.
*
* ---
*
* ----------------- ---------------------------------------------------------
* Text Code Effect (Name Window Only)
* ----------------- ---------------------------------------------------------
* Positions the name box window to the left.
* Positions the name box window to the center.
* Positions the name box window to the right.
* Replace 'x' with a number from 0 to 10. This positions
* the name box window on the screen relative to the
* position of the value 'x' represents.
* \NormalBG Changes background type of window to normal type.
* \DimBG Changes background type of window to dim type.
* \TransparentBG Changes background type of window to transparent type.
*
* ---
*
* ------------------------------- ------------------------------------------
* Text Code Effect (Message Window Only)
* ------------------------------- ------------------------------------------
*
* Forces the message window to exact listed
* coordinates and dimensions. Replace each
* of the arguments with numbers. *Note*
*
* Forces the message window to the exact
* listed coordinates. Replace each of the
* arguments with numbers. *Note*
*
* Forces the message window size to the
* exact listed dimensions. Replace each of
* the arguments with numbers. *Note*
*
* Quickly adjust the message window offset
* values to the x and y amounts. The values
* will replace the previous offset settings
* if there were any.
*
* *NOTE* These text codes do not work with Word Wrap.
*
* ---
*
* ------------------ -------------------------------------------------------
* Text Code Effect (Requires VisuMZ_0_CoreEngine)
* ------------------ -------------------------------------------------------
* Display's VisuMZ_0_CoreEngine's button assist text.
* Display's VisuMZ_0_CoreEngine's button assist text.
* Display's VisuMZ_0_CoreEngine's button assist text.
* Display's VisuMZ_0_CoreEngine's button assist text.
*
* Display's VisuMZ_0_CoreEngine's button assist text.
* Display's VisuMZ_0_CoreEngine's button assist text.
* Display's VisuMZ_0_CoreEngine's button assist text.
*