Hermes - Hermes Extends RPGXP's MEssage System v0.4 - User's manual

Introduction

Hermes is a script for RPG Maker XP that extends the functionality of the built-in message window. It it highly configurable and comes with some enhancement for text display in other windows as well.

The current version is Hermes 0.4. Before you ask, yes, that means it's 40% finished. Yet it is much better than many other scripts that claim to be 100% finished. I can't test everything, and Hermes probably is not bug-free. If you find a bug, please tell me about it! I might not be able to fix it right away, but I will try my best to memorize it until I get to work on Hermes again!

Version history

Installation

Hermes 0.4 is the first version to not ship as a single script. Not even as four single scripts, like the developer version used to. No, it comes in 25 files spread across 6 folders. Why? Because it's easier - easier for me to maintain, easier for you to install.

Installing Inserter

Inserter is a script that can modify existing RPG Maker scripts on-the-fly: When the game is started, it imports all the scripts (*.rb files) it will find in the Data/Scripts folder or sub folders, sorted by path / file name. If no further instructions are given in a certain script, it will be inserted above Main. However, Inserter scripts also have the ability to alter existing scripts, for example to add features to standard classes. For this to work, however, the scripts it tries to alter must not have been changed manually. Hermes inserts code into Game_Temp, Scene_Map, Scene_Save, Scene_Load and Main, so make sure these scripts have not been altered. Also, insertion might fail if you are not using the scripts from the official English RGSS version.

If your project fulfills these requirements, the only thing you really need to do is to install Inserter. Since Inserter is a previously unreleased script, I have included it with Hermes 0.4. If you haven't downloaded Hermes yet, you can get it from its official website. If you only want to install Inserter for some reason, you can also download it from the Inserter website.

Either way, the archive will contain a text file called plainly inserter.txt. Open it with your favorite text Editor, copy the complete contents to the clipboard, launch RPGXP, open your pet project, open the script editor, insert a new script at the very top of the list (not directly above Main!), select the script and paste from clipboard. Optionally, rename the script into "Inserter". Then hit OK, done!

Installing Hermes

If you haven't deleted or modified and of RPG Maker's original scripts, Inserter should be able to patch the required files into your project. If you get a message from Inserter that not all Scripts could be modified, Hermes will not work correctly. In this case, make sure all the original scripts in your project are virgin. Having other scripts installed is not a reason why Insertion would fail, only if original scripts have been changed in-place!

Configuring Hermes

