#=============================================================================
# ■ Hermes - Hermes Extends RMXP's MEssage System - Version 0.3c
#-----------------------------------------------------------------------------
# For more infos and latest updates, visit:
#
http://www.uglyhorst.de/rPG%20Maker/rGSS-Scripts.txt
#
# Hermes is originally based on AMS which is based on XRXS which is based on
# the default RMXP message system. However, there isn't much left from any of
# those scripts. Almost everything has been revised or rewritten (or both).
#
# Special Thanks:
# - KD: You just rock. And, without you, I would never have finished this.
# - The users on Creation Asylum who support me with bug reports and
# great ideas for future versions.
# - Also the users from RPG Architects, which have supported me, too.
# - Knumonmaster, who inspired me to add some great, new features
# - Satoru Takabayashi for his great Ruby/Romkan library
#=============================================================================
=begin
==============================================================================
1. How to install
==============================================================================
1) Open your RPG Maker project you want to use Hermes with.
2) Open the script editor by clicking the icon with the sheet of paper and the
pencil in RMXP's toolbar.
3) Insert a new script above Main by right-clicking Main and selecting Insert.
4) Rename the new script to Hermes (not required, but might be helpful) using
the edit box at the bottom left of the window.
5a) If you got the end users' version: open "Hermes Script.rb" in a text editor,
e.g. Windows' Notepad (the script might look odd in Notepad; ignore this,
it will work fine in RMXP).
5b) If you got the developers' version: repeat steps 3 to 5a) for all the
numbered .rb files in the archive you downloaded.
6) Copy the complete contents to the clipboard (for example by pressing Ctrl+A
followed by Ctrl+C).
5) Go back to RPG Maker, click in the large, empty text field on the right and
paste the just copied text (by pressing Ctrl+V).
==============================================================================
2. How to configure
==============================================================================
At the beginning of the script (Configuration & Tags script for developers'
version users), you will find changeable parameters to affect the display of
Message Windows and others. All of them are described there. If you think you
"messed" Hermes "up" by wrongly changing a parameter there, you can always paste
a fresh Hermes installation over yours, and the values will be reset to default.
See "Customize other aspects of Hermes" near the end of this document for
further information.
==============================================================================
3. How to extend
==============================================================================
Hermes is easily extensible (if you know "how to ruby", that is). If you plan on
writing an "extension" (i.e., an extra tag for Hermes), you should first get the
developers' version from my homepage. This is not required, it is just way more
easy to navigate and to learn. You can then look at the Hermes/Romkan example
extension, which shows some basic maneouvers, as well as some tricks you can use
when writing an "extension".
==============================================================================
4. How to use
==============================================================================
Each of those "commands" can be used in your message events. None of them makes
any permanent changes, only temporary ones. If you want to know how to change
aspects of Hermes permanently, see below (search for "Permanent settings:").
Below is a description of the default commands, or tags, for Hermes 0.3+.
Alternatively, there are two built-in compatibility modes: AMS+ and Hermes0.2.
These will allow you to use (most of the) Tags you could use in AMS+ (thus, also
those of AMS) respectively Hermes 0.1/0.2. Compatibility mode can be activated
by changing the TAG_VERSION constant (see "Customize other aspects" for detail).
Append a second message to your message:
\*
This appends the text (including commands) of the following message to the
current message. E.g.:
Show Message: These two lines will be\*
Show Message: displayed in one message box.
When more than four lines are to be shown in one message box (except for \p
messages), the text is scrolled upwards automatically.
Change the text color temporarily:
\c[ColorCode] or \Color[ColorCode]
ColorID is either an RPGXP color ID (as defined in Window_Base starting at line
39), where 0 is white, or an HTML style hexadecimal color code, where #FFFFFF is
white and #000000 is black.
http://html-color-codes.com/ provides a handy collection of some of such codes.
If no argument is specified, the color will be reset to default stored in $msg.
Align the text in the window:
\x[Horz,Vert] or \Align[Horz,Vert]
Enter a code for the alignment in there. The first argument is for horizontal
alignment, and can be l, left, c, center, r, or right. The second character is
for vertical alignment, and can be t, top, m, middle, b or bottom.
E.g. \x[c,m] will center the text in the message, horizontally and vertically.
There's no difference between short and long form. The comma can be left out.
For example, \x[l,b], \Align[lb] \Align[leftb] and \x[l,bottom] are the same.
If the argument is left out, it will be reset to the default stored in $msg.
Bold and italic:
\b[on|off] / \Bold[on|off], \i[on|off] / \Italic[on|off]
Will turn bold or italic on or off. If no argument is specified, bold or italic
will be toggled. Example:
\b[on]This text is bold,\b \i[on]this text is italic, \bthis text is both
and\b\i[off] this text isn't bold nor italic.
If bold / italic are set by default, use \b or \i to unset them.
Show the gold window:
\g or \Gold
This will show a gold window in a free corner of the screen, with the amount of
gold the player has in possesion.
Show an actor's name:
\a[ActorID] or \Actor[ActorID]
Use the ID of the actor whose name you want to be displayed in the message box.
If the argument is left out, the party leader's name will be shown.
Show an event's name:
\e[EventID] or \Event[EventID]
Shows the name of the event on the current map with the specified event id.
If no argument is specified or "this" is used, the current event's name will be
shown.
Get hero ID by position in party:
\#[PositionInParty] or \MemberID[PositionInParty]
Use this command to find out which ID the hero in your party has. E.g., \#[0]
gets the hero ID for the first hero in your party (i.e., the leader).
If the argument is left out, it will get the party leader's ID.
Show an item's cost:
\q[ItemID] or \Price[ItemID]
Use the item ID of the item which's price you want to be displayed in the
message box.
The argument must be specified.
Show the current map name:
\m or \Map
This will show the name of the map you are currently on.
Show a face graphic in your message box:
\f[FaceName(,ID)] or \Face[FaceName(,ID)]
FaceName must be either the filename of a graphic file found in the directory
Graphics\Images of your RPG Maker XP project, or the ID of the Actor which's
face is to be shown. When specifying an Actor ID, it will look for the file
Graphics\Images\face_<id>, make sure your Actors' faces are saved there.
The file must either be a single face graphic of any size, or follow these
specifications:
- At least four faces of the same height* and width, lined up horizontally.
- The first line should represent a normal, a happy, a sad and an angry face.
- The faceset can have any number of rows, every face graphic must have equal
height and width.
*The height of the face graphics must be equally-sized (exception: single face
graphics), this height must be specified in the beginning on the configuration
file (Hermes::FACE_HEIGHT).
If FaceName is a set of more than one face graphic, you need to specify the ID
of the face you want to use. Either a number (beginning with 1) from the top
left to right bottom, or one of normal (=1), happy (=2), sad (=3) or angry (=4).
These text IDs can also be changed in the top if the config section.
If the argument is left out, the normal face (id=1) of the party leader will be
shown.
Show the class name of a character:
\j[ActorID] or \Class[ActorID]
Use the actor's ID whose class name you want to display in the message box.
If the argument isn't specified, the party leader's class is shown.
Show icons inline:
\y[FileName] or \Icon[FileName]
Will show an icon in the text.
The argument must be specified.
Show variables, items, weapons, armor, skill names, and enemies:
\v[x,ID] or \Variable[x,ID]
Replace the x by the first letter of what you want to display:
e = enemy, i = item, a = armor, w = weapon, s = skill
If x is left out, the value of the variable with this ID is shown.
The comma can be left out (e.g., \v[i13]=\Variable[i,13]=Name of 13th item)
This command also shows the icon of your item / armor / weapon / skill.
The argument must be specified.
Show a name or other info in a name box:
\n[Text/HeroID] or \Name[Text/HeroID]
Use this to show a name box above the message box that will contain the text
you specified. When you enter a number instead of text, the name of the Actor
with that ID will be shown. Example:
\Name[\v[12]] --> Will show the name of the actor in the name box whose ID
equals the value of variable 12.
\n[derula] --> Will show "derula" in the name box.
\n[1] --> Will show the name of actor 1 in the name box.
\Name[\#[2]] --> Will show the name of your third party member.
If the argument is left out, the party leader's name will be shown in the box.
Show a name and a face graphic with one command:
\d[Name/HeroID(,FaceID)] or \Chara[Name/HeroID(,FaceID)]
This will show a name and a face graphic at once. The graphic must exist. Either
the name or the Hero ID of the hero can be specified. Using the Hero ID will
search for a file "face_<ID>" in the Graphics\Images folder, where <ID> will
be replaced by the ID you've specified. When you use a Hero's name instead,
Hermes will use the picture with the same name. Examples:
\d[7] --> Will show the name of the 7th hero in the database and select the file
Graphics\Images\face_7 to use it as a face graphic.
\Data[\#[1],sad] --> Will show the second party member's name and sad face.
\d[derula,5] --> Will show the name "derula" and the fifth face graphic found in
the faceset at Graphics\Images\derula.
If the argument is left out, the party leader's name and normal face are shown.
Modify the text opacity:
\o[Opacity] or \Opacity[Opacity]
Use this to modify the opacity of the text in the message box. Enter a number
between 0 and 255, where 255 is fully opaque and 0 is fully transparent.
If the argument is left out, opacity will be reset to default value in $msg.
Modify the text speed:
\s[Speed] or \Speed[Speed]
Use this to modify the speed of the text in the message box. Enter a number
between 0 and 20, where 20 is the slowest. A value of 0 will result in the text
being shown immediately.
If the argument is left out, speed will be reset to the value stored in $msg.
Modify the text size:
\th[Size] or \theight[Size]
Use this to modify the size of the text in the message box. Enter a number
between 6 and 32, where 32 is the biggest.
If the argument is left out, text size will be reset to default stored in $msg.
Show the message box above player or events:
\p[Option] or \Popup[Option]
Use this to set the window to appear whether above the player or any event
present in your map. Use the following options:
\p[Event ID]
\P[0] or \p[hero]
\p[-1] or \p[screen]
\p or \p[this]
Using "\p[Event ID]" will put the window on top of the specified event ID.
Using "\p[0]" or "\p[hero]" will put the window on top of the player.
Using "\p[-1]" or \p[screen]" will make a transparent full screen window.
Using only "\p" or \p[this] will cause the window to popup over the currently
playing event. Note that if you call "\p" without arguments from an autostart or
parallel process event, the window will pop up over the hero. BUT this leads to
a problem when showing messages during parallel process events: by starting to
talk to a character while a parallel process message is still to be shown, this
message will pop up over that character (RMXP bug).
Note: You can't use other tags inside the \p brackets. Thus, you cannot use a
variable to determine where to pop up a message (sorry).
Add wait in message and other commands like that:
\| --> Wait for 1 second
\. --> Wait for .25 second
\^ --> Auto close window at last letter
\! --> Wait for key input from the player
\\ --> Will show the backslash \ character
Allow / Disallow Text Skip button:
\%
Use this command to toggle prevention of text skipping. That means, the player
will no longer be able to let the whole message appear at once by pushing enter.
He will, however, be able to close the message boxes by himself. To prevent
that, use a combination of \. , \| and \^ commands.
It can be toggle multiple times while inside a message, but won't be saved
across messages.
Change the font in a message box:
\f[FontName] or \Font[FontName]
FontName must be a .TTF found in Windows\Fonts and is case sensitive. The
changes made to the font will only apply for the text after this command in the
same Window.
If the argument is left out, the default font will be used (as in $msg).
Play an SE as the letter are shown:
\s[FileName] or \Sound[FileName]
File must be in directory Audio\SE
The sound will only be heard for the letters that follow this command.
If the argument is left out, the sound will be disabled.
Modify the text color of the name box:
\z[ColorCode] or \NameColor[ColorCode]
Use this as you use the normal color command \c[ColorCode] - But this one will
set the color used in the name box. In order for it to work, this must be called
after the \n command. Only applies to the current message.
If the argument is left out, the color will be reset to default saved in $msg.
Permanent settings:
To change settings permanently, use the global variable $msg. You must call
scripts that change the options of $msg to change any setting permanently.
Instance methods of the $msg object:
- $msg.font: The font used in the message window.
- $msg.name_font: The font used in the name window.
The two above should not be changed directly, the reason for this follows soon.
- $msg.font_name, $msg.font_size, ..., $msg.font_shadow:
Use these if you want to read or write single aspects of the message font.
- $msg.name_font_name, $msg.name_font_size, ..., $msg.name_font_shadow:
Use these if you want to read or write single aspects of the name box font.
- $msg.skin, $msg.name_skin: Windowskins of message and name box, respectively
- $msg.opacity, $msg.name_opacity: Opacities of the two boxes
- $msg.align, $msg.valign: Global setting for text alignments. Possible values
are 0, 1, and 2, meaning left/top, center, right/bottom, respectively.
- $msg.prevent_skipping: global setting whether or not to prevent text skipping
- $msg.speed: global setting for text speed.
- $msg.sound: global setting for typing sound.
The defaults of all of these settings can be restored by setting the
corresponding value to nil. For example:
$msg.name_font_name = nil
print $msg.name_font_name # => Arial
This _doesn't work_ if you set $msg.name_font.name instead of
$msg.name_font_name:
$msg.font.size = nil
print $msg.font.size # => nil
$msg.font_size = nil
print $msg.font_size # => 22
So be careful! and better don't use $msg.font or $msg.name_font at all!
Customize other aspects of the Hermes:
In the config section of the Hermes, you can customize stuff.
That script helps you configure the defaults you will use in Hermes. This
includes, but is not limited to, the permanent settings described above.
Additionally, you can set global font settings which will affect the font in
every window. Of course you can also just leave it as it is, if you want to use
the default settings.
Additionally to the font settings, you can set the geometry for both the message
and the name box. These settings are a bit documented, if you don't understand
the documentation, just try it out. You can still repaste the original script if
you messed the settings up.
In the middle of the config section (maybe not the physical middle, but the
logical one), there's a hash called @@face_aliases. In this hash, you can
configure which special face name will be translated to which face number in the
\f command. You could, e.g., add something like this to the list:
"sleepy" => 5
end then, \f commands in the following style will be legit: \f[hero,sleepy] and
would simply be the same as \f[hero,5]. Note that commas need to be typed
between the replacement definitions.
Below that, there is a hash called @@replacements. This one is quite similar,
it replaces all commands of the form $x, where x is commonly a letter, with a
single character that cannot be typed easily normally. This setting defaults to
the same replacements as can be found in RPG2k (with a few exceptions, which are
explained there).
Beyond those hashes, the tags are configured. If you are interested in adding a
tag to Hermes, please have a look at the Hermes/Romkan sample extension. It is
well documented, and shouls help you out in many cases.
Have fun, and report any bug in the topic on Creation Asylum, or (if you speak
German) on RPG Architects. But take note that some bug may occur due to another
script, and I may not be able to help if it's the case (although I am willing to
try my best).
=end