There are lots of settings available for Hermes. Some of them can even be changed while the game is running, others are static. To adjust the settings to your liking, please have a look at the config scripts that should be located in Data/Scripts/Hermes/0 - config/*.rb. They are segmented into four parts for convenience. Open the .rb files with your favorite text editor and change the settings to your liking. Their meanings are mostly described in the scripts themselves, however some of the savable settings are only introduced briefly. To see a more detailed description for those, please read on.

Savable settings

Here is a complete list of settings you can change during the game. Most of them are obvious or well enough explained in the config section, so I won't talk about them too much. But I do want to say a few things about the less obvious options; see below this table.

Hermes' savable settings
SettingDefaultExpected
font_nameHermes::Message::Text::NAME String, Array or :default
font_sizeHermes::Message::Text::SIZE Positive whole number or :default
font_boldHermes::Message::Text::BOLD true, false or :default
font_italicHermes::Message::Text::ITALIC true, false or :default
font_colorHermes::Message::Text::COLOR Color, "#RRGGBB[AA]" or :default
font_shadowHermes::Message::Text::SHADOW TextEffect, Array or :default
font_outlineHermes::Message::Text::OUTLINE TextEffect, Array or :default
font_textureHermes::Message::Text::TEXTURE String, :default or :none
alignHermes::Message::Text::ALIGN 0 for left, 1 for center or 2 for right
valignHermes::Message::Text::VALIGN 0 for top, 1 for middle, 2 for bottom
soundHermes::Message::Text::SOUND String or :off
speedHermes::Message::Text::SPEED Non-negative Integer
prevent_skipping Hermes::Message::Text::PREVENT_SKIPPING true or false
widthHermes::Message::Box::WIDTH Positive Integer
line_maxHermes::Message::Box::LINE_MAX Positive Integer
shrinkHermes::Message::Box::SHRINK true / false
line_heightHermes::Message::Box::LINE_HEIGHT Positive Integer
marginHermes::Message::Box::MARGIN Integer
event_xHermes::Message::Box::EVENT_X Integer
event_yHermes::Message::Box::EVENT_Y Integer
opacityHermes::Message::Box::OPACITY Integer between 0 and 255
skinHermes::Message::Box::SKIN String or :default
name_font_nameHermes::Name::Text::NAME String, Array or :default
name_font_sizeHermes::Name::Text::SIZE Positive whole number or :default
name_font_boldHermes::Name::Text::BOLD true, false or :default
name_font_italicHermes::Name::Text::ITALIC true, false or :default
name_font_colorHermes::Name::Text::COLOR Color, "#RRGGBB[AA]" or :default
name_font_shadowHermes::Name::Text::SHADOW TextEffect, Array or :default
name_font_outlineHermes::Name::Text::OUTLINE TextEffect, Array or :default
name_font_textureHermes::Name::Text::TEXTURE String, :default or :none
name_posHermes::Name::Box::POS 0, 1, 2 or 3
name_overlapHermes::Name::Box::OVERLAP Integer
name_offsetHermes::Name::Box::OFFSET Integer
name_paddingHermes::Name::Box::PADDING Integer
name_swapHermes::Name::Box::SWAP true of false
name_opacityHermes::Name::Box::OPACITY Integer between 0 and 255
name_skinHermes::Name::Box::SKIN String or :default

All these settings can be changed at any time during the game and will be saved to and loaded from game saves. To change e.g. the message font, you can insert a Script event command into your event body and write something like Hermes.font_name = "Times New Roman". Alternatively, you can use the (shorter) global variable $msg, e.g., to make the font in the name box bold, type $msg.name_font_bold = true. By definition, all the changeable settings have a default value (which can be changed in the config section). To reset a setting to its default, you can simply set it to nil. The default will then be assumed automatically. For example, if you want to reset the message window's font color to the one specified in the config file, write Hermes.font_color = nil.

The value :default

The value ":default" is something different than the "default value"! Changing a setting to :default will not reset it to the defult specified in the config file. Rather, it will cause this setting to use RGSS' default value.

For fonts, setting Hermes.font_* to :default will result in the value being changed to Font.default_*. Since when Hermes is started, Font.default_* are set to the values font in Hermes::GlobalText::*, you can roughly say the value :default refers to those (which is not entirely true, because Font.default_* can be changed later).

If you set the message or name window skin to :default, it will use the default skin you set in RPG Maker. Even if you change the window skin during the game, it will always use the one currently set. (This behavior was bugged in Hermes <0.4, where setting it to :default only copied the default skin once)

Handling of unexpected values

If an unexpected value is tried to be assigned to one of the properties, Hermes will spit out a warning (if the game is run in debug mode; this behavior can be disabled, see DEBUG_WARNINGS in the config section) and then set the setting to a fallback value. It is recommended not to turn off debug warnings during the development and when a warning appears, don't just ignore it but try to fix the issue! While you might be lucky and the Game will continue without crashing, you'll never know what unexpected side results might have arisen.

More about some settings

Shadows and Outlines

These settings rely on a common class, TextEffect. When you set either of them, you have the choice to pass a TextEffect object or an Array. If you pass an Array, it will be immediately used to create a TextEffect. So consider the Array option a convenience to take less space. To create a TextEffect, you can specify either one or two arguments. The first one is the strength of the effect (offset for shadow, width for outline), the second one a Color. If the latter is left out, a default color (black, 50% opacity) will be used. So, for example, Hermes.name_font_outline = TextEffect.new(2, Color.new(255,255,255)) will create a 2 pixel wide, white outline and make the name box use it. The following does the same, but is more likely to fit into the short lines of Call Script event command: $msg.name_font_outline = [2, "#FFFFFF"].

Text textures

A texture is a small Bitmaps which Hermes will use as a "skin" for your font. It can be of any size, but since Hermes usually draws every letter individually (but at least every line), it will only ever use the upper left part of the image if it's too large. It can't be to small though, as it's automatically repeated in both dimensions. The picture needs to be in the Graphics/Picture folder.

If a texture is set, Hermes will first draw the text as usual including any text effects if set. Then, it tiles the texture over the text. To determine the color to use for each new pixel, Hermes calculates, for each color channel, the square root of the product of this channel's values from the text and the texture bitmap. This causes the effects to stay intact, but is really slow, too! So please use textures carefully.

Box shrinking

This is a new feature of Hermes that will, if enabled, change the height of the message window dynamically depending on how many lines are actually in the box compared to the maximum line number. For example, if line_max is 6, shrink is set to true and a message is shown with only 3 lines, the box is shrunk to that height. This setting cooperates nicely with the vertical align setting. E.g., if vertical align it set to bottom, the message window will shrink "towards" the bottom of where it is shown.

Name box settings

name_pos
ValueMeaning
0Position name box in upper left corner of message window
1Position name box in upper right corner of message window
2Position name box in lower right corner of message window
3Position name box in lower left corner of message window
other settings
SettingMeaning
name_overlap Number of pixels the name box should be moved in y direction towards the center of the message window. If negative, it will be moved away. A value of 0 means that they are directly on top of each other.
name_offset Number of pixels the name box should be moved in x direction towards the center of the message window. If negative, it will be moved away. A value of 0 means that their outer borders line up vertically.
name_padding Number of pixels of empty space between the name and the name box borders.
name_swap If this is activated, the name box's position will be changed to the opposite to avoid getting pushed out of the screen.

Tag reference

Hermes can easily be expanded to support more tags. Instead of the full name, you can shorten every tag in your Show Text command, as long as it stays ambiguous. For example, you can safely abbreviate \Sound to \so, but not to \s because then it would conflict with other Hermes tags, for example \Shadow.

Syntax explanation

In the following, I will use a simple-as-possible Backus-Naur form variant to describe the syntax of the Hermes tags. Here's a quick overview of how it works:

Syntax description used in tag reference
NotationMeaningExample
green colorWhole, positive number meaning of life could be 42 but not -1 or 42.5
red colorA string of characters rgss could be completely bugged or well that's it
blue colorA fixed value life must be life
a..bNumbers between a and b 2..6 could be 4 or 6 but not 9
( a / b )Alternate ( pork / beef ) could be pork or beef but not ham or 5
[ a ]Optional [ hero ] could be I or you or nothing
{ a }None, one or more { 2 / girls / 1 / cup } could be 21cupcupcup or nothing

Font display options

\ty font name Reset to default font
Draws the following text using the specified font name.
\TypeFace[Times New Roman]
\h number Reset to default font size
Draws the following text in the specified size (≈height in pixel).
\Height
\b on / off Toggle from on to off and vice versa
Draws the following text in bold face.
\Bold[on]
\i on / off Toggle from on to off and vice versa
Draws the following text in italic face.
\Italic
\co 0..9 / # RRGGBB [ AA ] Reset to default font color

Draws the following text in the specified color, which is either a color code from 0 to 7 (see table below) or a hexadecimal color code which may include an alpha value. The latter should start with a # sign, like in HTML/CSS.

RGSS color codes
Color codeColor
0
1
2
3
4
5
6
7
8-9
Hexadecimal color codes (examples)
Color codeColor
#FFFFFF
#8080FF
#FF8080
#80FF80
#80FF80FF
#80FF8080 (semi-transparent)
#80FF8000(invisible)
#FF8000
#0080FF
#fd6e57
#79e7e6
........
\Color[#DEADBEEF]
\op 0..255 Reset to default opacity
As an alternative to setting a font color with an alpha channel, this tag can be used to change only the opacity. 0 is fully transparent, 255 fully opaque.
\Opacity[128]
\sh [ number ] [,] [ # RRGGBB [ AA ] ] Reset to default shadow
Enables a shadow for the following text. The first argument is the offset in pixels, the second a hex-code color as described in \Color. If either is left out, the corresponding value will not be changed. If both are left out, the default is assumed. If the first value is a 0, the shadow will be disabled.
\Shadow[#00D000]
\ou [ number ] [,] [ # RRGGBB [ AA ] ] Reset to default outline
Enables an outline for the following text. The first argument is the width in pixels, the second a hex-code color as described in \Color. If either is left out, the corresponding value will not be changed. If both are left out, the default is assumed. If the first value is a 0, the Outline will be disabled.
\Outline[3,]

Tags for name boxes

For all of the above tags, there is an equivalent one for name boxes (see \NameBox), by prepending the respective tags with an underscore character (_). For example, to change the text size in the name box. You can write \_size[26]. However, this will only work when a \NameBox tag has been used before, in the same message. If you try to set a font property prior to setting a name box text, it simply won't work.

Message flow control

\al ( l / c / r ) , ( t / m / b ) Reset to default alignment
Sets the text alignment for the current message. If this tag is used multiple times in a single message, only the last one will take effect. The value before the comma is for horizontal alignment (left / center / right), the one after for vertical alignment (top / middle / bottom). These words can also be written out in the tag, e.g. \x[right,bottom] will work.
\Align[center,b]
\sp number Reset to default typing speed
Sets the typing speed for the following text. Larger numbers means slower typing. A value of zero means that the following text will be displayed immediately.
\Speed
\% on / off Toggle from on to off and vice versa
Normally, the player skip over text (i.e., the text will be displayed at once instead of being typed) by pressing the SKIP_TEXT_CODE key specified in the Hermes settings. This tag can be used to disallow skipping of certain parts of a message. These parts cannot be displayed immediately, and if the player starts a text skip before this part, it will stop skipping as soon as the tag is reached.
\%
\.
Pauses typing for five frames, or a quarter second. Can be skipped.
\..\..\..\. What?
\|
Pauses typing for twenty frames, or a whole second. Can be skipped.
Oh.\| My.\| GOD!
\!
Requires the player to press a choice key to continue. It will show the same little arrow in the bottom of the message window as if the message was over. This cannot be skipped by the player.
Press any key to continue.\!
\^
Closes the message window immediately. This can be used in combination with the \% and wait tags to create automated text in cutscenes.
Hello?\|\| Is anyone there?\|\| Good night.\.\.\^

Variable text display

\# 0..3 Retrieve the party leader's actor ID
Retrieves the actor ID of the party member with the given position. This can be useful in combination with other tags, e.g. \a or \j (see below). Caution: the party leader has the position 0, not 1!
\NameBox[\MemberID[3]]
\ac actor id Display the party leader's name
Displays the name of the actor with the given actor ID.
\Actor
\cl actor id Display the party leader's class name
Displays the name of the class the actor with the given actor ID belongs to.
\Class[\Variable[5]]
\m map id Display current map's name
Displays the name of the map with the given map ID.
\Map[2]
\v [ e / i / w / a / s ] [ , ] number

Displays one of the following things:

Possible \Variable tag arguments
First argumentSecond argumentResult
e enemy id Name of the enemy with the given ID
i item id Icon and name of item with the given ID
w weapon id Icon and name of weapon with the given ID
a armor id Icon and name of armor with the given ID
s skill id Icon and name of skill with the given ID
(none) variable id Value of game variable with the given ID
\Variable[i\Variable[\Variable[8]]]
\e event id Display the name of the event currently being executed
Displays the name of the event with the given event ID. At the moment, this only works for the events on the current map.
\NameBox[\Event]
\pr item id
Displays the price of the item with the given item ID.
\Variable[i13] (\Price[13] Gold)
\/
Inserts a line break. This tag is only available if Hermes::WORD_WRAP has been set to :manual.
Line1\/Line2
\sy icon name
Draws the icon with the given file name into the message window at the current position. The argument must point to a valid file in the Graphics/Icons folder of your project. This tag is also used by the \v tag to draw icons.
\Symbol[sword_gold]

Additional objects

\f [ actor id / file name ] [ , ( face id / face alias) ] [ , { a / 1..9 / c / s / p / d / l / r / n / m } ] Show the face graphic for the party leader as single image

Shows a single face graphic or a face graphic out of a faceset image. These images need to be present in the Graphics/Pictures folder of your project. If an actor ID is specified, it will look for the file Graphics/Pictures/face_actor id, if a file name is specified, it will naturally look for Graphics/Pictures/file name.

If a face alias was specified, it will translate it into a face ID via the rules specified in config/face.rb. By default, these are:

Default face aliases
AliasFace ID
normal1
happy2
sad3
angry4


If a face id was specified directly or resolved this way, the picture file will be considered a faceset, consisting of an arbitrary number of rows with 4 faces each. The row height is assumed as Hermes::Face::HEIGHT, the face width is assumed as image width divided by four, and the face id is counted left-to-right, top-to-bottom. Example:

1
normal
2
happy
3
sad
4
angry
5688
9101112


The third part is a string of flags, which will be loaded one after another. If one property is set more than once, only the last version will be used. Here is what the flags stand for:

\Face tag flags
FlagMeaningExplanation
aAnimate the face The face will be animated by using the a single column of the graphic as the set of frames. In the above example, 2, 6, and 10 would form the animation frames if we called \f[bla,happy,a].
1..9 Animation speed Ineffective if a is not set. If it is, the animation speed will be set to the given value (1=fast, 9=slow).
c Animation type "cycle" Ineffective if a is not set. If it is, the animation will be a repeat-from-start type, e.g. the frame sequence would be 2, 6, 10, 2, 6, 10, 2,... if we take the same example as above.
s Animation type "seesaw" Ineffective if a is not set. If it is, the animation will be a inverse-direction type, e.g. the frame sequence would be 2, 6, 10, 6, 2, 6, 10, 6,... if we take the same example again.
p Pause animation along with message Ineffective if a is not set. If it is, the animation will be paused when the message is paused, i.e., when it shows the small blinking arrow and waits for the user to hit a choice key.
d Don't pause along with message Ineffective if a is not set. If it is, the animation will not be paused with the message.
l Face position: left Face graphic will be shown in the left of the message window.
r Face position: right Face graphic will be shown in the right of the message window.
n Face orientation: normal Face graphic will be shown in the same orientation it has in the original graphic.
m Face orientation: mirrored Face graphic will be flipped horizontally.
\Face[,sad,a]
\n actor id / value Show name of party leader in the name box
Shows a smaller box next to message window that contain any given value. Usually, this is used for the name of the current speaker. Therefore, an actor ID can be passed instead of a value, in which case the name if the actor belonging to this ID will be drawn in the box.
\NameBox[Mysterious Chicken]
\d see here Show face and name of party leader
Combines the \f and \n commands into a single command.
\Chara[\MemberID[2]]
\g
Shows or hides a notification box containing the party's current possession of game gold.
You have this much: \Gold\|\|\|Okay, that's enough.\Gold
\so file name Turn typing sound off
Sets a typing sound to be played on each individual letter drawn. To turn the sound off for the current message, use \Sound without an argument.
\Sound[click_\Variable[23]]

Pseudo tags

The tags in this section are different from all the others in that they aren't defined and parsed as usual. They are "magic" in a way, being executed outside of the normal procedure.

\*
Merges a Show Text command with the next one. This way, you can accumulate multiple Show Text event commands into a single message window. If the collected text exceeds $msg.max_lines, it will "scroll" inside the message box, pausing every $msg.max_lines lines. Once you reach a Show Choice or Input Number command, further accumulation is impossible and the message will be shown (the tag is ignored in Choices).
\*
\p [ screen / -1 / hero / 0 / event id / this ] [ , async ] Pop-up message over event currently being executed

If this tag is specified, the containing message will be opened as a speech-bubble-esque pop-up over a defined character, or in full screen mode with transparent background. The first argument is used as follows:

\Popup tag arguments
ValueMeaning
screen, -1 Full screen message with transparent background
hero, 0 Pop-up over the player
event id Pop-up over the event with the specified ID
this, (none) Pop-up over the event currently being executed


The full screen text box will display as many lines as fit the screen and can be used for various overlay text, e.g. game credits. The pop-up version will be automatically resized to the size of the text it contains and will be fixed to the event it is attached to. If the event moves, the box follows. When the second argument is not set, the box will try everything to stay on screen, while still staying as close to its host as possible.

But the second parameter (async) is where it gets really interesting. If it is set, the message window will not be controlled by the player. Instead, it will stay by its event until you close it manually. This can either be done with a \Close command inside this message or by opening a new message attached to the same event. If you want to close it with the latter method without opening a new window, simply set an empty message to pop up over the event. Empty messages will not be shown, however the old box will still be closed.

Asynchronous messages (i.e., such with the async flag set) can use all the things normal messages can, except for choices and input numbers. They will move with their events, even outside of the visible area. There's a virtually unlimited number of asynchronous messages possible, but only one per event at a time.

An interesting edge-case is when a synchronous pop-up message is showing, and then, invoked by e.g. a parallel process event, an asynchronous message is shown. The synchronous will then be killed without player interaction. You can see this demonstrated in the Hermes Demo, along with related behaviors when using asynchronous messages.

In battle, pop-up messages can also be used. If the supplied argument is a number less than 4, it will pop up over the party member with the fitting ID. If it is greater than three, it will pop up over the enemies (i.e., if 4, it will appear over the first monster, if 5, over the second etc.). However, battle might be bugged. I haven't properly tested this, in particular not with asynchronous messages.

\Popup[screen,async]