RPG Maker VX Ace
RPG Maker VX Ace Help

This Help file describes the various features offered by RPG Maker VX Ace.

The left side of the window contains the Help file's contents. Use the context field to select the item you want to view. When you know exactly what you want to find, click the Search tab on the upper left part of the window to perform a more direct search.

Help window tabs

This program also provides pop-up hints for most items. Placing the mouse pointer over an item in the editor causes a simple description to pop up. Use this feature to learn more about the program.

©2011 ENTERBRAIN, INC./YOJI OJIMA


RPG Maker VX Ace

What Is RPG Maker VX Ace?

RPG Maker VX Ace is a tool designed especially for creating role-playing games (RPGs). Even if players do not have RPG Maker VX Ace, they will still be able to play the games you create.

Main Features

This product is an improved and enhanced version of the previous release, RPG Maker VX. The highly acclaimed user friendliness of the previous version has been maintained, while at the same time adding greater flexibility and advanced features.

Streamlined Database

Database structure has been dramatically revamped in this version. Lists such as "Features" and "Effects" have been added to each database entry, allowing a variety of settings that were formerly handled as separate data options to be more freely combined. Many new features that make for diverse and interesting battles have also been added, including counterattacking and magic reflection.

Character Generation Tool

This version of RPG Maker includes an advanced version of Chibi Character Maker, a popular tool from the web version. It allows you to create a walking graphic (small character) and face graphic all at once. Now you can easily create your own original characters simply by selecting a hairstyle, mouth, nose, outfit and so on.

Standard Audio Format (Ogg Vorbis)

The RPG Maker series has traditionally used MIDI files for background music, but now that environments allow for larger files it has been revamped for full support of Ogg Vorbis format audio. This allows you to give your game sumptuous audio unlike anything possible before and even resume background music from where it left off after returning to the map screen after a battle.

Support for Ogg Theora Movies

It is now possible to play Ogg Theora-format movies. Since decoding has been built into the engine itself, there is no need to worry about movies not playing back on different environments.

Advanced Scripting System

Games created with this version are written in the Ruby scripting language. You can create a thoroughly enjoyable game simply by using the scripts that are provided, but you can also choose to customize a wide variety of game elements as necessary. RPG Maker uses Ruby Game Scripting System (RGSS) 3.0, which features a number of improvements. Preset scripts have been further streamlined, and the structure is now easier to modify. See RGSS Specifications: New Functionality in RGSS3 for more information.

Minimum System Requirements

The minimum requirements for using RPG Maker VX Ace are as follows:

OS | Microsoft® Windows® XP/Vista/7 (32/64-bit OS support)
CPU | Intel® Pentium® 4 2.0 GHz or equivalent processor
Memory | 512 MB
Video | 1,024 × 768 resolution
Hard disk | 400 MB free
  • Your hardware must support the version of DirectX that you are using. (Any version of DirectX that came with Windows XP or later will work.)
  • The specifications for trouble-free game play differ depending on the game itself.
  • The video and hard disk drive specifications listed here are the minimum values for RPG Maker itself.


Getting Started

Creating a Project

To create a game with this program you must first create a project. A project is a collection of data and resources that constitutes your game. You can even use images and music you created yourself by importing files into your project.

Create projects using the steps below.

(1) Create a new project

Click the New Project button on the toolbar or click File - New Project on the menu bar.

(2) Specify a project name, game title, and save location

Enter a project name in Folder Name and the game's title in Game Title. The default save location for your project will be displayed in Location. To change it, click the ... button to the right and specify a different location.

Once you have made the aforementioned settings, click the OK button to make a project with the minimal required data for creating your very own game.

Creating a new project Specifying a save location

Managing Your Project

Saving/Loading

If you want to take a break from working on your project and close the program, make sure that you save your project before doing so. Click the Save Project button (or click File - Save Project) to save the project you are currently working on. This overwrites any existing data for the same project.

To resume game creation, click the Open Project button (or click File - Open Project), select the Game (or Game.rvproj2) file in the project folder, and then click the Open button.

Backing Up/Deleting

Project content is saved all together in the folder you specified at the time you first created it. To back it up, simply copy the entire folder to another hard disk, removable media, and so on. To delete a project you no longer need, simply delete its folder in the usual manner.

Creating Your Game

The RPGs you create with this program consist of a variety of elements, including graphics displayed on the game screen, player-controlled characters, items and magic, tricks and traps, and the game's story.

These elements are created and organized in three separate data categories: maps (the stage on which the game takes place), events (represents what happens and what can be done in the game), and databases (determines the settings for characters and so on).

There is no set way to go about creating a game. But if this is the first time you are creating a game in RPG Maker, we recommend you start by creating a map. Once you have a map, you can create or use premade events and characters that fit the kind of game you are making.


Basic Operation

Window Elements and Functions

The window that appears when you open a project is known as the main window. This window is mainly used for editing maps and events. The Database, Resource Manager, and other tools are opened from the main window's menu bar. The functions of each window element are described below.

(1) Menu Bar

The program's commands can be accessed through the menu bar.

(2) Toolbar

You can also access certain commands by clicking buttons on the toolbar.

(3) Tile Palette

The tile palette displays the tilesets that can be placed on maps. You can use the tabs at the bottom to switch between sets.

(4) Map List

This list shows the map data included in the game you are currently creating.

(5) Map View

This pane displays the map currently selected in the map list. Use it to perform such actions as editing the map design and specifying where to place events.

(6) Status Bar

The status bar displays information on the currently selected command, the map name, and map coordinates.

UI Elements and Editing Methods

Creating games with this program mainly involves specifying text, items, and other data by means of the UI elements provided in the various windows and dialog boxes. The kinds of UI elements and editing methods are described below.

Text Entry

Clicking in a text box displays a flashing bar cursor. This indicates you can enter text using the keyboard. The text you type will be entered at the cursor's current position. You can also move the cursor using the keyboard's cursor keys.

Numeric Value Entry

As with text entry, clicking in one of these boxes displays a flashing bar cursor. Enter single-byte numbers using the keyboard. You can also increment/decrement values by clicking the up arrow and down arrow buttons to the right of the box.

Option Buttons

These buttons specify one option to apply from a number of choices. The option with a black dot in the center of the circle is the current selection. Clicking another one clears the previous selection.

Check Boxes

These boxes select or clear the indicated item. The check boxes with checks in them indicate that they are selected. Clicking a selected check box clears it.

Drop-Down Lists

These lists are used to specify one of the items contained within them. They open by clicking on the down arrow to the right of them.

List Boxes

These boxes display a list of items that can be set. Double-clicking an item opens its corresponding dialog box where you can edit its content.

Ellipse (...) Button

An item with an ellipse (...) next to its box indicates that another dialog box will open. Click the ellipse button and then edit the setting in the dialog box that appears.

OK, Cancel, and Apply Buttons

Settings that you edit will only be applied once you confirm them by clicking the appropriate button. To confirm a setting and close its dialog box, click the OK button. To close the dialog box without confirming the setting, click the Cancel button. And to confirm a setting without closing the dialog box, click the Apply button.


Menu Bar

The menus and commands available on the menu bar are described below.

A number of menu bar commands can also be executed by clicking their associated icon buttons on the toolbar. In addition, menus and commands with shortcut keys displayed next to them can be selected by pressing the associated keys.

This means there are a number of ways to execute the same command. For example, to execute the Undo command, you can click Undo on the Edit menu, hold down the CTRL key while pressing the Z key (CTRL+Z), or click the Undo button on the toolbar.

File Menu
New Project

Creates a new project. If a project is already open, it will be closed once the new one has been created.

Open Project

Opens a previously saved project so that you can continue creating your game. In the Open window that appears, select the Game or Game.rvproj2 file in the project folder.

Close Project

Closes the current project. A confirmation dialog box appears if there is unsaved data. To save your project before closing it, click Yes, or to close it without saving, click No.

Save Project

Saves the project you are currently working on. (This overwrites any existing data for the same project.)

Compress Game Data

Compresses the project you are currently working on into a single file to make it easier to distribute. See Support Tools for more information.

Exit RPG Maker VX Ace

Closes the program. As with the Close Project command, a confirmation dialog box appears if there is unsaved data.

Edit Menu
Undo

Undoes the previous operation, returning to the state immediately before it was performed. Up to sixteen previous operations can be undone.

Cut

Copies the selected map data or map event to the clipboard and deletes the original selection.

Copy

Copies the selected map data or map event to the clipboard without deleting the original selection.

Paste

Adds the content of the clipboard as new map data or a new map event.

Mode Menu
Map

Switches to the mode for editing map design.

Event

Switches to the mode for creating/editing map events. In map view, a grid split up into tile-size spaces is overlaid onto the map.

Region

Switches to the mode for editing regions, which define the encounter area for enemy groups.

Draw Menu

Contains tools for drawing tiles used in map editing mode. See Editing Map Design for more information.

Scale Menu

Switches the display scale for the map displayed in map view. The standard scale is 1/1, but you can select 1/2, 1/4, or 1/8 to reduce the map to the indicated scale.

Tools Menu
Database

Opens a dialog box for setting the database used to create/edit game elements, such as characters and items.

Manage Resources

Displays tools for managing resource files used to create games, including images, music, and movies. See Support Tools for more information.

Script Editor

Opens the Script Editor tool for scripting and editing the game system. See Support Tools for more information.

Test Audio

Listen to the audio you imported into your project as resource files. See Support Tools for more information.

Generate Characters

Create a walking graphic and a face graphic for characters by combining various parts that are provided. See Support Tools for more information.

Options

Change settings related to image transparency and grid display in the editor. See Support Tools for more information.

Game Menu
Play Test

Start the play test tool. See Support Tools for more information.

Start in Full Screen

Change the setting for starting a game in full screen mode. Selecting this item switches between enabled (a check in the check box) and disabled.

Display Console

Change the setting for displaying a console window for debugger output. Selecting this item switches between enabled (a check in the check box) and disabled.

Open Game Folder

Open the save folder for the project. Use this command to check the location of the project folder and to access files that you want to work on manually.

Help Menu
Contents

Display Help (this window).

RPG Maker Web

Open the RPG Maker Web (http://tkool.jp/) site in your browser. Visit the site whenever you want to check support information for the program and get other important information.

About RPG Maker

View version and other information about the program.


Using Support Tools

Compress Game Data

Compress Game Data

Save project content into a compressed file by selecting Compress Game Data on the File menu. This is handy when you want to distribute your completed game. In the Output Folder box, specify where you want to saved the compressed file.

Enabling Create encrypted archive when saving encrypts your project content to keep it safe from prying eyes. To compress your project along with RTP data, enable the Include RTP data option. This will eliminate the need to download RTP data to play the game, but please note that it will markedly increase the file size.

Note that the Compress Game Data command may fail with game projects exceeding approximately 2 GB.*
*This value is merely a guideline. It will vary depending on the PC hardware and OS you are using and the game you are creating.

Manage Resources

The Manage Resources dialog box displayed by selecting Manage Resources on the Tools menu is for managing the resource files included in your project. The various parts of the dialog box and the functions of its buttons are described below. Note that in order to use your own images, music, and other files to create a game, they must be in one of the designated standard formats. See Resource Standards for more information.

Folder List

A list of folders containing resource files is displayed here. To import a resource file into your project, specify the folder where it is located.

File List

A list of files located in the folder selected in the folder list is displayed here. A red circle before a file name indicates a resource file that was imported into RPG Maker, while a blue circle indicates a resource file that is included in the RTP.

Import

Imports a resource file into your project. In the folder list, select the folder you want to import the resource file into, click the Import button, and then specify the target resource file. When importing an image, left-clicking assigns a transparent color and right-clicking assigns a translucency color.

Export

Saves a project resource file outside of the project. In the file list, select the file you want to export, click the Export button, and then specify the save location. Resource files you export in this manner will remain within the project. Note that you can select multiple resource files in the file list by drag-selecting and then export them all at once.

Preview

Displays the image contained in the graphics resource file selected in the file list. To check an audio file, use the Test Audio tool.

Delete

Deletes from the project the resource files selected in the file list. You cannot delete standard RTP resource files (those with a blue circle in front of their name). Note that deleted files cannot be recovered, so make sure you really want to delete the selected files before proceeding.

Test Audio

The Test Audio dialog box displayed by selecting Test Audio on the Tools menu is for managing the audio files included in your project. Audio playback continues even after you close the dialog box, allowing you to use this command to play music while you create your game.

The dialog box contains tabs for four different types of audio: BGM (background music), BGS (background sounds), ME (music effects), and SE (sound effects). Click the tab for the type of audio file you want to test and then select a file from the list. The selected audio file will start playing when you click the Play button. To stop playback, click the Stop button.

Use the Volume control to adjust the playback volume between 0% and 100% and the Pitch control to adjust the pitch between 50% and 150%.

Generate Characters

The Generate Characters dialog box displayed by selecting Generate Characters on the Tools menu is for easily creating character images that you can assign to actors and events.

Start by clicking the Male or Female tab, depending on the gender of the character you want to create. Next, select the various available parts using the settings provided for the character's face, clothing, and so on. Clicking the Random button randomly specifies the parts to use.

Changing the setting of any part automatically applies the change to both face graphic and walking graphic as a general rule. However, there are some cases where one of the graphics may not change depending on the part.

When the image is complete, you will save it as an image file. Click the Output Face button or Output Character button, and in the dialog box that appears, enter a file name, and then click the Save button. Note that if you save the file in the Face or Character folder, which are the standard locations specified for saving the respective type of image, there will be no need to separately import it into your project using Manage Resources.

Options

The Options tool that appears when you select Options on the Tools menu is for changing settings related to image transparency and grid display in the editor. These settings have no effect on game play.

Transparent Color

Set the color to use for the part of a graphic set to Transparent. Use the Red, Green, and Blue slider bars to specify the color to display. Transparent parts of the graphic will be displayed with a checkerboard pattern that uses the specified color.

Grid

Set whether to display a grid in map view (map editing mode). To display a grid, select the Valid check box and then specify the grid interval in Horizontal and Vertical using a value between 2 and 100 tiles.

Play Test

The Play Test command executed by selecting Play Test on the Game menu allows you to immediately start testing the game you are creating. Use it to check whether settings and events are operating as you would expect from the final distributable version of the game.

Using the Debugger

Pressing the F9 key during play testing displays the debugger window. This window allows you to change the values of switches and variables for the currently displayed portion of the game.

To change a value, select the desired switch or variable from the list on the left side of the window ("S" indicates a switch and "V" a variable, while the numbers show the valid range), press the indicated key to confirm, and then move the cursor to the desired switch/variable in the list on the right side. For a switch, use the indicated key to turn it on/off, and for a variable, use the left and right cursor or the L and R keys to change its value.

Ending Play Testing

You cannot edit your game during play testing. To exit play testing, click the close box (×) in the upper right corner of the window. You can also exit by pressing Alt+F4 or selecting Shut Down on the game's menu.

Script Editor

The simple programs that control game execution are known as scripts.

Generally, commands such as Show Text are referred to as scripts, but in this application, the word script is reserved for code that is more complex than event commands and almost to the level of an actual program. All event commands are interpreted and executed at the script level, rather than by the application itself.

Script editing is a feature for advanced users to employ in customizing the game system. As such, it has a high level of difficulty. However, there is no need to learn how to use it if you will create your game the normal way. We recommend creating your first game without worrying about scripts. Once you are more experienced with RPG Maker and feel that the default system leaves something to be desired, it will be time to try your hand at scripting.

RPG Maker uses the Ruby programming language, a proven scripting solution, as its scripting engine. The official website for Ruby is http://www.ruby-lang.org/.

Ruby is freeware developed primarily by Yukihiro Matsumoto. It offers the performance necessary for writing large-scale games. However, as it was originally designed for text processing and similar applications, it is rather difficult to use for game development as is. That is why the Ruby Game Scripting System (RGSS) was developed especially for games. See the RGSS Reference for more information.

Editing Scripts

Selecting Script Editor on the Tools menu displays a large dialog box for editing scripts.

Since running a large game application such as an RPG requires a large number of programs, the entire game needs to be divided up into an appropriate number of subunits. This application refers to such subunits as sections. The list on the left side of the Script Editor dialog box displays the game's sections.

The Script Editor was designed to be controlled just like the game's database. Pressing the F4 and F5 keys enables one-touch selection of the previous section and next section, respectively, just as with the database. In addition, the F6 key copies the term where the cursor is as the section name.

Section-Related Commands

Right-clicking a section name displays the shortcut menu. Selecting Insert here inserts a new empty section before the selection position. Similarly, using commands such as Cut and Paste allows you to change section order.

Unlike the database, sections are not managed using IDs. Sections are executed in the order they are listed (top to bottom). Preset scripts include a section called "Main" at the very bottom, and actual game operation does not begin until all the various types of definitions have been made.

Editing-Related Commands

Right-clicking in the text editor area on the right side of the window displays the shortcut menu shown in the figure to the right. The menu contains a variety of basic editing commands, including Cut, Paste, Find, and Replace.

Shortcuts key combinations such as Ctrl+F and Ctrl+G work even when the text editor is not in focus.

To search for text in all sections, not just the one you are editing, select Find on the section shortcut menu. The shortcut key combination for this is Ctrl+Shift+F.

Using Scripts

In addition to directly editing scripts in the Script Editor, you can also use them in the following four ways:

  1. Use them with the Script event command.
  2. Use them as a condition for the Conditional Branch event command.
  3. Use them as an operand for the Control Variables event command.
  4. Use them as a command within the Move Route command.

For example, you could use scripts in the above-mentioned ways to call an event command you added with the Script Editor. The fun and interesting ways you can use scripts is limited only by your imagination.


Playing a Game

Basic Controls

Starting a Game

Games created by RPG Maker are started by double-clicking the Game.exe (or Game) file located in the game data folder. If the game data has been compressed, extract it ahead of time by double-clicking.

Controls

The controls for games created with RPG Maker are based on the use of a six-button game pad. For descriptive purposes, the button names will be referred to as A, B, C and so on here. The following table shows the correspondence between game pad buttons/keyboard keys and commands in a standard game. To move characters and the cursor, use the directional buttons on the game pad or the arrow keys on the keyboard.

Name | Game pad | Keyboard | Main function
A | Button 1 | Shift | Dash
B | Button 2 | Esc, Num 0, X | Cancel, Menu
C | Button 3 | Space, Enter, Z | Confirm, OK, Enter
X | Button 4 | A | -
Y | Button 5 | S | -
Z | Button 6 | D | -
L | Button 7 | Q, Page Up | Previous page
R | Button 8 | W, Page Down | Next page
Game Properties

Pressing the F1 key while a game is running displays the dialog box shown here. Use this dialog box to customize game pad button and keyboard key assignments. Clicking the Reset button reverts assignments to their default settings.

The following settings are available on the General tab.

Start in Full Screen
Automatically switches to full screen mode when the game starts.
Suppress Screen Flicker
Minimizes the flicker associated with screen drawing. Screen drawing may slow down slightly.
Play BGM and ME
Specifies whether to play back music while playing a game.
Play BGS and SE
Specifies whether to play sound effects while playing a game.
Other Commands
Key | Description
Alt+Enter | Switches between window mode and full-screen mode.
Alt+F4 | Forcibly exits the game.
F12 | Forcibly returns to the title screen.
F2 | Displays the frames per second (FPS) on the title bar.
F9 | Opens the debugging window (list of switches and variables) when pressed while moving during play testing.
Ctrl | Enables characters to move through impassible tiles and disables random encounters when the key is held down while moving during play testing.

In-Game Menu Operations

Title Menu

The title menu appears when a game is started. The following commands are available on the title menu.

New Game
Starts the game from the beginning.
Continue
Resumes a game from the previously saved data. Select the save data from which to continue.
Shut Down
Exits the game.
Menu When Moving

This is the menu that appears when the player presses the cancel button while moving on the map. The commands that appear are for using items to recover the actor's stats, saving game progress, and so on. The commands are described below.

Items
View/use the party's items. To use an item, select it from the list. For some items, you will also have to select the target of the item's effect.
Skills
View/use skills (such as magic). To use a skill, select it from the list. For some skills, you will also have to select the target of the skill's effect.
Equipment
View/change equipment. Select the actor for which you want to view or change equipment. To change equipment, you must also select the slot you want to change and the equipment you want to equip there (or to empty a slot, select a blank item).
Status
View an actor's status. Select the actor you want to view.
Change Formation
Change the order in which actors are arranged. Select two actors to swap places.
Save
Saves current game progress. Select one of up to four save files.
Exit Game
Exits the game. Select Return to Title Screen, Shut Down (exit the game application), or Cancel (cancels the exit operation).
Menu When Fighting

When the player encounters an enemy character during the game, the screen switches to the battle screen. The player selects the following commands to proceed through the battle. The game ends if all party members are reduced to zero HP.

Party Commands
These are commands that are displayed each turn. Select Fight to continue the battle and Escape to flee from the enemy. But even if the player selects Escape, if the enemy circles around, only the enemy can act until the turn ends.
Actor Commands
After selecting the party command Fight, select actions for each party member. The main actions are Attack (with the currently equipped weapon), Defend (character protects himself to lessen damage), and Item (use an item on hand). Available actions vary by actor settings.


Editing Maps

What is a Map?

A map is data representing the stage on which the game takes place. The game unfolds primarily on a screen with the player's characters moving over a map.

Maps are created and edited using combinations of map pieces known as tiles.

Basic Specifications of Maps

Role of Tiles

Tiles give graphical representations to the map you create and allow you to make a number of different settings, such as whether characters can pass through them.

Each map has one group of tiles known as a title set assigned to it, and the titles therein are used to design the map itself. You can also completely change the look of a map by changing the tileset it uses. Title set content is edited using the Database.

Types of Tiles

Each title set can have five types of tiles labeled A through E. Type A titles are for the lowest layer on the map and are used for representing such things as terrain and ground, while types B through E are for representing upper layer objects such as trees and signs.

Both lower layer and upper layer titles can be placed at the same position on the map. You can use this two-layer structure to expand the range of expression of your maps.

Standard tilesets (those included in the RTP) include lower-layer tiles representing oceans, grasslands, floors, walls and other surfaces, and upper-layer tiles for embellishing them.

Map Size and Display Method

Map size is measured in tiles and can range from 17 to 500 tiles horizontally and 13 to 500 tiles vertically.

An area equivalent to 17 × 13 tiles (H × V) can be displayed on the game screen at any time. Maps larger than this will move automatically (scroll) with the player remaining at the center. It is also possible to connect the edges of a map to form a loop to create effects such as going around the world and coming back to your starting point.

Map Positions

Positions on map tiles are represented using map coordinates. The tile at the upper left corner is the origin (0, 0) of a map's coordinates, with the first number representing the number of the tile on the x axis, and the second the number of the tile on the y axis. For example, the map coordinates of the lower right corner on a 500 × 500 tile map would be 499 × 499. The status bar displays the map coordinates of the tile that is currently being edited.

Map coordinates can be used to specify a move destination for the party based on a variable or to monitor a party's current position in an event command.


Editing Map Design

Basic Editing

Switching Between Editing Modes

If you want to edit a map's design, click the Map button on the toolbar (or select Map on the Mode menu) to switch to editing mode.

Selecting Map Data

Select the map data you want to edit by clicking on the map list on the lower left part of the window. The current look of the map is displayed in the map view on the right side of the window.

Selecting Tiles

Select the tiles you want to use by clicking them on the tile palette. The currently selected tile will have a white border around it. Switch between the types of tiles displayed on the tile palette by clicking tabs A through E.

You can specify multiple tiles to draw on your map by drag-selecting on the tile palette.

Selecting and Drawing With Drawing Tools

Select the tool you want to use to draw tiles by clicking it on the tool bar. There are four tools in all. Once you have selected a tool, click or drag on the map displayed on the right side of the window (map view) to draw the selected tile(s). You can also select drawing tools on the Draw menu.

You can delete the tiles you have drawn by drawing transparent tiles over them. Upper-layer tiles on the B tab to the upper left are transparent.

Pencil Pencil

Draws the selected tile(s) where you click.

Rectangle Rectangle

Draws the selected tile(s) within the entire area bounded by the rectangle you dragged.

Oval Oval

Draws the selected tile(s) within the entire area bounded by the oval you dragged.

Fill Fill

Draws the same kind of tile in a contiguous area, starting from the position you first clicked.

Other Editing Features

Eyedropper

Right-clicking on map view sets the tile at the clicked position as the tile to draw. Right-clicking a position where both upper and lower-level tiles have been drawn sets both of them as the tiles to draw in an overlapping state.

Auto Tile

Some tiles on the tile palette's A tab include a feature known as auto tile. The auto tile feature has multiple patterns for each type of tile. Boundaries will be automatically adjusted according to how tiles are arranged. Tile types A1 through A4 in the tileset database have the auto tile feature.

Note that you can temporarily disable the auto tile feature by holding down the Shift key while drawing tiles or using the eyedropper.

Automatic Shadow Generation

Arranging two or more auto tiles vertically will automatically draw a shadow on the bottom right side of some tiles. However, there are other tiles where no shadow will be drawn.

Shadow Pen Shadow pen

The shadow pen is a tool for drawing wall and building shadows. It allows you to shade one-quarter of a tile.

To edit a map with the shadow pen, click the Shadow Pen button on the toolbar (or select Shadow Pen on the Draw menu), and then click on the map view. Clicking where there is no shadow will draw one, and clicking where there already is a shadow will erase it.

Special Specifications for Lower-Layer Tiles

The A2 tiles in the tileset under the tile palette's A tab (rows three through six) are divided into base tiles (columns one through four from the left) and embellishment tiles (columns five through eight from the left). Embellishment tiles can be placed on top of base tiles.

However, with tilesets where Mode in the tileset dialog box is set to Field type, placing embellishment tiles over base tiles selected from columns two or four transforms them into column-one or three base tiles.


Manipulating Map Data

Shortcut Menu Operations

Right-clicking a map on the map list displays a shortcut menu containing commands for that map, including commands for changing settings and copying data. The functions of each command are described below.

Create Map

Adds new map data. See Setting Map Data for more information on available settings.

Map Settings

Opens the Create Map dialog box. See Setting Map Data for more information on available settings.

Load Sample Map
Load Sample Map

Create new map data based on sample data. Click a map name in the list, check its content, and then click OK.

Copy

Copies map data to the clipboard.

Paste

Pastes map data from the clipboard.

Delete

Deletes map data.

Shift

Shifts tile placement for the entire map. Specify the shift direction and number of tiles.

Generate Dungeon
Generate Dungeon B Generate Dungeon A

Automatically generates a maze-like map. By specifying the tiles to use for the ground and walls, you can have the application automatically draw a maze-like map with a number of rooms connected by corridors.

A dungeon will be generated for the entire map that you selected, so if you want to create a large dungeon, start by creating a large map. You will end up with a rather poor dungeon map if you start with a map that is too small.

Grouping Maps

Dragging map data on the map list to another location on the list allows you to place it near related data. This is handy for managing map data by grouping it, such as placing the internal maps for buildings under a town map. Maps moved to the bottom can be moved to the top level by dragging them to the project name folder.

This hierarchical display is only for the map list. It has no effect whatsoever on map design and settings.


Setting Map Data

Create Map Dialog Box

The Create Map dialog box appears when you create a new map or right-click a map and select Map Settings on the shortcut menu. This dialog box allows you to create and edit maps by setting their size, the tilesets they use, background music, conditions for encounters with enemy troops (battle occurrences) and other items that affect game play.

Available Settings

Create Map dialog box
Name

The name of the map you are creating/editing. This setting is only used by the editor and has no impact on game play.

Display Name

Name displayed when the player moves on this map.

Width/Height

Size of the map. Specify a value between 17 and 500 for Width (horizontal) and 13 and 500 for Height (vertical). If you change a map's size so that it is smaller than before, the portion that will no longer fit will be deleted.

Tileset

Specify the tileset to use for the map design.

Scroll Type

Method for looping the map. Setting a loop connects the edges of the map together in a specified direction, allowing travel in an endless loop.

No Loop

No loop processing.

Vertical Loop

Connects the top edge of the map to the bottom edge.

Horizontal Loop

Connects the left edge of the map to the right edge.

Both Loop

Connects the map at its top and bottom edges and left and right edges.

Specify Battle Background
Specify Battle Background

When selected, this setting allows you to specify a combination of two graphics to display as a battle background when a battle occurs on this map.

When it is not selected, processing depends on the Mode of the tileset that was set for this map.

Mode is Field Type

The battle background is automatically determined by the tile where the player is standing when the battle occurs.

Mode is Area Type or VX-Compatible Type

The map and its effects will be used for the battle background.

Auto-Change BGM/Auto-Change BGS

When selected, this setting automatically starts playing background music (BGM)/background sounds (BGS) when the player is on this map. Specify the audio files you want to play.

Disable Dashing

When selected, this setting prevents the player from dashing on this map.

Parallax Background

Graphic displayed on the blank area of the map. Click ... to open a window for specifying an image file.

Selecting Loop Horizontal or Loop Vertical scrolls the parallax background when the player moves in the specified direction. And specifying a value between -31 and 32 (except for 0) automatically scrolls the parallax background. A positive value scrolls left/up and a negative value right/down, and the greater the absolute value, the faster the scrolling speed.

Selecting Show in the Editor allows you to check the parallax background you set. Note that the display method may differ from that when actually playing the game.

Note

Allows you to enter notes when creating a game. This setting is only used by the editor and has no impact on game play.

Encounters

Specifies the enemy troop that the player will randomly encounter while moving on this map. This dialog box opens when you double-click on a blank area within the field, and you can specify the settings described below. Right-clicking on an enemy troop that has been added displays a shortcut menu in which you can copy, delete, and perform other such operations.

Troop

Specifies the enemy troop you want to set.

Weight

Specifies the priority (0 to 100) for this enemy troop to appear as a battle opponent. When multiple enemy troops are set, the larger this value, the higher the encounter rate for this enemy troop.

Specifically, the encounter rate is calculated using the percentage accounted for by the total value of the weights of the enemy troops that were set.
For example, let's say you set a weight of 9 for troop A, 7 for troop B, and 4 for troop C. In that case, the encounter rate for troop A would be 9/20 (9 + 7 + 4 = 20) or 45%. Similarly, the rates for B and C would be 7/20 (35%) and 4/20 (20%), respectively.

Range

Specifies the area in which this enemy troop is encountered. To have the encounter occur regardless of the area, select Entire Map. To have the encounter occur in a specific area only, select Specify by Region ID and then specify up to three region IDs. The method for setting regions is described at the bottom of the page.

Steps Average

Specifies the frequency of encounters while moving on the map using a value that stands for the average number of steps taken (1 to 999 steps with each step representing traveling over one tile). Use a smaller value if you want to have monsters appear more frequently.

Setting Regions

Regions as specified in the Encounter dialog box are areas indicating where enemy troop encounters occur. Each map can be divided into 63 regions.

To set one or more regions, click the Region button on the toolbar (or select Region on the Mode menu) to switch to editing mode. Next, click a region ID (1 through 63) in the upper left part of the window to select it, and then click on map view to set the selected region ID for the clicked position (tile). You can only set one region ID per tile.


Editing the Database

What is the Database?

The Database is a collection of elements other than maps and map events that comprise the game. The Database dialog box allows you to prepare game elements and settings, including the characters the player controls, items, and magic, as the fourteen different kinds of data described below.

You will prepare data for each item appearing in the game, except for System and Terms data, which apply globally. For example, on the Items tab, you create data entries for each item that will appear in your game, such as keys and recovery items, by setting their names, graphics, effects when used, and other characteristics.

Resource files imported into your project can also be displayed or played back in-game by assigning them to purpose-specific data entries.

Actors | Characters the player can control
Classes | Characteristics to give to the actors (such as parameters and development conditions)
Skills | Special abilities and actions during battles (normal attacks, special attacks, and magic etc.)
Items | The items the player can possess (recovery items and keys etc.)
Weapons | Equipment actors use for attacks (swords, staves, and bows etc.)
Armor | Equipment actors use for defense (body armor, shields, and accessories etc.)
Enemies | Characters that fight against actors
Troops | Groups of enemies that appear
States | States that affect actors (poison and K.O. etc.)
Animations | Visual effects displayed when using skills etc.
Tilesets | Tilesets used in creating maps
Common Events | Commonly executed event processing
System | Basic settings for the overall game, including default settings and music
Terms | Names of commands and settings used throughout the game

Editing Procedure

Displaying the Database Dialog Box

Database content is edited using the Database dialog box. To display it, click the Database button on the tool bar (or select Database on the Tools menu).

Database Dialog Box

The Database dialog box is divided into tabs by data type. To create/edit data, start by clicking the tab for the type of data you want to work with.

To edit data other than that on the System and Terms tabs, select the data entry you want on the data list on the left side of the dialog box by clicking it. This will allow you to define the data's characteristics by editing the settings on the right side of the dialog box.

You can switch between the data entries in the data list using the F4 and F5 keys.

Changing the Number of Data Entries

You can define up to 999 data entries for each data type except for System and Terms. To change the number of data items, click Change Maximum at the bottom of the data list and then specify a value between 1 and 999. If you decrease the maximum number, all data entries exceeding the new maximum number will be deleted.

Shortcut Menu Operations

Right-clicking an entry in the data list displays a shortcut menu in which you can copy it to the target and perform other such operations. The available operations are as follows:

Copy

Copies data settings to the clipboard.

Paste

Applies the settings in the clipboard to the data (overwrites). All data settings from before the operation will be lost. If you copied multiple data entries to the clipboard with the Copy Multiple command, settings will be applied all at once to all the data entries starting from the one that was right-clicked.

Clear

Clears all data settings.

Copy Multiple

Copies multiple data settings to the clipboard. Specify the number of entries to load from the right-clicked items.

About Data IDs

The numbers displayed preceding each entry in the data list are data IDs (unique numbers). These IDs can be used in different ways, including when specifying data subject to processing by event commands.

Using the Memo Field

The Memo field is provided for some data types (actors, classes, skills, items, weapons, armor, enemies, states, and tilesets). It is used for writing notes during game creation. It has no impact on game play.


Actor Settings

Data Role

Actor data represents the characters that the player controls. It can also represent actor-specific characteristics.

Available Settings

Name/Nickname

Name is the actor's name displayed during game play, while Nickname is the actor's alternate name, usually a more descriptive designation. Long names may not display in their entirety in menus and battle screens while playing the game. The name entered in Nickname is displayed at the upper right of the status list window.

Class

Specifies the actor's class. This has an impact on, among other things, the skills that can be used and the weapons and items that can be equipped. The data for classes can be edited on the Classes tab.

Initial Level/Max Level

Initial Level is the actor's level at the start of the game, and Max Level is the maximum level the actor can attain. The actor cannot exceed the level set for Max Level. Both fields can be specified using a value between 1 and 99.

Description

Specifies introductory text for the actor. This text is displayed at the bottom of the actor's status list screen while playing the game.

Graphics

Specifies images for the actor. The left pane is for setting a walking graphic to display while moving on the map, and the right pane is for setting a face graphic to display in the status screen and elsewhere. Double-clicking either pane displays a dialog box for specifying the image to use. If you do not want to display a graphic, specify None.

Initial Equipment

Specifies the equipment with which the actor starts the game. Use the Weapon, Shield, Head, Body, and Accessory drop-down lists to select the actor's starting equipment. Selectable equipment is limited to that which the actor's class can equip. If you do not want to equip anything for a slot, specify None.

Features

Specifies the actor's unique features. Define them in the window that appears when you double-click each line in the Features box. See Setting Features for more information.


Class Settings

Data Role

Class data defines the features and abilities of actors. Actors must belong to one of the available classes. The way they level up, how their parameters rise, the skills they can learn, and so on are determined by these settings. You can also assign class-specific features.

Available Settings

Name

The name of the class. This text is displayed on the menu screen and at the top of the actor's status list screen while playing the game.

EXP Curve

This setting is for the experience points required to level up. Actors gain one level each time they earn the amount of experience required for the next level. Leveling up raises parameters and enables the learning of skills.

Set the experience points required for leveling up by setting the following four values in the dialog box that appears when you click ... in the setting field. The To Next Level tab displays the experience points required to reach the next level along with a graph in the background. Use this information to help you make your settings. The Total tab displays the experience point totals for attaining each level.

Base Value

Sets the base value for calculating the required experience points. Setting a smaller value reduces the required experience points overall.

Extra Value

Sets an extra value to add to the experience points necessary for each level.

Acceleration A

Adjusts the degree of acceleration for the required experience points. Setting a larger value proportionally increases the required experience points as levels increase.

Acceleration B

Adjusts the degree of acceleration for the required experience points. Setting a larger value increases the required experience points mainly at higher levels.

Parameter Curves

Sets parameters by level. Double-clicking a graph displays the Parameter Curves. See Setting Parameter Curves for more information.

Skills

Sets the skills that can be learned by leveling up. Double clicking the field displays a dialog box for specifying skills and the level at which they can be learned. Memo is for writing notes while creating your game.

Features

The features given to the actors for which this class is set are displayed here. See Setting Features for more information.

Setting Parameter Curves

In the Parameter Curves dialog box, specify parameters per level using the settings described below. Switch between the parameters you want to edit by clicking on their tabs. When you are done editing parameters, click the OK button to apply your settings (clicking Cancel will discard the settings you made).

Quick Setting

Applies a predetermined value to the parameters for all levels. There are five value patterns (A through E). Apply the one you want by clicking its button.

Level/Value

Directly edit parameters per level. After specifying a level (1 to 99) in the Level box, enter 1 to 999 in the Value box for parameters at the specified level (enter 1 to 9999 for max HP/max MP).

Generate Curve

Automatically calculates the level values between level 1 and level 99.

Clicking this button displays the Generate Curve dialog box where you enter 1 to 999 in the Level 1 and Level 99 boxes for the value at each level (enter 1 to 9999 for max HP/max MP).

Next, determine the growth type using the slider. The closer to Fast the slider is, the faster the growth rate (parameter increase), and the closer to Slow it is, the slower the growth rate. Clicking the OK button sets parameters according to the settings you made.

Graph

Displays a bar graph for the parameters set by level. Clicking/dragging on the display area changes level parameters at that location.


Skill Settings

Data Role

Skill data defines the actions that actors perform, including attacks and defense during combat and abilities (special attacks and magic). Defining a series of settings such as the conditions and occasions under which action is possible, the success rate, and the damage dealt to the target allows you to represent a variety of actions.

Available Settings

Name

The name of the skill you are creating/editing. If the name you enter is too long, the entire string may not fit onscreen.

Icon

The icon that displays along with the skill name during the game. Double-clicking it displays the Icon window where you can specify an image. Generally, you should select an image that fits the skill's characteristics.

Description

Descriptive text that appears when the player points the cursor at the skill on the game screen.

Skill Type

Specifies the type of skill. Initially, there are only two default settings (Special Attack and Magic), but you can set/change additional skill types on the Terms tab. All skill types except None can only be used by actors and classes that have been assigned the type in question using Add Skill Type.

MP Cost/TP Cost

The number of MP (0 to 9999) and TP (0 to 100) that are consumed when using the skill. The skill can only be used if the user's MP/TP equals or exceeds this value.

Scope

The target(s) affected when the skill is used. Specify one of the following:

None

The skill does not require you to specify an area-of-effect.

One Enemy

Affects one specific enemy.

All Enemies

Affects entire enemy troop.

x Random Enemies

Affects several randomly selected enemies (x is the number of targets).

One Ally

Affects one specific ally.

All Allies

Affects the entire ally group.

x Random Allies

Affects several randomly selected allies (x is the number of targets).

The User

Affects the user only.

Occasion

Select the occasions when the skill can be used. Specify Always (always available during battle and on the menu), Only in battle (only available during battle), Only from the menu (only available on the menu), or Never.

Speed

The value (-2000 to 2000) added to the character's agility when using the skill. This affects attack order in battle and allows you to create skills that are powerful but take a long time to perform or skills that are weaker but can be quickly performed.

Success Rate

The rate (0 to 100%) at which the use of this skill succeeds. The actual success rate is affected by the skill's effectiveness against the target.

Repeats

The number of times (1 to 9) the effect of a skill is applied to the target per use.

TP Gain

The number of TP that will be gained by successively performing the skill and having an effect on the target.

Hit Type

The method for determining a hit. Specify one of the following:

Certain Hit

Treats a successful use of the skill as a hit. Counterattacks, magic reflection, and substitution are disabled.

Physical Attack

Determines hits based on the user's hit rate and target's evasion rate. This method is subject to counterattacks and substitution.

Magical Attack

Determines hits based on the target's magic evasion rate. This method is subject to magic reflection and substitution.

Animation

The animation displayed for the target when using the skill in battle.

Use Message

A fixed phrase (up to two lines long) displayed as a message when using the skill in battle. Click the Cast x, Performed x, or Used x button to enter that fixed phrase.

Weapon Type 1/Weapon Type 2

The weapon that must be equipped as a condition for using the skill. Specify the weapon types in the two fields. Setting both to None means there is no weapon type that must be equipped to use the skill. Setting a weapon type for both means that at least one of the types of weapons that you set must be equipped to use the skill.

Damage

To have the skill deal damage to the target, specify the type of damage and the formula for calculating the amount of damage.

Type

The effect type on HP/MP. Specify one of the six available types. Damage reduces HP/MP, Recover raises HP/MP, Drain transfers HP/MP from target to user (the amount drained will be subtracted from the target and added to the user).

Element

The element applied to the effect.

Formula

The formula for calculating damage.

To directly enter a formula, use the character strings shown in the table below to specify parameters you want to look up. To look up the attacker's parameters, change "x" to "a", and to look up the target's parameters, change "x" to "b". The string "a.atk" looks up the attacker's ATK parameter. You can also use "v[n]" (n is a numeric value) to look up the value of the nth variable. You can use the four arithmetic operators (+, -, *, and /) in your formulas.

Entering "a.atk * 4 - b.def * 2" specifies that the damage dealt will be the value calculated by (attacker's ATK × 4) - (target's DEF × 2).

Note that you can also create a formula by clicking the Easy Create button. In the dialog box that appears, specify the basic value for the calculation in Base Value, the degree of effect (0 to 1000/100 is standard) the user's ATK and the target's DEF have in Physical, and the degree of effect (0 to 1000/100 is standard) the user's MAT and the target's MDF have in Magical, and then click the OK button.

The effects of elements and defense actions are reflected elsewhere, and are therefore not included in this formula.

x.atk | Attack power
x.def | Defense power
x.mat | Magic attack
x.mdf | Magic defense
x.agi | Agility
x.agi | Agility
x.luk | Luck
x.mhp | Max HP
x.mmp | Max MP
x.hp | Current HP
x.mp | Current MP
x.tp | Current TP
x.level | Level
Variance

The degree of variability (0 to 100%). The value of the calculated damage will vary by the percentage value you specify here. For example, if damage was calculated to be 100 and variance was set to 20, the final damage would be between 80 and 120 (100 ±20).

Critical

Specify whether to enable critical hits by selecting Yes or No. When you select Yes, critical hits will be determined based on the user's critical rate and the target's critical avoidance rate.

Effects

Effects other than damage. Double-clicking the field displays the Effects dialog box. See Setting Effects for more information.


Item Settings

Data Role

Item data is for defining items other than equipment. It allows you to define the effect that an item has when an actor uses it. It can also be used to create articles that can change the game's story (event details), such as a key to a door.

Available Settings

Name

The name of item you are setting. If the name you enter is too long, the entire string may not fit onscreen.

Icon

The icon that displays along with the item name during the game. Double-clicking it displays the Icon window where you can specify an image.

Description

Descriptive text that appears when the player selects the item on the game screen.

Item Type

The type of item you are setting. Setting Key Item displays the item in a different type of frame than normal in the item list that appears in the menu while playing the game.

Price

The item's price when purchased at a shop. The player can sell the item for half this price. Setting "0" prevents the item from being sold.

Consume

Set whether or not the item disappears after use. Setting Yes means the quantity of the item the player has decreases by one when used.

Scope

The target(s) affected when the item is used. Specify one of the following:

None

The item does not require you to specify an area-of-effect.

One Enemy

Affects one specific enemy.

All Enemies

Affects the entire enemy troop.

x Random Enemies

Affects several randomly selected enemies (x is the number of targets).

One Ally

Affects one specific ally.

All Allies

Affects the entire ally group.

x Random Allies

Affects several randomly selected allies (x is the number of targets).

The User

Affects the user only.

Occasion

Select the occasions when the item can be used. Specify Always (always available during battle and on the menu), Only in battle (only available during battle), Only from the menu (only available on the menu), or Never.

Speed

The value (-2000 to 2000) added to the character's agility when using the item. This affects attack order in battle and allows you to create items that are powerful but take a long time to use or items that are weaker but can be quickly used.

Success Rate

The rate (0 to 100%) at which the use of this item succeeds. The actual success rate is affected by the item's effectiveness against the target.

Repeats

The number of times (1 to 9) the effect of the item is applied to the target per use.

TP Gain

The number of TP that will be gained by successfully using the item and having an effect on the target.

Hit Type

The method for determining a hit.

Certain Hit

Treats a successful use of the item as a hit.

Physical Attack

Determines hits based on the user's hit rate and target's evasion rate. This method is subject to counterattacks and substitution.

Magical Attack

Determines hits based on the target's magic evasion rate. This method is subject to magic reflection and substitution.

Animation

The animation displayed for the target when using the item in battle.

Type

The effect type on HP/MP. Specify one of the six available types. Damage reduces HP/MP, Recover raises HP/MP, Drain transfers HP/MP from target to user (the amount drained will be subtracted from the target and added to the user).

Element

The element applied to the effect.

Damage

To have the item deal damage to the target, specify the type of damage and the formula for calculating the amount of damage.

Type

The effect type on HP/MP. Specify one of the six available types. Damage reduces HP/MP, Recover raises HP/MP, Drain transfers HP/MP from target to user (the amount drained will be subtracted from the target and added to the user).

Element

The element applied to the effect.

Formula

The formula for calculating damage.

To directly enter a formula, use the character strings shown in the table below to specify parameters you want to look up. To look up the attacker's parameters change "x" to "a", and to look up the target's parameters, change "x" to "b". The string "a.atk" looks up the attacker's ATK parameter. You can also use "v[n]" (n is a numeric value) to look up the value of the nth variable. You can use the four arithmetic operators (+, -, *, and /) in your formulas.

Entering "a.atk * 4 - b.def * 2" specifies that the damage dealt will be the value calculated by (attacker's ATK × 4) - (target's DEF × 2).

Note that you can also create a formula by clicking the Easy Create button. In the dialog box that appears, specify the basic value for the calculation in Base Value, the degree of effect (0 to 1000/100 is standard) the user's ATK and the target's DEF have in Physical, and the degree of effect (0 to 1000/100 is standard) the user's MAT and the target's MDF have in Magical, and then click the OK button.

The effects of elements and defense actions are reflected elsewhere, and are therefore not included in this formula.

x.atk | Attack power
x.def | Defense power
x.mat | Magic attack
x.mdf | Magic defense
x.agi | Agility
x.agi | Agility
x.luk | Luck
x.mhp | Max HP
x.mmp | Max MP
x.hp | Current HP
x.mp | Current MP
x.tp | Current TP
x.level | Level
Variance

The degree of variability (0 to 100%). The value of the calculated damage will vary by the percentage value you specify here. For example, if damage was calculated to be 100 and variance is set to 20, the final damage will be between 80 and 120 (100 ±20).

Critical

Specify whether to enable critical hits by selecting Yes or No. When you select Yes, critical hits will be determined based on the user's critical rate and the target's critical avoidance rate.

Effects

Effects other than damage. Double-clicking the field displays the Effects dialog box. See Setting Effects for more information.


Weapons/Armor Settings

Data Role

This data is for the weapons and armor that actors equip. It allows you to raise/lower specific parameters or assign specific abilities to the actor that equips them.

Available Settings

Name

The name of the weapon or armor. If the name you enter is too long, the entire string may not fit onscreen.

Icon

The icon that displays along with the weapon/armor name during the game. Double-clicking it displays the Icon window where you can specify an image.

Description

Descriptive text that appears when the player selects the weapon/armor on the game screen.

Weapon Type/Armor Type

The type of the weapon or armor. Sets the actor and class characteristics for the weapon and armor, enabling you to define who can equip it. You can set/change the types of weapons/armor that can be selected on the Terms tab.

Equip Type

Specifies where the weapon/armor is equipped (shield/head/body/accessory). Actors can equip one piece of armor in the slot matching the armor's equipment type.

Price

The weapon/armor's price when purchased at a shop. The player can sell it for half this price. Setting "0" prevents it from being sold.

Parameter Changes

The value(s) applied to the parameters of the equipping actor. Max HP and Max MP can be specified between -5000 and 5000, while the rest are between -500 and 500. Setting a negative value causes the affected parameters to go down.

Features

The features to apply to the equipping actor. Define them in the window that appears when you double-click each line in the Features box. See Setting Features for more information.


Enemy Settings

Data Role

This data represents the enemies that that player will battle. In addition to parameters like those you set for actors, you also set action patterns for the enemies you define.

Available Settings

Name

The name of the enemy you are creating. If the name you enter is too long, the entire string may not fit onscreen.

Graphic

The image of the enemy to display in battle. Double-clicking it displays the Battle Graphic dialog box where you can specify an image file. When specifying a file, you can use the Hue slider to adjust the graphic's hue. Set None if you do not want to display a graphic.

Max HP/Max MP/ATK/DEF/MAT/MDF/AGI/LUK

Set the enemy's parameters at the start of battle. Max HP can be specified between 1 and 999999, Max MP between 0 and 9999, and the rest between 1 and 999.

Rewards

The EXP (1 to 9999999) and Gold (0 to 9999999) the party earns for winning a battle against the enemy.

Drop Items

Items (including weapons and armor) earned by the party by winning a battle against the enemy. Double-click the field and in the dialog box that appears, specify the target item(s) and the Probability (between 1/1 and 1/1000) that they will be spawned.

Action Patterns

Set how the enemy will act in battle. The enemy's normal attack is automatically set by default. In the Action Patterns dialog box that appears when you double-click, specify the action type in Skill, the action's priority of use in Rating, and the condition for using the action in Conditions. Battle actions are defined based on Rules for Using Action Patterns described later on.

Turn No.

Set the number of turns elapsed as a condition. Define it using the formula A + B × X, where A is the number of turns since the start of battle and B is the number of turn cycles. When "2" is specified for A and "3" for B, the condition is fulfilled each time three turns elapse after the second turn (in other words, the action occurs on the fifth turn, eighth turn and so on).

HP

Set the enemy's HP value as a condition. Specify a percentage range (0 to 100%) of the enemy's max HP. The condition is fulfilled when HP enters the specified range.

MP

Set the enemy's MP value as a condition. Specify a percentage range (0 to 100%) of the enemy's max MP. The condition is fulfilled when MP enters the specified range.

State

Set the application of the specified state(s) to the enemy as a condition.

Party Level

Set the level of the party members as a condition. The condition is fulfilled when the highest level among party members is at or above the specified value.

Switch

Set the specified switch as a condition. The condition is fulfilled when the switch is on.

Features

The features of the enemy you are creating. Define them in the window that appears when you double-click each line in the Features box. See Setting Features for more information.

Rules for Using Action Patterns

The rules below determine which one of the action patterns set in the Action Patterns dialog box the enemy will adopt in combat.

(1) Action patterns that fulfill the conditions that were set are collected. No action is triggered if there are no action patterns that fulfill the set conditions.

(2) Out of the action patterns that fulfill the conditions, those that are within two rating points of the highest priority rating will be candidates for use.

(3) Actions 1 rating point away from the highest priority rating will be used 2/3 of the time and those 2 rating points away will be used 1/3 of the time. If there are actions with the same ratings, their probability of use will be the same.

Example 1: Two possible actions with ratings of 5 and 5 respectively

Each has a 50% chance of being used.

Example 2: Four possible actions with ratings of 6, 5, 4, and 3 respectively

The action with a "6" rating has a 50% chance of being used, a "5" rating a 33.3% chance (2/3 of 50%), and a "4" rating a 16.6% chance (1/3 of 50%). The action with a "3" rating is not considered a candidate.

Example 3: Three possible actions with ratings of 5, 3, and 3 respectively

The action with a "5" rating has a 60% chance of being used and the two actions with a "3" rating each have a 20% chance (1/3 of 60%).

(4) Once the candidate actions are selected and the probabilities assigned, one is selected using a random number.


Enemy Troop Settings

Data Role

Enemy troop data sets the groups of enemies that appear during the game. Enemies that battle the player in response to map movement or event commands are specified based on this data. Even if you will have a single enemy battle the player, you must prepare troop data for it. Battle events (event processing during battles) are also set up per enemy troop.

Available Settings

Name

The name of the enemy troop you are creating. This setting is only used by the editor and has no impact on game play. Clicking the Autoname button automatically generates a name based on the enemies you added to the troop.

Change Battle Background

Changes the battle background to display in disposition view. On the left side of the dialog box that appears, specify the parallax background image, and on the right side, specify the ground image. This setting is only used by the editor and has no impact on game play. It will also be used when editing other data.

Battle Test

Runs a test battle with the troop. Use tabs 1 through 4 on the dialog box that appears to specify the actors to include in the battle, equipment, and levels. Parameters based on these settings will be displayed in Status. Clicking OK opens a window and starts the battle test. Close the window when you want to end the battle test.

Disposition View

Enemies that have been added to the troop. You can add up to eight enemies (including enemies of the same type) to a troop.

You can change the position of enemies in disposition view by dragging them. Normally, you can drag them in eight-pixel increments, but hold down the Alt key if you want to drag them in two-pixel increments. Right-clicking and then selecting Appear Halfway allows you to set an enemy that does not appear until the Enemy Appear command is executed in a battle event.

Use the following buttons to edit the settings you have made.

Add

Adds to disposition view the enemy selected by clicking an entry in the enemy list on the right side of the dialog box. You can also add an enemy by double-clicking an entry in the enemy list. The order in which you add enemies will also be reflected in the order of the selection list for enemies that appear in battle.

Remove

Deletes the enemy selected by clicking it on disposition view.

Clear

Removes all enemies from disposition view.

Arrange

Arranges enemies in disposition view in line starting from the left in the order they were added.

Battle Event Settings

Battle Event is for setting conditions and execution data for events to execute during battles against the troop. As with map events, battle events can be set up on case-by-case basis, using event pages and spawning conditions.

Event Page Controls

Use New Event Page, Copy Event Page, Paste Event Page, Delete Event Page, and Clear Event Page on the left side of the dialog box to control your event pages. These commands function in a similar manner to those for map events.

Condition

The conditions for executing event page processing. In the dialog box that appears when you click the ... button, activate up to five conditions and set the values for determining when they are satisfied. Unlike with map events, event pages for battle events cannot execute unless at least one condition has been specified. And when more than one event page satisfies a condition, the page with the lowest number will execute.

At End of Turn

Set the end of a turn as a condition.

Turn No.

Set the specified number of turns elapsed from the start of battle as a condition. Specify the number of turns since the start of battle in the left field and the number of turn cycles in the right field.

Enemy

Set enemy HP at or below a specified value as a condition. Specify the target enemy and the HP value (percentage of max HP).

Actor

Set actor HP at or below a specified value as a condition. Specify the target actor and the HP value (percentage of max HP).

Switch

Set the specified switch being on as a condition.

Span

Specifies when an event page subject to execution is allowed to run.

Battle

Only executes the page once conditions have been satisfied after a battle starts. After executing once, the page will not execute again.

Turn

Executes the page once per turn if conditions are satisfied.

Moment

Repeats page execution as long as conditions continue to be met. Note that the battle may not proceed unless you add some sort of control process, such as a switch.

Contents

Use event commands to set the processing to run when Conditions and Span are satisfied. The editing method is the same as with Contents for map events.


State Settings

Data Role

States are an abnormal status that impacts a character's health and actions and include things like poison and confusion. You must set the specific effects for when each state is applied. Note that not all states are negative, such as HP being reduced by poison. You can also define positive states, such as ATK being increased by a character getting excited.

State number 001 (knockout) is a special state that is automatically applied when an actor or enemy's HP falls to zero. The game is over if this state is applied to all party members.

Available Settings

Name

The name of the state. States are displayed using icons, so the name you set here will not actually be used in-game.

Icon

The image to display with the actor's name while in the state. Double-clicking it displays the Icon dialog box where you can specify an image. Specify an image that makes the state easily identifiable.

Restriction

A restriction on actions by the character in this state. Specify using the following six items. When multiple restrictions are applied, the one at the bottom of the list takes precedence.

None

There are no restrictions on actions.

Attack Enemy

The character will always attack an enemy.

Attack Enemy or Ally

The character will always attack either an enemy or an ally.

Attack Ally

The character will always attack an ally.

Unable to Act

The character will not be able to take any sort of action.

Priority

The priority (0 to 100) for displaying state icons. When multiple states have been applied, the state icon that has a higher value for this setting will be displayed. When state icons have the same priority, the one with the most recent ID is given preference.

Removal Conditions

Conditions for removing the state. Specify using the following items. When multiple conditions are set, removal is determined by each of those standards.

Remove at Battle End

The state is removed once the battle is over.

Remove by Restriction

The state is removed if a state with a different action restriction is applied.

Auto-Removal Timing/Duration in Turns

The state is removed after the turn elapses. At End of Action removes the state once the actor's action is over, while At End of Turn removes it once the turn has ended and the game returns to action selection. In Duration in Turns, specify the minimum and maximum number of turns (0 to 9999) until the state is removed after it is first applied.

Remove by Damage

The state is removed at the specified probability (0 to 100%) when the target suffers some sort of damage.

Remove by Walking

The state is removed after moving the specified number of tiles (0 to 9999) on the map.

Messages

These are messages displayed when the state is applied/removed during battle. For each of the four situations provided (Message When Actor Enters State, Message When Enemy Enters State, Message When State Remains, and Message at State Removal) specify a message to display after the target's name.

Features

A list of features to give the target to which the state has been applied. See Setting Features for more information.


Animation Settings

Data Role

Animation data is for displaying attacks on enemy characters on the battle screen and for visual representations that can be played back on the map screen and other places. They are created by placing image patterns (cells) in frames.

Available Settings

Name

The name of the animation. This setting is only used by the editor and has no impact on game play.

Graphic

The graphic files (maximum of two) used in creating the animation. Click the ... button in the boxes to display the Animation Graphics dialog box in which you can specify the file you want to use. When specifying a file, you can use the Hue slider to adjust the graphic's hue. When you specify a file, a pattern image will be displayed in the Pattern Palette.

Position

Specify the animation's display position. Head, Center, and Feet specify the top, middle, and bottom of the target character, respectively. Specifying Screen displays the animation over the entire screen. Note that when the scope of a skill or item that uses this animation is all targets, animations set to Head, Center, or Feet are displayed for each character.

Max #

Sets the number of frames (1 to 200) for the entire animation. Click the ... button and specify a value in the dialog box that appears. The number of frames specified here will be displayed in the frame list. Reducing the number of frames will delete frames beyond the specified number.

SE and Flash Timing

Set the sound effects and screen flash colors used in the specified frame during the animation. In the SE and Flash Timing dialog box that appears when you double-click a row in the list (or a blank row to create a new setting), specify the items shown below.

Right-clicking a list item displays a shortcut menu containing the Edit, Cut, Copy and Delete commands.

Frame

Specify the frame number subject to processing.

SE

Specify the sound effect to play back.

Flash

Specifies the type of flash processing. Specify Target to make a character flash or Screen to make the entire screen flash. Specify the flash color using the Red, Green, and Blue controls and the flash transparency using the Strength control (1 to 255 for all four controls). For Duration, specify the playback time in frames (1 to 200). Hide Target temporarily hides the target character when you want to display a full-body character animation or other such situations.

Frame List

A list of frames within the animation. The frame number selected by clicking will be edited and is displayed in frame view on the right. Use the Back and Next buttons at the top and bottom of the list to move to the frame you want to edit. And in the shortcut menu that appears when you right-click a frame number, you can select the commands Copy, Paste, Clear, Insert, and Delete per frame.

Frame View

Shows a preview of the frame. You can set the display content by placing a pattern palette image here as a cell. The green square represents the game window's display area.

See "Frame View Controls" below for more information on editing frames.

Change Target

Changes the graphic for the enemy character currently displayed in frame view. This setting is only used by the editor and has no impact on game play.

Paste Last

Pastes the cell placed on the previous frame onto the frame currently being edited.

Copy Frames

Copies the specified range of frames all at once. Specify the starting and ending number of the target frames and to the right of to, specify the frame number of the copy destination.

Clear Frames

Clears the specified range of frames all at once. Specify the starting and ending number of the target frames.

Tweening

Automatically tweens the frames between two frames for smoother animation. In Frames and Cells, specify the range of frames and cells subject to tweening, in Tweening Items, select the items to tween, and then click the OK button. For example, if you were to tween frames 1 to 10 targeting the position with frame 1 at the left end and frame 10 at the right end, cells that shift position from left to right would be automatically set in frames 2 through 9.

Cell Batch

Changes the cells in the specified range of frames to the same settings. In Frames and Cells, specify the range of frames and cells to set, select the items to set, and then specify values for each setting.

Entire Slide

Moves the cells in the specified range of frames all at once. In Frames, specify the starting and ending number of the target frames, and in X and Y of Movement Amount, specify the movement distance in each direction in pixels. To move to the left or upwards, specify a negative value in X and Y.

Play

Clicking this button plays the animation you are creating.

Pattern Palette

Displays the pattern image in the file specified by Graphic. Clicking a pattern selects it to be placed in the frame. Patterns are numbered starting from 1 on the upper left of the palette, and numbers (pattern numbers) are assigned in order from left to right.

Frame View Controls

Frame View Controls
Cell Placement

Use the Pattern Palette to select the image to place in the frame and then click on an empty part of the frame editing area. A cell with the image will be placed. You can place up to sixteen cells in one frame.

Display

Borders and numbers are displayed for each cell. A white border means the cell is selected, red means it has been placed, and blue means it was placed in the previous frame. The numbers indicate cell priority, with the higher number being closer to the front.

Selecting a Cell to Edit

Clicking a cell turns its border white, indicating that it has been selected to be edited. Lower-number cells that have other cells over them can be selected by holding down the Ctrl key while clicking.

Cell Movement

Move cells by dragging them. Normally, you can drag them in eight-pixel increments, but hold down the Alt key if you want to drag them in two-pixel increments. The position of the currently selected cell is displayed as coordinates at the bottom right of the frame editing area. The x and y coordinates for the center of the screen are (0, 0), and the x axis ranges between -272 to 272, while the y axis ranges between -208 and 208.

Shortcut Menu Operations

Right-clicking a cell displays the shortcut menu in which you can execute the commands described below. The Cell Settings dialog box can be opened by double-clicking a cell.

Shortcut Menu Commands
Set

Opens the Cell Settings dialog box. (details below)

Undo

Undoes the previous operation and reverts to the previous state. You can undo up to eight previous operations.

Redo

Reverses the result of the Undo command.

Cut

Copies the selected cell to the clipboard and deletes the original selection.

Copy

Copies the selected cell to the clipboard.

Paste

Places the cell that is currently in the clipboard.

Delete

Deletes the currently selected cell.

Up/Down

Changes the display priority (forward/back) of the cell.

Cell Settings Dialog Box
Pattern

The number of the pattern. Changing a number changes the pattern to the corresponding number.

X/Y

The cell's display position. Specify -272 to 272 for the x axis and -208 to 208 for the y axis.

Zoom

The cell's zoom rate. Specify a zoom rate that is between 20% and 800% of the original image size.

Angle

The cell's angle of rotation (1 to 360 degrees). The cell will be displayed rotated clockwise by the angle you specify. Note that over use of this command will cause game processing to slow down.

Flip

Setting Yes will flip the cell pattern horizontally.

Opacity

The cell's opacity (0 to 255). The lower the value, the greater the transparency. Setting "0" renders the cell invisible.

Blending

Specifies how to blend colors when one cell overlaps another. Normal is the standard method, Additive results in a lighter color, and Subtractive results in a darker color.


Tileset Settings

Data Role

Tileset data defines the tiles used to design a map. You create tilesets by setting how tiles behave in the game, such as whether characters can pass over them.

You can also create tilesets that use images that you yourself have created for use on maps and then use those tilesets by assigning them to map data.

Note that whether a vehicle (such as a boat or ship) can pass over a tile is dependent on its position on the tileset. See Resource Standards for more information.
Airships can pass over all tiles. However, they can only land on locations where characters can walk.

Available Settings

Name

The name of the tileset. This setting is only used by the editor and has no impact on game play.

Mode

The purpose of the tileset. This mainly impacts the special specifications of lower-layer tiles and the handling of battle backgrounds.
As a general rule, select Field Type for tilesets representing world maps, including oceans and landmasses, and Area Type for all others.

To use resources created for RPG Maker VX, select VX-Compatible Type.

Graphic

Set the image files to use for the tiles. Click the ... button in the boxes for each set type (A through E) to display the Tileset Graphics dialog box in which you can specify the files you want to use. When you specify a file, its content will be displayed in the tile list to the right.

Tile List

Displays images for the tiles set by Graphics. Switch between tilesets by clicking tabs A through E. The A tab displays tiles for the files specified in A1 through A5 in order.

Each tile is displayed with a superimposed mark that shows the editing mode that is currently set for it. You can change the setting by clicking it.

Passage

Switches to the editing mode for specifying whether the tile is passable. A circle displayed on the tile list means the tile can be passed through, while an x means it cannot. A star also means a passable tile, but the character will be hidden behind a structure (can only be set for tiles in tabs other than A).

Passage (4 dir)

Switches to the editing mode for specifying the direction through which the tile is passable. This setting is supplementary to Passage and is used to make tiles over which movement is possible in specific directions. For example, you could represent a change in elevation by disabling movement past the edge of a cliff tile.

Up, down, left, and right arrows indicating the direction of allowable movement are displayed on the tile list. Movement in a specific direction is only allowed if its corresponding arrow is displayed. Note that if you change the Passage setting, this setting will automatically change.

Ladder

Switches to the editing mode for ladder settings. Sets a character as looking upward while on this tile. This makes it look as if the character is going up/down a ladder, rope, or other such object.

Turn the setting on/off by clicking the mark on the tile list. Tiles with this setting will have a ladder mark on them.

Bush

Switches to the editing mode for bush settings. Applying this setting makes the bottom 8 pixels of a character on the tile invisible, which can make the character's feet look as if they are hidden in a thicket.

However, when set for tiles in A1 through A4, certain images may not turn translucent on some tiles. See Resource Standards for more information.

Turn the setting on/off by clicking the mark on the tile list. Tiles with this setting will have a mark that looks like two wavy lines on them.

Counter

Switches to the editing mode for counter settings. Applying this setting enables events to trigger even if the character is not next to the event tile. Use in situations such as the character talking to someone behind a counter.

Note that when this is set for an A2 tile, the bottom will be shifted 8 pixels downward.

Turn the setting on/off by clicking the mark on the tile list. Tiles with this setting will have a rhombus mark on them.

Damage Floor

Switches to the editing mode for damage floors. Applying this setting creates a tile that deals damage when passed over. Use it to define a poisonous swamp, a floor that shoots out spikes, or other such dangers.

Turn the setting on/off by clicking the mark on the tile list. Tiles with this setting will have a mark that looks like two triangles on them.

Terrain Tag

Switches to the editing mode for terrain tags. Terrain tags assign a numeric value between 0 and 7 to tiles. The value can be obtained by using the Get Location Info event command and used to trigger events based on it.

Change setting values by clicking/right-clicking the numbers on the title list. When there are terrain tags where multiple tiles overlap, the value of upper-layer titles with terrain tags set to values other than zero are prioritized when they are obtained by event commands.


Common Event Settings

Data Role

Common events are events that can be run at any time during the game. Use then to define general processes within the game as a whole, including the monitoring of play status and performing a process when an item or skill is used. The common events you create can be run using the Common Event event command or by flipping a specific switch on.

Available Settings

Name

The name of the common event. This setting is only used by the editor and has no impact on game play.

Trigger

Specify one of the following triggers for starting the process defined in Contents. Note that Autorun and Parallel are only valid while displaying the map screen.

None

Starts running the defined common event when explicitly called, such as with the Common Event event command.

Autorun

Starts running the defined common event when a switch specified by Condition Switch flips on.

Parallel

Starts running the defined common event when a switch specified by Condition Switch flips on, and will repeatedly run it while the switch remains on.

Condition Switch

If the trigger is Autorun or Parallel, specify the switch that will be the signal for starting the common event. If there are multiple common events for which the same switch is specified, the one with the most recent ID number (on the list) will be run.

Contents

Set the event commands to be run by this common event. The editing method is the same as that for Contents defined for map events.

Notes on Using Autorun and Parallel Triggers

When the Autorun or Parallel trigger is specified, the common event defined in Contents will repeatedly run while the switch specified in Condition Switch is on.

To stop this repeated running, the switch must be flipped off. If this is not done, the game may become unresponsive to user input.

If you find that the game becomes unresponsive during play testing, click the close box (×) at the top right corner of the game window or press Alt+F4 to abort the game.


System Settings

Data Role

System data is a collection of important data, including default settings for your game. You can specify settings such as the organization and position of party members at the start of the game and the music to play in various situations.

Available Settings

Initial Party

The party members at the start of the game.

You can add as many actors as you want to the party, but only the front four can fight in battles.

To add/change an actor, double-click a list entry (or a blank space to add a new actor), and then specify an actor. To remove an actor, right-click the one you want to remove and then select Remove in the shortcut menu that appears.

Game Title

The title of your game. The name you entered in the Title box when you created the project will be set automatically here. The game title appears on the game's title screen and on the game window's title bar.

Vehicle Graphics

Images for the vehicles (boats, ships, and airships) that appear on maps. Specify the images you want to use in the dialog boxes that open when you double-click each field. If you do not want to display a graphic, specify None.

Currency Unit

The unit of currency used in the game. It will be used to display the party's money on the menu screen.

Window Color

The background color of windows used during the game. In the dialog boxes that open when you double-click the field, specify color values (-255 to 255) for R, G, and B.

Options

Allows you to set special processing and rules for game operations.

Initialize MIDI at Startup

Selecting this option initializes DirectMusic at game startup. It may take some time to initialize when using Windows Vista or Windows 7.

Start Transparent

Selecting this option starts the game with the transparency flag set to on (invisible) for the player character graphic. This can be switched off by the Change Transparency event command.

Show Player Followers

Selecting this option starts the game displaying walking graphics for party members behind the first actor while moving on the map. If there are five or more party members, only walking graphics for the first four will be displayed.

K.O. by Slip Damage

Selecting this option allows HP to be reduced to 0 by status ailment damage, such as poison. If it is not selected, damage stops at 1 HP.

K.O. by Floor Damage

Selecting this option allows HP to be reduced to 0 by damage caused by map terrain. If it is not selected, damage stops at 1 HP.

Display TP in Battle

Selecting this option displays the TP of each party member in the status window during battles.

Reserve Members' EXP

Selecting this option allows party members that did not participate in a battle to get a share of the resulting EXP when a battle is won.

Music

The music to play while playing the game Specify the BGM/ME files to play for each scene. The settings for the various scenes are described below. Note that the music that plays while the player is moving on a map is set by map data.

Title Screen | BGM played on the title screen
Battle | BGM played during battles
Battle End | ME played at the end of battle (when player wins)
Game Over | ME played on the Game Over screen
Boat | BGM played while onboard a boat
Ship | BGM played while onboard a ship
Airship | BGM played while onboard an airship
Sound Effects

The sound effects to play when the player controls characters, an action starts in battle, and other in-game situations. Specify the SE file to play in the box that matches the type of sound effect you want to set. The settings for the various situations are described below.

Cursor | SE to play when moving the cursor
OK | SE to play when confirming a command
Cancel | SE to play when canceling a command, such as on a menu screen
Buzzer | SE to play when selecting an invalid command, such as on a menu screen
Equip | SE to play when changing equipment on a menu screen
Save | SE to play when saving a game
Load | SE to play when loading a game
Battle Start | SE to play when encountering an enemy
Escape | SE to play when trying to flee from battle
Enemy Attack | SE to play when an enemy attacks on the battle screen
Enemy Damage | SE to play when an enemy takes damage on the battle screen
Enemy Collapse | SE to play when an enemy is defeated on the battle screen
Boss Collapse 1 | SE to play upon the defeat of an enemy whose Collapse Effect under Features is Boss.
Boss Collapse 2 | SE to play while the collapse effect is displayed for the defeat of an enemy whose Collapse Effect under Features is Boss.
Actor Damage | SE to play when an ally takes damage.
Actor Collapse | SE to play when an actor is knocked out (K.O. state) on the battle screen.
Recovery | SE to play when a recovery message is displayed on the battle screen.
Miss | SE to play when a physical attack misses, resulting in no damage being dealt
Evasion | SE to play when a physical attack is dodged
Magic Evasion | SE to play when a magic attack is evaded
Reflection | SE to play when a magic attack is reflected
Shop | SE to play when buying or selling items during shop events
Use Item | SE played when using an item on a menu screen
Use Skill | SE played when using a skill on a menu screen
Starting Positions

The positions of the player and vehicle (boat, ship, or airship) at the start of the game. Specify by clicking ... in each box to open the dialog box where you set the map name in the box to the left and a position in the box to the right.

An icon with the letter S on it will be displayed on the map at the specified starting positions. This icon can be moved by dragging or deleted with the Delete key, just as with map events.

However, a game cannot be started without the player's starting position set (icon deleted).

Title Screen

The image displayed on the game screen immediately after the game starts. Specify the image you want to use in the dialog box that appears when you click ... in the setting box. Selecting the Draw Game Title option displays the title you specified with the Game Title setting on the upper part of the title screen. Do not select this option if the title of your game is incorporated into the title screen image you are using.


Term Settings

Data Role

Term data is collection of data defining the names of game commands, parameters, and so on. You can ramp up the originality of your game by changing the standard terms to fit the world you are creating.

Enter terms within the space provided in each box. Terms that are too long may not fully display within the game.

Available Settings

Elements

A list of element names. To change a name, select it by clicking it on the list and then enter a name in the box below it. To change the number of items on the list, click Change Maximum and then specify a new maximum number.

These names will be used when making selections on the editor. The specific content of elements is defined by the data for skills, weapons, and so on.

Skill Types

A list of names for skill types specified by the Skill Type setting in the skill database. Changing names and other operations are the same as with the Elements setting.

Weapon Types

A list of names for weapon types specified by the Weapon Type setting in the weapon database. Changing names and other operations are the same as with the Elements setting.

Armor Types

A list of names for armor types specified by the Armor Type setting in the armor database. Changing names and other operations are the same as with the Elements setting.

Basic Status

The names of the level, HP, MP, and TP parameters. Specify the terms you want to apply to the existing names. For the (Short) settings, specify an abbreviated form of the name to be displayed in the status window of battle screens and other places where space is limited.

Parameters

The names of parameters. Specify the terms you want to apply to the existing names.

Equipment Types

The names of the slots for equipment. Specify the terms you want to apply to the existing names.

Commands

The names of commands and choices displayed on the game's menu screens and so on. Specify the terms you want to apply to the existing names.


Setting Features

Overview

The Features setting for actor, class, weapon, armor, enemy, and state data defines the unique characteristics and functions of each type of data.

The following 24 types of features can be applied. Complex features can be defined by combining the data created here.

Class, weapon, armor, and state features are applied as character features while their data is applied to the character.

Be careful when setting features that permanently restrict actions. For example, a weapon set with a feature that locks the equipping of weapons will prevent an actor from unequipping it once it has been equipped.

Setting Method

To set a feature, double-click a blank area within the field. In the Features dialog box that appears, select the type of feature you want to set and then specify its settings.

The characteristics you set for a feature will be displayed in the features list. You can edit the settings you made by clicking a feature in the list. And in the shortcut menu that appears when you right-click a feature, you can perform such operations as copying and deleting settings.

Available Settings

Resistance Tab
Element Rate

Changes damage taken from elemental attacks. Specify the target element and the rate of variability (0 to 1000%). Specifying a rate over 100% results in damage greater than the standard amount, indicating a weakness against the specified element.

Debuff Rate

Changes the probability at which the use of a skill or item for which the Debuff effect has been set will succeed in debuffing a parameter. Specify the target parameter and the rate of variability (0 to 1000%). A 100% setting means no variability.

State Rate

Changes the probability at which the use of a skill or item for which the Add State effect has been set will succeed in adding a state. Specify the target state and the rate of variability (0 to 1000%). A 100% setting means no variability.

State Resist

Negates the specified state. Specifying K.O. results in characters failing to be knocked out even when their HP falls to 0.

Parameters Tab
Parameter

Rate of increase/decrease for parameters such as max HP and ATK. Specify the target parameter and the rate of variability (0 to 1000%). A 100% setting means no variability.

Ex-Parameter

The rate of increase/decrease for additional parameters such as max accuracy and evasion. Specify the target parameter and the percentage to add on (-100 to 100%). The default value is 0%.

Sp-Parameter

The rate of increase/decrease for special parameters such as probability of being targeted for attack and defense effectiveness. Specify the target parameter and the rate of variability (0 to 1000%). The default value is 100%.

ATK Tab
Atk Element

Applies an element for normal attacks.

Atk State

Applies a state change effect for normal attacks. Specify the target effect and the success variability (0 to 1000%). A 100% setting means no variability.

Atk Speed

Increases/decreases agility when the player selects a normal attack in battle. Specify a value between -999 and 999.

Atk Times+

Increases the number of times a normal attack damages a target. The standard value is 1. Specify the number of times you want to increase it.

Skills Tab
Add Skill Type

Allows the specified skill type to be selected as a command.

Disable Skill Type

Prevents the specified skill type from being selected.

Add Skill

Sets the specified skills as being available for use.

Disable Skill

Disables the use of the specified skill.

Equip Tab
Equip Weapon

Enables the equipping of the specified type of weapon.

Equip Armor

Enables the equipping of the specified type of armor.

Lock Equip

Prevents the changing of equipment for the specified equipment slot. Used for instances where you do not want the player changing the equipment of an actor that has been temporarily added to the party.

Seal Equip

Prevents the equipping of equipment for the specified equipment slot. For example, preventing the use of shields for a given weapon makes it a two-handed weapon, and preventing the wearing of a headgear for a given piece of armor results in full body armor.

Slot Type

Can only be set to Dual Wield. This enables the equipping of two weapons in exchange for not being able to equip a shield.

Other Tab
Action Times+

Increases by one the number of times actions can be taken in battle by the specified probability. When you apply multiple instances of this setting, the game decides whether to increase the number of times actions can be taken individually based on the specified probabilities. For example, entering 50% twice results in the probability of the actions increasing by two and the probability of them not even increasing by one to both be 25% (50% × 50%).

Special Flag

Applies a feature relating to battle actions.

Auto Battle | Character acts independently without accepting player commands.
Guard | Reduces damage taken at a set rate.
Substitute | Character suffers attack in place of allies with less HP.
Preserve TP | Accumulated TP are retained for the next battle.Without Preserve TP, TP is reset at each combat and TP of each character is set at random when beginning the next battle.
Collapse Effect

Valid only for enemies. Changes the effect for when they are knocked out to the one that you specify.

Party Ability

Applies a feature relating to party actions. It is enabled as a characteristic for the entire party if at least one of the party members has it.

Halve Encounters | Halves the frequency of encounters while moving on the map.
Disable Encounters | Eliminates the chance of encounters while moving on the map.
Disable Surprise | Eliminates the chance of surprises (situations in which only the enemy troop is able to act on the first turn) when battles occur.
Increase Preemptive Strike Rate | Increases the chance of a preemptive strike (only the party is able to act on the first turn) when battles occur.
Double Money Earned | Doubles the amount of gold earned when the party wins a battle.
Double Item Acquisition Rate | Doubles the chance of getting items from enemies when the party wins a battle (only when items have been set for the defeated enemy).


Setting Effects

Overview

The Effects setting for skill and item data defines the effects to apply to the target character when an actor/enemy uses the skill/item in question.

The following thirteen types of effects can be applied. Skills/items with complex effects can be defined by setting multiple effects.

Setting Method

To set an effect, double-click a blank area within the field. In the Effects dialog box that appears, select the type of effect to set and then specify its target and the magnitude of the effect.

The effect you set will be displayed in the Effects list. You can edit the settings you made by clicking an effect in the list. And in the shortcut menu that appears when you right-click an effect, you can perform such operations as copying and deleting settings.

Available Settings

Recovery Tab
Recover HP

Restores HP (adds HP to the current value). Specify the recovery value as sum of the percentage (0 to 100%) of the target character's max HP and a set value (1 to 9999). To specify either one as the standard value, set the value of the other to "0". When setting this effect for items, the recovery multiplier of the user's Medicine Lore sp-parameter is applied.

Recover MP

Restores MP (adds MP to the current value). Specify the recovery value as sum of the percentage (0 to 100%) of the target character's max MP and a set value (1 to 9999). To specify either one as the standard value, set the value of the other to "0".

Recover TP

Restores TP (adds TP to the current value). Specify the recovery value as a percentage (0 to 100%) of the target character's max TP.

State Tab
Add State

Adds a state. Specify the target state and the rate of success (0 to 1000%). Setting a value higher than 100% results in a success rate higher than the inherent effectiveness.

Remove State

Removes a state. Specify the target state and the rate of success (0 to 100%).

Parameters Tab
Add Buff

Raises the fluctuation level of a parameter in combat by one. Specify the target parameter and number of turns (1 to 1000) the effect will last. The fluctuation level varies between -2 and +2, and the change in the value of the original parameter is 25% per level.

Add Debuff

Lowers the fluctuation level of a parameter in combat by one. Specify the target parameter and number of turns (1 to 1000) the effect will last. The fluctuation level varies between -2 and +2, and the change in the value of the original parameter is 25% per level.

Remove Buff

Returns a parameter to its original fluctuation level if it has been buffed.

Remove Debuff

Returns a parameter to its original fluctuation level if it has been debuffed.

Other Tab
Special Effect

Escape is the only setting available. Allows the target character to escape from battles. No EXP will be earned by actors to which this effect is applied.

Raise Parameter

Permanently raises a parameter. Specify the target parameter and the value to add (1 to 1000).

Learn Skill

Allows a character to learn the specified skill. This effect is not applied to enemies.

Common Event

Runs the specified common event. This effect can only be set once per data type.


Editing Events

What Are Events?

In RPGs, events move the game forward by various means, such as talking to a specific person, getting an item from a treasure chest or battling a boss enemy.

Events carry out some sort of processing within the game. For example, an event can be defined by assigning a graphic to an event character and making text appear on screen when the player talks to them.

By making events trigger according to the player's circumstances and behavior, you can build an entertaining game where many different things happen.

Types of Events

There are three types of events as described below. Events relating to the game's story and progress are map events.

Map Events

These are events that occur on the map screen. Use them to represent events such as dialogue scenes between characters and getting items from treasure chests. You can also define events without graphics for the game system or to advance the game story, including moving the player from one location to another or playing a cut scene.

To create/edit an event, click the Event button on the main window's tool bar (or select Event on the Mode menu), and then switch to the event editing mode you want.

Battle Events

These are events that occur on the battle screen. Use them to represent events such as an enemy that transforms when its HP falls below a set value. Edit/create such events on the database's Troops tab.

Common Events

These are commonly executed events. Use them to call map events and battle events or to set up a process to run when a special item is used. Edit/create such events on the database's Common Events tab.


Map Event System

Flow of Map Event Processing

Event Representation

Map events are created by defining where the event occurs (location), under what circumstances it is possible (condition), how it is started (trigger), and what happens when it starts (contents).

NPCs and treasure chests where items can be obtained are represented by assigning graphics to map events for which you have defined what will happen. You can also create events where no graphics are set, such as those where the player goes outside a building or moves between maps, or even cut scenes that play automatically.

When creating an event, you must first decide where it occurs (location) on map view in the main window. Next, you set under what circumstances the event is possible (condition) and the rest of the items that define it.

Event Pages for Content Variation

Map events can change the content of events according to the status of game play.

Event pages make this possible by enabling variations in event content. Each event can have up to 99 event pages, with each page having a different graphic, trigger, and/or content to execute. In short, one map event can have up to 99 different variants.

Controlling Event Pages Using Conditions

The Conditions setting is what determines which variation of an event appears. A variety of conditions can be set, including switches, variables (described later), and whether a specific item is possessed.

Map events occur during the game based on the content of event pages that satisfy these conditions. When there are multiple event pages satisfying Conditions settings, the event set on the event pages with the highest number will occur. Conversely, when there are no event pages satisfying Conditions settings, no events will occur on the map.

Determining Game Status

Using Switches to Determine Game Status

Switches and variables are the primary conditions on event pages for determining game status.

Switches are for keeping track of whether a value is on or off. Use them to determine game status and progress, such as whether the quest was accepted from the king or whether the boss was defeated.

At the start of the game, all switches are set to off. The execution of events that change game status will change the value of certain switches according to the Contents setting (use the Control Switches event command).

By using the same switch in the Condition setting of other event pages, you can switch the content of map events all at once when the value of all the switches is on. Build the game story by changing overall game status through changes in these events.

Using Variables to Keep Track of Numeric Values

Unlike switches, variables are used to keep track of numeric values (integers). Variables are set to 0 at the start of the game, and are subsequently assigned other values according to game status or used in calculations that include other values (use the Control Variables event command).

Use these variables to enable detailed control of map event conditions and results, such as changing what happens depending on the player's HP, money, or other values.

Managing Switches and Variables

You can use up to 5,000 switches and 5,000 variables in a single game. The number of switches/variables used and the situations they are used to determine are completely up to the game creator. Make sure to name them according to usage so as to prevent the relationship between them from getting confused. You can set the name for switches and variables in the Name field of the selection dialog box.

Using Self Switches in Self-Contained Events

You can also use self switches in map events. These switches can only be used in individual map events. Up to four self switches (A through D) can be used per event.

Self switches are used to determine the status of self-contained events by their own processing alone. For example, a treasure chest from which items are obtainable can be managed using a self switch that keeps track of whether the chest has been opened. By setting two event pages (one for before the chest is opened and another for after), you can create an event where the items in the chest are obtainable only the first time it is searched.


Creating and Controlling Map Events

Creating and Controlling Map Events

Switching Between Editing Modes

To create/edit a map event, click the Event button on the main window's tool bar (or select Event on the Mode menu), and then switch to the event editing mode you want.

Creating a New Map Event

To create a new map event, double-click where you want to place it on map view. In the Create Event dialog box that appears, edit event settings and then click the OK button. See Setting Map Events for more information on available settings.

Note that placing too many events on a single map may slow down the game. We recommend placing no more than 100 events on a single map.

Editing/Moving Map Events

Placing a map event displays an icon at the location (the graphic set on the first event page is applied to the icon). Double-clicking this icon displays the Edit Event dialog box where you can edit the settings of events that have already been created. You can also move event positions by dragging and dropping event icons.

Shortcut Menu Operations

Right-clicking on map view in event editing mode displays a shortcut menu where you can perform a variety of operations on events you have placed, including copying and deleting. The functions of each command are described below.

Edit Event (or Create Event if no event has been placed)

Opens the Edit Event dialog box.

Cut

Copies the right-clicked map event to the clipboard before deleting it.

Copy

Copies the right-clicked map event to the clipboard.

Paste

Places the map event that is in the clipboard at the position you right-clicked.

Delete

Deletes the right-clicked map event.

Easy Create

Allows the easy creation of four types of events (described later).

Set as Starting Position

Sets the starting position of the player and vehicles at the start of the game. The starting position is marked by an icon with the letter S on it.

Easy Create Command for Events

The Easy Create command on the shortcut menu allows you to easily create four types of events that are commonly used in RPGs, including moving the player's location and opening treasure chests. The content and settings of the events you can create using the dialog box that opens are described below.

As with other events, you can use commands to edit, copy, and perform other operations on events created using the Easy Create command.

Transfer Player

Creates a transparent event (no graphic) that moves the player to the specified location. Use it for entrances/exits, stairways, and other such locations. Specify the position and display direction of the character after moving to the location specified by Destination and Direction.

Door

Creates an event with a door graphic that moves the player to the specified location. Specify the graphic to display in Graphic and the post-move position in Destination.

Treasure Chest

Creates a treasure chest event in which items and so on can be obtained only the first time it is checked. Specify the graphic to display in Graphic and the obtainable objects (gold/items/weapons/armor) in Content.

Inn

Creates an event where the party can fully recover. Specify the graphic to display in Graphic and the price to stay at the inn in Price.


Setting Map Events

Common Settings and Event Page Controls

Setting Map Events
ID (on title bar)

A unique number assigned to each event. These numbers are set automatically in the order you create events on each map. Example uses include employing them to specify events in variables.

Name

The name of the event. This setting is only used by the editor and has no impact on game play. The default name "EV" followed by the event ID number will be entered automatically. Change as necessary to make the event content readily identifiable.

Event Page Numbers

The numbers of the event pages included in events are displayed on each tab. You can edit the settings on each tab by clicking the respective tab.

Event Page Control Buttons

The buttons along the top of the Create Event dialog box include those for creating and deleting event pages. The functions of each button are described below.

Create Event Page

Creates a new event page with a number one greater than the event page you are currently editing. The page number of all subsequent event pages will be increased by one.

Copy Event Page

Copies to the clipboard the content of the event page you are currently editing.

Paste Event Page

Event pages in the clipboard will be added (inserted) using the next event page number after the page currently being edited. The page number of all subsequent event pages will be increased by one.

Delete Event Page

Deletes the event page you are currently editing. Each time you delete an event page, the numbers of the following pages are sequentially decremented by one.

Clear Event Page

Clears all the settings for the event page you are currently editing (returns it to its initial state).

Available Settings

Map event settings
Conditions

The conditions under which the event will spawn based on the settings on the event page. Select the conditions you want to set to determine whether the event spawns. The available conditions are Switch, Variable, Self Switch, Item, and Actor.

Do not set any conditions if you want the event to spawn unconditionally. If you set multiple conditions, the event only spawns if all of them are satisfied.

If there are multiple event pages satisfying conditions, the event will spawn based on the event page with the highest number. The event will not spawn if none of the pages have their conditions satisfied.

Graphic

The graphic displayed when the event spawns on the map. In the Graphic dialog box that appears when you double-click the field, specify the graphic you want by first clicking a selection in the file list (left side) and then an image (right side).

If you do not specify a graphic, the event will be spawned on the map without one. To clear a previously set graphic, select None at the very top of the file list in the Graphic dialog box.

Autonomous Movement

Use the Type, Speed, and Freq settings to specify the movement method for map events. Speed defines the speed of movement, with higher values specifying faster speeds. Freq defines the movement cycle, with higher values specifying a faster frequency. Type allows you to specify one of the four following movement types:

Fixed

Do not move.

Random

Move around randomly.

Approach

Move toward the player's position.

Custom

Move along a specified route. Routes can be specified in the dialog box that appears when you click Move Route. See Setting Move Routes for more information.

Options

Display options for graphics. Set the options you want to apply as necessary.

Walking Animation

Displays an animation when moving. Use it to represent characters or animals that are moving.

Stepping Animation

Displays an animation when not moving. Use it for events where there is a wavy ocean surface or flames.

Direction Fix

Makes it impossible to change a graphic's direction when moving.

Through

Makes it possible to pass through a normally impassable terrain or event.

Priority

Specify one of the following choices for the positional relationship between the player and event. If the event and player can overlap, the display of the graphic that goes on top will be prioritized.

Under Normal Characters

The player and others will be able to walk over this event. However, if a tile is selected in the Graphic settings, passage will conform to that tile's setting.

Same as Normal Character

Positions the event at the same level as the player, preventing entry into the event's location.

Above Normal Characters

The player and others will be able to walk under this event.

Trigger

For events that spawn on maps, use one of the settings described below to specify when to start running the event commands entered in Contents.

Action Button

Starts when the player presses the confirm button while next to the event and facing it in a certain direction (or when overlapping events that allow overlapping).

Player Touch

Starts when the player touches the map event (or overlaps an event that allows overlapping). The event also starts if the player presses the confirm button while in this state.

Event Touch

Starts when an event with Autonomous Movement bumps up against the player (or overlaps, in the case of events that allow overlapping). The event also starts if the player presses the confirm button while in this state.

Autorun

Starts when the conditions have been satisfied and the event spawns on the map.

Parallel Process

Starts when the conditions have been satisfied and the event spawns on the map, and cyclically repeats the process defined in Contents.

Contents

A list of commands to run when the specified trigger is satisfied. See the next item, "Editing Command Contents," for more information.

Editing Command Contents

Command List

In the Contents box, edit the event commands you want to use to define the events to add to the game.

Event commands are processed in order, starting from the top of the list, and applied to game play. Rows in the list that have a diamond-shaped mark indicate event commands that have been added. Rows with a colon are those that display settings for event commands above, the position for branching processing, and so on.

Adding Event Commands

To add an event command to the list, double-click a row displaying a diamond-shaped mark. In the dialog box that appears, select the event command to use and then define the desired processing (excluding some settings). Double-clicking a row for which you have already added an event command inserts a new one at that position.

Shortcut Menu Operations

Event commands that have already been added are displayed with a diamond-shaped mark next to them. Right-clicking such rows displays a shortcut menu where you can select such commands as Copy and Delete. The functions of each command are described below.

Insert

Inserts a new event command at the selected row.

Edit

Edits the settings for the selected event command.

Cut

Copies the event command on the selected row to the clipboard and deletes it from the list.

Copy

Copies the event command on selected row to the clipboard.

Paste

Inserts the event command copied to the clipboard at the selected row.

Delete

Deletes the event command on the currently selected row.

Select All

Selects the entire list for editing.

Selecting Multiple Rows

Selecting any row on the list by clicking it and then holding down the Shift key while clicking another row selects all the event commands between them (those with the diamond-shaped mark). Right-clicking the selected rows (those displayed in blue) opens a shortcut menu in which you can select commands that affect the entire range selected. With branch processing, however, only event commands within the same branch can be selected in this manner.


Event Commands

The following event commands are available for use in the Contents field. You can portray an interesting and dynamic story within your game by using these commands in a skillful manner.

Tab 1
Messages | Party
Show Text | Change Gold
Show Choices | Change Items
Input Number | Change Weapons
Select Item | Change Armor
Show Scrolling Text | Change Party Member
Game Progress | Actors
Control Switches | Change HP
Control Variables | Change MP
Control Self Switch | Change State
Control Timer | Recover All
Flow Control | Change EXP
Conditional Branch | Change Level
Loop | Change Parameters
Break Loop | Change Skills
Exit Event Processing | Change Equipment
Call Common Event | Change Name
Label | Change Class
Jump to Label | Change Nickname
Comment |

Tab 2
Movement | Time Adjustment
Transfer Player | Wait
Set Vehicle Location | Pictures and Weather
Set Event Location | Show Picture
Scroll Map | Move Picture
Set Move Route | Rotate Picture
Get On/Off Vehicle | Tint Picture
Characters | Erase Picture
Change Transparency | Set Weather
Change Player Followers | Music and Sound Effects
Gather Followers | Play BGM
Show Animation | Fadeout BGM
Show Balloon Icon | Save BGM
Erase Event | Replay BGM
Screen Effects | Play BGS
Fadeout Screen | Fadeout BGS
Fadein Screen | Play ME
Tint Screen | Play SE
Flash Screen | Stop SE
Shake Screen |

Tab 3
Scene Control | Maps
Battle Processing | Change Map Name Display
Shop Processing | Change Tileset
Name Input Processing | Change Battle Background
Open Menu Screen | Change Parallax Background
Open Save Screen | Get Location Info
Game Over | Battles
Return to Title Screen | Change Enemy HP
System Settings | Change Enemy MP
Change Battle BGM | Change Enemy State
Change Battle End ME | Enemy Recover All
Change Save Access | Enemy Appear
Change Menu Access | Enemy Transform
Change Encounter | Show Battle Animation
Change Formation Access | Force Action
Change Window Color | Abort Battle
Change Actor Graphic | Advanced
Change Vehicle Graphic | Script
Movies |
Play Movie |


Messages

Show Text

Description

Opens a message window for displaying text.

Available Settings
Text

Enter the text to display. Up to four lines at a time can be displayed in the message window. To display the second line onward, press the Enter key for each new line.

Face Graphic

Specify the face graphic to display on the left side of the message window. Specify an image in the Face Graphic dialog box that appears when you double-click the field.

Background

Select the format of the message window for displaying text.

Position

Specify either Bottom, Middle, or Top for the position at which the message window will appear.

Preview

Click this button to check the display of the message window.

Batch Entry

Selecting this option enables the entry of text beyond four lines. Text exceeding four lines is set in the Contents list divided into separate Show Text event commands for each block of four lines.

Notes

EPressing Ctrl+Enter while inputting text is the same as clicking the OK button.

EThe downward facing triangles at the top of the Text field are guides indicating the number of characters that fit in the message window. (The triangle on the left indicates the limit when displaying a face graphic.) Use the Preview button to see whether text will display as intended.

EThe Background and Position settings do not apply to message windows that appear in battle.

EEntering control characters in messages allows you to display the value of variables and the name of actors among other things. A description of available control characters is provided below. Make sure to enter control characters in single-byte characters.

\V[n] | The control characters are replaced by the value of variable n.
\N[n] | The control characters are replaced by the name of actor n.
\P[n] | The control characters are replaced by the name of party member n (numbered in formation order).
\G | The control characters are replaced by the currency unit.
\C[n] | Display text that follows it in color n. Color n conforms to the graphic content set for the window skin.
\I[n] | Draw icon n.
\{ Increase text size by one step.
\} Decrease text size by one step.
\$ Open the money window.
\. Pause text display for 1/4 second.
\| Pause text display for 1 second.
\! Wait for a button press during text display.
\> Instantly display the remaining text on the same line.
\< Clear the change in display format set by the \> control character.
\^ Do not wait for a button press after displaying text.
\\ These control characters are replaced by a backslash (\).

EThe number (n) that you specify with control characters can also be specified using a variable. For example, entering "\N[\V[1]]" displays the name of the actor with the same ID as the value of the first variable (\V[1]).

Show Choices

Description

Displays up to four choices, allowing the processing to branch according to the player's selection.

Available Settings
Choice 1 to 4

Enter text for the choices. Leave unused selections blank.

Cancel

Specify the handling for when the player cancels while choices are displayed. Choice 1 to Choice 4 are considered to be selections of the specified choice. Disallow disables the cancellation itself. Branch branches cancellation processing.

Notes

EConfirming the settings you made will create branches in Contents corresponding to the choices (including cancel). Set the commands to run after selecting choices in these branches.

Input Number

Description

Displays a window for entering a value and then assigns the value the player entered to a variable.

Available Settings
Variable for Number

Specify the variable to which to assign the number the player entered.

Digits

Specify the number of digits (1 to 8) for the value to be entered.

Notes

EWhen value input processing starts, the value assigned to the specified variable will be displayed.

Select Item

Description

Displays a selection screen for items categorized as key items. The ID of the item the player selects is assigned to a variable.

Available Settings
Variable for Item ID

Specify the variable to which to assign the number of the item (item ID) selected by the player.

Show Scrolling Text

Show Scrolling Text
Description

Displays text by scrolling it upward from the bottom of the screen. Pressing the confirm button enables fast scrolling.

Available Settings
Text

Enter the text to display.

Speed

Specify the scrolling speed (1 to 8). The larger the value, the faster the speed.

No Fast Forward

Disables the fast-scrolling feature by the confirm button.


Game Progress

Control Switches

Description

Changes the switch value (on/off).

Available Settings
Switch

Specify the switch to change. To operate a single switch, select Single and specify the target switch. To change the values of two or more switches with consecutive numbers, select Batch and then specify the switch number range.

Operation

Specify the value (on/off) to assign to the switch.

Control Variables

Description

Changes a value stored in a variable.

Available Settings
Variable

Specify the variable for which you want to change the value. To change a single variable, select Single and specify the target variable. To change the values of two or more variables with consecutive numbers, select Batch and then specify the variable number range.

Operation

Specify the calculation method for the value. (See "Notes" below.) The value of the variable specified by Variable will change to a value calculated based on the value of the pre-operation variable, the calculation method, and the value of the operand.

Operand

Specify the value to use in the calculation of Operation. (See "Notes" below.)

Notes

• The following table shows the calculation methods that you can specify in Operation.

Set | Assigns an operand value (no calculation).
Add | Assigns the value calculated by adding the value of the pre-operation variable to the operand.
Sub | Assigns the value calculated by subtracting the operand from the value of the pre-operation variable.
Mul | Assigns the value calculated by multiplying the value of the pre-operation variable by the operand.
Div | Assigns the value calculated by dividing the value of the pre-operation variable by the operand.
Mod | Assigns the remainder calculated by dividing the value of the pre-operation variable by the operand.

• The following table shows the values that you can specify in Operand.

Constant | Applies a fixed value. Specify the value in the field to the right.
Variable | Uses the value of a variable. Specify the variable to look up.
Random | Uses a random value. Specify the range for generating the random value between -99999999 and 99999999.
Game Data | Applies values relating to the current game play situation. In the dialog box that appears when you click ..., specify the information to look up. (See the table below.)
Script | Applies the values of evaluation results of the Ruby script that was entered.

• If you specified Game Data in Operand, select one of the following for the operand data.

Item | Applies the quantity of the specified item.
Weapon | Applies the quantity of the specified weapon.
Armor | Applies the quantity of the specified armor.
Actor | Applies the value of an actor's parameter (HP, MP, or other parameter). Specify the target actor and parameter. This setting is valid only during map movement.
Enemy | Applies the value of an enemy's parameter (HP, MP, or other parameter). Specify the target enemy and parameter. This setting is valid only during battles.
Character

Applies the display position of the player/map event or the value related to a state. Specify one of the following :

Map X/Map Y: Map coordinates of current location
Direction: Current direction being faced (Up: 8, Left: 4, Right: 6, Down: 2)
Screen X/Screen Y: The coordinates (pixels) of onscreen display position
Map ID: ID of map for current position
Party Members: Number of members in the party
Gold: Party's total gold
Steps: Number of steps player has taken since start of game
Play Time: Number of seconds elapsed since start of game
Timer: Time remaining (in seconds)
Save Count: Number of saves since start of game

Control Self Switch

Control Self Switch
Description

Controls the value of a self switch. Cannot be used in battle events.

Available Settings
Self Switch

Specify the target self switch (A through D).

Operation

Specify the value (on/off) to assign to the switch.

Notes

• Cannot be used in battle events.

Control Timer

Description

Starts/stops a timer that keeps track of a time limit (time remaining). When the timer starts, the remaining time will be automatically displayed at the top right part of the screen. The timer countdown will pause while a menu is displayed. To branch processing depending on a timer's remaining time, use an event command such as Conditional Branch.

Available Settings
Operation

To start keeping track of a time limit, specify Start, and to stop, specify Stop.

Time

If starting the timer, specify the time limit in minutes and seconds (00:00 to 99:59).


Flow Control

Conditional Branch

Description

Sets the event command for which processing will branch, so that special processing will run only when the specified conditions are met. Selecting Set handling when conditions do not apply allows branching even when the specified conditions are not met.

Available Settings

Specify conditions based on the settings described below.

Switch

Sets a switch value as a condition. Specify the target switch and a value (on/off).

Variable

Sets the result of a comparison with the variable as a condition. Specify the variable to use, comparison value, and comparison method. To use a variable for the comparison value, select Variable and specify the variable to look up.

Self Switch

Sets the value of the specified self switch as a condition. Specify the target switch and a decision value (on/off).

Timer

Sets the time remaining on the timer as a condition. Specify the time limit and the decision value (more than/less than).

Actor

Sets actor information as a condition. Specify the target actor, information to look up (In the Party, Name, Skill, Weapon, Armor, or State), and decision criteria (specific items).

Enemy

Sets the state of an enemy in battle as a condition. Specify the target enemy and decision criteria (Appeared/State). This is valid only in battle events.

Character

Sets the direction the player or map event is facing as a condition. Specify the target character and direction. This is valid only in map events.

Vehicle

Sets whether the player is on the specified vehicle (boat, ship, or airship) as a condition.

Gold

Sets the party's total gold as a condition. Specify the amount of gold and comparison method (greater than/less than).

Item

Sets the party's possession of the specified item as a condition.

Weapon

Sets the party's possession of the specified weapon as a condition. Selecting Include Equipments will also make the weapons the actor has equipped subject to the condition decision.

Armor

Sets the party's possession of the specified armor as a condition. Selecting Include Equipments will also make the armor the actor has equipped subject to the condition decision.

Button

Sets the pressing of the specified button as a condition.

Script

Sets the evaluation results of a Ruby script as the standard.

Loop

Description

Adds the Loop and Repeat controls for event command processing. The events set between these lines are able to run repeatedly. Multiple loops are also possible within loop processing.

Notes

• The event commands within the Loop and Repeat structure are repeated infinitely. To escape repeat processing, use event commands such as Break Loop.

Break Loop

Description

Breaks the loops being repeated by the Loop event command. When this command runs, it shifts processing to the event command set on the line after Repeat. There are no settings to be made for this command.

Exit Event Processing

Description

Ends the execution of event commands. No event commands will run once this command executes. There are no settings to be made for this command.

Call Common Event

Call Common Event
Description

Calls a common event. Once the called common event is done running, the next event command will run.

Available Settings
Common Event

Specify the common event to call.

Label

Description

Creates a jump destination (marker) for the Jump to Label event command.

Available Settings
Label Name

Specify the label's name.

Jump to Label

Jump to Label
Description

Moves to the position of the label specifying the line to process. The event command on the line following the jump label will be processed.

Available Settings
Label Name

Specify the label name to jump to. You can only specify labels that have been set in the Contents box on the same event page.

Comment

Description

Adds any comment you want to the Contents list. It will have no impact on game play.

Available Settings
Comment

Specify the text to display as a comment.


Party

Change Gold

Description

Increases/decreases the party's gold.

Available Settings
Operation

Specify the desired operation (Increase/Decrease).

Operand

Specify the amount of increase/decrease. To increase/decrease party gold by a fixed amount, select Constant and then enter the amount. To specify an amount using a variable value, select Variable and then specify the variable to look up.

Change Items

Description

Increases/decreases the quantity of an item the party possesses. If the quantity of the item ends up outside a range between 0 and 99 as a result of this operation, it will be adjusted to 99 (maximum quantity allowed) or 0 (not possessed) as the case may be.

Available Settings
Item

Specify the item for which to change the quantity.

Operation

Specify the desired operation (Increase/Decrease).

Operand

Specify the amount of increase/decrease. To increase/decrease the item quantity by a fixed amount, select Constant and then enter the amount. To specify an amount using a variable value, select Variable and then specify the variable to look up.

Change Weapons

Description

Increases/decreases the quantity of a weapon the party possesses. If the quantity of the weapon ends up outside a range between 0 and 99 as a result of this operation, it will be adjusted to 99 (maximum quantity allowed) or 0 (not possessed) as the case may be.

Available Settings
Weapon

Specify the weapon for which to change the quantity.

Operation

Specify the desired operation (Increase/Decrease).

Operand

Specify the amount of increase/decrease. To increase/decrease the weapon quantity by a fixed amount, select Constant and then enter the amount. To specify an amount using a variable value, select Variable and then specify the variable to look up.

Include Equipments

Selecting Include Equipments will also make the weapons actors have equipped subject to increase/decrease.

Change Armor

Description

Increases/decreases the quantity of armor the party possesses. If the quantity of the armor ends up outside a range between 0 and 99 as a result of this operation, it will be adjusted to 99 (maximum quantity allowed) or 0 (not possessed) as the case may be.

Available Settings
Armor

Specify the armor for which to change the quantity.

Operation

Specify the desired operation (Increase/Decrease).

Operand

Specify the amount of increase/decrease. To increase/decrease the armor quantity by a fixed amount, select Constant and then enter the amount. To specify an amount using a variable value, select Variable and then specify the variable to look up.

Include Equipments

Selecting Include Equipments will also make the armor actors have equipped subject to increase/decrease.

Change Party Member

Change Party Member
Description

Change party actors. You can even change party members so that there are zero actors in the party. In that case, the player will no longer be displayed on the map.

Available Settings
Actor

Specify the actor subject to the change.

Operation

Specify the desired operation (Add/Remove).

Initialize

Selecting this option uses the values in the Database for the settings applied when adding an actor.


Actor

Change HP

Description

Increases/decreases the HP of one or more actors.

Available Settings
Actor

Select the target actor(s). To target a specific actor, select Fixed and then specify the actor. To target all actors in the party, select Whole Party. To specify the target actor by ID number, select Variable and then specify the variable to look up.

Operation

Specify the desired operation (Increase/Decrease).

Operand

Specify the amount by which to increase/decrease HP. To set a fixed value, select Constant and then enter a value between 1 and 9999. To specify a value using a variable, select Variable and then specify the variable to look up.

Allow Knockout

Selecting this option enables the K.O. state when Change HP results in HP falling to 0 or less. If it is not selected, HP will be set to 1 if it falls to 0 or less as a result of Change HP.

Change MP

Description

Increases/decreases the MP of one or more actors.

Available Settings
Actor

Select the target actor(s). To target a specific actor, select Fixed and then specify the actor. To target all actors in the party, select Whole Party. To specify the target actor by ID number, select Variable and then specify the variable to look up.

Operation

Specify the desired operation (Increase/Decrease).

Operand

Specify the amount by which to increase/decrease MP. To set a fixed value, select Constant and then enter a value between 1 and 9999. To specify a value using a variable, select Variable and then specify the variable to look up.

Change State

Description

Changes the state of one or more actors.

Available Settings
Actor

Select the target actor(s). To target a specific actor, select Fixed and then specify the actor. To target all actors in the party, select Whole Party. To specify the target actor by ID number, select Variable and then specify the variable to look up.

Operation

Specify the desired operation (Add/Remove).

State

Select the target state.

Recover All

Description

Restores the HP and MP of one or more actors to their maximum values and removes all states.

Available Settings
Actor

Select the target actor(s). To target a specific actor, select Fixed and then specify the actor. To target all actors in the party, select Whole Party. To specify the target actor by ID number, select Variable and then specify the variable to look up.

Change EXP

Description

Increases/decreases the EXP of one or more actors.

Available Settings
Actor

Select the target actor(s). To target a specific actor, select Fixed and then specify the actor. To target all actors in the party, select Whole Party. To specify the target actor by ID number, select Variable and then specify the variable to look up.

Operation

Specify the desired operation (Increase/Decrease).

Operand

Specify the amount by which to increase/decrease EXP. To set a fixed value, select Constant and then enter a value between 1 and 9999999. To specify a value using a variable, select Variable and then specify the variable to look up.

Show Level Up Message

Selecting this option displays a message telling the player that a character has leveled up when their EXP has increased to the necessary amount due to the Change EXP command.

Change Level

Description

Increases/decreases the number of levels for one or more actors.

Available Settings
Actor

Select the target actor(s). To target a specific actor, select Fixed and then specify the actor. To target all actors in the party, select Whole Party. To specify the target actor by ID number, select Variable and then specify the variable to look up.

Operation

Specify the desired operation (Increase/Decrease).

Operand

Specify the amount by which to increase/decrease levels. To set a fixed value, select Constant and then enter a value between 1 and 9999999. To specify a value using a variable, select Variable and then specify the variable to look up.

Show Level Up Message

Selecting this option displays a message telling the player that a character has leveled up when their level has risen due to the Change Level command.

Change Parameters

Description

Increases/decreases a parameter of one or more actors.

Available Settings
Actor

Select the target actor(s). To target a specific actor, select Fixed and then specify the actor. To target all actors in the party, select Whole Party. To specify the target actor by ID number, select Variable and then specify the variable to look up.

Operation

Specify the desired operation (Increase/Decrease).

Operand

Specify the amount by which to increase/decrease the parameter. To set a fixed value, select Constant and then enter a value between 1 and 9999. To specify a value using a variable, select Variable and then specify the variable to look up.

Change Skills

Description

Makes an actor learn/forget an available skill.

Available Settings
Actor

Select the target actor. To target a specific actor, select Fixed and then specify the actor. To specify the target actor by ID number, select Variable and then specify the variable to look up.

Operation

Specify Learn to allow the actor to use the skill and Forget to prevent the actor from using it.

Skill

Select the target skill.

Change Equipment

Description

Changes an actor's equipment.

Available Settings
Actor

Select the target actor.

Equipment

Select the slot where you want to change equipment and then specify the equipment. Specifying None removes the equipment equipped in that slot.

Notes

• The party's equipment will only be changed if they have the specified equipment. To force the equipping of some sort of equipment, you must first use event commands such as Change Weapon or Change Armor to give an actor the desired equipment.

Change Name

Description

Changes an actor's name.

Available Settings
Actor

Select the target actor.

Name

Specify the name to which to change.

Change Class

Description

Changes an actor's class.

Available Settings
Actor

Select the target actor.

Class

Specify the class to which to change.

Notes

• Changing classes causes the actor's level to be recalculated based on his/her current EXP. Parameters and available skills may also change. Furthermore, weapons and armor that can no longer be equipped will be removed automatically.

Change Nickname

Description

Changes an actor's nickname.

Available Settings
Actor

Select the target actor.

Nickname

Specify the nickname to which to change.


Movement

Transfer Player

Description

Changes the party's location.

Available Settings
Location

Specify the location to which to move. To move to a specific location, select Direct designation, click ..., and then in the dialog box that appears, click the location to which to move. To specify a location using a map ID and coordinates, select Designation with variables and select the variables to look up in Map ID, Map X, and Map Y.

Direction

Specify the direction the player will be facing after the move.

Fade

Specify the screen transition method when transferring the player from one location to another. Normal fades to black before displaying the destination map, while White fades to white.

Set Vehicle Location

Set Vehicle Location
Description

Changes the location of a vehicle.

Available Settings
Vehicle

Specify the target vehicle (Boat, Ship, or Airship).

Location

Specify the location to which to move. To move to a specific location, select Direct designation, click ..., and then in the dialog box that appears, click the location to which to move. To specify a location using a map ID and coordinates, select Designation with variables and select the variables to look up in Map ID, Map X, and Map Y.

Set Event Location

Set Event Location
Description

Changes an event's location.

Available Settings
Event

Select the target event. Selecting This Event makes the event you are currently setting up subject to the move. Only events on the same map can be moved.

Location

Specify the location to which to move. To move to a specific location, select Direct designation, click ..., and then in the dialog box that appears, click the location to which to move. To specify a location using a map ID and coordinates, select Designation with variables and select the variables to look up in Map ID, Map X, and Map Y.

Notes

ECannot be used in battle events.

Scroll Map

Description

Scrolls the map displayed on the game screen without moving the player's location.

Available Settings
Direction

Specify the direction in which to scroll.

Distance

Specify the distance to scroll (in tiles).

Speed

Specify the scrolling speed (6 levels).

Notes

EIf this event command has been set to run repeatedly, the next scroll operation will not start until the previous one ends.

EUnless the map is returned the exact distance it was scrolled, its currently displayed position will be offset from the player's position.

EThis command cannot be used in battle events.

Set Move Route

Description

Forces the player or map event to move along a specific route.

Available Settings
Target Character (upper left part of dialog box)

Select the command's target (Player or Event).

Command List

Use movement commands to specify the route. See Setting Move Routes for more information.

Repeat Action

Selecting this option makes the command list for the movement route run repeatedly.

Skip If Cannot Move

Selecting this option skips commands that cannot run, such as when the player cannot move because of some sort of obstacle.

Wait for Completion

Pauses event processing until the specified move commands have all completed.

Notes

EMovement starts immediately for the character for which the route was set.

ERunning this event command for a character for which a move route was already set will result in the discarding of settings made up to that point. Only the latest setting will be valid. To set the next movement route after the previous one ends, select the Wait for Completion option.

EWhen Wait for Completion is selected, the player will not be able to perform any operations until the movement commands finish (parallel processing excluded). If a movement command cannot run because the character for which the movement route is specified bumps into an obstacle or otherwise impassible area, processing ends immediately. You can avoid such situations by selecting the Skip If Cannot Move option.

EEven if the player moves via this event command, it will not add to the total number of steps moved.

EThis command cannot be used in battle events.

Get On/Off Vehicle

Description

Controls getting on/off of vehicles. If on a vehicle, the player will get off, and if not on a vehicle, the player will get on. There are no settings to be made for this command.

Notes

EThe player usually presses the confirm key to get on/off of a vehicle, but this event command forces that transition. Nothing happens if normal getting on/off operation is impossible (for example, when there are no vehicles to get on or the player cannot get down to the ground).

EThis command cannot be used in battle events.


Character

Change Transparency

Description

Controls the transparency of the party moving on the map.

Available Settings
Transparency

Select On to hide the party and Off to display it.

Change Player Followers

Change Player Followers
Description

Controls whether the walking graphics of the second and subsequent party members are displayed.

Available Settings
Player Followers

Select On to show the other party members and Off to hide them.

Notes

• If there are five or more party members, only walking graphics for the first four will be displayed.

Gather Followers

Description

Displays the walking graphics of party members at the same position as the first actor. There are no settings to be made for this command.

Show Animation

Description

Displays an animation on the map.

Available Settings
Character

Specify the display location based on the position of the player or the event.

Animation

Specify the animation to display.

Wait for Completion

When this option is selected, event processing stops until the animation is finished displaying.

Notes

• This command cannot be used in battle events.

• If you want to display an animation during a battle, use the Show Battle Animation event command.

Show Balloon Icon

Show Balloon Icon
Description

Displays a balloon icon indicating an emotion above the party or event. There are ten emotion icons in all, such an exclamation point (!) for surprise and a light bulb for inspiration.

Available Settings
Character

Specify the display location based on the position of the player or the event.

Balloon Icon

Specify the balloon icon to display.

Wait for Completion

When this option is selected, event processing stops until the balloon icon is finished displaying.

Erase Event

Description

Temporarily clears an executing event. There are no settings to be made for this command. The cleared state will continue until the party moves to another map.

Notes

• This command cannot be used in battle events.


Screen Effects

Fadeout Screen

Description

Performs a screen fadeout (gradually turns the screen black). There are no settings to be made for this command.

Notes

• The fadeout state continues until the Fadein Screen event command is executed.

• Menus, the message window, and the battle command window are among the UI elements that will still be displayed during a fadeout.

• When this command is run in a battle event, everything except for the command window and messages will be blacked out, and the player will not be able to see enemies and other onscreen elements.

Fadein Screen

Description

Returns a screen blacked out by Fadeout Screen to its original state. There are no settings to be made for this command.

Tint Screen

Description

Changes the overall screen color. The color of the message window and pictures will not be changed.

Available Settings
Color Tone

Adjust the color tone (-255 to 255) for Red, Green, and Blue. Use Gray to set the intensity (0 to 255) of the grayscale filter. The higher the value, the greater the overall strength of the color. You can also click the Normal, Dark, Sepia, Dusk, and Night buttons at the bottom of the dialog box to apply the standard values for the tones represented by their respective names. The Normal button reverts to the original color tone. You can check color tone changes in the preview area on the right side of the dialog box.

Time

Specify the time to spend on processing in frames (1 to 600). One frame is equivalent to 1/60 of a second.

Wait for Completion

When this option is selected, processing stops until this command is finished running.

Notes

• The change in color tone is active until it is changed again by this command, even during combat.

Flash Screen

Description

Fills the entire screen with the specified color for an instant, and then gradually reverts to the original color. This allows you to represent a flash of lightning, etc.

Available Settings
Flash Color

Use the Red, Green, and Blue slider bars (0 to 255) to specify the color to flash. You can check the color you specified in the preview area on the right side of the dialog box. Use Strength to specify the color's opacity (0 to 255). Setting "0" makes the color completely transparent, rendering it invisible on screen.

Time

Specify the time processing continues in frames (1 to 600). One frame is equivalent to 1/60 of a second.

Wait for Completion

When this option is selected, processing stops until this command is finished running.

Shake Screen

Description

Shakes the entire screen left and right.

Available Settings
Shake

In Power, specify the intensity (1 to 9) of the shaking, and in Speed, specify how fast (1 to 9) the screen will shake.

Time

Specify the time processing continues in frames (1 to 600). One frame is equivalent to 1/60 of a second.

Wait for Completion

When this option is selected, processing stops until this command is finished running.


Time Adjustment

Wait

Description

Temporarily halts event processing. The player will not be able to perform any operations while processing is halted (parallel processing excluded).

Available Settings
Time

Specify the length of time to halt processing in frames (1 to 999). One frame is equivalent to 1/60 of a second.


Pictures and Weather

Show Picture

Description

Displays a picture (still image) onscreen.

Available Settings
Number

Specify a control number (1 to 100) to associate with the picture.

Picture Graphic

Specify the image file to display.

Display Position

Specify the picture's display position. Start by selecting either Upper Left or Center as the Origin. Then, specify the exact coordinates of the display position (with the origin you set being 0, 0). To use the Constant setting, enter coordinates (-9999 to 9999) in the X box (horizontal) and Y box (vertical). To specify coordinates using variable values, select Variable and then specify the variables to look up in the X and Y boxes.

Zoom

Specify the picture's zoom factor in Width % and Height % using a value between 0 and 2000%, with 100% being original image size.

Blending

Specify the opacity (0 to 225) of the picture in Opacity. The lower the value, the more transparent the image will be. Setting "0" means the picture will not be displayed. In Type, specify the blending method to use when displaying a transparent picture. Normal is the standard method, Additive results in a lighter color, and Subtractive results in a darker color.

Notes

• Up to 100 pictures can be simultaneously displayed. The higher a picture's control number, the greater the priority at which it will be displayed.

• If pictures have the same control number, only the one displayed last will appear. (The rest will be cleared.)

Move Picture

Description

Moves the picture currently being displayed.

Available Settings
Number

Specify the control number (1 to 100) of the target picture.

Display Position

Specify the position to which to move the picture. Start by selecting either Upper Left or Center as the Origin. Then, specify the exact coordinates of the display position (with the origin you set being 0, 0). To enter specific coordinates, select Constant, and then enter coordinates (-9999 to 9999) in the X box (horizontal) and Y box (vertical). To specify a coordinate using variable values, select Variable and then specify the variables to look up in the X and Y boxes.

Zoom

Specify the picture's post-move zoom factor in Width % and Height % using a value between 0 and 2000%.

Blending

Specify the opacity (0 to 225) of the post-move picture in Opacity. The lower the value, the more transparent the image will be. Setting "0" means the picture will not be displayed. In Type, specify the blending method to use when displaying a transparent picture. Normal is the standard method, Additive results in a lighter color, and Subtractive results in a darker color.

Time

Specify the time to spend on moving the picture in frames (1 to 600). One frame is equivalent to 1/60 of a second.

Wait for Completion

When this option is selected, processing stops until this command is finished running.

Rotate Picture

Description

Rotates the currently displayed picture.

Available Settings
Number

Specify the control number (1 to 100) of the target picture.

Speed

Specify a rotation speed between -90 and 90. A positive value indicates counterclockwise rotation, and a negative value clockwise rotation. Specify "0" to stop rotation.

Notes

• The rotational axis (central point) depends on the origin (upper left or center) specified the last time the target picture was displayed or moved.

• Overuse of this event command may slow the game down.

Tint Picture

Description

Changes the color tone of the currently displayed picture.

Available Settings
Number

Specify the control number (1 to 100) of the target picture.

Color Tone

Adjust the color tone (-255 to 255) for Red, Green, and Blue. Use Gray to set the intensity (0 to 255) of the grayscale filter. The higher the value, the greater the overall strength of the color. You can check color tone changes in the preview area on the right side of the dialog box.

Time

Specify the time to spend on changing the picture's color tone in frames (1 to 600). One frame is equivalent to 1/60 of a second.

Wait for Completion

When this option is selected, processing stops until this command is finished running.

Notes

• The change in color tone is active until it is changed again by this command.

Erase Picture

Description

Clears the currently displayed picture.

Available Settings
Number

Specify the control number (1 to 100) of the picture to clear.

Set Weather

Description

Controls the display of effect images representing weather (rain, storms, and snow).

Available Settings
Type

Specify the kind of image to display. Specify None if you do not want to display an image.

Power

Specify the image's display intensity (1 to 9).

Time

Specify the time to spend on changing the processing in frames (1 to 600). One frame is equivalent to 1/60 of a second.

Wait for Completion

When this option is selected, processing stops until this command is finished running.

Notes

• This command cannot be used in battle events.


Music and Sound Effects

Play BGM

Description

Starts playing BGM (background music).

Available Settings
File List

Specify the BGM file to play. Select None to stop BGM playback.

Volume

Specify the playback volume.

Pitch

Specify the playback pitch between 50 and 150%. Setting a value higher than 100% results in a playback speed faster (i.e. a higher pitch) than the original.

Play/Stop

Clicking Play plays BGM using the current settings. To halt playback, click Stop.

Notes

• If the specified BGM is already being played, this event command will not run.

Fadeout BGM

Description

Lowers BGM volume while stopping playback.

Available Settings
Time

Specify the fadeout time in seconds (1 to 60).

Save BGM

Description

Saves the currently playing BGM along with its playback position. There are no settings to be made for this command.

Replay BGM

Description

Starts playing BGM from the state in which it was saved by Save BGM. There are no settings to be made for this command.

Play BGS

Description

Starts playing BGS (background sound).

Available Settings
File List

Specify the BGS file to play. Select None to stop BGS playback.

Volume

Specify the playback volume.

Pitch

Specify the playback pitch between 50 and 150%. Setting a value higher than 100% results in a playback speed faster (i.e. a higher pitch) than the original.

Play/Stop

Clicking Play plays BGS using the current settings. To halt playback, click Stop.

Notes

• If the specified BGS is already being played, this event command will not run.

Fadeout BGS

Description

Lowers BGS volume while stopping playback.

Available Settings
Time

Specify the fadeout time in seconds (1 to 60).

Play ME

Description

Starts playing ME (a music effect).

Available Settings
File List

Specify the ME file to play. Select None to stop ME playback.

Volume

Specify the volume.

Pitch

Specify the playback pitch between 50 and 150%. The standard pitch is 100%, and the higher the value you specify, the faster the tempo and higher the pitch.

Play/Stop

Clicking Play plays ME using the current settings. To halt playback, click Stop.

Notes

• If the specified ME is already being played, this event command will not run.

Play SE

Description

Starts playing SE (a sound effect).

Available Settings
File List

Specify the SE file to play.

Volume

Specify the volume.

Pitch

Specify the playback pitch between 50 and 150%. The standard pitch is 100%, and the higher the value you specify, the faster the tempo and higher the pitch.

Play/Stop

Clicking Play plays SE using the current settings. To halt playback, click Stop.

Notes

• If this event command is run before SE playback completes, sound effect playback will overlap.

• SE playback will not stop even if you set None. To stop an SE, use the Stop SE event command.

Stop SE

Description

Stops all SE (sound effect) playback. There are no settings to be made for this command.


Scene Control

Battle Processing

Description

Spawns an enemy troop and begins a battle against it.

Available Settings
Troop

Specify the enemy troop the player will battle. To have the player battle a specific troop, select Direct designation and then specify the desired troop. To specify a troop by its ID, select Designation with a variable and then specify the variable to look up. Selecting Same as Random Encounter spawns a troop selected based on the Encounters settings for the map the party is on.

Can Escape

Selecting this option enables the Escape command during battles, and processing can be branched depending on whether the party won or escaped (If Won or If Escaped).

Continue Even When Loser

When this option is selected, the game does not end even if the entire party is defeated, and processing can be branched depending on whether the party won or lost (If Won or If Lost).

Notes

• This command cannot be used in battle events.

Shop Processing

Description

Starts shop processing for buying/selling weapons, armor, and other items.

Available Settings
Merchandise List

Specify what is for sale. Double-clicking on a blank row displays a dialog box in which you can enter settings for Merchandise and Price. Setting Price to Standard specifies prices set in the Database, while Specify is for specifying prices to apply only to this event command.

Purchase Only

When this option is selected, the player will not be able to sell inventory items.

Notes

• This command cannot be used in battle events.

Name Input Processing

Name Input Processing
Description

Displays a window for the player to enter a new name for an actor.

Available Settings
Actor

Specify the actor subject to the name change.

Max Characters

Specify the maximum number of characters (1 to 16) that can be entered.

Notes

• This command cannot be used in battle events.

• Name entry while playing the game uses the directional buttons to move the cursor, the confirm button to add characters, and the cancel button to clear a character from the end of the name with each press.

Open Menu Screen

Description

Calls a menu screen. There are no settings to be made for this command.

Notes

• This command cannot be used in battle events.

Open Save Screen

Description

Calls a save screen. There are no settings to be made for this command.

Notes

• This command cannot be used in battle events.

Game Over

Description

Forcibly ends the game and displays the Game Over screen. There are no settings to be made for this command.

Return to Title Screen

Description

Forcibly ends the game and returns to the title screen. There are no settings to be made for this command.


System

Change Battle BGM

Change Battle BGM
Description

Changes the settings for the background music to play during battles. The post-change setting is active until it is changed again by this command.

Available Settings
File List

Specify the BGM file to use. If you do not want to play BGM, specify None.

Volume

Specify the volume.

Pitch

Specify the playback pitch between 50 and 150%. The standard pitch is 100%, and the higher the value you specify, the faster the tempo and higher the pitch.

Play/Stop

Clicking Play plays BGM using the current settings. To halt playback, click Stop.

Notes

• Mid-battle changes will not be applied until the next battle.

Change Battle End ME

Change Battle End ME
Description

Changes the settings for the music effect to play at the end of a battle. The post-change setting is active until it is changed again by this command.

Available Settings
File List

Specify the ME file to use. If you do not want to play ME, specify None.

Volume

Specify the volume.

Pitch

Specify the playback pitch between 50 and 150%. The standard pitch is 100%, and the higher the value you specify, the faster the tempo and higher the pitch.

Play/Stop

Clicking Play plays ME using the current settings. To halt playback, click Stop.

Change Save Access

Change Save Access
Description

Controls whether a player can save game data. The post-change setting is active until it is changed again by this command.

Available Settings
Operation

Select Disable to prevent saving, and Enable to allow it.

Change Menu Access

Change Menu Access
Description

Controls whether a player can display a menu screen. The post-change setting is active until it is changed again by this command.

Available Settings
Operation

Select Disable to prevent menu screen display, and Enable to allow it.

Change Encounter

Description

Controls whether the party will encounter enemies while moving. When enabled, this command allows the random spawning of battles against enemy troops. The post-change setting is active until it is changed again by this command.

Available Settings
Operation

Select Disable to prevent the spawning of encounters, and Enable to allow it.

Change Formation Access

Change Formation Access
Description

Controls whether the player can change the party member formation. The post-change setting is active until it is changed again by this command.

Available Settings
Operation

Select Disable to prevent formation changing, and Enable to allow it.

Change Window Color

Change Window Color
Description

Changes the window color setting. The post-change setting is active until it is changed again by this command.

Available Settings
Color Tone

Use the Red, Green, and Blue slider bars (0 to 255) to specify the color to which to change. You can check the color you specified in the preview area on the right side of the dialog box.

Change Actor Graphic

Change Actor Graphic
Description

Changes an actor's graphic. The post-change setting is active until it is changed again by this command.

Available Settings
Actor

Select the target actor.

Graphic

Specify the post-change walking graphic (left) and face graphic (right) in the dialog boxes that open when you double-click the respective Graphic boxes. Select None if you do not want to display a graphic.

Change Vehicle Graphic

Change Vehicle Graphic
Description

Changes a vehicle's graphic. The post-change setting is active until it is changed again by this command.

Available Settings
Vehicle

Specify the target vehicle.

Graphic

Specify the post-change graphic in the dialog box that opens when you double-click the Graphic box. Select None if you do not want to display a graphic.


Movies

Play Movie

Description

Plays a movie.

Available Settings
File List

Specify the movie file to play.


Map

Change Map Name Display

Change Map Name Display
Description

Controls whether a map name is displayed when moving to different map.

Available Settings
Map Name Display

Select On to show the map name and Off to hide it.

Change Tileset

Description

Changes the tileset that was set for the map. Only maps on which you placed events are subject to this command.

Available Settings
Tileset

Specify the tileset to which to change.

Change Battle Background

Change Battle Background
Description

Changes the battle background that was set for the map. Only maps on which you placed events are subject to this command.

Available Settings
File List

Specify the post-change background (left) and floor surface (right). You can check the graphic you specified in the preview area on the right side of the dialog box.

Notes

• If this command runs during a battle, the background will not change until the beginning of the next battle.

Change Parallax Background

Change Parallax Background
Description

Changes the parallax background that was set for the map. Only maps on which you placed events are subject to this command.

Available Settings
Graphic

Specify the graphic to which to change.

Loop Horizontal

Selecting this option loops the graphic horizontally. Specify a speed value between -32 and 32 (0 to stop) in Auto Scroll to automatically scroll.

Loop Vertical

Selecting this option loops the graphic vertically. Specify a speed value between -32 and 32 (0 to stop) in Auto Scroll to automatically scroll.

Get Location Info

Get Location Info
Description

Gets the value of a specific position on a map and assigns it to a variable. Only maps on which you placed events are subject to this command.

Available Settings
Variable for Info

Specify the variable to which to assign the retrieved value.

Info Type

Specify the kind of information to obtain.

Location

Specify the location of target information. To specify a specific location, select Specify Directly, and then in the dialog box that opens when you click ..., specify the desired location. To specify a location using coordinates, select Specify with Variable, and then in the Map X and Map Y boxes, enter the coordinates for the information to obtain.


Battle

Change Enemy HP

Change Enemy HP
Description

Increases/decreases the HP of one or more enemies.

Available Settings
Enemy

Select the target enemy or enemies. Selecting Entire Troop makes all enemies subject to the command.

Operation

Select Increase or Decrease.

Operand

Specify the amount by which to increase/decrease HP. To specify a fixed value, select Constant and then enter a value. To specify the amount with a variable value, select Variable and then specify the variable to look up.

Allow Knockout

Selecting this option results in the K.O. state when HP falls to 0 or less. If it is not selected, HP will revert to 1 every time it falls to 0 or less.

Notes

• This command runs only when used in battle events.

Change Enemy MP

Change Enemy MP
Description

Increases/decreases the MP of one or more enemies.

Available Settings
Enemy

Select the target enemy or enemies. Selecting Entire Troop makes all enemies subject to the command.

Operation

Select Increase or Decrease.

Operand

Specify the amount by which to increase/decrease MP. To specify a fixed value, select Constant and then enter a value. To specify the amount with a variable value, select Variable and then specify the variable to look up.

Notes

• This command runs only when used in battle events.

Change Enemy State

Change Enemy State
Description

Changes the state of one or more enemies.

Available Settings
Enemy

Select the target enemy or enemies. Selecting Entire Troop makes all enemies subject to the command.

Operation

Select Add or Remove.

State

Specify the type of state to add/remove.

Notes

• This command runs only when used in battle events.

Enemy Recover All

Enemy Recover All
Description

Restores the HP and MP of one or more enemies to their maximum values and removes all states.

Available Settings
Enemy

Select the target enemy or enemies. Selecting Entire Troop makes all enemies subject to the command.

Notes

This command runs only when used in battle events.

Enemy Appear

Description

Spawns the enemies for which the Appear Halfway option was set in troop data.

Available Settings
Enemy

Select the target enemy or enemies.

Notes

• This command runs only when used in battle events.

Enemy Transform

Description

Transforms the currently spawned enemy into another enemy. The HP and MP of the transformed enemy will be the same as that of the pre-transformation enemy.

Available Settings
Enemy

Select the enemy to transform.

Transform To

Select the enemy into which to transform.

Notes

• This command runs only when used in battle events.

Show Battle Animation

Show Battle Animation
Description

Displays an animation targeting an enemy.

Available Settings
Enemy

Select the target enemy.

Animation

Specify the animation to display.

Notes

• This command runs only when used in battle events.

Force Action

Description

Forces an enemy/actor to use a specific skill.

Available Settings
Action Subject

Select the target enemy/actor.

Action

In Skill, specify the skill to be forcibly used. In Target, specify the target of the skill by selecting Last Target (same target as the most recent action taker), Random (randomly selected), or Index X (X is a value between 1 and 8). See the notes below for more information.

Notes

• This command runs only when used in battle events.

• The specified action is performed when the character's turn comes around. The character's action (unforced) will be cancelled on that turn.

• This event command will not be processed if the specified character is done with his action on the same turn when the command runs.

• When the scope of the specified skill is all enemies/actors or the user, the setting in Target will be ignored in favor of the specified scope.

• Specifying Index X (where X is 1 to 8) for Target results in the target being the corresponding actor in the party formation (first actor when X is 1) if Action Subject is an enemy, and if Action Subject is an actor, it results in the target being the corresponding enemy in the enemy setting order (first enemy when X is 1).

Abort Battle

Description

Forcibly ends the battle and returns to the map. There are no settings to be made for this command.

Notes

• This command runs only when used in battle events.


Advanced

Script

Description

Evaluates a Ruby script.

Available Settings
Script

Enter the Ruby script to evaluate.


Set Move Route

What Is a Move Route?

A move route is what determines how to move a player or event. You set a move route when you specify Custom under the Autonomous Movement setting for an event or use the Set Move Route event command.

In either case, you set the route in the Move Route dialog box. Routes are created/edited by combining movement commands that control such things as the player/event's movement and direction. For example, if you enter the move commands Move Right, Move Down, Move Left, and Move Up in that order, the player/event will move in a clockwise lap.

Available Settings

Set Move Route
Target Character

Select the target actor/event. Specify this only when setting the Set Move Route event command.

Command List

A list of movement commands that have been added. Add movement commands in order according to the route you want to set.

Selecting a list item by clicking it specifies the position for adding the command clicked on the command list. In the shortcut menu that appears when you right-click an item, you can perform such operations as copying and editing settings.

Movement Commands

A command group for controlling the character (player/event) movement and direction. Clicking a button adds (inserts) the corresponding command at the currently selected position on the command list. The commands are described below. Note that one step is equal to moving one tile.

Move Down/Move Left/Move Right/Move Up/Move Lower Left/Move Lower Right/Move Upper Left/Move Upper Right

Moves the player/event one step in the direction indicated by the command name.

Move At Random

Moves the player/event one step up, down, left, or right, as selected at random.

Move Toward Player

Moves the event one step toward the player.

Move Away From Player

Moves the event one step away from the player.

1 Step Forward

Moves the player/event one step forward in the current direction.

1 Step Backward

Moves the player/event in the opposite direction, without changing the direction being faced.

Jump

Moves the player/event by jumping. Specify the distance to jump in X and Y (-100 to 100, with positive values indicating right/down). Obstacles will be passed through when jumping. Note that when a party for which the Player Followers setting is On is moved by jumping, the second and subsequent members will stay where they are.

Wait

Specify the length of time to halt processing in frames (1 to 999). One frame is equivalent to 1/60 of a second.

Turn Down/Turn Left/Turn Right/Turn Up

Changes the direction the player/event is facing to the direction indicated by the command name.

Turn 90° Right/Turn 90° Left

Changes the direction the player/event is facing 90 degrees in the direction indicated by the command name.

Turn 180°

Changes the direction the player/event is facing to the opposite direction.

Turn 90° Right or Left

Turns the character/event right/left at random.

Turn At Random

Changes the character/event's direction up/down/left/right at random.

Turn Toward Player

Changes the character/event's direction toward the player.

Turn Away From Player

Changes the character/event's direction away from the player.

Switch ON/Switch OFF

Changes the specified switch to the value indicated by the command name.

Change Speed

Changes the Speed setting for Autonomous Movement for the target map event. This change stays in effect even after movement ends.

Change Frequency

Changes the Frequency setting for Autonomous Movement for the target map event. This change stays in effect even after movement ends.

Walking Animation ON/Walking Animation OFF

Changes the Walking Animation setting under Options for the target map event. This change stays in effect even after movement ends.

Stepping Animation ON/Stepping Animation OFF

Changes the Stepping Animation setting under Options for the target map event.

Direction Fix ON/Direction Fix OFF

Changes the Direction Fix setting under Options for the target map event. This change stays in effect even after movement ends.

Through ON/Through OFF

Changes the Through setting under Options for the target map event. This change stays in effect even after movement ends.

Transparent ON/Transparent OFF

Changes the show/hide setting for the character graphic. Setting it to ON hides the graphic. This change stays in effect even after movement ends.

Change Graphic

Changes the character graphic to the one specified. This change stays in effect even after movement ends.

Change Opacity

Changes the transparency of the character graphic. Setting "0" renders the graphic invisible. This change stays in effect even after movement ends.

Change Blending

Changes the blending method for the display colors of character and map graphics. Setting Additive results in a lighter color and Subtractive a darker color. This change stays in effect even after movement ends.

Play SE

Plays the specified SE.

Script

Runs the script you entered.

Options

These options affect the overall processing of the movement commands you added. Set the options you want to apply as necessary.

Repeat Action

Selecting this option makes the commands in the list run repeatedly.

Skip If Cannot Move

Selecting this option enables the skipping of movement commands that are not possible because of obstacles and so on.

Wait for Completion

When this option is selected, other processing stops until movement command processing is all done. This can only be specified when setting the Set Move Route event command.


Reference Material

Additional information is available for the formulas and resources used in creating games. Refer to these additional references for more information on using RPG Maker.

  • Resource Standards
  • Parameters and Formulas


Resource Standards

  • Graphic Resources
  • Tilesets
  • Window Skins
  • Audio Resources
  • Movie Resources

RPG Maker VX Ace allows you to use your own original files for various resources, including graphics and audio.

Selecting Manage Resources on the Tools menu displays a dialog box for importing/exporting a variety of resources. You can also directly copy resource files to the game folder, but the Manage Resources dialog box offers you commands to change transparency and other settings, so we recommend you use it while you are still getting familiar with the program.

Graphic Resources

You can use PNG and JPG files. PNG files with 32-bit color (alpha channel) are fully supported.

Characters (Graphics/Characters)

Files containing images of characters to display on the map screen.

A character can be of any size, and a total of twelve patterns (four directions (down, left, right, up) × 3 patterns) are arranged in the designated order. In each file, arrange characters two down and four across, for a total of eight. The size of this character is calculated based on one-twelfth the width and one-eighth the height of this file.

Note that RPG Maker VX Ace displays characters offset four pixels from tiles so as to more naturally portray them with buildings.

  • Adding an exclamation point (!) to the beginning of a file name cancels the application of the four-pixel offset, and also turns off the translucent effect applied by the bush attribute. This is used mainly for object-type characters on maps, such as doors and treasure chests. It can also be used in combination with the dollar sign ($) special character.
  • Adding a dollar sign ($) to the beginning of a file name allows you to treat one character as one file. In this case, the size of the character will be one-third of the width and one-fourth of the height of the file. It can also be used in combination with the exclamation point (!) special character.
Face Graphics (Graphics/Faces)

A file containing images of face graphics to display mainly on menus and in message windows.

One file contains up to eight 96 × 96 images arranged four across and two down.

Battle Graphics (Graphics/Battlers)

A file containing images of enemy characters to display on the battle screen.

You can choose the size, but in general images must fit on the 544 × 296 battle screen.

Animations (Graphics/Animations)

A file containing images for animations to display mainly as effects on the battle screen.

Five animation cells in a row, each consisting of a 192 × 192 image, comprise one block, and each file is only as long as is required to accommodate the number of blocks used. A file can contain up to twenty blocks (100 cells), but it would be best not to make images too large, as they will slow down game performance, including load times.

Tilesets (Graphics/Tilesets)

A file containing the tiles that comprise maps.

See Tilesets for more information.

Battle Backgrounds (Graphics/Battlebacks1, Graphics/Battlebacks2)

A file containing images to be used as backgrounds on the battle screen.

Battlebacks1 is mainly floor images, while Battlebacks2 is mainly wall images. The two can be freely combined as a battle background.

The size is fixed to 580 × 444, slightly larger than the screen.

Parallaxes (Graphics/Parallaxes)

A file containing images (parallaxes) to display at the back layer of maps.

There are no particular size restrictions. To loop a parallax, match up the top and bottom and left and right sides, just like you would for Web page wallpaper.

Titles (Graphics/Titles1, Graphics/Titles2)

A file containing images to display on the title screen.

Titles1 draws the main background, while Titles2 draws borders, etc. Combine the two any way you want to make a title screen.

The size is fixed at 544 × 416.

Balloon Icons (Graphics/System/Balloon.png)

A file containing the icons to display when running the Show Balloon Icon event command.

The size is fixed at 256 × 320. Arrange 8 patterns × 10 types of balloon icons, each of the size 32 × 32 per pattern, therein.

Icons (Graphics/System/IconSet.png)

A file containing icon images for displaying next to skill and item names.

Arrange icons (each a 24 × 24 image) in rows of sixteen and include as many rows as necessary.

Note that the icons used for indicating parameter buff and debuff states are limited to icons numbers 64 to 95.

Battle Start Effects (Graphics/System/BattleStart.png)

A file containing effect images to display at the start of battles.

Size is fixed at 544 × 416, and the file must be a 256-bit grayscale PNG file. The screen is overwritten from the lowest palette number to the highest.

Airship Shadows (Graphics/System/Shadow.png)

A file containing the image of the shadow displayed when on an airship.

The image can be any size.

Game Over (Graphics/System/Gameover.png)

A file containing the image to display on the game over screen.

The size is fixed at 544 × 416.

Window Skins (Graphics/System/Window.png)

A file containing the images that comprise windows.

See Window Skins for more information.

Pictures (Graphics/Pictures)

A file containing the images to display using in-game events.

The images can be any size.

Tilesets

Each tile is 32 × 32, and they must be grouped into five sets labeled A through E according to the rules detailed below.

Note that specifications may vary according to the database settings made in Mode for Tileset. For information on the specifications when Mode is set to VX-Compatible Type, refer to RPG Maker VX resource standards.

Set A

This set is handled as lower layer tiles during map drawing. It is further divided up into five groups, with almost all of the groups comprised of auto tiles (special tiles for which borderlines are automatically created).

As a rule, the basic structure of auto tiles follows the six patterns shown below.

a.
Typical patterns (for tile palette display)
b.
Patterns with borders on all four sides
c.
Combined patterns (represents a group of an eight tile boundary and one tile in the middle)

Forest tiles that will not turn translucent

Auto tile images will be determined to be forest tiles if the (4, 4) position from the lower right is transparent. If the bush attribute is assigned to a forest-type auto tile, walking graphics will not turn translucent, including the lower right corner and lower left corner boundaries, on the eight kinds of tiles described below.

Group 1

The size is fixed at 512 × 384. As the figure above shows, the tiles are comprised of a combination of five block patterns. As a rule, the tiles in this group will not create a borderline, even when placed adjacent to each other.

Only tiles in this group can be passed over by boats and ships. However, if they are specifically set to be passable by walking, they will become impassible to boats and ships.

Block A

Auto tiles used for oceans. They can be animated by placing the three tiles that comprise the basic auto tile structure side by side.

Block B

Auto tiles used for deep oceans. Only tiles in this block can create borderlines for ocean tiles when they are adjacent to group 1 tiles. The transparent color portion of this block is automatically complemented by block A tiles. As with block A, they can be animated by placing the three tiles that comprise the basic auto tile structure side by side.

Note that tiles in this block are impassable by boats.

Block C

Auto tiles for embellishing block A ocean tiles. The transparent color portion of this block is automatically complemented by block A tiles.

Note that tiles in this block are impassable by boats and ships.

Block D

Auto tiles used for water. They can be animated by placing the three tiles that comprise the basic auto tile structure side by side.

Block E

Tiles used for waterfalls. Two tiles side by side form a pattern, and they can be animated by placing three vertically.

Note that tiles in this block are impassable by boats and ships.

Group 2

The size is fixed at 512 × 384. As shown in the above figure, the tiles are comprised of combination of two block patterns arranged in four vertical sets. For this group only, specifications will vary according to the settings made in Mode for Tileset in the Database.

When the counter attribute is applied to this group, it can be used as an auto tile for representing tables, and when placed on a map, the eight pixels at the bottom of the pattern are offset downward.

Block A (Field Type)
TileA2 - Block A - Field Type

This block is comprised of four patterns of auto tiles, and in the actual tileset, it is handled as 1 only, 1 and 2 overlapped, 3 only, or 3 and 4 overlapped.

Block B (Field Type)

This block can contain four patterns, and in the actual tileset, they are tiles with special specifications that enable placement overlapping block A tiles.

Block A (Area Type)

This block is comprised of four patterns of auto tiles, and in the actual tileset, the three patterns from the left are handled as not having borderlines the compete with each other, while the right most pattern is handled as not making a borderline with other tiles.

Block B (Area Type)

This block can contain four patterns, and in the actual tileset, they are tiles that enable placement overlapping block A tiles.

Group 3

These auto tiles are mainly used for building facades. This group has a size of 512 × 256, and it is comprised only by group patterns of auto tiles that are eight wide and four long.

Tiles in this group automatically produce a shadow on adjacent right-side tiles when two or more are placed vertically at map drawing time. However, no shadow will be produced if the adjacent tiles are not group 2 (excluding block C) or group 5.

Group 4

These auto tiles are mainly used for walls. They are also used for walls in dungeon generation. The size is fixed at 512 × 480. They are comprised by the basic auto tile structure or only group patterns of auto tiles that are eight wide and three long.

Tiles in this group automatically produce a shadow on adjacent right-side tiles when two or more are placed vertically at map drawing time. However, no shadow will be produced if the adjacent tiles are not group 2 (excluding block C) or group 5.

Group 5

The size is 256 × 512 and you should place 8 × 16 of these tiles therein. The tiles in this file are all treated as ordinary tiles. The tiles on the third, fifth, and seventh rows from the top are also used for floors in dungeon generation.

Sets B through E

These sets are handled as upper layer tiles during map drawing.

Each is sized 512 × 512 and you should place 16 × 16 of these tiles therein.

  • The tile on the furthest upper left of set B is for representing nothing placed on the upper layer, so make sure to leave it empty.

Window Skins

Window skins are 128 × 128 images. You should normally use a 32-bit PNG file.

A

Window background 1. The 64 × 64 pattern is drawn by growing or shrinking to fit the actual window. Strictly speaking, it is two pixels smaller around the window. This is done to show a natural-looking window with rounded corners.

B

Window background 2. The 64 × 64 pattern is drawn tile style so as to cover background 1.

C

Window frames and arrows. Four corners that are 16 × 16 are drawn and the remaining frame (the sides) are drawn tile style at a 16-pixel thickness to match the window. Arrows are used as marks when scrolling window content.

D

The command cursor used to show items that are selected in windows. The two pixels on the periphery are expanded/contracted horizontally and vertically, and the rest is expanded/contracted evenly to fit the size of the cursor.

E

The pause sign used to show the waiting-for-button-press state in message windows. It animates based on four 16 × 16 patterns.

F

Text colors that can be used by control characters of the Show Text event command. You can place four rows of eight 8 × 8 images (colors) each.

Audio Resources

You can use fives types of files, namely OGG, WMA, MP3, WAV, and MID. (Note that the MID format is limited to BGM and ME.) In general, the use of OGG files is recommended for all resource types.

BGM (Audio/BGM)

Audio resources used for background music.

BGM (Audio/BGM)

Audio resources used for background sounds.

ME (Audio/ME)

Audio resources used for music effects.

SE (Audio/SE)

Audio resources used for sound effects.

The following table describes the features of each file format.

OGG | These files contain Ogg Vorbis data, an audio compression format with excellent sound quality and compression. Files with playback times three seconds or longer are automatically played by streaming them. For such files, embedding the values LOOPSTART and LOOPLENGTH as comments allows the sample position corresponding to those values to be recognized as a loop.
WMA | The sound compression format used by Windows Media Player. Files are played using DirectShow.
MP3 | A popular audio compression format. Files are played using DirectShow. Its features are the same as the WMA format.
WAV | The standard sound format in Windows. In addition to ordinary uncompressed WAV files, the loading of Microsoft ADPCM files is also supported.
MID | MIDI files played by DirectMusic Synthesizer. In the case of BGM, when there is the number 111 control change in MIDI data, it is recognized as a mark for a repeat position after playing a song to the end.

Movie Resources

Movie resources are stored in the Movies folder. OGV (Ogg Theora) files are the only format you can use.

Movies are displayed over the center of the game screen. Movies larger than the screen size (544×416) will have their edges cut off to fit within the screen.


Parameters and Formulas

  • Parameters
  • Ex-Parameters
  • Sp-Parameters
  • Preemptive Strikes and Surprise
  • Escape Success Rate

RPG Maker VX Ace has a large number of features that are set up as parameters. There is no single formula for calculating damage. Such formulas are set on a per skill/item basis.

Parameters

Parameters are basic values set by the Parameter Curves of the class in question (or in the case of enemies, directly by numeric values). They are then multiplied by the settings in the features list.

Parameter | Abbreviation | Description
Max HP | MHP | Max value of HP
Max MP | MMP | Max value of MP
Attack power | ATK | Affects amount of damage dealt mainly by physical attacks
Defense power | DEF | Affects amount of damage suffered mainly from physical attacks
Magic attack | MAT | Affects amount of damage dealt mainly by magic attacks
Magic defense | MDF | Affects amount of damage suffered mainly from magic attacks
Agility | AGI | Determines action order during a turn
Luck | LUK | Affects chance of adding state or debuffing a parameter

Attack power, defense power, magic power, and magic defense have no special effects beyond being looked up by the damage calculation formulas that are set for skills/items.

The change in states and debuff effectiveness due to luck is as shown below. Note, however, that 0 is the lower limit.

Chance (%) = 100 + (user's luck - target's luck) ÷ 10

Ex-Parameters

The default value for ex-parameters is 0%, but they can be set to other percentages in the characteristics list.

Ex-Parameter | Abbreviation | Description
Accuracy | HIT | Chance of a physical attack scoring a hit on a target
Evasion | EVA | Chance of evading a physical attack
Critical hit | CRI | Chance of scoring a critical hit
Critical evasion rate | CEV | Chance of preventing a critical hit
Magic evasion rate | MEV | Chance of nullifying a magic attack
Magic reflection | MRF | Chance of reflecting back a magic attack
Counter attack | CNT | Chance of a counterattack against a physical attack
HP regeneration rate | HRG | Percentage of HP restored at end of each turn
MP regeneration rate | MRG | Percentage of MP restored at end of each turn
TP regeneration rate | TRG | Percentage of TP added at end of each turn

Hit determinations and avoidance determinations for physical attacks are performed independently of each other. For example, if accuracy on the attacking side is 90% and avoidance on the target side is 10%, avoidance will be 10% of 90%, resulting in the overall accuracy being calculated at 81%.

Counterattacking is only possible against physical attacks from enemies.

Sp-Parameters

The default value for sp-parameters is 100%, but they can be multiplied by settings in the characteristics list.

Sp-Parameter | Abbreviation | Description
Probability of being targeted | TGR | Chance of being a target of an enemy attack
Defense effectiveness | GRD | Strength of damage reduction effect of the defense command
Recovery effectiveness | REC | Percentage of HP/MP recovery effect received
Medicine lore | PHA | Percentage of HP/MP recovery enhancement by an item
MP consumption rate | MCR | Percentage by which to vary MP consumption by a skill
TP charge rate | TCR | Percentage by which to vary TP charging by a skill/item
Physical damage rate | PDR | Percentage of physical damage received
Magic damage rate | MDR | Percentage of magic damage received
Floor damage rate | FDR | Percentage of damage received from map terrain
Experience acquisition rate | EXR | Percentage at which to vary the amount of experience points acquired

The damage reduction rate by defense effectiveness is as follows:

Damage when defending = Normal damage ÷ (2 × defense effectiveness)

Preemptive Strikes and Surprise

If actor's average agility value >= enemy's average agility value
Preemptive strike rate (%) = 5
Surprise rate (%) = 3
If actor's average agility value < enemy's average agility value
Preemptive strike rate (%) = 3
Surprise rate (%) = 5
  • During a preemptive strike, the enemy will not be able to act on the first turn.
  • When surprised, actors will not be able to act on the first turn.
  • Preemptive strikes and surprise do not occur in event battles.
  • When the party ability Increase Preemptive Strike Rate is enabled, the chance of a preemptive strike increases by a factor of four.
  • When the party ability Disable Surprise is enabled, the party will not be surprised.

Escape Success Rate

Escape success rate (%) = 150 - 100 × Average value of enemy's agility ÷ Average value of actor's agility
  • 10% is added each time an escape fails.
  • The player can escape unconditionally during a preemptive strike.


RGSS Reference Manual

RGSS (Ruby Game Scripting System) uses the object-oriented scripting language Ruby to develop 2D games for the Windows® platform.

Contents

  • RGSS Specifications
  • Ruby Syntax
    • Syntax and Expressions
    • Variables and Constants
    • Literals
    • Operator Expressions
    • Control Structures
    • Method Calls
    • Class and Method Definitions
  • Standard Library
    • Built-in Functions
    • Built-in Variables
    • Built-in Classes
    • Built-in Modules
    • Built-in Exception Classes
  • Game Library
    • RGSS Built-in Functions
    • RGSS Built-in Classes
    • RGSS Built-in Modules
    • RPGVXAce Data Structure
  • Appendix
    • Regular Expressions
    • sprintf Format

About This Document

This document presents a selection of entries from the Ruby reference manual--the bare minimum needed for using RGSS. It has been edited to include explanations of RGSS's unique specifications. Since it is basically based on the old version compatible with Ruby 1.8, there may be some slight differences with the specifications in Ruby 1.9, which is employed in RGSS3.

The original Ruby language, as well as the source for this document, can be found at the official Ruby homepage: http://www.ruby-lang.org/. Check it out if you need more detailed Ruby information.

User Support

Enterbrain provides no user support for creating games with the script editor or any problems that may arise from the game-creation process. Furthermore, neither Enterbrain nor Yukihiro Matsumoto assumes any obligations to provide Ruby script support. Make sure you have a thorough understanding of RGSS's functions when attempting to edit a script.

Be a responsible programmer. Make sure to check these pages, the Ruby homepage, any other Ruby information and support sites, and similar resources before approaching a site administrator or other users for assistance.


RGSS Specifications

  • New Functionality in RGSS3
  • Starting a Game
  • Game.ini
  • RGSS-RTP
    • Installation Data
  • Encrypted Archives
  • Other
    • Extension Libraries
    • Character Set
    • Properties

New Functionality in RGSS3 (RGSS3)

RGSS3, which is incorporated into RPG Maker VX Ace, has a number of differences from RGSS2, which was included with RPG Maker VX. The main differences are listed below.

  • The program has been rebuilt using Ruby 1.9.2. Ruby 1.9 includes a number of improvements, including faster processing speed.
  • Japanese and English DLLs have been integrated. Windows will automatically recognize a Japanese environment, and in all other cases display messages in English.
  • The internal specifications of encrypted archives have been overhauled, solving the problem of long startup times for large games.
  • It is now possible to control the position that is returned to by a reset using the F12 key. Use the rgss_main function.
  • It is now possible to adjust the padding between a window's frame and contents using the Window class.
  • The drawing of outline text is now supported using the Font class.
  • It is now possible to use editor options to open a console window for debugging output during play testing.
  • Output to message boxes using the print function and the p function has been abolished due to the aforementioned improvement. These functions have been renamed msgbox and msgbox_p.
  • Support has been added for the playback of Ogg Theora movies. Use the Graphics.play_movie method.
  • Support has been added for playback of ogg and wav files midway through by using an Audio module.
  • It is now possible to specify button names with symbols by using an Input module. Shorter notations can now be used, such as Input.trigger?(:C).
  • It is now possible to display a message box containing detailed information on syntax errors whenever they occur.

In addition to the above, a number of other minor changes have been made.

In this manual, new functionality, modified specifications, and other changes are followed by RGSS3 in parentheses (RGSS3).

Starting a Game

game folder

Normally, you launch RGSS by double-clicking the icon for the game file, Game.exe (or Game if the Windows option "Hide extensions for known file types" has been turned on). The folder that contains this file is called the game folder.

In-progress games can be started up by selecting [Playtest] from the menu or [Battle Test] from the Troop database. When this is done, the global variable $TEST will be set to true. When performing a Battle Test, the $BTEST variable will also be set to true.

Game operation is specified in Game.ini, the configuration file.

Game.ini

The Game.ini file is automatically created and updated by RPG Maker. It can also be edited manually with Notepad or another text editor.

Example:

[Game]
RTP=RPGVXAce
Library=System\RGSS300.dll
Scripts=Data\Scripts.rvdata2
Title=RubyQuest
RTP

The trademark name of the RGSS-RTP the game is using. Usually "RPGVXAce".

If the specified RTP isn't installed, an error message will be displayed.

Library

The name of the RGSS DLL. The file that was copied to the "System" folder within the game folder is the one that is normally used. (RGSS3)

Scripts

The data file in which scripts are stored. Specified with a relative path to the game folder.

Ruby's scripts usually take the form of text files with the extension .rb, but RGSS uses one proprietary packaged file. This file cannot usually be edited without using RPG Maker's script editor. The data is comprised of multiple sections and is executed in the order lists are displayed.

Title

The game title displayed in the game window's title bar.

RGSS-RTP

An RTP (run-time package) is a mechanism that reduces game data size for distribution. It contains standard graphic and audio resources used across many different games. Installing these resources as a common file before playing a game eliminates the need to download the same files over and over.

RTP files can use the following methods from the built-in game library to access files as though they were in the game folder. The extensions can be left off the file names that are passed to the methods below. Their file types (such as .png or .mid) are identified automatically.

Bitmap.new, Audio.bgm_play, Audio.bgs_play, Audio.me_play, Audio.se_play, Graphics.transition

Installation Data

The only standard RTP for RPG Maker VX Ace is "RPGVXAce", but it is now possible to use RTPs with different structures. If you know how to make an installer, you can create a unique RTP at the user level according to the following rules.

By default, the RTP is installed in the following folder:

[CommonFilesFolder]\Enterbrain\RGSS3\[RTPName]
Here, [CommonFilesFolder] is the location of the Windows "Common Files" folder, while [RTPName] is the name of the RTP. Here's an example:
C:\Program Files\Common Files\Enterbrain\RGSS3\Standard

The RTP installer creates a string value containing the RTP name in the "HKEY_LOCAL_MACHINE\SOFTWARE\Enterbrain\RGSS3\RTP" registry key and uses it to set the path. RGSS recognizes the string specified in this key as the RTP.

Encrypted Archives

Encrypted archives make it difficult for others to analyze and/or modify the game contents. Normally, all data and graphic files (but not audio and font files) are stored in Game.rgss3a. You can create an encrypted archive by checking the [Create encrypted archive] box when compressing the game data.

The files within the encrypted archive can be accessed as though they were in the game folder by using the following methods from the built-in game library:

load_data, Bitmap.new, Graphics.transition

When there is an encrypted archive in the game folder, the script data (normally Data\Scripts.rvdata) defined in the Scripts line of Game.ini will always be read from the archive. This is a limitation that prevents files within the archive from being read by an external script.

Due to its nature, the encrypted archive's internal format has not, and will not, be released to the public. Please refrain from analyzing it.

Other

Extension Libraries

RGSS cannot load Ruby extension libraries written in C. That is why an exception was made to allow the following extension libraries to be treated as if they were built in.

  • dl
  • zlib
  • single_byte
  • utf_16_32
  • japanese_sjis
  • Win32API

Character Set

RGSS uses the UTF-8 character set. UTF-8 is a way of encoding Unicode, a character set that can display letters and characters from all the world's languages.

Script data and other text data output by RPG Maker is all UTF-8, but there is normally no need to pay particular attention to the difference between character sets.

Properties

The term "property" is used in the game library overview. This is not a concept in Ruby's specifications, but rather a term unique to RGSS.

For example, this is how to obtain and set a sprite's x-coordinate (Sprite#x):

x = sprite1.x         # obtain
sprite2.x = x + 32    # set

For the sake of convenience, methods that are defined to both obtain (read) and set (write) via assignment operators in this manner are called "properties".

When objects such as the Color class, the Tone class, or the Rect class are defined as properties, a reference to the object itself is returned to the caller, rather than a copy. This makes it possible to change the color of a font by using this format:

color = font1.color
color.set(255, 0, 0)


Ruby Syntax

  • Syntax and Expressions
    • Identifiers
    • Comments
    • Reserved Words
    • Expressions
  • Variables and Constants
    • Local Variables
    • Instance Variables
    • Class Variables
    • Global Variables
    • Pseudo Variables
    • Constants
  • Literals
    • Number Literals
    • String Literals
      • Backslash Notation
      • Expression Substitution
    • Array Expressions
    • Hash Expressions
    • Range Expressions
    • Symbols
  • Operational Forms
    • Assignment
      • Self-assignment
      • Multiple Assignment
    • and
    • or
    • not
    • Conditional Operators
  • Control Structures
    • Conditional Branching
      • if
      • if Modifier
      • unless
      • unless Modifier
      • case
    • Looping
      • while
      • while Modifier
      • until
      • until Modifier
      • for
      • break
      • next
    • Exception Handling
      • raise
      • begin
      • rescue Modifiers
    • Method Exit
      • return
  • Calling Methods
    • super
    • Iterators
    • yield
  • Class and Method Definitions
    • Class Definitions
    • Module Definitions
    • Method Definitions
      • Method Evaluations
    • Singleton-Method Definitions
    • Class Method Definitions
    • Definition Controls
      • alias


Syntax and Expressions

  • Identifiers
  • Comments
  • Reserved Words
  • Expressions

Ruby is a case-sensitive language. Apart from within identifiers and some literals, spaces and comments may be placed anywhere as needed. Line breaks are treated as spaces only when used to clearly show a line is continuing; otherwise, they are treated as phrase delimiters.

Identifiers

Example:

foobar
ruby_is_simple

An identifier in Ruby begins with an alphabetic character or underscore '_' and consists of alphanumeric characters or underscores '_' . There is no limit on length.

Comments

Example:

# this is a comment line

Strings beginning with # except in a string liteal are considered comments.

Reserved Words

The following are reserved words:

BEGIN    class    ensure   nil      self     when
END      def      false    not      super    while
alias    defined? for      or       then     yield
and      do       if       redo     true
begin    else     in       rescue   undef
break    elsif    module   retry    unless
case     end      next     return   until

Reserved words cannot be used for names of classes, variables, or the like. However, words prefixed by $ or @ are not considered reserved. Furthermore, these words can be used as method names after def, after a method-call period, and in other cases where it is clear that the word is acting as a method name.

Expressions

Example:

true
(1+2)*3
foo()
if test then ok else ng end

The term "expressions" encompasses everything from variables and literals to operational forms and control structures.

A collection of these expressions makes up a Ruby program. Expressions are separated from one another with semicolons (;) or line breaks. However, a line break following a backslash is not considered a new expression boundary; instead, the expression continues on the next line.

Expressions can be grouped with parentheses.


Variables and Constants

  • Local Variables
  • Instance Variables
  • Class Variables
  • Global Variables
  • Pseudo Variables
  • Constants

The type of variable or constant in Ruby--local variables, instance variables, class variables, global variables, and constants--can be determined from its initial character. Normally, a variable has an alphanumeric name (outside of its first character) which can include an underscore, but some built-in variables begin with '$' + one character (see Built-In Variables).

Variables and constants point to specified objects. Assigning objects to variables and constants simply makes them point to new objects; it does not create new copies of objects.

Local Variables

Example:

foobar

Identifiers beginning with a lowercase letter or '_' are local variables or method calls.

Within a local variable's scope (classes, modules, method definitions), the initial assignment to an identifier beginning with lowercase letters is the declaration of that scope's local variable. Referencing undeclared identifiers is considered a call to a method with no arguments.

Instance Variables

Example:

@foobar

Variables beginning with '@' are instance variables and belong to specific objects. Instance variables can be referenced from any method of their class or subclass. When referenced, the value of an uninitialized instance variable is nil.

Class Variables

Example:

class Foo
  @@foo = 1
  def bar
    puts @@foo
  end
end

Variables beginning with @@ are class variables. Class variables are defined within the class definition and can be referenced/assigned from class-unique methods, instance methods, etc.

The differences between class variables and constants are as follows.

  • They may be reassigned (constants will give a warning if this is done).
  • They cannot be directly referenced from outside the class (they may be referenced/assigned from an inherited class).

Global Variables

Example:

$foobar

Variables beginning with '$' are global variables and can be referenced from anywhere in the program (thus requiring some caution when using). Global variables do not need declarations. When referenced, the value of an uninitialized global variable is nil.

Pseudo Variables

Apart from the usual variables, there are also special variables known as pseudo variables.

self

The current method's execution constituent.

nil

The only instance of the NilClass class. Signifies NIL.

true

The only instance of the TrueClass class. Signifies TRUE.

false

The only instance of the FalseClass class. Signifies FALSE.

The value of a pseudo variable cannot be changed. Assigning values to pseudo variables will result in a syntax error.

Constants

Example:

FOOBAR

Identifiers beginning with an uppercase letter are constants. The definition of a constant (and its initialization) depends on its assignment; constants cannot be defined with a method. Accessing an undefined constant throws a NameError exception.

Within the class or module in which a constant is defined, the constant can be referenced by inheriting classes, classes that include modules, and modules. To reference constants externally, use the '::' operator.

class Foo
  FOO = 'FOO'
end

class Bar < Foo
  p FOO             # => "FOO"
end

p Foo::FOO          # => "FOO"

The names of classes and modules are also handled as constants.


Literals

  • Numeric Literals
  • String Literals
    • Backslash Notation
    • Expression Substitution
  • Regular Expression Literals
  • Array Expressions
  • Hash Expressions
  • Range Expressions
  • Symbols

Values that can be expressed directly in Ruby programs, such as the number 1 or the string "hello world", are called literals.

Numeric Literals

123
0d123

integer

-123

integer (signed)

123.45

floating-point number

Floating-point numbers beginning with a decimal point, such as .1, are not allowed. They must be written with a leading zero (0.1).

1.2e-3

floating-point number

0xffff

hexadecimal integer

0b1011

binary integer

0377
0o377

octal integer

Numeric literals can contain an underscore (_). The Ruby interpreter simply ignores these underscores and does not interpret them in a special way. This can be useful as a thousands separator for large values. However, placing an underscore before and after a literal or using consecutive underscores will result in an error.

1_000_000_000   # => 1000000000
0xffff_ffff     # => 0xffffffff

String Literals

Example:

"this is a string expression\n"
'this is a string expression'

String expressions begin and end with double or single quote marks.

Double-quoted string expressions are subject to backslash notation and expression substitution. Single-quoted strings are not (except for \'(single quotation) and \\(backslash itself)).

String literals with a space on either side are treated as a single string literal.

p "foo" "bar"   # => "foobar"

Backslash Notation

The backslash character (\) is the same as the yen sign (¥) used in Japanese fonts.

\t

tab (0x09)

\n

newline (0x0a)

\r

carriage return (0x0d)

\f

form feed (0x0c)

\b

backspace (0x08)

\a

bell (0x07)

\e

escape (0x1b)

\s

space (0x20)

\nnn

character at octal value nnn (n = 0-7)

\xnn

character at hexadecimal value xnn (n = 0-9, a-f)

Expression Substitution

In double-quoted strings and regular expressions, the form "#{expression}" can be extended to the (string of the) contents of that expression. If the expressions are variables beginning with either $ or @, the surrounding braces may be omitted and the variable can be expressed as a #variable. The character # is interpreted literally if it is not followed by the characters {, $, or @. To explicitly prevent expression substitution, place a backslash in front of the #.

$ruby = "RUBY"
p "my name is #{$ruby}"     # => "my name is RUBY"
p 'my name is #{$ruby}'     # => "my name is #{$ruby}"

Regular Expressions Literals

Example:

/^Ruby the OOPL/
/Ruby/i
/my name is #{myname}/

Strings delimited by slashes are regular expressions. Regular expressions are instances of the Regexp class.

Refer to Regular Expressions for more information on which metacharacters are interpreted as regular expressions.

The characters immediately following the final slash denote a regular expression option as follows:

i

The matching regular expression is not case sensitive.

m

Multiple line mode. Newlines are treated as normal characters (matching with the . character).

Ruby correctly handles multibyte characters (such as Chinese and Japanese) in regular expressions.

Backslash notation and expression substitution are available in regular expressions, as in strings.

If a regular expression literal does not include expression substitution, it will return the same regular expression object every time it is evaluated. If expression substitution is included, the regular expression will be compiled with every evaluation (based on the expression substitution results) and a new regular expression object will be created.

Array Expressions

Example:

[1, 2, 3]

Syntax:

'[' expr ',' ... ']'

Returns an array containing the result of each expression. Arrays are instances of the class Array.

Array expressions spawn a new array object every time they are evaluated.

Hash Expressions

Example:

{1=>2, 2=>4, 3=>6}

Syntax:

'{' expr '=>' expr ',' ... '}'
'{' expr ',' expr ',' ... '}'

Returns a new hash object that maps each resulting value to a key. Hashes are instances of the class Hash.

A hash (also called an associative array) can associate one object of an arbitrary type with another.

Hash expressions spawn a new hash object every time they are evaluated.

Range Expressions

Example:

1 .. 20

Syntax:

expr1 '..' expr2
expr1 '...' expr2

If a range expression appears anywhere but a conditional expression, returns the range object from expression 1 to expression 2. Range objects are instances of the class Range.

Range objects spawned by .. operators include the final expression, while those spawned by ... operators do not.

If both ends of a range expression are numeric literals, the expression will return the same object every time it is evaluated. Otherwise, the expression will return a new range object every time it is evaluated.

Symbols

Example:

:class
:lvar
:method
:$gvar
:@ivar
:+

Syntax:

':' identifier
':' variable name
':' operator

Returns symbols that have a one-to-one correspondence with arbitrary strings. Symbols are an instance of the Symbol class.

Symbols are unique objects that return the same object every time they are evaluated.


Operator Expressions

  • Assignment
    • Self-Assignment
    • Multiple Assignment
  • and
  • or
  • not
  • Conditional Operators

Example:

1+2*3/4

Some method calls and control structures take the form of operators for ease in programming. Ruby contains the following operators:

high   ::
       []
       **
       -(unary)  +(unary)  !  ~
       *  /  %
       +  -
       << >>
       &
       |  ^
       > >=  < <=
       <=> ==  === !=  =~  !~
       &&
       ||
       ..  ...
       ?:(conditional operator)
       =(+=, -= ... )
       not
low    and or

"High" and "low" signify the operators' priority level. For example, "&&" has a higher priority than "||", so it would be interpreted in the following way:

a && b || c   # => (a && b) || c
a || b && c   # =>  a || (b && c)

Most operators are method calls in special form, but some are built into the language and cannot be redefined.

  • Redefinable operators (methods)

    +@ and -@ represent the unary operators + and -. This notation is used in method definitions and the like.

    |  ^  &  <=>  ==  ===  =~  >   >=  <   <=   <<  >>
+  -  *  /    %   **   ~   +@  -@  []  []=  `

  • Nonredefinable operators (control structures)

    Combination operators (i.e., self-assignment operators, !=, and !~) cannot be redefined.

    =  ?:  ..  ...  !  not  &&  and  ||  or  ::

Assignment

Example:

foo = bar
foo[0] = bar
foo.bar = baz

Syntax:

variable '=' expr
constant '=' expr
expr '['expr..']' '=' expr
expr '.' identifier '=' expr

Assignment expressions are used to assign values to variables and the like. Assignments can also be used as declarations for local variables or constants. The left side of an assignment expression must be one of the following:

  • a variable

    variable '=' expr

    If there is a variable on the left side, the value of the expression is assigned to the variable.

  • an array reference

    expr1 '[' expr2 ... ']' '=' exprN

    For the object obtained by evaluating expr1, this form is converted into a []= method call with expr2 through exprN as arguments.

    class C
  def initialize
    @ary = [0,1,2,3,4,5,6,7]
  end
  def [](i)
    @ary[i * 2]
  end
  def []=( i, v )
    @ary[i * 2] = v
  end
end
c = C.new
p c[3]      # converted to c.[]( 3 ); result is 6
p c[3] = 1  # converted to c.[]=(3,1); result is 1

  • An attribute reference

    expr1 '.' identifier '=' expr2

    For the object obtained by evaluating expr1, calls the identifier= method with expr2 as an argument.

    class C
  def foo
    @foo
  end
  def foo=( v )
    @foo = v
  end
end
c = C.new
c.foo = 5   # converted to c.foo=( 5 )
p c.foo     # => 5

    Attributes can be defined with attr_accessor in the same way:

    class C
  attr_accessor :foo
end
c = C.new
c.foo = 5   # converted to c.foo=( 5 )
p c.foo     # => 5

Self-Assignment

Example:

foo += 12       # foo = foo + 12
foo *= 3        # foo = foo * 3

Syntax:

expr1 op= expr2     # expr1 is one of the standard left sides of an assignment

op is one of the following. There can be no space between the operator and =.

+, -, *, /, %, **, &, |, ^, <<, >>, &&, ||

In this assignment format, most cases are evaluated as:

expr1 = expr1 op expr2

Multiple Assignment

Example:

foo, bar, baz = 1, 2, 3
foo, = list()
foo, *rest = list2()

Syntax:

expr [',' [ expr ',' ... ] ['*' [ expr ]]] = expr [, expr ... ]['*' expr ]
'*' [ expr ] = expr [, expr ... ]['*' expr ]

Multiple assignment performs assignments from multiple expressions or arrays. Each expression on the left must be assignable. If there is only one expression on the right, its value will be converted into an array whose elements will be assigned to the expressions on the left. If there are more elements in the array than on the left, the extra elements are ignored. If there are too few elements in the array, nil will be assigned to the extra elements on the left.

Prepend * to the final expression on the left to assign all extra left-side elements to that expression as an array. If there are no extra elements, an empty array will be assigned.

foo, bar  = [1, 2]      # foo = 1; bar = 2
foo, bar  = 1, 2        # foo = 1; bar = 2
foo, bar  = 1           # foo = 1; bar = nil
foo, bar  = 1, 2, 3     # foo = 1; bar = 2
foo       = 1, 2, 3     # foo = [1, 2, 3]
*foo      = 1, 2, 3     # foo = [1, 2, 3]
foo, *bar = 1, 2, 3     # foo = 1; bar = [2, 3]

and

Example:

test && set
test and set

Syntax:

expr '&&' expr
expr and expr

First evaluates the left side; if the result is true, evaluates the right side. and does the same as &&, but is a lower priority operator.

or

Example:

demo || die
demo or die

Syntax:

expr '||' expr
expr or expr

First evaluates the left side; if the result is false, evaluates the right side. or does the same as ||, but is a lower priority operator.

not

Example:

! me
not me
i != you

Syntax:

'!' expr
not expr

If the value of the expression is true, returns FALSE; if the value is false, returns TRUE.

The following notation is also possible:

expr '!=' expr          # same as !(expr == expr)
expr '!~' expr          # same as !(expr =~ expr)

Conditional Operators

Example:

obj == 1 ? foo : bar

Syntax:

expr1 ? expr2 : expr3

Returns expr2 or expr3 depending on the results of expr1. This is identical to the following:

if expr1 then expr2 else expr3 end


Control Structures

  • Conditional Branching
    • if
    • if Modifier
    • unless
    • unless Modifier
    • case
  • Looping
    • while
    • while Modifier
    • until
    • until Modifier
    • for
    • break
    • next
  • Exception Handling
    • raise
    • begin
    • rescue Modifier
  • Method Exit
    • return

Unlike in C, control structures in Ruby are expressions that return some sort of value.

Ruby has some control structures inherited from C and Perl, but it also features loop abstraction functionality known as iterators. Iterators are user-definable control structures for looping, etc.

Conditional Branching

if

Examples:

if age >= 12 then
  print "adult fee\n"
else
  print "child fee\n"
end
gender = if foo.gender == "male" then "male" else "female" end

Syntax:

if expr [then]
  expr ...
[elsif expr [then]
  expr ... ]
...
[else
  expr ... ]
end

If a conditional expression is evaluated as true, evaluates the expression beginning with then. If the if expression is false, evaluates the elsif condition. Multiple elsif clauses can be specified; when all if or elsif conditional expressions are false, the else clause expression, if any, is evaluated.

if returns the value of the last evaluated expression in the conditional expression clause (or else clause). If there is no else clause and no conditional expression in effect, returns nil.

In Ruby, the values false and nil are false; everything else, including zero and empty text strings, is true.

Note that Ruby uses elsif after if, not else if and not elif.

if Modifier

Example:

print "debug\n" if $DEBUG

Syntax:

expr if expr

Evaluates and returns the result of the expression on the left if the condition on the right is true. If the condition is not in effect, returns nil.

unless

Example:

unless baby?
  feed_meat
else
  feed_milk
end

Syntax:

unless expr [then]
  expr ...
[else
  expr ... ]
end

unless is the reverse of if; if the conditional expression is false, evaluates the expression beginning with then. elsif cannot be specified with unless.

unless Modifier

Example:

print "stop\n" unless valid(passwd)

Syntax:

expr unless expr

Evaluates and returns the result of the expression on the left if the condition on the right is false. If the condition is not in effect, returns nil.

case

Example:

case $age
when 0 .. 2
  "baby"
when 3 .. 6
  "little child"
when 7 .. 12
  "child"
when 13 .. 18
  "youth"
else
  "adult"
end

Syntax:

case expr
[when expr [, expr] ... [then]
  expr ..]..
[else
  expr ..]
end

case expressions execute branching for a single expression via matching. Comparisons of values specified in a when clause to the evaluated result of the first expression are performed by the === operator. When the values match, evaluates the contents of the when clause.

case returns the result of the last evaluated expression in a conditional when (or else) clause. If neither condition is in effect, returns nil.

Looping

while

Example:

ary = [0,2,4,8,16,32,64,128,256,512,1024]
i = 0
while i < ary.length
  print ary[i]
  i += 1
end

Syntax:

while expr [do]
   ...
end

Executes the contents of an expression as long as the expression remains true.

while returns nil. Alternatively, the while return value can also be the value of an argument to a break.

while Modifier

Example:

sleep(60) while io_not_ready?

Syntax:

expr while expr

Repeatedly executes the expression on the left as long as the expression on the right is evaluated as true. If the expression on the left is begin, while evaluates it first before looping.

The while modifier returns nil. Alternatively, the while modifier return value can also be the value of an argument to a break.

until

Example:

until f.eof?
  print f.gets
end

Example:

until expr [do]
   ...
end

Repeatedly executes the expression until it is evaluated as true.

until returns nil. Alternatively, the until return value can also be the value of an argument to a break.

until Modifier

Example:

print(f.gets) until f.eof?

Syntax:

expr until expr

Repeatedly executes the expression on the left until the expression on the right is evaluated as true. If the expression on the left is begin, the until modifier evaluates it first before looping.

The until modifier returns nil. Alternatively, the until modifier return value can also be the value of an argument to a break.

for

Example:

for i in [1, 2, 3]
  print i*2, "\n"
end

Syntax:

for lhs ...  in expr [do]
  expr ..
end

Repeatedly executes the contents for each evaluated object element. This is approximately identical to the following:

(expr).each '{' '|' lhs..'|' expr .. '}'

It is only approximately identical because while blocks defined by do ... end or by { } introduce a new block scope for local variables, while for has no effect on the scope of local variables.

for returns the return value of the each method for the objects specified in in.

break

Example:

i = 0
while i < 3
  print i, "\n"
  break
end

Syntax:

break [expr]

break escapes from the innermost loop. A "loop" is one of the following:

  • while
  • until
  • for
  • an iterator

Unlike in C, break can only escape from loops. It does not exit from case.

for or an iterator that has escaped from a loop via break returns nil. However, if an argument is specified, the loop's return value will become that argument.

next

Example:

str.each_line do |line|
  next if line.empty?
  print line
end

Syntax:

next [expr]

next jumps to the next iteration of the innermost loop. In an iterator, next is an escape for a yield call.

A yield that has escaped via next returns nil. However, if an argument is specified, the return value of yield will be that argument.

Exception Handling

raise

Examples:

raise
raise "you lose"
raise SyntaxError.new("invalid syntax")
raise SyntaxError, "invalid syntax"

Syntax:

raise
raise message
raise exception
raise error_type, message

Throws an exception. In the first format, throws the last exception again. In the second format, given a string argument, throws a RuntimeError exception with the given string as a message. In the third format, throws the exception if the argument is an exception object. In the last format, throws the exception specified in the first argument with the message given in the second argument.

Thrown exceptions can be trapped with a rescue clause in the begin expression.

raise is not a reserved word in Ruby, but rather a built-in function.

begin

Example:

begin
  do_something
rescue
  recover
ensure
  must_to_do
end

Syntax:

begin
  expr ..
[rescue [error_type,..] [then]
  expr ..]..
[ensure
  expr ..]
end

If an exception is thrown while begin is being executed, a rescue clause can trap the exception. Multiple clauses can be specified. If a rescue clause with a matching exception type exists, it is executed. The thrown exception can be referenced with the built-in variable $!.

When error_type is omitted, it traps all exceptions in the StandardError subclasses, of which most built-in exceptions in Ruby are members. See Built-in Exception Classes.

In rescue clauses, error_type is evaluated in the same way as an argument. If any value matches, the clause will be executed. If the value of error_type is not a class or a module, rescue throws a TypeError exception.

If there is an ensure clause, its contents are always evaluated immediately before a begin expression exits.

begin returns the result of the final argument evaluated in either its contents or in the rescue clause.

rescue Modifier

Example:

File.open("file") rescue print "can't open\n"

Syntax:

expr1 rescue expr2

When an exception is thrown in the first expression, evaluates the second expression. You cannot specify the exception class(es) to be trapped. In other words, you can only trap the subclasses of the StandardError exception class.

Expressions associated with the rescue modifier return expr1 if no exception is thrown and expr2 if an exception is thrown.

Method Exit

return

Example:

return
return 12
return 1,2,3

Syntax:

return [expr[',' expr ... ]]

Exits from a method with the return value. If two or more expressions are provided, the method's return value will consist of an array containing those values. If the expression is omitted, the return value will be nil.


Method Calls

  • super
  • Iterators
  • yield

Example:

foo.bar()
foo.bar
bar()
print "hello world\n"
print

Syntax:

[expr '.'] identifier ['(' expr ... ['*' [expr]] ')']

Method calls invoke the method of the receiver (the value of the expression to the left of the dot). If no receiver is specified, calls the method of self.

Method names can be normal identifiers or identifiers followed by the character ? or !. Customarily, ? is used for predicates (methods returning true/false values), while ! is used for methods that are more destructive than their !-less counterparts (tr versus tr!).

If the last argument is preceded by *, the value of that expression is expanded to its arguments.

foo(*[1,2,3])   # same as foo(1,2,3)

super

Example:

super
super(1,2,3)

Syntax:

super
super(expr , ... )

super calls the method that is being overridden by the current method. If the parentheses and arguments are omitted, the current method's arguments are passed to super as is. To call the overridden method without passing any arguments, indicate the parentheses as in super().

class Foo
  def foo(arg=nil)
    p arg
  end
end

class Bar < Foo
  def foo(arg)
    super(5)       # called with 5 as an argument
    super(arg)     # called with 5 as an argument
    super          # called with 5 as an argument; abbreviation of super(arg)
    arg = 1
    super          # called with 1 as an argument; abbreviation of super(arg)
    super()        # called with no argument
  end
end
Bar.new.foo 5

Iterators

Example:

[1,2,3].each do |i| print i*2, "\n" end
[1,2,3].each {|i| print i*2, "\n" }

Syntax:

method(arg1, arg2, ...)  do ['|' expr ... '|'] expr ... end
method(arg1, arg2, ...) '{' ['|' expr ... '|'] expr ... '}'

Iterators are methods used for abstracting control structures (especially loops). If you call a method that is followed by a code segment enclosed by do ... end or by { ... } (called a block), the method can evaluate the block from within. Methods that call these kinds of blocks are called iterators. Block calls from iterators use yield. The value passed to yield is assigned to the variable between the two pipes ( | ).

{ ... } binds more strongly than a do ... end block.

foobar a, b do .. end   # foobar is called as an iterator
foobar a, b { .. }      foobar a, b { .. }      # b is called as an iterator

Local variables that are first assigned (declared) in a block are only valid within that block.

foobar {
  i = 20                # local variable 'i' is declared
   ...
}
                        # 'i' is undefined here
foobar a, b do
  i = 11                # declaration of a totally different variable 'i'
   ...
end

Like most methods, an iterator's return value is nil if it is interrupted by break from within a block. When break has an argument, that value will become the iterator's return value.

yield

Example:

yield data

Syntax:

yield '(' [ expr [',' expr ... ]] ')'
yield [ expr [',' expr ... ]]

Passes the argument(s) as the block's argument(s) and evaluates the block. yield is used within Method Definition to define iterators.

def foo
  yield(1,2)
end

foo {|a,b| p [a,b]}

Assignment of the block argument(s) is carried out according to the rules of multiple assignment. If no block is supplied to the method that executed yield (i.e., it is not an iterator), throws a LocalJumpError exception.

yield returns the result of the block's last evaluated expression. If block execution has been interrupted by next, returns nil. When next has an argument, that value will become yield's return value.


Class and Method Definitions

  • Class Definitions
  • Module Definitions
  • Method Definitions
    • Method Evaluation
  • Singleton-Method Definitions
  • Class Method Definitions
  • Definition Operations
    • alias

Class Definitions

Example:

class Foo < Super
  def test
     :
  end
     :
end

Syntax:

class identifier ['<' superclass ]
  expr ..
end

Defines a class. Class names are identifiers beginning with an uppercase letter.

Class definitions assign a class to a constant specified by an identifier. In Ruby, classes, too, are objects and one instance of the Class class.

When a class is already defined, writing a class definition with the same class name will add to the existing class definition.

class Foo < Array
  def foo
  end
end

class Foo
  def bar
  end
end

In a class definition, self is that class itself; otherwise, it is no different from a top-level definition. Class definitions can contain arbitrary expressions that will be executed when the class is defined.

Class definitions can operate as nests. In the following example, there is absolutely no functional relationship (such as inheritance) between the outer class Foo and the inner class Bar, other than the fact that the constant Bar is Foo's inner constant Foo::Bar. Class nests group together semantically related classes into the outer class or module, and can be used to express an inclusion relationship.

class Foo
  class Bar
  end
end

Class definitions return the result of the last evaluated expression. If that expression does not return a value, the class definition returns nil.

Module Definitions

Example:

module Foo
  def test
     :
  end
     :
end

Syntax:

module identifier
  expr ..
end

Defines a module. Module names are identifiers beginning with an uppercase letter.

Module definitions assign a module to a constant specified by an identifier. In Ruby, modules, too, are objects and one instance of the Module class.

When a module is already defined, writing a module definition with the same module name will add to the existing module definition.

Module definitions return the result of the last evaluated expression. If that expression does not return a value, the module definition returns nil.

Method Definitions

Example:

def fact(n)
  if n == 1 then
     1
  else
    n * fact(n-1)
  end
end

Syntax:

def methodname ['(' [arg ['=' default]] ... [',' '*' arg] ')']
  expr ..
[rescue [error_type,..] [then]
  expr ..]..
[ensure
  expr ..]
end

Defines a method, or in other words, defines the method of a class or module if within the definition of that class or module. If top-level, defines methods that can be called from anywhere. This kind of method can be used like functions are in other scripting languages.

Method names can be normal identifiers or redefinable operators (==, +, -, and so on; see Operator Expressions).

When a default expression has been provided to a dummy argument, it becomes the default value when the actual argument is omitted through a method call. The default expression is evaluated at the time of the call and in the context of the method definition.

When the last dummy argument has a * immediately before it, the remaining actual arguments are all stored in this argument as an array.

Example:

# method with no argument. end omitted below
def foo
end

# method with arguments
def foo(arg, arg2)

# method with default argument
def foo(arg = nil)

# with everything
def foo(arg, arg2, arg3 = nil, *rest)

# operator format
def ==(other)
def +(other)
def *(other)

For method definition, each type of dummy argument can only be specified according to the following sequence. Any of the following arguments can be omitted:

  • arguments without default expressions (can specify multiple arguments)
  • arguments with default expressions (can specify multiple arguments)
  • arguments with * (can specify only one)

The following method definitions have special formats:

# unary plus/minus
def +@
def -@

# element substitution
def foo=(value)             # obj.foo = value

# [] and []=
def [](key)                 # obj[key]
def []=(key, value)         # obj[key] = value
def []=(key, key2, value)   # obj[key, key2] = value

Furthermore, a begin expression as well as rescue and/or ensure clauses can be specified to trap exceptions when executing a method.

Method definition returns nil.

Method Evaluation

When a method is called, its expressions are evaluated in the following order:

  • Default expressions in arguments (when specified)
  • The method itself
  • The method's rescue or else clauses (when specified), depending on whether an exception has been thrown
  • The ensure clause (when specified)

Everything is evaluated in the method's context, including the argument's default expression.

The method's return value is the value passed to return. When return is not called, returns the value of the last evaluated expression in the method, before any ensure clause is executed.

Methods cannot be called before they are defined. Take the following example:

foo
def foo
  print "foo\n"
end

Calling an undefined method, as in the above example, throws a NameError exception.

Singleton-Method Definitions

Example:

def foo.test
  print "this is foo\n"
end

Syntax:

def expr '.' identifier ['(' [ argument ['=' default]] ... [',' '*' argument ]')']
  expr ..
[rescue [error_type,..] [then]
  expr ..]..
[else
  expr ..]
[ensure
  expr ..]
end

A singleton method belongs to a certain object and not to a class. Singleton-method definitions can be nested.

The singleton methods of a class carry over to its subclasses. In other words, they act like the class methods in other object-oriented languages.

Singleton-method definitions return nil.

Class Method Definitions

In Ruby, class methods are the methods specific to a class. Classes are also objects, so these singleton methods can be defined like regular objects.

Therefore, when a method in a class object is defined in some way, that object becomes a class method. Specifically, these methods can be defined in the following way (as can modules):

# singleton method
class Hoge
  def Hoge.foo
  end
end

# can use outside class definition, too
def Hoge.bar
end

# even if the class name changes, you don't have to change the method
class Hoge
  def self.baz
  end
end

Definition Operations

alias

Example:

alias foo bar
alias :foo :bar

Syntax:

alias newmethod oldmethod

Assigns an alias to a method or global variable. Specifies an identifier or a Symbol as the method name (expressions like obj.method are not permitted). alias's argument performs no evaluation of method calls or the like.

An aliased method carries over that method definition, retaining it even if the original method is redefined. This can be used when you want to change the actions of a given method, then use the result of the original method in the redefined method.

# defining method "foo"
def foo
  "foo"
end

# setting alias (retracting method definition)
alias :_orig_foo :foo

# "foo" redefined (using the old definition)
def foo
  _orig_foo * 2
end

p foo  # => "foofoo"

alias returns nil.


Standard Library

  • Built-in Functions
  • Built-in Variables
  • Built-in Classes
    • Object
      • Array
      • Exception
      • FalseClass
      • Fiber
      • Hash
      • IO
        • File
      • MatchData
      • Method
      • Module
        • Class
      • NilClass
      • Numeric
        • Integer
          • Bignum
          • Fixnum
        • Float
      • Proc
      • Range
      • Regexp
      • String
      • Symbol
      • Time
      • TrueClass
  • Built-in Modules
    • Comparable
    • Enumerable
    • Errno
    • FileTest
    • GC
    • Kernel
    • Marshal
    • Math
  • Built-in Exception Classes


Built-in Functions

Strictly speaking, Ruby does not have functions, but since methods defined in the Kernel module can be called from anywhere, they can be used like functions are in other languages. Carefully consider the repercussions of redefining the methods here.

block_given?

Returns true if the method has been supplied with a block; otherwise, returns false. See Iterators for more information.

catch(tag) {|tag| .... }

Executes the block and returns its value. If a throw with the same name as tag takes place while the block is running, the return value will be that throw's second argument.

break cannot break out of all nested loops at once. Use catch in these circumstances.

catch(:loop1) {
  for i in 1..2
    for j in 1..2
      throw :loop1, j
    end
  end
}
eval(expr)

Evaluates the string expr as a Ruby program and returns the result.

exit

Exits a running Ruby program.

exit throws a SystemExit exception to terminate the program, so it can be trapped by a rescue clause where necessary.

loop { ... }

Evaluates a block in an infinite loop (until explicitly terminated).

open(file[, mode])
open(file[, mode]) {|io| ... }

Opens file and returns a File object. mode specifies one of the following strings. When mode is omitted, the default is "r".

  • "r": Opens the file in read mode.
  • "w": Opens the file in write mode. If a file already exists when file is opened, the previous file's contents will be deleted.
  • "a": Opens file in write mode. Output will always be appended to the end of the file.

Using "+" opens the file in read-write mode (RDWR):

  • "r+": Sets the read-write position to the beginning of the file.
  • "w+": The same as "r+", but if a file already exists when file is opened, the previous file's contents will be deleted.
  • "a+": The same as "r+", but if a file already exists when file is opened, the read-write position will be set to the end of the file.

The "b" flag can also be added to any of these (in the format "r+b") to open the file in binary mode.

When open is called along with a block, it opens the file, executes the block, then closes the file when execution is complete. The result of the block evaluation is returned in that case. See the following code sample.

open(path, mode) do |f|
   ...
end

# almost identical to the above
f = open(path, mode)
begin
   ...
ensure
  f.close
end
p(obj, [obj2, ...])

Outputs obj in a human-readable format. Identical to the following code (see Object#inspect):

print obj.inspect, "\n", obj2.inspect, "\n", ...

Returns nil.

print(arg[, ...])

Prints the arguments in order. If a non-string object has been supplied as an argument, it will be converted into a string with to_s and printed. However, if the argument is nil, it will print the string "nil".

Returns nil.

printf(format[, arg[, ...]])

Converts arguments to text according to format and outputs them, just like with printf in C. If no arguments are specified, does nothing.

See the sprintf Format page for more information on format string extension in Ruby.

Returns nil.

putc(ch)

Outputs the text ch. Outputs a string between 0 and 255 if ch is a number. Outputs the text at the beginning if ch is a text string.

Returns ch.

putc("ch")
putc(?c)
putc(99)
# => ccc
puts([obj[, obj2[, ....]]] )

Outputs obj and a line feed in that order. Outputs only a line feed if there are no arguments.

If the argument is an array, its elements and a line feed are output in that order. If an object other than an array or a character string is given as an argument, an attempt is made to first convert it to an array with to-ary and then to a character string with the to_s method. For nil, however, the string "nil" is output.

For arguments that end with a line feed, puts itself does not output a line feed.

puts "foo", "bar\n", "baz"
puts ""    # Only outputs a line feed
puts       # Only outputs a line feed
puts "foo"
=> foo
   bar
   baz

   foo

Returns nil.

raise
raise(message)
raise(exception)
raise(error_type, message)

Throws an exception. See raise for more information.

rand([max=0])

Creates a random integer in the range 0 ≤ integer < max. Automatically calls srand if it hasn't already been called.

If max is nil or 0, uses Float to return a random number in the range 0 ≤ real number < 1.

sprintf(format[, arg[, ...]])

Interprets the string format as does C's sprintf, returning a string of formatted arguments.

See sprintf Format for more information.

srand([seed])

Sets the rand random number seed and returns the old initial value. If seed is omitted, uses the current time (or a similar value) as the seed.

throw(tag[, value])

Escapes (across methods) to the end of a catch block with the same tag. If there is no catch with the same tag, the thread terminates with NameError. tag is a character string or symbol. value will be the return value of the catch.


Built-in Variables

Built-in variables are a type of global variable, but their values are not only used globally.

The following are examples of built-in variables categorized by their scope.

Local Scope

$~

The information about the last match in the current scope (MatchData object). Setting this variable changes the values of $&, $1 ... $9 and so on.

Identical to Regexp.last_match.

$&

The string matched by the last successful regular expression pattern match in this scope, or nil if the last pattern match failed.

Identical to Regexp.last_match[0]

$1
$2
$3 ...

Contains the subpattern from the corresponding set of parentheses in the last successful pattern matched, or nil if the last pattern match failed.

Identical to Regexp.last_match[1], Regexp.last_match[2], ...

Global Scope

$!

Information on the latest exception. Set with raise.

$DEBUG

The debug mode flag.


Built-in Classes

  • Object
    • Array
    • Exception
    • FalseClass
    • Fiber
    • Hash
    • IO
      • File
    • MatchData
    • Method
    • Module
      • Class
    • NilClass
    • Numeric
      • Integer
        • Bignum
        • Fixnum
      • Float
    • Proc
    • Range
    • Regexp
    • String
    • Symbol
    • Time
    • TrueClass


Object

The superclass of all classes. Defines the general behavior of objects.

Included Modules

  • Kernel

Methods

self == other

Checks whether self and other are equal. By default, has the same effect as equal?.

This method must be redefined with respect to each class's properties.

self === other

This method is mainly used for comparison within case statements. By default, acts like Object#==, but this behavior can be redefined in the subclass to implement an ownership check.

class

Returns the receiver class.

clone
dup

Creates a copy of the object. clone returns a complete clone of the original object, including freeze status and singleton methods, while dup duplicates the object contents only.

Note that clone and dup perform only a shallow copy. They duplicate the object itself, but nothing it points to (such as array elements).

For duplicated objects,

obj.equal?(obj.clone)

generally does not hold, while

obj == obj.clone

is correct in most cases.

Attempting to duplicate true, false, nil,Numeric objects, Symbol objects, and the like results in TypeError exceptions.

equal?(other)

When other is self, returns true. This method must not be redefined.

freeze

Prohibits an object's contents from being modified. Modifying a frozen object throws a TypeError exception.

frozen?

Returns true if the object's contents are prohibited from being modified.

inspect

Returns the object in a human-readable string format.

instance_of?(klass)

Returns true if self is a direct instance of the class klass. When obj.instance_of?(c) is true, obj.kind_of?(c) is always true as well.

instance_variable_get(var)

Gets and returns the value of the object's instance variables.

Specify the instance variable name for var using a character string or a Symbol.

Returns nil if the instance variable is undefined.

class Foo
  def initialize
    @foo = 1
  end
end

obj = Foo.new
p obj.instance_variable_get("@foo")     # => 1
p obj.instance_variable_get(:@foo)      # => 1
p obj.instance_variable_get(:@bar)      # => nil
instance_variable_set(var, val)

Sets object's instance variable to value val and returns val.

Specify the instance variable name for var using a character string or a Symbol.

A new instance variable is defined if one has not already been.

obj = Object.new
p obj.instance_variable_set("@foo", 1)  # => 1
p obj.instance_variable_set(:@foo, 2)   # => 2
p obj.instance_variable_get(:@foo)      # => 2
instance_variables

Returns the object's instance variable name as a string array.

obj = Object.new
obj.instance_eval { @foo, @bar = nil }
p obj.instance_variables

# => ["@foo", "@bar"]
is_a?(mod)
kind_of?(mod)

Returns true if self is the class mod (or its subclass) or a class (or its subclass) that includes the module mod.

module M
end
class C < Object
  include M
end
class S < C
end

obj = S.new
p obj.is_a? S       # true
p obj.is_a? M       # true
p obj.is_a? C       # true
p obj.is_a? Object  # true
p obj.is_a? Hash    # false
method(name)

Returns the Method object that encapsulated the name method of self in an object. name is specified with a Symbol or character string.

nil?

Returns true if the receiver is nil.

respond_to?(name[, priv=false])

Returns true if the object has the public method name.

name is a Symbol or character string. Returns true even for the private method if priv is true.

send(name[, args ... ])
send(name[, args ... ]) { .... }

Calls args to the argument, calls the object's name method, and returns the result of the method.

Passes the block as is when called with a block. The method name name is a character string or Symbol.

object_id

Returns a unique integer for each object. The integers are assigned to objects arbitrarily.

to_ary

Called internally when an object's implicit conversion to an array is required.

to_hash

Called internally when an object's implicit conversion to a hash is required.

to_int

Called internally when an object's implicit conversion to an integer is required.

to_s

Returns the string representation of the object.

When non-string objects are passed to arguments in print and sprintf, use this method to convert the objects to strings.

to_str

Called when an object's implicit conversion to a string is required.

Private Method

initialize

The object initialization method for user-defined classes. This method is called from Class#new to initialize a newly created object. The default behavior is to do nothing, as it is assumed that this method will be redefined in the subclass as needed. The argument given to Class#new will be passed to initialize as is.


Array

The array class. The elements of an array are arbitrary Ruby objects. See Array Expressions for more information.

Superclass

  • Object

Included Module

  • Enumerable

Class Methods

Array[item,...]

Creates an array with arguments as its elements.

Array.new([size[, val]])
Array.new(ary)
Array.new(size) {|index| ... }

Creates an array. When size is specified, an array of that size is created, and it is initialized by nil. If the second argument val is also specified, the object is set to all elements instead of nil. (Note that this does not mean that val is duplicated for each element. References the object val with all the same elements trap::Array).

The second format duplicates and returns the array specified in the argument.

p Array.new([1,2,3]) # => [1,2,3]

The third format sets a value with the evaluation results of the block. The block is executed for each element, so it is possible make all elements a duplicate of a certain object.

p Array.new(5) {|i| i }         # => [0, 1, 2, 3, 4]

ary = Array.new(3, "foo")
ary.each {|obj| p obj.object_id }
# => 537774036
     537774036
     537774036

ary = Array.new(3) { "foo" }
ary.each {|obj| p obj.object_id }
# => 537770448
     537770436
     537770424

Methods

self[nth]

Retrieves the nth item from an array. The index starts from zero. If the nth value is negative, counts backward from the end of the array (the index of the last element is -1). If the nth element does not exist in the array, returns nil.

self[start, length]

Returns an array containing length items from start. If the start value is negative, counts backward from the end of the array (the index of the last element is -1).If length is longer than the length of the array from start, the length of the overlong portion is ignored. Returns nil if length is negative.

self[nth]=val

Changes the nth element of the array into val. If nth is outside the array range, the array will automatically be extended. The extended region will be initialized by nil.

Returns val.

self[start, length]=val

Replaces the length items from index start with the contents of val. If val is not an array, the items will be replaced by the contents of val.to_ary or [val]. Returns val.

ary = [0, 1, 2, 3]
ary[1, 2] = ["a", "b", "c"]
p ary                        # => [0, "a", "b", "c", 3]
ary[2, 1] = 99
p ary                        # => [0, "a", 99, "c", 3]
ary[1, 0] = ["inserted"]
p ary                        # => [0, "inserted", "a", 99, "c", 3]
self + other

Returns a new array with the concatenated contents of self and other. If other is not an array, uses the return value of other.to_ary. If that return value is not an array, throws a TypeError exception.

a = [1, 2]
b = [8, 9]
p a + b     # => [1, 2, 8, 9]
p a         # => [1, 2]        (no change)
p b         # => [8, 9]        (no change here, either)
self * times

Creates and returns a new array that iterated the contents of the array.

p [1, 2, 3] * 3  #=> [1, 2, 3, 1, 2, 3, 1, 2, 3]
self - other

A set subtraction operation. Returns a new array containing self without the elements of other.

self & other

A set intersection operation. Returns a new array containing elements belonging to both arrays. Duplicate elements will be removed.

self | other

A set union operation. Returns a new array containing all elements belonging to either array. Duplicate elements will be removed.

self <=> other

Compares each element with <=> and returns positive integer if self is greater than, 0 if equal to, or a negative integer if less than other. If the end of one array is reached with each element being equal, the shorter array will be treated as being the lesser of the two.

self == other

Compares each element with == and returns TRUE if all elements are equal.

clear

Deletes all elements of an array, making it empty. Returns self.

ary = [1, 2]
ary.clear
p ary     # => []
clone
dup

Returns a new array with the same contents as the receiver. clone returns a complete clone of the original array, including freeze status and singleton methods, while dup duplicates the object contents only. Neither method copies the methods or elements themselves.

compact
compact!

compact returns a new array consisting of self without any nil elements. compact! performs a destructive update; if modified, returns self, if not modified, returns nil.

ary = [1, nil, 2, nil, 3, nil]
p ary.compact   # => [1, 2, 3]
p ary           # => [1, nil, 2, nil, 3, nil]
ary.compact!
p ary           # => [1, 2, 3]
p ary.compact!  # => nil
concat(other)

Appends (destructively) the other array to the end of self. Returns self.

array = [1, 2]
a     = [3, 4]
array.concat a
p array          # => [1, 2, 3, 4]
p a              # => [3, 4]       # this doesn't change
delete(val)
delete(val) { ... }

Deletes all elements equal to val (via ==). When elements equal to val are found, returns val.

If there are no elements equal to val, returns nil. However, if a block has been specified, it will be evaluated and the result returned.

array = [1, 2, 3, 2, 1]
p array.delete(2)       # => 2
p array                 # => [1, 3, 1]

# if the argument is nil and there's no block, there's no way
# to determine from the return value whether it was deleted
ary = [nil,nil,nil]
p ary.delete(nil)       # => nil
p ary                   # => []
p ary.delete(nil)       # => nil
delete_at(pos)

Removes the element at the position specified by pos and returns the removed element. If pos is out of range, returns nil.

array = [0, 1, 2, 3, 4]
array.delete_at 2
p array             # => [0, 1, 3, 4]
delete_if {|x| ... }
reject! {|x| ... }

Passes elements to the block in order and evaluates them, deleting all those for which the result is true.

delete_if always returns self, while reject! will return self if one or more elements are deleted and nil if none are deleted.

each {|item| .... }

Evaluates a block for each element. Returns self.

# 1, 2, 3 are displayed in order
[1, 2, 3].each do |i|
  puts i
end
each_index {|index| .... }

Evaluates a block for each element's index. Identical to the following:

(0 ... ary.size).each {|index| ....  }

Returns self.

empty?

Returns TRUE if the number of elements in the array is zero.

include?(val)

Returns TRUE if the array contains an element equal to val (using ==).

index(val)

Returns the position of the first element equal to val (using ==). If no such element is found, returns nil.

insert(nth, [val[, val2 ...]])

Inserts the value of the second or later arguments immediately before the nth element. Returns self. Defined as follows:

class Array
  def insert( n, *vals )
    self[n, 0] = vals
    self
  end
end

ary = ["foo", "bar", "baz"]
ary.insert 2, 'a', 'b'
p ary                  # => ["foo", "bar", "a", "b", "baz"]

If no argument val is specified, does nothing.

length
size

Returns the length of the array. If the array is empty, returns zero.

nitems

Returns the number of non-nil elements.

pop

Removes the last element and returns it. If the array is empty, returns nil.

array = [1, [2, 3], 4]
p array.pop      # => 4
p array.pop      # => [2, 3]
p array          # => [1]

p array.pop      # => 1
p array.pop      # => nil
p array          # => []
push(obj1[, obj2 ...])

Appends obj1, obj2 ... to the end of the array, in order.

Returns self.

array = [1, 2, 3]
array.push 4
array.push [5, 6]
array.push 7, 8
p array          # => [1, 2, 3, 4, [5, 6], 7, 8]
reverse
reverse!

reverse returns a new array of all elements in reverse order. reverse! destructively updates the elements in the array.

reverse always returns a new array, while reverse! returns self.

shift

Removes the first element of the array and returns it. The remaining elements are moved up to fill the gap. If the array is empty, returns nil.

sort
sort!
sort {|a, b| ... }
sort! {|a, b| ... }

Sorts the contents of the array. If called with a block, it passes two arguments to the block, then uses the result to compare. Without a block, it compares elements with the operator <=>. sort! destructively updates the elements in the array.

sort returns a new, sorted array, while sort! always returns self.

uniq
uniq!

uniq returns a new array by removing duplicate elements. The remaining elements will then be shifted forward to fill the gaps. uniq! performs destructive deletion and returns self if deletion was performed and nil if it was not.

unshift(obj1[, obj2 ...])

Inserts obj1, obj2 ... to the start of the array, in order.

Returns self.


Exception

The ancestor class of all exceptions.

Refer to Built-in Exception Classes for information on its subclasses.

Superclass

  • Object

Class Method

Exception.new([error_message])

Creates and returns a new exception object. A string representing an error message can be supplied as an argument. This message will become the value of the message attribute (below) and will be displayed by the default exception handler.

Methods

exception([error_message])

Returns self when no argument is specified. Otherwise, creates a copy of itself with the message attribute as error_message and returns it.

raise essentially calls the Exception object's exception method.

backtrace

Returns backtrace information.

  • "#{sourcefile}:#{sourceline}:in `#{method}'"

    (within methods)

  • "#{sourcefile}:#{sourceline}"

    (at the top level)

A String array of this format.

message

Returns the error message string.


FalseClass

The false class. false is the only instance of the FalseClass class. false, like nil, denotes a FALSE condition, while all other objects are TRUE.

Superclass

  • Object

Methods

self & other

Always returns FALSE.

self | other
self ^ other

If other is TRUE, returns TRUE. If FALSE, returns FALSE.


Fiber

Provides a non-preemptive lightweight thread (fiber), also known as a coroutine or a semicoroutine in other programming languages.

A fiber's context does not change unless explicitly specified. A fiber also has a parentage. The fiber that called Fiber#resume is the parent, and the fiber that was called is the child. Transitions that destroy parentage (for example, switching to a parent fiber of one's own parent) are not allowed. They will result in a FiberError exception. The following two actions are possible:

  • Fiber#resume switches the context to the child.
  • Fiber.yield switches the context to the parent.

This parentage is dynamic, and is dissolved upon switching the context to the parent fiber.

When a fiber ends, the context switches to its parent.

Superclass

  • Object

Short Tutorial

Fibers are used to switch the context to another routine at a processing point and to resume from that point. Fiber.new creates a fiber along with the provided block. Calling Fiber#resume for a created fiber switches the context. Calling Fiber.yield within the child fiber's block switches the context to the parent. The arguments of Fiber.yield are the return values of Fiber#resume on the parent.

f = Fiber.new do
  n = 0
  loop do
    Fiber.yield(n)
    n += 1
  end
end

5.times do
  p f.resume
end

#=> 0
    1
    2
    3
    4

Singleton Method

new {|obj| ... }

Creates and returns a fiber along with the provided block. The block is executed with the provided arguments as its arguments.

The context switches to the parent when the block ends. The block's evaluated value is returned at that time.

a = nil
f = Fiber.new do |obj|
  a = obj
  :hoge
end

b = f.resume(:foo)
p a  #=> :foo
p b  #=> :hoge
yield(*arg = nil)

Switches the context to the parent of the current fiber.

The yield method returns the provided arguments to Fiber#resume when switching the context.

For arg, specify the object to pass to the parent of the current fiber.

a = nil
f = Fiber.new do
  a = Fiber.yield()
end

f.resume()
f.resume(:foo)

p a  #=> :foo

Instance Method

resume(*arg = nil)

Switches the context to the fiber represented by self, which is the child of the fiber that called resume.

The resume method returns the arguments provided to Fiber.yield when switching the context.

For arg, specify the object to pass to the fiber represented by self.

f = Fiber.new do
  Fiber.yield(:hoge)
end

a = f.resume()
f.resume()

p b  #=> :hoge


Hash

The hash class. See Hash Expressions for more information.

Superclass

  • Object

Included Modules

  • Enumerable

Methods

self[key]

Returns the value mapped to key. If the corresponding key is not registered returns the default value (or nil if not specified).

self[key]=value

Maps value to key. Returns value.

clear

Clears the hash contents. Returns self.

clone
dup

Returns a new hash with the same contents as the receiver. Using clone on a frozen hash will return a similarly frozen hash, but dup returns an unfrozen hash with identical contents.

Returns value.

delete(key)
delete(key) {|key| ... }

Deletes the mapping from key. Returns the removed value, or nil if there is no value corresponding to key.

Evaluates a block if it is supplied but there are no matches with key and then returns the result.

each {|key, value| ... }
each_pair {|key, value| ... }

Evaluates a block with key and value as arguments. Returns self.

each_key {|key| ... }

Evaluates a block with key as the argument. Returns self.

each_value {|value| ... }

Evaluates a block with value as the argument. Returns self.

empty?

Returns true if the hash is empty.

has_key?(key)
include?(key)

Returns true if the hash includes key as a key.

has_value?(value)

Returns true if the hash includes value as a value as determined by ==.

index(val)

Returns the key corresponding to val. If there is no corresponding element, returns nil.

If there are multiple corresponding keys, arbitrarily returns one of them.

keys

Returns an array of all keys.

length
size

Returns the number of elements in the hash.

values

Returns an array of all values in the hash.


IO

The IO class provides basic IO functions.

Superclass

  • Object

Included Modules

  • Enumerable

Methods

binmode

Converts the stream into binary mode. The only way to revert to normal mode is to reopen the stream.

Returns self.

close

Closes the IO port. An Errno::EXXX exception is thrown if close fails.

Returns nil.

each_line {|line| ... }

Reads from the IO port line by line.

Returns self.

each_byte {|ch| ... }

Reads from the IO port byte by byte.

Returns self.

eof?

Returns true if the stream reaches the end of the file.

pos

Returns the current position of the file pointer.

pos=n

Moves the file pointer to the indicated position.

read([length])

Reads length bytes and returns the string. If length is omitted, reads all data until the end of the file.

If the IO has already reached the end of the file, returns nil.

Throws an Errno::EXXX exception if the data read fails and an ArgumentError exception if length is negative.

readlines([rs])

Reads all the data and returns an array whose elements consist of the lines that were read. If the IO has already reached the end of the file, returns the empty array [].

Lines are separated by the string indicated in the argument rs, whose default value is "\n".

Specify nil for rs and the lines will not be separated. Specify the empty string "" and consecutive line feeds will be treated as line separators (paragraph mode).

write(str)

Outputs str to the IO port. If str is not a string, tries converting it to a string with to_s.

Returns the actual number of bytes written. Throws an Errno::EXXX exception if the output action fails.


File

The file access class, normally created by open or File.open.

Open file objects that cannot be referenced will be closed and discarded by the next garbage collection.

Superclass

  • IO

Class Methods

File.mtime(filename)

Returns the file's last modified time (Time object).

If time retrieval fails, throws an Errno::EXXX exception.

File.basename(filename[, suffix])

Returns the final slash-delimited component of filename. If suffix is supplied and is identical to the end of filename, filename is returned without the suffix.

p File.basename("ruby/ruby.c")        # => "ruby.c"
p File.basename("ruby/ruby.c", ".c")  # => "ruby"
p File.basename("ruby/ruby.c", ".*")  # => "ruby"
p File.basename("ruby/ruby.exe", ".*")  # => "ruby"

Also see File.dirname and File.extname.

File.delete(filename ... )

Deletes a file or files and returns the number of files deleted. If deletion fails, throws an Errno::EXXX exception.

This method is for file deletion and cannot delete directories.

File.dirname(filename)

Returns all but the final slash-delimited component of filename as a string. Returns "." (the current directory) for a filename that does not include a slash.

p File.dirname("dir/file.ext")    # => "dir"
p File.dirname("file.ext")        # => "."
p File.dirname("foo/bar/")        # => "foo"
p File.dirname("foo//bar")        # => "foo"

Also see File.basename and File.extname.

File.expand_path(path[, default_dir])

Returns a string containing path's expanded absolute path. If path is relative, sets default_dir as the base directory. If default_dir is nil or missing, uses the current directory.

p File.expand_path("..")         # => "/home/matz/work"
p File.expand_path("..", "/tmp") # => "/"
File.extname(filename)

Returns filename's extension (the string after the final dot). Dots in directory names or at the start of filenames are not considered to be denoting extensions. If filename contains no extension, returns an empty string.

p File.extname("foo/foo.txt")     # => ".txt"
p File.extname("foo/foo.tar.gz")  # => ".gz"
p File.extname("foo/bar")         # => ""
p File.extname("foo/.bar")        # => ""
p File.extname("foo.txt/bar")     # => ""
p File.extname(".foo")            # => ""

Also see File.basename and File.dirname.

File.open(path[, mode])
File.open(path[, mode]) {|file| ... }

Opens the file specified by path and returns the file object. If file opening fails, throws an Errno::EXXX exception.

The mode argument is identical to the built-in function open.

Blocks can be specified for open(). When called with a block, executes the block with the given file object. The file will be closed automatically after executing the block.

When a block is specified, the return value of this method is the result of the block's execution.

File.rename(from, to)

Renames the file, moving it to a different directory as required. If a file already exists at the destination, it is overwritten.

Returns 0 if file movement is successful. Throws an Errno::EXXX exception if it fails.

Methods

mtime

Returns the time when the file was last modified (Time object).

Throws an Errno::EXXX exception if time retrieval fails.

path

Returns the path of the opened file.


MatchData

The class handling regular expression match data. Instances of this class can be obtained via code such as the following:

  • Regexp.last_match,
  • Regexp#match, and
  • $~.

Superclass

  • Object

Methods

self[n]

Returns the nth substring. 0 signifies the entire matching string. When the value of n is negative, it is treated as a backwards index (the final element being in the position -1). When the nth element does not exist, returns nil.

/(foo)(bar)(BAZ)?/ =~ "foobarbaz"
p $~.to_a       # => ["foobar", "foo", "bar", nil]
p $~[0]         # => "foobar"
p $~[1]         # => "foo"
p $~[2]         # => "bar"
p $~[3]         # => nil        (doesn't match)
p $~[4]         # => nil        (out of range)
p $~[-2]        # => "bar"
post_match

Returns the string after the matching portion.

pre_match

Returns the string before the matching portion.

to_a

Returns an array containing $&, $1, $2, ...

to_s

Returns the entire matching string.


Method

A class of methods that have been encapsulated into objects by Object#method. The method itself (not its name) and the receiver are encapsulated as a pair. Unlike Proc objects, context is not preserved.

Differences with Proc: Method can only be created if there is a method to be fetched, but Proc can be created without any preparation. In light of this, Proc is suited for single uses, whereas Method is suited for repeated uses.

class Foo
  def foo(arg)
    "foo called with arg #{arg}"
  end
end

m = Foo.new.method(:foo)

p m             # => #<Method: Foo#foo>
p m.call(1)     # => "foo called with arg 1"

Superclass

  • Object

Methods

call(arg ... )
call(arg ... ) { ... }

Starts a method encapsulated in a method object. Arguments and blocks are passed to the method as is.


Module

The module class.

Superclass

  • Object

Method

self === obj

This method is mainly used for comparison within case statements. Returns true if obj has an Object#kind_of? relationship with self. In other words, case can be used to check the owner relationship of classes and modules.

str = String.new
case str
when String     # evaluates String === str
  p true        # => true
end

Private Methods

attr_accessor(name ... )

Defines both the read and write methods for the attribute name, where name is specified by Symbol or a string.

The definition of the method defined by attr_accessor is as follows:

def name
  @name
end
def name=(val)
  @name = val
end
attr_reader(name ... )

Defines the read method for the attribute name, where name is specified by Symbol or a string.

The definition of the method defined by attr_reader is as follows:

def name
  @name
end
attr_writer(name ... )

Defines the write method for the attribute name (name=), where name is specified by Symbol or a string.

The definition of the method defined by attr_writer is as follows:

def name=(val)
  @name = val
end
include(module ... )

Includes the specified modules' properties (methods and constants). Returns self. include is used to implement a mix-in in place of a multiple inheritance.

class C
  include FileTest
  include Math
end

Module capabilities are included by inserting modules into a class inheritance. Therefore, when searching for methods, included modules will be given priority over superclasses.

If the same module is included two or more times, the second and later instances will be ignored. Furthermore, executing an include that results in a recursive module inheritance will throw an ArgumentError exception.


Class

The class of classes. More accurately speaking, each class has its own unnamed "metaclass", and Class is the class of these metaclasses. This relationship is a little complicated, but it is not especially important to keep in mind while using Ruby.

The differences Class has with Module are as follows:

  • Class can create instances.
  • Class cannot perform mix-in using include.

Besides that, nearly all of its functionality is inherited from Module.

Superclass

  • Module

Method

new( ... )

Creates a class instance and returns it. This method's arguments, including block arguments, are passed to initialize.


NilClass

The class of nil. nil is the sole instance of this class, signifying FALSE along with the false object. All other objects are true.

Superclass

  • Object

Methods

self & other

Always returns false.

self | other
self ^ other

If other is true, returns true; if false, returns false.

nil?

Always returns true.

to_a

Returns the empty array [].

to_f

Returns 0.0.

to_i

Returns 0.

to_s

Returns the empty string "".


Numeric

Numeric is the abstract class for numbers. In Ruby, operations are possible among different numerical classes.

Operations and comparison methods (+, -, *, /, <=>), etc. are defined in a subclass. For increased efficiency, methods identical to the Numeric method may also be redefined in a subclass.

Superclass

  • Object

Included Modules

  • Comparable

Methods

+ self

Returns self.

- self

Returns self, negated.

This method is defined by the binary operator - in 0 - self.

abs

Returns the absolute value of self.

ceil

Returns the smallest integer equal to or greater than self (i.e., the ceiling).

floor

Returns the largest integer that does not exceed self (i.e., the floor).

integer?

Returns true when self is an integer.

round

Returns the integer closest to self.

truncate

Discards the decimal point and all digits after it.


Integer

The abstract class for integers. Its subclasses are Fixnum and Bignum. These two types of integers are automatically converted into one another according to their values. Integers can be treated as infinite bit strings for bit operations.

Superclass

  • Numeric

Methods

self[nth]

Returns 1 if the nth bit of the integer is set (with the LSB, or least significant bit, at position 0), otherwise returns 0.

self[nth]=bit is not an Integer method because the associated Numeric class is immutable.

self + other
self - other
self * other
self / other
self % other
self ** other

Arithmetic operators that compute the sum, difference, product, quotient, remainder, and exponent, respectively.

self <=> other

Compares self with other and returns a positive integer if self is larger, 0 if the two are equal, and a negative integer if self is smaller.

self == other
self < other
self <= other
self > other
self >= other

Relational operators.

~ self
self | other
self & other
self ^ other

Bit operators that compute bitwise negation, logical OR, logical AND, and logical XOR, respectively.

self << bits
self >> bits

Shift operators that shift only bits to the right or left, respectively.

The signed bit (MSB or most significant bit) is retained in a right shift.

chr

Returns a 1-byte string corresponding to the numeric position in the character set. For example, 65.chr returns "A".

The integer must be within the range of 0 to 255. Calling this method with an out-of-range integer will throw a RangeError exception.

downto(min) {|n| ... }

Iterates from self to min, decrementing by 1 each time. If self < min, does nothing.

Also see upto, step, and times.

next
succ

Returns the "next" value of an integer.

step(limit, step) {|n| ... }

Iteratively evaluates a block from self, incrementing by step, until limit is about to be surpassed. step can also be a negative number.

Throws an ArgumentError exception when step is set to 0.

Returns self.

Also see upto, downto, and times.

times {|n| ... }

Iterates self number of times, from 0 to self-1. If self is negative, does nothing.

Returns self.

Also see upto, downto, and step.

to_f

Converts a value to a floating-point number (Float).

to_s([base])

Converts an integer to a base-10 string expression.

If an argument is specified, it will be used as the base number for conversion. If a base outside the range of 2-36 is specified, an ArgumentError exception will be thrown.

p 10.to_s(2)    # => "1010"
p 10.to_s(8)    # => "12"
p 10.to_s(16)   # => "a"
p 35.to_s(36)   # => "z"
upto(max) {|n| ... }

Iterates from self to max, incrementing by 1 each time. If self > max, does nothing.

Returns self.

Also see downto, step, and times.


Bignum

The class for long integers, limited only by memory size. The result of an operation is automatically converted into a Fixnum if its value is within Fixnum range. If the value is out of Fixnum range, it is extended into a Bignum. For bit operations, Bignum can be considered to be an infinite 2's complement bit string. Negative numbers in particular can operate as a string of 1 bits extending indefinitely to the left. Mixing Bignum with Float can result in digit cancellation errors upon conversion.

Superclass

  • Integer


Fixnum

The class for fixed-length integers that fit into the machine's pointer, which is 31 bits long in most cases. If the result of an operation is out of Fixnum range, it is automatically extended into a Bignum.

Superclass

  • Integer

Methods

id2name

Returns the string corresponding to the Symbol object's integer (obtained with Symbol#to_i). If there is no symbol that corresponds to the integer, returns nil.

to_sym

Returns the Symbol object corresponding to the integer value of the object's self. If there is no symbol that corresponds to the integer, returns nil.


Float

The floating-point number class. The implementation of Float is double in C.

Superclass

  • Numeric

Methods

self + other
self - other
self * other
self / other
self % other
self ** other

Arithmetic operators that compute the sum, difference, product, quotient, remainder, and exponent, respectively.

self <=> other

Compares self with other and returns a positive integer if self is larger, 0 if the two are equal, and a negative integer if self is smaller.

self == other
self < other
self <= other
self > other
self >= other

Relational operators.

finite?

Returns TRUE if the value is neither infinite nor NaN.

infinite?

Returns 1 when a value is positive and infinite; returns -1 when a value is negative and infinite. Otherwise, returns nil. The floating-point zero ensures infinite division.

inf = 1.0/0
p inf
p inf.infinite?

=> Infinity
   1

inf = -1.0/0
p inf
p inf.infinite?

=> -Infinity
   -1
nan?

Returns true if a value is NaN (not a number). The floating-point zero ensures the result of division by 0 is NaN.

nan = 0.0/0.0
p nan
p nan.nan?

=> NaN
   true


Range

The range object class. See Range Expressions for more information.

Superclass

  • Object

Included Module

  • Enumerable

Class Method

Range.new(first, last[, exclude_end])

Creates and returns a range object from first to last. Creates a range object without an end point if exclude_end is true. Includes the end point when exclude_end is omitted.

Methods

self === other

This method is mainly used for comparison within case statements. Returns true if other is within range.

begin
first

Returns the initial element.

each {|item| ... }

Iterates over each element within the range.

end
last

Returns the end point, regardless of whether the range object is inclusive of the end point.

p (1..5).end   # => 5
p (1...5).end  # => 5
exclude_end?

Returns true if the range object is exclusive of the end point.


Proc

Proc is a procedure object in which both a block and its context (local variable scope and stack frame) have been encapsulated as an object. Proc can be used like an unnamed function, except that it does not have its own local variable scope.

We can see that Proc retains a local variable scope, however, by observing that the variable var can be referenced, as in the following example:

var = 1
$foo = Proc.new { var }
var = 2

def foo
  $foo.call
end

p foo       # => 2

Superclass

  • Object

Class Method

Proc.new
Proc.new { ... }

Encapsulates a block, along with its context, into an object and returns it.

If no block is specified, but the method that called Proc.new contains a block, that block will be created as a Proc object and returned.

Method

call(arg ... )

Executes a procedure object and returns the result. Arguments are assigned to block parameters as is (according to the rules of multiple assignation).


Regexp

The regular expression class. See Regular Expression Literals for more information.

Superclass

  • Object

Class Methods

Regexp.last_match

Returns the MatchData object for the last regular expression match performed in the current scope. This method call is identical to a $~ reference.

/(.)(.)/ =~ "ab"
p Regexp.last_match      # => #<MatchData:0x4599e58>
p Regexp.last_match[0]   # => "ab"
p Regexp.last_match[1]   # => "a"
p Regexp.last_match[2]   # => "b"
p Regexp.last_match[3]   # => nil
Regexp.last_match([nth])

If the integer nth is 0, returns the matching string ($&). Otherwise, returns the substring matching the nth set of parentheses ($1, $2, ...). When there are no corresponding parentheses or no matches, returns nil.

/(.)(.)/ =~ "ab"
p Regexp.last_match      # => #<MatchData:0x4599e58>
p Regexp.last_match(0)   # => "ab"
p Regexp.last_match(1)   # => "a"
p Regexp.last_match(2)   # => "b"
p Regexp.last_match(3)   # => nil

Because Regexp.last_match, with no arguments, returns nil when the entire regular expression does not match, the format last_match[1] will throw a NameError exception. On the other hand, last_match(1) returns nil.

Methods

self =~ string
self === string

Matches the string string to a regular expression. If the argument is not a string or does not match, returns false; if it matches, returns true.

Matching information can be set in the built-in variable $~.

If string is neither nil nor a String object, throws a TypeError exception.

match(str)

Identical to self=~str, except that it does not return a MatchData object. If there is no match, returns nil.

When only the substring matching the regular expression is needed, use match(str) like this:

bar = /foo(.*)baz/.match("foobarbaz").to_a[1]

_, foo, bar, baz = */(foo)(bar)(baz)/.match("foobarbaz")

to_a takes failed matches into account.

to_s

Creates and returns a string expression for a regular expression. Preserves the meaning of the returned string even if the string is embedded in another regular expression.

re = /foo|bar|baz/i
p re.to_s       # => "(?i-mx:foo|bar|baz)"
p /#{re}+/o     # => /(?i-mx:foo|bar|baz)+/

However, some regular expressions with backreferences may not work as expected. This is because backreferences can only be specified by number at present.

re = /(foo|bar)\1/      # # \1 is foo or bar
p /(baz)#{re}/          # \1 is baz

# => /(baz)(?-mix:(foo|bar)\1)/


String

The string class. Can handle character sequences of arbitrary lengths. See String Literals for more information.

Superclass

  • Object

Included Modules

  • Comparable
  • Enumerable

Methods

self + other

Returns a new concatenated string.

self * times

Creates and returns a new string consisting of the string contents repeated times times.

self <=> other

Compares self with other by ASCII order. Returns a positive integer if self is larger, 0 if the two are equal, and a negative integer if self is smaller.

self == other

Determines whether the strings are equal.

self[nth, len]

Returns a len-character-long substring found at the nth character. When nth is negative, counts from the end of the string.

If nth is out of range, returns nil.

self[regexp]

Returns the first substring matching regexp. Matching information can be set in the built-in variable $~.

If there is no match to regexp, returns nil.

p "foobar"[/bar/]   # => "bar"
self[nth, len]=val

Replaces the len-character-long substring found at the nth character with the string val. When nth is negative, counts from the end of the string.

Returns val.

self[regexp]=val

Replaces the first substring matching the regular expression regexp with the string val.

If there is no match to the regular expression, throws an IndexError exception.

Returns val.

clone
dup

Returns a new string with the same contents as the original string. Using clone on a frozen string will return a similarly frozen string, but dup returns an unfrozen string with identical contents.

concat(other)

Appends the contents of the string other to self. Returns self.

downcase
downcase!

Replaces all uppercase characters with lowercase characters.

downcase creates and returns the modified string. downcase! modifies and returns self, but if no characters were replaced, returns nil.

Also see upcase.

each_line {|line| ... }

Iterates over each line in the string.

Returns self.

each_byte {|byte| ... }

Iterates over each byte of the string. Returns self.

empty?

Returns true if the string is empty (i.e., a zero-length string).

gsub(pattern) {|matched| .... }
gsub!(pattern) {|matched| .... }

Replaces all substrings within the string matching pattern with the results of the block evaluation. The matching substring is passed to the block as an argument. The built-in variable $<digits> can be referenced within the block.

p 'abcabc'.gsub(/b/) {|s| s.upcase }    # => "aBcaBc"
p 'abcabc'.gsub(/b/) { $&.upcase }      # => "aBcaBc"
p 'abbbcd'.gsub(/a(b+)/) { $1 }         # => "bbbcd"

gsub creates and returns the post-replacement string. gsub! modifies and returns self, but if no characters were replaced, returns nil.

Also see sub.

include?(substr)

Returns true if the substring substr is included in the text string.

If substr is a Fixnum from 0 to 255, it is determined to be a character code, and if that character is included, it returns true.

index(pattern[, pos])

Performs a search for the substring from left to right. Returns the left-hand position of the found substring. If nothing is found, nil is returned.

The pattern argument is used to specify the substring to search for, using a text string, an integer from 0 to 255, or a regular expression.

If pos is provided, the search starts from that position. The value of pos when it is omitted is 0.

insert(nth, other)

Inserts the string other immediately before the character in the nth position. Returns self.

p "foobaz".insert(3, "bar")         # => "foobarbaz"
to_sym

Returns the symbol value (Symbol) corresponding to the string.

Use Symbol#id2name to obtain the string corresponding to a symbol.

p "foo".to_sym                      # => :foo
p "foo".to_sym.to_s == "foo"        # => true
length
size

Returns the length of the string in characters.

scan(re)
scan(re) {|s| ... }

Repeatedly matches against self with the regular expression re and returns an array of matching substrings.

p "foobarbazfoobarbaz".scan(/ba./)
# => ["bar", "baz", "bar", "baz"]

p "abcde".scan(/./)
# => ["a", "b", "c", "d", "e"]

When called with a block specified, the matching substrings become the block's parameters. (If parentheses are included, an array of strings that match the patterns in parentheses becomes the block's parameter.) If a block is specified, returns self.

"foobarbazfoobarbaz".scan(/ba./) {|s| p s}
# => "bar"
     "baz"
     "bar"
     "baz"
slice(nth, len)
slice(regexp)

Identical to self[].

slice!(nth, len)
slice!(regexp)

Removes a specified range (see self[]) from a string and returns the removed substring.

If the argument is out of range, returns nil.

sub(pattern) {|matched| ... }
sub!(pattern) {|matched| ... }

Replaces the first substring matching pattern with the results of the block evaluation.

sub creates and returns the post-replacement string. sub! modifies and returns self, but if no characters were replaced, returns nil.

Identical to gsub, except that sub only matches once.

to_f

Interprets the string as a base-10 expression and converts it into a floating-point number (Float).

to_i([base])

Interprets the string as a numeric expression and converts it into an integer.

The default is base-10. By specifying base, you can perform base 2-36 conversions as well.

upcase
upcase!

Replaces all lowercase characters with uppercase characters.

upcase creates and returns the modified string. upcase! modifies and returns self, but if no characters were replaced, it returns nil.

Also see downcase.


Symbol

The class that represents symbols. See Symbol for more information.

Superclass

  • Object

Methods

id2name

Returns the string corresponding to a symbol.

Use String#to_sym to obtain the symbol corresponding to a string.

p :foo.id2name.to_sym == :foo       # => true
to_i

Returns the integer corresponding to a symbol.

Use Fixnum#to_sym to obtain the symbol corresponding to this integer.

p :foo.to_i                         # => 8881
p :foo.to_i.to_sym                  # => :foo

In Ruby, reserved words, variable names, method names, and the like are controlled by these integers. Integers corresponding to objects (obtained via Object#object_id) and those corresponding to symbols are separate items.


Time

The time class.

Superclass

  • Object

Included Module

  • Comparable

Class Method

Time.now

Returns the current Time object.

Methods

self + other

Returns a time that is later than self by other seconds.

self - other

When other is a Time object, returns the difference between the two times with Float. If other is a numeric value, returns a time that is earlier than self by other.

self <=> other

Compares times. other must be a Time object or a numeric value. If it is a numeric value, the times are compared in terms of seconds since the epoch began.

strftime(format)

Returns the time converted into a string via a format string. The format string may be specified with the following:

  • %A

    Day of the week (Sunday, Monday ... )

  • %a

    Day of the week in abbreviated form (Sun, Mon ... )

  • %B

    Month (January, February ... )

  • %b

    Month in abbreviated form (Jan, Feb ... )

  • %c

    Date and time

  • %d

    Day of the month (01-31)

  • %H

    Time of day in 24-hour format (00-23)

  • %I

    Time of day in 12-hour format (01-12)

  • %j

    Day of the year (001-366)

  • %M

    Minutes (00-59)

  • %m

    Month of the year (01-12)

  • %p

    AM or PM

  • %S

    Seconds (00-60, 60 being a leap second)

  • %U

    Week of the year, with the first week starting on the first Sunday (00-53)

  • %W

    Week of the year, with the first week starting on the first Monday (00-53)

  • %w

    Day of the week (0-6 where 0 denotes Sunday)

  • %X

    Time

  • %x

    Date

  • %Y

    Year in 4-digit format

  • %y

    Year in 2-digit format (00-99)

  • %Z

    Time zone

  • %%

    The character %

sec

Returns the seconds.

min

Returns the minutes.

hour

Returns the hour.

mday

Returns the day.

mon

Returns the month.

year

Returns the year.

wday

Returns the number representing the day of the week.


TrueClass

The true class. true is the only instance of the TrueClass class. true is a representative object that denotes a TRUE condition.

Superclass

  • Object

Methods

self & other

If other is TRUE, returns TRUE. If FALSE, returns FALSE.

self | other

Always returns TRUE.

self ^ other

If other is TRUE, returns FALSE. If FALSE, returns TRUE.


Built-in Modules

  • Comparable
  • Enumerable
  • Errno
  • FileTest
  • GC
  • Kernel
  • Marshal
  • Math


Comparable

A mix-in for classes allowing relational operations. Classes including this module must define the basic relational operators <=>. All other relational operators can be derived through use of those definitions.

Methods

self == other

Returns true if self and other are equal.

Returns nil if <=> returns nil.

self > other

Returns true if self is greater than other.

If <=> returns nil, throws an ArgumentError exception.

self >= other

Returns true if self is greater than or equal to other.

If <=> returns nil, throws an ArgumentError exception.

self < other

Returns true if self is less than other.

If <=> returns nil, throws an ArgumentError exception.

self <= other

Returns true if self is less than or equal to other.

If <=> returns nil, throws an ArgumentError exception.

between?(min, max)

Returns true if self falls within a range from min to max, inclusive.

If self <=> min or self <=> max returns nil, throws an ArgumentError exception.


Enumerable

A mix-in for repeating classes. This module's methods are all defined via each, so each must be defined in any class that includes this module.

Methods

all?
all? {|item| ... }

Returns true if all items are true. If any item is false, immediately returns FALSE.

When using a block, evaluates the block for each item and returns TRUE if all outcomes are true. If the block returns FALSE at any time, immediately returns FALSE.

p [1,2,3].all? {|v| v > 0}   # => true
p [1,2,3].all? {|v| v > 1}   # => false
any?
any? {|item| ... }

Returns FALSE if all items are false. If any item is true, immediately returns TRUE.

When using a block, evaluates the block for each item and returns FALSE if all outcomes are false. If the block returns TRUE at any time, immediately returns TRUE.

p [1,2,3].any? {|v| v > 3}   # => false
p [1,2,3].any? {|v| v > 1}   # => true
collect {|item| ... }

Returns an array that includes all the results of block evaluations for each item.

find {|item| ... }

Returns the first item that tested as true during the block evaluation. If no item was true, returns nil.

find_all {|item| ... }
select {|item| ... }

Returns an array of all items that tested as true during the block evaluation. If no item was true, returns an empty array.

include?(val)

Returns true if the list includes an item that satisfies the relationship of val and ==.

inject([init]) {|result, item| ... }

Passes the initial value init and the first item of self as arguments before executing the block. On the second and subsequent loops, passes the result of the previous block and the next item of self as arguments before executing the block. Iterates up to the last item and then returns the result of the final block.

Returns init if an item is empty.

If the initial value init is omitted, passes the first and second item to the block. If there is only one item in this case, the first item is returned without executing the block. Returns nil if an item is empty.

Example

Calculating the total:

p [1,2,3,4,5].inject(0) {|result, item| result + item }
  => 15

This is equivalent to the following code:

result = 0
[1,2,3,4,5].each {|v| result += v }
p result
=> 15
max

Returns the largest item. Assumes all items are comparable via the <=> method.

max {|a, b| ... }

Compares each item based on the block's evaluated value and returns the largest item.

Anticipates a block value that will be a positive integer if a>b, 0 if a==b, and a negative integer if a<b. If the block returns a non-integer, throws a TypeError exception.

max_by {|item| ... }

Compares block evaluation results via <=> and returns the largest item. Returns nil if there are no items.

min

Returns the smallest item. Assumes all items are comparable via the <=> method.

min {|a, b| ... }

Compares each item based on the block's evaluated value and returns the smallest item.

Anticipates a block value that will be a positive integer if a>b, 0 if a==b, and a negative integer if a<b. If the block returns a non-integer, throws a TypeError exception.

min_by {|item| ... }

Compares block evaluation results via <=> and returns the smallest item. Returns nil if there are no items.

sort
sort {|a, b| ... }

Creates and returns an array of all items sorted in ascending order.

When not using a block, calls the <=> for each item and sorts based upon those results.

To sort using other methods besides <=>, specify a block. The items will be sorted based on the evaluation of that block. Anticipates a block value that will be a positive integer if a>b, 0 if a==b, and a negative integer if a<b. If the block returns a non-integer, throws a TypeError exception.

sort_by {|item| ... }

Sorts self in ascending order by comparing block evaluation results via the <=> method. Creates and returns a new sorted array.

to_a
entries

Returns an array of all items.


Errno

A module containing exceptions corresponding to system call errors.

Inner Classes

The following are typical exception classes. Many others are defined as well, but you need not be concerned about them.

E2BIG
The argument list is too long.
EACCES
Access permission was denied.
EAGAIN
Cannot create any more processes.
EBADF
Invalid file number.
ECHILD
No child process exists.
EDEADLOCK
Possibility of a resource deadlock.
EDOM
The argument of the numeric operation function is outside the function's domain.
EEXIST
File already exists.
EINVAL
Invalid argument.
EMFILE
Too many open files.
ENOENT
No file or directory.
ENOEXEC
Executable file error.
ENOMEM
Not enough memory.
ENOSPC
Not enough free space on device.
ERANGE
Results are too large.
EXDEV
Device interlink.


FileTest

A module containing file test functions.

Module Functions

FileTest.exist?(filename)

Returns true if filename exists.

FileTest.directory?(filename)

Returns true if filename is a directory.

FileTest.file?(filename)

Returns true if filaname is an ordinary file.

FileTest.size(filename)

Returns the size of filename. If filename does not exist, throws an Errno::EXXX exception (most likely Errno::ENOENT).


GC

A module that controls garbage collection in the Ruby interpreter.

Module Method

GC.disable

Disables garbage collection.

Returns the previous disable state (if disabled, returns TRUE; if garbage collection was enabled, returns FALSE).

GC.enable

Enables garbage collection.

Returns the previous disable state (if disabled, returns TRUE; if garbage collection was enabled, returns FALSE).

GC.start

Starts garbage collection.

Returns nil.


Kernel

A module defining the methods that can be referred to by all classes. Object classes are included in this module. The methods explained on the Built-in Functions page are defined in this module.

Object class methods are defined in this module. This ensures compatibility with top-level method redefinition.


Marshal

A module providing the functionality for writing a Ruby object to and reading it from a file (or string).

Module Functions

Marshal.dump(obj[, port][, limit])

Writes obj to a file recursively.

Some objects may not be writeable to a file, such as in instances of File or MatchData, or with objects that define unusual methods. When attempting to write such objects to a file, a TypeError will occur.

port specifies an instance of IO (or a subclass). In this case, returns port. When omitted, dump returns the object's dump as a string.

When limit is specified, no objects linked at or deeper than limit can be dumped (The default is 100 levels.) When limit is negative, no depth checking is performed.

Marshal.load(port)

Reads marshal data from port (i.e., the string output from Marshal.dump) and creates an object with the same state as the original object. port specifies a string or an instance of IO (or a subclass).


Math

A module that supports floating-point calculations.

Module Functions

Math.acos(x)
Math.asin(x)
Math.atan(x)

Returns the value of the inverse trigonometric functions of x in radians.

Values that can be returned have ranges of [0, +Π], [-Π/2, +Π/2], and (-Π/2, +Π/2), respectively.

In acos(x), and asin(x), x must be in the range -1.0 <= x < 1 (normally returns NaN).

acos() and asin() will throw an Errno::EDOM exception for out-of-range arguments.

Math.atan2(y, x)

Returns the arctangent of y/x in the range [-Π, Π].

Math.acosh(x)
Math.asinh(x)
Math.atanh(x)

Returns the value of the inverse hyperbolic functions of x.

asinh(x) = log(x + sqrt(x * x + 1))
acosh(x) = log(x + sqrt(x * x - 1)) [x >= 1]
atanh(x) = log((1+x)/(1-x)) / 2     [-1 < x < 1]

In acosh(x), x must be >= 1 (normally throws an Errno::EDOM exception).

In atanh(x), x must be in the range -1.0 < x < 1 (normally throws an Errno::EDOM exception).

Math.cos(x)
Math.sin(x)
Math.tan(x)

Returns the value of the trigonometric functions of x in radians, in the range [-1, 1].

Math.cosh(x)
Math.sinh(x)
Math.tanh(x)

Returns the value of the hyperbolic functions of x.

cosh(x) = (exp(x) + exp(-x)) / 2
sinh(x) = (exp(x) - exp(-x)) / 2
tanh(x) = sinh(x) / cosh(x)
Math.erf(x)
Math.erfc(x)

Returns the values of the error function (erf) and complementary error function (erfc) of x.

Math.exp(x)

Returns the value of the exponential function of x.

Math.frexp(x)

Returns the exponent and mantissa of the real number x.

Math.hypot(x, y)

Returns sqrt(x*x + y*y).

Math.ldexp(x, exp)

Returns the real number x multiplied by 2 to the power of exp.

Math.log(x)

Returns the natural logarithm of x.

x must be a positive value (normally returns NaN for negative values and -Infinity for 0).

Negative out-of-range arguments throw Errno::EDOM exceptions, while a 0 argument throws an Errno::ERANGE exception.

Math.log10(x)

Returns the common logarithm of x.

x must be a positive value (normally returns NaN for negative values and -Infinity for 0).

Negative out-of-range arguments throw Errno::EDOM exceptions, while a 0 argument throws an Errno::ERANGE exception.

Math.sqrt(x)

Returns the square root of x. When x is a negative value, throws an ArgumentError exception.

Normally, when x is negative, throws an Errno::EDOM exception.

Constants

E

The natural logarithmic base.

p Math::E
# => 2.718281828
PI

The ratio of a circle's circumference to its diameter.

p Math::PI
# => 3.141592654


Built-in Exception Classes

Exception
The superclass of all exceptions.
NoMemoryError
Thrown when attempting to reserve too much memory at once.
ScriptError
Indicates a script error.
NotImplementedError
Thrown when an unimplemented feature is invoked.
SyntaxError
Thrown by a syntax error.
StandardError
This exception class and its subclass can be trapped even when the class is omitted in the rescue clause.
ArgumentError
Thrown when argument numbers do not match or when the values are incorrect.
IndexError
Thrown when the index is out of range.
IOError
Thrown when an I/O error occurs.
EOFError
Thrown when EOF (end of file) has been reached.
LocalJumpError
Thrown when no jump destination is found for a control structure.
NameError
Thrown when using an undefined local variable or constant.
NoMethodError
Thrown when calling an undefined method.
RangeError
A range exception. Thrown in situations such as when an out-of-range integer conversion (from Bignum to Fixnum) occurs.
FloatDomainError
Thrown when trying to convert a positive or negative infinite number or NaN (Not a Number) into Bignum , or when comparing a number to a NaN.
RegexpError
Thrown when compiling a regular expression fails.
RuntimeError
A runtime exception. Thrown when calling raise without specifying an exception.
SystemCallError
Thrown when a system call fails.
Errno::EXXX
Exception class for each errno. See the Errno module for more on each class name.
SystemStackError
Thrown when a stack level becomes too deep.
TypeError
Thrown when an illegal type is invoked.
ZeroDivisionError
Thrown when dividing by zero.
SystemExit
Terminates the program. See exit for more information.
fatal
A fatal (internal) error. This object is not visible via the normal method.


Game Library

  • RGSS Built-in Functions
  • RGSS Built-in Classes
    • Bitmap
    • Color
    • Font
    • Plane
    • Rect
    • Sprite
    • Table
    • Tilemap
    • Tone
    • Viewport
    • Window
    • RGSSError
    • RGSSReset
  • RGSS Built-in Modules
    • Audio
    • Graphics
    • Input
    • RPG
  • RPGVXAce Data Structures
    • RPG::Map
    • RPG::Map::Encounter
    • RPG::MapInfo
    • RPG::Event
    • RPG::Event::Page
    • RPG::Event::Page::Condition
    • RPG::Event::Page::Graphic
    • RPG::EventCommand
    • RPG::MoveRoute
    • RPG::MoveCommand
    • RPG::BaseItem
      • RPG::Actor
      • RPG::Class
      • RPG::UsableItem
        • RPG::Skill
        • RPG::Item
      • RPG::EquipItem
        • RPG::Weapon
        • RPG::Armor
      • RPG::Enemy
      • RPG::State
    • RPG::BaseItem::Feature
    • RPG::UsableItem::Damage
    • RPG::UsableItem::Effect
    • RPG::Class::Learning
    • RPG::Enemy::DropItem
    • RPG::Enemy::Action
    • RPG::Troop
    • RPG::Troop::Member
    • RPG::Troop::Page
    • RPG::Troop::Page::Condition
    • RPG::Animation
    • RPG::Animation::Frame
    • RPG::Animation::Timing
    • RPG::Tileset
    • RPG::CommonEvent
    • RPG::System
    • RPG::System::Vehicle
    • RPG::System::Terms
    • RPG::System::TestBattler
    • RPG::AudioFile
      • RPG::BGM
      • RPG::BGS
      • RPG::ME
      • RPG::SE


RGSS Built-in Functions

The following built-in functions are defined in RGSS.

rgss_main { ... } (RGSS3)

Evaluates the provided block one time only.

Detects a reset within a block with a press of the F12 key and returns to the beginning if reset.

rgss_main { SceneManager.run }
rgss_stop (RGSS3)

Stops script execution and only repeats screen refreshing. Defined for use in script introduction.

Equivalent to the following.

loop { Graphics.update }
load_data(filename)

Loads the data file indicated by filename and restores the object.

$data_actors = load_data("Data/Actors.rvdata2")
This function is essentially the same as:
File.open(filename, "rb") { |f|
  obj = Marshal.load(f)
}

However, it differs in that it can load files from within encrypted archives.

save_data(obj, filename)

Saves the object obj to the data file indicated by filename.

save_data($data_actors, "Data/Actors.rvdata2")
This function is the same as:
File.open(filename, "wb") { |f|
  Marshal.dump(obj, f)
}
msgbox(arg[, ...]) (RGSS3)

Outputs the arguments to the message box. If a non-string object has been supplied as an argument, it will be converted into a string with to_s and output.

Returns nil.

msgbox_p(obj, [obj2, ...]) (RGSS3)

Outputs obj to the message box in a human-readable format. Identical to the following code (see Object#inspect):

msgbox obj.inspect, "\n", obj2.inspect, "\n", ...

Returns nil.


RGSS Built-in Classes

  • Bitmap
  • Color
  • Font
  • Plane
  • Rect
  • Sprite
  • Table
  • Tilemap
  • Tone
  • Viewport
  • Window
  • RGSSError
  • RGSSReset


Bitmap

The bitmap class. Bitmaps represent images.

Sprites (Sprite) and other objects must be used to display bitmaps onscreen.

Superclass

  • Object

Class Methods

Bitmap.new(filename)

Loads the graphic file specified in filename and creates a bitmap object.

Also automatically searches files included in RGSS-RTP and encrypted archives. File extensions may be omitted.

Bitmap.new(width, height)

Creates a bitmap object of the specified size.

Methods

dispose

Frees the bitmap. If the bitmap has already been freed, does nothing.

disposed?

Returns true if the bitmap has been freed.

width

Gets the bitmap width.

height

Gets the bitmap height.

rect

Gets the bitmap rectangle (Rect).

blt(x, y, src_bitmap, src_rect[, opacity])

Performs a block transfer from the src_bitmap box src_rect (Rect) to the specified bitmap coordinates (x, y).

opacity can be set from 0 to 255.

stretch_blt(dest_rect, src_bitmap, src_rect[, opacity])

Performs a block transfer from the src_bitmap box src_rect (Rect) to the specified bitmap box dest_rect (Rect).

opacity can be set from 0 to 255.

fill_rect(x, y, width, height, color)
fill_rect(rect, color)

Fills the bitmap box (x, y, width, height) or rect (Rect) with color (Color).

gradient_fill_rect(x, y, width, height, color1, color2[, vertical])
gradient_fill_rect(rect, color1, color2[, vertical])

Fills in this bitmap box (x, y, width, height) or rect (Rect) with a gradient from color1 (Color) to color2 (Color).

Set vertical to true to create a vertical gradient. Horizontal gradient is the default.

clear

Clears the entire bitmap.

clear_rect(x, y, width, height)
clear_rect(rect)

Clears this bitmap box or (x, y, width, height) or rect (Rect).

get_pixel(x, y)

Gets the color (Color) at the specified pixel (x, y).

set_pixel(x, y, color)

Sets the specified pixel (x, y) to color (Color).

hue_change(hue)

Changes the bitmap's hue within 360 degrees of displacement.

This process is time-consuming. Furthermore, due to conversion errors, repeated hue changes may result in color loss.

blur

Applies a blur effect to the bitmap. This process is time consuming.

radial_blur(angle, division)

Applies a radial blur to the bitmap. angle is used to specify an angle from 0 to 360. The larger the number, the greater the roundness.

division is the division number (from 2 to 100). The larger the number, the smoother it will be. This process is very time consuming.

draw_text(x, y, width, height, str[, align])
draw_text(rect, str[, align])

Draws the string str in the bitmap box (x, y, width, height) or rect (Rect).

If str is not a character string object, it will be converted to a character string using the to_s method before processing is performed.

If the text length exceeds the box's width, the text width will automatically be reduced by up to 60 percent.

Horizontal text is left-aligned by default. Set align to 1 to center the text and to 2 to right-align it. Vertical text is always centered.

As this process is time-consuming, redrawing the text with every frame is not recommended.

text_size(str)

Gets the box (Rect) used when drawing the string str with the draw_text method. Does not include the outline portion (RGSS3) and the angled portions of italicized text.

If str is not a character string object, it will be converted to a character string using the to_s method before processing is performed.

Property

font

The font (Font) used to draw a string with the draw_text method.


Color

The RGBA color class. Each component is handled with a floating-point value (Float).

Superclass

  • Object

Class Method

Color.new(red, green, blue[, alpha])
Color.new (RGSS3)

Creates a Color object. If alpha is omitted, it is assumed to be 255.

The default values when no arguments are specified are (0, 0, 0, 0). (RGSS3)

Methods

set(red, green, blue[, alpha])
set(color) (RGSS3)

Sets all components at once.

The second format copies all the components from a separate Color object. (RGSS3)

Properties

red

The red value (0-255). Out-of-range values are automatically corrected.

green

The green value (0-255). Out-of-range values are automatically corrected.

blue

The blue value (0-255). Out-of-range values are automatically corrected.

alpha

The alpha value (0-255). Out-of-range values are automatically corrected.


Font

The font class. Font is a property of the Bitmap class.

If there is a "Fonts" folder directly under the game folder, the font files in it can be used even if they are not installed on the system.

Superclass

  • Object

Class Methods

Font.new([name[, size]])

Creates a Font object.

Font.exist?(name)

Returns true if the specified font exists on the system.

Properties

name

The font name. Include an array of strings to specify multiple fonts to be used in a desired order.

font.name = ["Myriad", "Verdana"]

In this example, if the higher priority font Myriad does not exist on the system, the second choice Verdana will be used instead.

The default is ["Verdana", "Arial", "Courier New"].

size

The font size. The default is 24 (RGSS3).

bold

The bold flag. The default is FALSE.

italic

The italic flag. The default is FALSE.

outline (RGSS3)

The flag for outline text. The default is TRUE.

shadow

The flag for shadow text. The default is false (RGSS3). When enabled, a black shadow will be drawn to the bottom right of the character.

color

The font color (Color). Alpha values may also be used. The default is (255,255,255,255).

Alpha values are also used when drawing outline (RGSS3) and shadow text.

out_color (RGSS3)

The outline color (Color). The default is (0,0,0,128).

Class Properties

default_name
default_size
default_bold
default_italic
default_shadow
default_outline (RGSS3)
default_color
default_out_color (RGSS3)

You can change the default values set for each component when a new Font object is created.

Font.default_name = ["Myriad", "Verdana"]
Font.default_size = 22
Font.default_bold = true


Plane

The Plane class. Planes are special sprites that tile bitmap patterns across the entire screen and are used to display parallax backgrounds and so on.

Superclass

  • Object

Class Method

Plane.new([viewport])

Creates a Plane object. Specifies a viewport (Viewport) when necessary.

Methods

dispose

Frees the plane. If the plane has already been freed, does nothing.

disposed?

Returns TRUE if the plane has been freed.

Properties

bitmap

Refers to the bitmap (Bitmap) used in the plane.

viewport

Refers to the viewport (Viewport) associated with the plane.

visible

The plane's visibility. If TRUE, the plane is visible. The default value is TRUE.

z

The plane's z-coordinate. The larger the value, the closer to the player the plane will be displayed.

If multiple objects share the same z-coordinate, the more recently created object will be displayed closest to the player.

ox

The x-coordinate of the plane's starting point. Change this value to scroll the plane.

oy

The y-coordinate of the plane's starting point. Change this value to scroll the plane.

zoom_x

The plane's x-axis zoom level. 1.0 denotes actual pixel size.

zoom_y

The plane's y-axis zoom level. 1.0 denotes actual pixel size.

opacity

The plane's opacity (0-255). Out-of-range values are automatically corrected.

blend_type

The plane's blending mode (0: normal, 1: addition, 2: subtraction).

color

The color (Color) to be blended with the plane. Alpha values are used in the blending ratio.

tone

The plane's color tone (Tone).


Rect

The rectangle class.

Superclass

  • Object

Class Method

Rect.new(x, y, width, height)
Rect.new (RGSS3)

Creates a new Rect object.

The default values when no arguments are specified are (0, 0, 0, 0). (RGSS3)

Methods

set(x, y, width, height)
set(rect) (RGSS3)

Sets all parameters at once.

The second format copies all the components from a separate Rect object. (RGSS3)

empty

Sets all components to 0.

Properties

x

The x-coordinate of the rectangle's upper left corner.

y

The y-coordinate of the rectangle's upper left corner.

width

The rectangle's width.

height

The rectangle's height.


Sprite

The sprite class. Sprites are the basic concept used to display characters and other objects on the game screen.

Superclass

  • Object

Class Method

Sprite.new([viewport])

Creates a new sprite object. Specifies a viewport (Viewport) when necessary.

Methods

dispose

Frees the sprite. If the sprite has already been freed, does nothing.

disposed?

Returns TRUE if the sprite has been freed.

flash(color, duration)

Begins flashing the sprite. duration specifies the number of frames flashing will last.

If color is set to nil, the sprite will disappear while flashing.

update

Advances the sprite flash or wave phase. As a general rule, this method is called once per frame.

It is not necessary to call this if a flash or wave is not needed.

width

Gets the width of the sprite. Equivalent to src_rect.width.

height

Gets the height of the sprite. Equivalent to src_rect.height.

Properties

bitmap

Refers to the bitmap (Bitmap) used for the sprite's starting point.

src_rect

The box (Rect) taken from a bitmap.

viewport

Refers to the viewport (Viewport) associated with the sprite.

visible

The sprite's visibility. If TRUE, the sprite is visible. The default value is TRUE.

x

The sprite's x-coordinate.

y

The sprite's y-coordinate.

z

The sprite's z-coordinate. The larger the value, the closer to the player the sprite will be displayed.

If two sprites have the same z-coordinates, the one with the larger y-coordinate will be displayed closer to the player, and if the y-coordinates are the same, the one that was generated later will be displayed closer to the player.

ox

The x-coordinate of the sprite's starting point.

oy

The y-coordinate of the sprite's starting point.

zoom_x

The sprite's x-axis zoom level. 1.0 denotes actual pixel size.

zoom_y

The sprite's y-axis zoom level. 1.0 denotes actual pixel size.

angle

The sprite's angle of rotation. Specifies up to 360 degrees of counterclockwise rotation. However, drawing a rotated sprite is time-consuming, so avoid overuse.

wave_amp
wave_length
wave_speed
wave_phase

Defines the amplitude, frequency, speed, and phase of the wave effect. A raster scroll effect is achieved by using a sinusoidal function to draw the sprite with each line's horizontal position slightly different from the last.

wave_amp is the wave amplitude and wave_length is the wave frequency, and each is specified by a number of pixels.

wave_speed specifies the speed of the wave animation. The default is 360, and the larger the value, the faster the effect.

wave_phase specifies the phase of the top line of the sprite using an angle of up to 360 degrees. This is updated each time the update method is called. It is not necessary to use this property unless it is required for two sprites to have their wave effects synchronized.

mirror

A flag denoting the sprite has been flipped horizontally. If TRUE, the sprite will be drawn flipped. The default is false.

bush_depth
bush_opacity

The bush depth and opacity of a sprite. This can be used to represent a situation such as the character's legs being hidden by bushes.

For bush_depth, the number of pixels for the bush section is specified. The default value is 0.

For bush_opacity, the opacity of the bush section from 0 to 255 is specified. Out-of-range values will be corrected automatically. The default value is 128.

The bush_opacity value will be multiplied by opacity. For example, if both opacity and bush_opacity are set to 128, it will be handled as a transparency on top of a transparency, for an actual opacity of 64.

opacity

The sprite's opacity (0-255). Out-of-range values are automatically corrected.

blend_type

The sprite's blending mode (0: normal, 1: addition, 2: subtraction).

color

The color (Color) to be blended with the sprite. Alpha values are used in the blending ratio.

Handled separately from the color blended into a flash effect. However, the color with the higher alpha value when displayed will have the higher priority when blended.

tone

The sprite's color tone (Tone).


Table

The multidimensional array class. Each element is an integer of 2 signed bytes ranging from -32,768 to 32,767.

Ruby's Array class does not run efficiently when handling large amounts of data, hence the inclusion of this class.

Superclass

  • Object

Class Method

Table.new(xsize[, ysize[, zsize]])

Creates a Table object. Specifies the size of each dimension in the multidimensional array. 1-, 2-, and 3-dimensional arrays are possible. Arrays with no parameters are also permitted.

Methods

resize(xsize[, ysize[, zsize]])

Changes the size of the array. All data from before the size change is retained.

xsize
ysize
zsize

Gets the sizes of each of the array's dimensions.

Properties

self[x]
self[x, y]
self[x, y, z]

Accesses the array's elements. Pulls the same number of arguments as there are dimensions in the created array. Returns nil if the specified element does not exist.


Tilemap

The class governing tilemaps. Tilemaps are a specialized concept used in 2D game map displays, created internally from multiple sprites.

Superclass

  • Object

Class Method

Tilemap.new([viewport])

Creates a Tilemap object. Specifies a viewport (Viewport) when necessary.

Methods

dispose

Frees the tilemap. If the tilemap has already been freed, does nothing.

disposed?

Returns TRUE if the tilemap has been freed.

update

Updates the autotile animation etc. As a general rule, this method is called once per frame.

Properties

bitmaps[index]

Refers to the bitmap (Bitmap) indicated by the index number (0 - 8) that is used as a tile set.

The correspondence between numbers and sets is illustrated in the table below.

0 | TileA1 | 1 | TileA2 | 2 | TileA3
3 | TileA4 | 4 | TileA5 | 5 | TileB
6 | TileC | 7 | TileD | 8 | TileE
map_data

Refers to map data (Table). Defines a 3-dimensional array measuring [ horizontal size * vertical size * 3 ].

flash_data

Refers to the flash data (Table) used when showing range of possible movement in simulation games etc. Defines a 2-dimensional array measuring [ horizontal size * vertical size ]. This array must be the same size as the map data. Each element uses 4 bits to represent a tile's flash color in RGB; for example, 0xf84 flashes in RGB(15,8,4).

flags (RGSS3)

Refers to the flags table (Table). Defines a 1-dimensional array containing elements corresponding to tile IDs.

viewport

Refers to the viewport (Viewport) associated with the tilemap.

visible

The tilemap's visibility. If TRUE, the tilemap is visible. The default is TRUE.

ox

The x-coordinate of the tilemap's starting point. Change this value to scroll the tilemap.

oy

The y-coordinate of the tilemap's starting point. Change this value to scroll the tilemap.

Notes

The z-coordinate of each sprite used to create a tilemap is fixed to a specific value.

  1. A tile that should be displayed under the character has a Z coordinate of 0.
  2. A tile that should be displayed over the character has a Z coordinate of 200.

Keep these rules in mind when setting the z-coordinates of any map characters.


Tone

The color tone class. Each component is handled with a floating-point value (Float).

Superclass

  • Object

Class Method

Tone.new(red, green, blue[, gray])
Tone.new (RGSS3)

Creates a Tone object. If gray is omitted, it is assumed to be 0.

The default values when no arguments are specified are (0, 0, 0, 0). (RGSS3)

Methods

set(red, green, blue[, gray])
set(tone) (RGSS3)

Sets all components at once.

The second format copies all the components from a separate Tone object. (RGSS3)

Properties

red

The red balance adjustment value (-255 to 255). Out-of-range values are automatically corrected.

green

The green balance adjustment value (-255 to 255). Out-of-range values are automatically corrected.

blue

The blue balance adjustment value (-255 to 255). Out-of-range values are automatically corrected.

gray

The grayscale filter strength (0 to 255). Out-of-range values are automatically corrected.

When this value is not 0, processing time is significantly longer than when using tone balance adjustment values alone.


Viewport

The viewport class. Used when displaying sprites on one portion of the screen, with no overflow into other regions.

Superclass

  • Object

Class Methods

Viewport.new(x, y, width, height)
Viewport.new(rect)
Viewport.new (RGSS3)

Creates a viewport object.

Same size as the screen if no argument is specified. (RGSS3)

Methods

dispose

Frees the viewport. If the viewport has already been freed, does nothing.

This operation will not result in a separate associated object being automatically freed.

disposed?

Returns TRUE if the viewport has been freed.

flash(color, duration)

Begins flashing the viewport. duration specifies the number of frames the flash will last.

If color is set to nil, the viewport will disappear while flashing.

update

Refreshes the viewport flash. As a rule, this method is called once per frame.

It is not necessary to call this method if no flash effect is needed.

Properties

rect

The box (Rect) defining the viewport.

visible

The viewport's visibility. If TRUE, the viewport is visible. The default is TRUE.

z

The viewport's z-coordinate. The larger the value, the closer to the player the plane will be displayed.

If multiple objects share the same z-coordinate, the more recently created object will be displayed closest to the player.

ox

The x-coordinate of the viewport's starting point. Change this value to shake the screen, etc.

oy

The y-coordinate of the viewport's starting point. Change this value to shake the screen, etc.

color

The color (Color) to be blended with the viewport. Alpha values are used in the blending ratio.

Handled separately from the color blended into a flash effect.

tone

The viewport's color tone (Tone).


Window

The game window class. Created internally from multiple sprites.

Superclass

  • Object

Class Method

Window.new([x, y, width, height]) (RGSS3)

Creates a window object. Specifies position and size as necessary.

Methods

dispose

Frees the window. If the window has already been freed, does nothing.

disposed?

Returns TRUE if the window has been freed.

update

Refreshes the cursor blink and the pause graphic animation. As a general rule, this method is called once per frame.

move(x, y, width, height) (RGSS3)

Sets the x-coordinate, y-coordinate, width, and height all at once.

open? (RGSS3)

Returns true if the window is completely open (openness == 255).

close? (RGSS3)

Returns true if the window is completely closed (openness == 0).

Properties

windowskin

Refers to the bitmap (Bitmap) used as a window skin.

Skin specifications are nearly identical to those in the previous version (VX). Resource standards: See the detailed information on window skins.

contents

Refers to the bitmap (Bitmap) used for the window's contents.

cursor_rect

The cursor box (Rect).

Specifies a rectangle with coordinates based on the window's contents. (RGSS3)

viewport

Refers to the viewport (Viewport) associated with the window.

active

The cursor's blink status. If TRUE, the cursor is blinking. The default is TRUE.

visible

The window's visibility. If TRUE, the window is visible. The default is TRUE.

arrows_visible (RGSS3)

The visibility of scrolling arrows. If TRUE, the arrows are visible. The default is TRUE.

pause

The pause graphic's visibility. This is a symbol that appears in the message window when waiting for the player to press a button. If TRUE, the graphic is visible. The default is FALSE.

x

The window's x-coordinate.

y

The window's y-coordinate.

width

The window's width.

height

The window's height.

z

The window's z-coordinate. The larger the value, the closer to the player the window will be displayed.

If multiple objects share the same z-coordinate, the more recently created object will be displayed closest to the player.

The default is 100 (RGSS3).

ox

The x-coordinate of the starting point of the window's contents. Change this value to scroll the window's contents.

Also affects the cursor. (RGSS3)

oy

The y-coordinate of the starting point of the window's contents. Change this value to scroll the window's contents.

Also affects the cursor. (RGSS3)

padding (RGSS3)

The size of the padding between the window's frame and contents. The default value is 12. (RGSS3)

padding_bottom (RGSS3)

The padding for the bottom. Must be set after padding because it is changed along with it.

opacity

The window's opacity (0-255). Out-of-range values are automatically corrected. The default value is 255.

back_opacity

The window background's opacity (0-255). Out-of-range values are automatically corrected. The default value is 192 (RGSS3).

contents_opacity

The opacity of the window's contents (0-255). Out-of-range values are automatically corrected. The default value is 255.

openness

The openness of the window (from 0 to 255). Out-of-range values are automatically corrected.

By changing this value in stages from 0 (completely closed) to 255 (completely open), it is possible to create an animation of the window opening and closing. If the openness is less than 255, the contents of the window will not be displayed. The default value is 255.

tone (RGSS3)

The color (Tone) of the window's background.


RGSSError

An exception class providing notifications of RGSS internal errors.

Generated when, for instance, trying to access Bitmap or Sprite class objects that have already been freed.

Superclass

  • StandardError


RGSSReset

Exception class providing notifications for when the F12 key is pressed during game execution.

Name changed from the hidden class Reset before RGSS2. (RGSS3)

Superclass

  • Exception


RGSS Built-in Modules

  • Audio
  • Graphics
  • Input
  • RPG


Audio

The module that carries out music and sound processing.

Module Methods

Audio.setup_midi (RGSS3)

Prepares MIDI playback by DirectMusic.

A method of the processing at startup in RGSS2 for enabling execution at any time.

MIDI playback is possible without calling this method, but in Windows Vista or later, a delay of 1 to 2 seconds will result at playback.

Audio.bgm_play(filename[, volume[, pitch[, pos]]]) (RGSS3)

Starts BGM playback. Specifies the file name, volume, pitch, and playback starting position in that order.

The playback starting position (RGSS3) is only valid for ogg or wav files.

Also automatically searches files included in RGSS-RTP. File extensions may be omitted.

Audio.bgm_stop

Stops BGM playback.

Audio.bgm_fade(time)

Starts BGM fadeout. time is the length of the fadeout in milliseconds.

Audio.bgm_pos (RGSS3)

Gets the playback position of the BGM. Only valid for ogg or wav files. Returns 0 when not valid.

Audio.bgs_play(filename[, volume[, pitch[, pos]]]) (RGSS3)

Starts BGS playback. Specifies the file name, volume, pitch, and playback starting position in that order.

The playback starting position (RGSS3) is only valid for ogg or wav files.

Also automatically searches files included in RGSS-RTP. File extensions may be omitted.

Audio.bgs_stop

Stops BGS playback.

Audio.bgs_fade(time)

Starts BGS fadeout. time is the length of the fadeout in milliseconds.

Audio.bgs_pos (RGSS3)

Gets the playback position of the BGS. Only valid for ogg or wav files. Returns 0 when not valid.

Audio.me_play(filename[, volume[, pitch]])

Starts ME playback. Sets the file name, volume, and pitch in turn.

Also automatically searches files included in RGSS-RTP. File extensions may be omitted.

When ME is playing, the BGM will temporarily stop. The timing of when the BGM restarts is slightly different from RGSS1.

Audio.me_stop

Stops ME playback.

Audio.me_fade(time)

Starts ME fadeout. time is the length of the fadeout in milliseconds.

Audio.se_play(filename[, volume[, pitch]])

Starts SE playback. Sets the file name, volume, and pitch in turn.

Also automatically searches files included in RGSS-RTP. File extensions may be omitted.

When attempting to play the same SE more than once in a very short period, they will automatically be filtered to prevent choppy playback.

Audio.se_stop

Stops all SE playback.


Graphics

The module that carries out graphics processing.

Module Methods

Graphics.update

Refreshes the game screen and advances time by 1 frame. This method must be called at set intervals.

loop do
  Graphics.update
  Input.update
  do_something
end
Graphics.wait(duration)

Waits for the specified number of frames. Equivalent to the following:

duration.times do
  Graphics.update
end
Graphics.fadeout(duration)

Performs a fade-out of the screen.

duration is the number of frames to spend on the fade-out.

Graphics.fadein(duration)

Performs a fade-in of the screen.

duration is the number of frames to spend on the fade-in.

Graphics.freeze

Freezes the current screen in preparation for transitions.

Screen rewrites are prohibited until the transition method is called.

Graphics.transition([duration[, filename[, vague]]])

Carries out a transition from the screen frozen by Graphics.freeze to the current screen.

duration is the number of frames the transition will last. The default is 10.

filename specifies the file name of the transition graphic. When not specified, a standard fade will be used. Also automatically searches files included in RGSS-RTP and encrypted archives. File extensions may be omitted.

vague sets the ambiguity of the borderline between the graphic's starting and ending points. The larger the value, the greater the ambiguity. The default is 40.

Graphics.snap_to_bitmap

Gets the current game screen image as a bitmap object.

This reflects the graphics that should be displayed at that point in time, without relation to the use of the freeze method.

The created bitmap must be freed when it is no longer needed.

Graphics.frame_reset

Resets the screen refresh timing. Call this method after a time-consuming process to prevent excessive frame skipping.

Graphics.width
Graphics.height

Gets the width and height of the game screen.

These are normally 544 and 416, respectively.

Graphics.resize_screen(width, height)

Changes the size of the game screen.

Specify a value up to 640 × 480 for width and height.

Graphics.play_movie(filename) (RGSS3)

Plays the movie specified by filename.

Returns process after waiting for playback to end.

Module Properties

Graphics.frame_rate

The number of times the screen is refreshed per second. The larger the value, the more CPU power is required. Normally set at 60.

Changing this property is not recommended, but it can be set anywhere from 10 to 120. Out-of-range values are automatically corrected.

Graphics.frame_count

The screen's refresh rate count. Set this property to 0 at game start and the game play time (in seconds) can be calculated by dividing this value by the frame_rate property value.

Graphics.brightness

The brightness of the screen. Takes a value from 0 to 255. The fadeout, fadein, and transition methods change this value internally, as required.


Input

A module that handles input data from a gamepad or keyboard.

Managed by symbols rather than button numbers in RGSS3. (RGSS3)

Module Methods

Input.update

Updates input data. As a general rule, this method is called once per frame.

Input.press?(sym) (RGSS3)

Determines whether the button corresponding to the symbol sym is currently being pressed.

If the button is being pressed, returns TRUE. If not, returns FALSE.

if Input.press?(:C)
  do_something
end
Input.trigger?(sym) (RGSS3)

Determines whether the button corresponding to the symbol sym is currently being pressed again.

"Pressed again" is seen as time having passed between the button being not pressed and being pressed.

If the button is being pressed, returns TRUE. If not, returns FALSE.

Input.repeat?(sym) (RGSS3)

Determines whether the button corresponding to the symbol sym is currently being pressed again.

Unlike trigger?, takes into account the repeated input of a button being held down continuously.

If the button is being pressed, returns TRUE. If not, returns FALSE.

Input.dir4

Checks the status of the directional buttons, translates the data into a specialized 4-direction input format, and returns the number pad equivalent (2, 4, 6, 8).

If no directional buttons are being pressed (or the equivalent), returns 0.

Input.dir8

Checks the status of the directional buttons, translates the data into a specialized 8-direction input format, and returns the number pad equivalent (1, 2, 3, 4, 6, 7, 8, 9).

If no directional buttons are being pressed (or the equivalent), returns 0.

Constants

These constant names are used as the name of symbols. For example, right on the directional buttons can be specified using the notation :RIGHT. (RGSS3)

DOWN LEFT RIGHT UP

Symbols corresponding to the directions down, left, right, and up.

A B C X Y Z L R

The symbols corresponding to buttons.

SHIFT CTRL ALT

Symbols directly corresponding to the keyboard's SHIFT, CTRL, and ALT keys.

F5 F6 F7 F8 F9

Symbols corresponding to the keyboard's function keys. The other function keys are reserved by the system and cannot be obtained.


RPG

A module containing RPGVXAce data structures.


RPGVXAce Data Structures

  • RPG::Map
  • RPG::Map::Encounter
  • RPG::MapInfo
  • RPG::Event
  • RPG::Event::Page
  • RPG::Event::Page::Condition
  • RPG::Event::Page::Graphic
  • RPG::EventCommand
  • RPG::MoveRoute
  • RPG::MoveCommand
  • RPG::BaseItem
    • RPG::Actor
    • RPG::Class
    • RPG::UsableItem
      • RPG::Skill
      • RPG::Item
    • RPG::EquipItem
      • RPG::Weapon
      • RPG::Armor
    • RPG::Enemy
    • RPG::State
  • RPG::BaseItem::Feature
  • RPG::UsableItem::Damage
  • RPG::UsableItem::Effect
  • RPG::Class::Learning
  • RPG::Enemy::DropItem
  • RPG::Enemy::Action
  • RPG::Troop
  • RPG::Troop::Member
  • RPG::Troop::Page
  • RPG::Troop::Page::Condition
  • RPG::Animation
  • RPG::Animation::Frame
  • RPG::Animation::Timing
  • RPG::Tileset
  • RPG::CommonEvent
  • RPG::System
  • RPG::System::Vehicle
  • RPG::System::Terms
  • RPG::System::TestBattler
  • RPG::AudioFile
    • RPG::BGM
    • RPG::BGS
    • RPG::ME
    • RPG::SE


RPG::Map

The data class for maps.

Superclass

  • Object

Attributes

display_name

The map's display name.

tileset_id

The map's tile set.

width

The map's width.

height

The map's height.

scroll_type

The scroll type (0: No Loop, 1: Vertical Loop, 2: Horizontal Loop, 3: Both Loop).

specify_battleback

The truth value indicating whether the battle background specification is enabled.

battleback1_name

The file name of the floor graphic if the battle background specification is enabled.

battleback2_name

The file name of the wall graphic if the battle background specification is enabled.

autoplay_bgm

The truth value indicating whether BGM autoswitching is enabled.

bgm

The name of that BGM (RPG::BGM) if BGM autoswitching is enabled.

autoplay_bgs

The truth value indicating whether BGS autoswitching is enabled.

bgs

The name of that BGS (RPG::BGS) if BGS autoswitching is enabled.

disable_dashing

The truth value of the [Disable Dashing] option.

encounter_list

An encounter list. A RPG::Map::Encounter ID array.

encounter_step

The average number of steps between encounters.

parallax_name

The file name of the parallax background's graphic.

parallax_loop_x

The truth value of the [Loop Horizontal] option for the parallax background.

parallax_loop_y

The truth value of the [Loop Vertical] option for the parallax background.

parallax_sx

The automatic x-axis scrolling speed for the parallax background.

parallax_sy

The automatic y-axis scrolling speed for the parallax background.

parallax_show

The truth value of the [Show in the Editor] option for the parallax background.

note

The text of the note.

data

The map data. A 3-dimensional tile ID array (Table).

events

Map events. A hash that represents RPG::Event instances as values, using event IDs as the keys.

Inner Class

  • RPG::Map::Encounter

Definition

class RPG::Map
  def initialize(width, height)
    @display_name = ''
    @tileset_id = 1
    @width = width
    @height = height
    @scroll_type = 0
    @specify_battleback = false
    @battleback_floor_name = ''
    @battleback_wall_name = ''
    @autoplay_bgm = false
    @bgm = RPG::BGM.new
    @autoplay_bgs = false
    @bgs = RPG::BGS.new('', 80)
    @disable_dashing = false
    @encounter_list = []
    @encounter_step = 30
    @parallax_name = ''
    @parallax_loop_x = false
    @parallax_loop_y = false
    @parallax_sx = 0
    @parallax_sy = 0
    @parallax_show = false
    @note = ''
    @data = Table.new(width, height, 4)
    @events = {}
  end
  attr_accessor :display_name
  attr_accessor :tileset_id
  attr_accessor :width
  attr_accessor :height
  attr_accessor :scroll_type
  attr_accessor :specify_battleback
  attr_accessor :battleback1_name
  attr_accessor :battleback2_name
  attr_accessor :autoplay_bgm
  attr_accessor :bgm
  attr_accessor :autoplay_bgs
  attr_accessor :bgs
  attr_accessor :disable_dashing
  attr_accessor :encounter_list
  attr_accessor :encounter_step
  attr_accessor :parallax_name
  attr_accessor :parallax_loop_x
  attr_accessor :parallax_loop_y
  attr_accessor :parallax_sx
  attr_accessor :parallax_sy
  attr_accessor :parallax_show
  attr_accessor :note
  attr_accessor :data
  attr_accessor :events
end


RPG::Map::Encounter

The data class for the encounter settings.

Superclass

  • Object

Referrer

  • RPG::Map

Attributes

troop_id

The enemy troop ID.

weight

Weight.

region_set

An array containing region IDs.

Definition

class RPG::Map::Encounter
  def initialize
    @troop_id = 1
    @weight = 10
    @region_set = []
  end
  attr_accessor :troop_id
  attr_accessor :weight
  attr_accessor :region_set
end


RPG::MapInfo

The data class for map information.

Superclass

  • Object

Attributes

name

The map name.

parent_id

The parent map ID.

order

The map tree display order, which is used internally.

expanded

The map tree expansion flag, which is used internally.

scroll_x

The x-axis scroll position, which is used internally.

scroll_y

The y-axis scroll position, which is used internally.

Definition

class RPG::MapInfo
  def initialize
    @name = ''
    @parent_id = 0
    @order = 0
    @expanded = false
    @scroll_x = 0
    @scroll_y = 0
  end
  attr_accessor :name
  attr_accessor :parent_id
  attr_accessor :order
  attr_accessor :expanded
  attr_accessor :scroll_x
  attr_accessor :scroll_y
end


RPG::Event

The data class for map events.

Superclass

  • Object

Referrer

  • RPG::Map

Attributes

id

The event ID.

name

The event name.

x

The event's x-coordinate on the map.

y

The event's y-coordinate on the map.

pages

The event pages. RPG::Event::Page array.

Inner Class

  • RPG::Event::Page

Definition

class RPG::Event
  def initialize(x, y)
    @id = 0
    @name = ''
    @x = x
    @y = y
    @pages = [RPG::Event::Page.new]
  end
  attr_accessor :id
  attr_accessor :name
  attr_accessor :x
  attr_accessor :y
  attr_accessor :pages
end


RPG::Event::Page

The data class for the event page.

Superclass

  • Object

Referrer

  • RPG::Event

Attributes

condition

The event condition (RPG::Event::Page::Condition).

graphic

The event graphic (RPG::Event::Page::Graphic) .

move_type

The type of movement (0: fixed, 1: random, 2: approach, 3: custom).

move_speed

The movement speed (1: x8 slower, 2: x4 slower, 3: x2 slower, 4: normal, 5: x2 faster, 6: x4 faster).

move_frequency

The movement frequency (1: lowest, 2: lower, 3: normal, 4: higher, 5: highest).

move_route

The movement route (RPG::MoveRoute). Referenced only when the movement type is set to custom.

walk_anime

The truth value of the [Walking Animation] option.

step_anime

The truth value of the [Stepping Animation] option.

direction_fix

The truth value of the [Direction Fix] option.

through

The truth value of the [Through] option.

priority_type

The priority type (0: below characters, 1: same as characters, 2: above characters).

trigger

The event trigger (0: action button, 1: player touch, 2: event touch, 3: autorun, 4: parallel).

list

A list of event commands. An RPG::EventCommand array.

Inner Classes

  • RPG::Event::Page::Condition
  • RPG::Event::Page::Graphic

Definition

class RPG::Event::Page
  def initialize
    @condition = RPG::Event::Page::Condition.new
    @graphic = RPG::Event::Page::Graphic.new
    @move_type = 0
    @move_speed = 3
    @move_frequency = 3
    @move_route = RPG::MoveRoute.new
    @walk_anime = true
    @step_anime = false
    @direction_fix = false
    @through = false
    @priority_type = 0
    @trigger = 0
    @list = [RPG::EventCommand.new]
  end
  attr_accessor :condition
  attr_accessor :graphic
  attr_accessor :move_type
  attr_accessor :move_speed
  attr_accessor :move_frequency
  attr_accessor :move_route
  attr_accessor :walk_anime
  attr_accessor :step_anime
  attr_accessor :direction_fix
  attr_accessor :through
  attr_accessor :priority_type
  attr_accessor :trigger
  attr_accessor :list
end


RPG::Event::Page::Condition

The data class for the event page conditions.

Superclass

  • Object

Referrer

  • RPG::Event::Page

Attributes

switch1_valid

The truth value indicating whether the first [Switch] condition is valid.

switch2_valid

The truth value indicating whether the second [Switch] condition is valid.

variable_valid

The truth value indicating whether the [Variable] condition is valid.

self_switch_valid

The truth value indicating whether the [Self Switch] condition is valid.

item_valid

The truth value indicating whether the [Item] condition is valid.

actor_valid

The truth value indicating whether the [Actor] condition is valid.

switch1_id

The ID of that switch if the first [Switch] condition is valid.

switch2_id

The ID of that switch if the second [Switch] condition is valid.

variable_id

The ID of that variable if the [Variable] condition is valid.

variable_value

The standard value of that variable (x and greater) if the [Variable] condition is valid.

self_switch_ch

The letter of that self switch ("A".."D") if the [Self Switch] condition is valid.

item_id

The ID of that item if the [Item] condition is valid.

actor_id

The ID of that actor if the [Actor] condition is valid.

Definition

class RPG::Event::Page::Condition
  def initialize
    @switch1_valid = false
    @switch2_valid = false
    @variable_valid = false
    @self_switch_valid = false
    @item_valid = false
    @actor_valid = false
    @switch1_id = 1
    @switch2_id = 1
    @variable_id = 1
    @variable_value = 0
    @self_switch_ch = 'A'
    @item_id = 1
    @actor_id = 1
  end
  attr_accessor :switch1_valid
  attr_accessor :switch2_valid
  attr_accessor :variable_valid
  attr_accessor :self_switch_valid
  attr_accessor :item_valid
  attr_accessor :actor_valid
  attr_accessor :switch1_id
  attr_accessor :switch2_id
  attr_accessor :variable_id
  attr_accessor :variable_value
  attr_accessor :self_switch_ch
  attr_accessor :item_id
  attr_accessor :actor_id
end


RPG::Event::Page::Graphic

The data class for the Event page [Graphics].

Superclass

  • Object

Referrer

  • RPG::Event::Page

Attributes

tile_id

The tile ID. If the specified graphic is not a tile, this value is 0.

character_name

The file name of the character's graphic.

character_index

The index of the character's graphic file (0..7).

direction

The direction in which the character is facing (2: down, 4: left, 6: right, 8: up).

pattern

The character's pattern (0..2).

Definition

class RPG::Event::Page::Graphic
  def initialize
    @tile_id = 0
    @character_name = ''
    @character_index = 0
    @direction = 2
    @pattern = 0
  end
  attr_accessor :tile_id
  attr_accessor :character_name
  attr_accessor :character_index
  attr_accessor :direction
  attr_accessor :pattern
end


RPG::EventCommand

The data class for the Event command.

Superclass

  • Object

Referrers

  • RPG::Event::Page
  • RPG::Troop::Page
  • RPG::CommonEvent

Attributes

code

The event code.

indent

The indent depth. Usually 0. The [Conditional Branch] command, among others, adds 1 with every step deeper.

parameters

An array containing the Event command's arguments. The contents vary for each command.

Definition

class RPG::EventCommand
  def initialize(code = 0, indent = 0, parameters = [])
    @code = code
    @indent = indent
    @parameters = parameters
  end
  attr_accessor :code
  attr_accessor :indent
  attr_accessor :parameters
end


RPG::MoveRoute

The data class for the Move route.

Superclass

  • Object

Referrer

  • RPG::EventPage

Attributes

repeat

The truth value of the [Repeat Action] option.

skippable

The truth value of the [Skip If Cannot Move] option.

wait

The truth value of the [Wait for Completion] option.

list

Program contents. An RPG::MoveCommand array.

Definition

class RPG::MoveRoute
  def initialize
    @repeat = true
    @skippable = false
    @wait = false
    @list = [RPG::MoveCommand.new]
  end
  attr_accessor :repeat
  attr_accessor :skippable
  attr_accessor :wait
  attr_accessor :list
end


RPG::MoveRoute

RPG::MoveCommand

The data class for the Move command.

Superclass

  • Object

Referrer

  • RPG::MoveRoute

Attributes

code

Move command code.

parameters

An array containing the Move command's arguments. The contents vary for each command.

Definition

class RPG::MoveCommand
  def initialize(code = 0, parameters = [])
    @code = code
    @parameters = parameters
  end
  attr_accessor :code
  attr_accessor :parameters
end


RPG::Class::Learning

The data class for a class's [Skills to Learn].

Superclass

  • Object

Referrer

  • RPG::Class

Referrer

level

The skill's level.

skill_id

The ID of the skill to learn.

note

The text of the note.

Definition

class RPG::Class::Learning
  def initialize
    @level = 1
    @skill_id = 1
    @note = ''
  end
  attr_accessor :level
  attr_accessor :skill_id
  attr_accessor :note
end


RPG::BaseItem

A superclass of actor, class, skill, item, weapon, armor, enemy, and state.

Some items are unnecessary depending on the type of data, but they are included for convenience sake.

Superclass

  • Object

Attributes

id

The item ID.

name

The item name.

icon_index

The icon number.

description

The description text.

features

A list of features. An RPG::BaseItem::Feature array.

note

The text of the note.

Inner Classes

  • RPG::BaseItem::Feature

Definition

class RPG::BaseItem
  def initialize
    @id = 0
    @name = ''
    @icon_index = 0
    @description = ''
    @features = []
    @note = ''
  end
  attr_accessor :id
  attr_accessor :name
  attr_accessor :icon_index
  attr_accessor :description
  attr_accessor :features
  attr_accessor :note
end


RPG::Actor

The data class for actors.

Superclass

  • RPG::BaseItem

Attributes

nickname

The actor's nickname.

class_id

The actor's class ID.

initial_level

The actor's initial level.

max_level

The actor's max level

character_name

The file name of the actor's walking graphic.

character_index

The index (0..7) of the actor's walking graphic.

face_name

The file name of the actor's face graphic.

face_index

The index (0..7) of the actor's face graphic.

equips

The actor's initial equipment. An array of weapon IDs or armor IDs with the following subscripts:

  • 0: Weapon
  • 1: Shield
  • 2: Head
  • 3: Body
  • 4: Accessory

Definition

class RPG::Actor < RPG::BaseItem
  def initialize
    super
    @nickname = ''
    @class_id = 1
    @initial_level = 1
    @max_level = 99
    @character_name = ''
    @character_index = 0
    @face_name = ''
    @face_index = 0
    @equips = [0,0,0,0,0]
  end
  attr_accessor :nickname
  attr_accessor :class_id
  attr_accessor :initial_level
  attr_accessor :max_level
  attr_accessor :character_name
  attr_accessor :character_index
  attr_accessor :face_name
  attr_accessor :face_index
  attr_accessor :equips
end


RPG::Class

The data class for class.

Superclass

  • RPG::BaseItem

Attributes

exp_params

An array of values that decides the experience curve. The subscripts are as follows:

  • 0: Base value
  • 1: Extra value
  • 2: Acceleration A
  • 3: Acceleration B
params

The parameter development curve. A 2-dimensional array containing ordinary parameters according to level (Table).

The format is params[param_id, level], and param_id is assigned as follows:

  • 0: Maximum hit points
  • 1: Maximum magic points
  • 2: Attack power
  • 3: Defense power
  • 4: Magic attack power
  • 5: Magic defense power
  • 6: Agility
  • 7: Luck
learnings

The skills to learn. An array of RPG::Class::Learning.

Method

exp_for_level(level)

Calculates and returns the total experience required for leveling up to level.

Inner Class

  • RPG::Class::Learning

Definition

class RPG::Class < RPG::BaseItem
  def initialize
    super
    @exp_params = [30,20,30,30]
    @params = Table.new(8,100)
    (1..99).each do |i|
      @params[0,i] = 400+i*50
      @params[1,i] = 80+i*10
      (2..5).each {|j| @params[j,i] = 15+i*5/4 }
      (6..7).each {|j| @params[j,i] = 30+i*5/2 }
    end
    @learnings = []
    @features.push(RPG::BaseItem::Feature.new(23, 0, 1))
    @features.push(RPG::BaseItem::Feature.new(22, 0, 0.95))
    @features.push(RPG::BaseItem::Feature.new(22, 1, 0.05))
    @features.push(RPG::BaseItem::Feature.new(22, 2, 0.04))
    @features.push(RPG::BaseItem::Feature.new(41, 1))
    @features.push(RPG::BaseItem::Feature.new(51, 1))
    @features.push(RPG::BaseItem::Feature.new(52, 1))
  end
  def exp_for_level(level)
    lv = level.to_f
    basis = @exp_params[0].to_f
    extra = @exp_params[1].to_f
    acc_a = @exp_params[2].to_f
    acc_b = @exp_params[3].to_f
    return (basis*((lv-1)**(0.9+acc_a/250))*lv*(lv+1)/
      (6+lv**2/50/acc_b)+(lv-1)*extra).round.to_i
  end
  attr_accessor :exp_params
  attr_accessor :params
  attr_accessor :learnings
end


RPG::UsableItem

The Superclass of Skill and Item.

Superclass

  • RPG::BaseItem

Attributes

scope

The scope of effects.

  • 0: None
  • 1: One Enemy
  • 2: All Enemies
  • 3: One Random Enemy
  • 4: Two Random Enemies
  • 5: Three Random Enemies
  • 6: Four Random Enemies
  • 7: One Ally
  • 8: All Allies
  • 9: One Ally (Dead)
  • 10: All Allies (Dead)
  • 11: The User
occasion

When the item/skill may be used.

  • 0: Always
  • 1: Only in battle
  • 2: Only from the menu
  • 3: Never
speed

The speed correction.

success_rate

The success rate.

repeats

The number of repeats.

tp_gain

The number of TP gained.

hit_type

The type of hit.

  • 0: Certain hit
  • 1: Physical attack
  • 2: Magical attack
animation_id

The animation ID.

damage

Damage (RPG::UsableItem::Damage).

effects

A list of use effects. An RPG::UsableItem::Effect array.

Methods

for_opponent?

Determines whether the area of effect is enemies. Returns true if the value of scope is 1, 2, 3, 4, 5, or 6.

for_friend?

Determines whether the area of effect is allies. Returns true if the value of scope is 7, 8, 9, 10, or 11.

for_dead_friend?

Determines whether the area of effect is downed allies. Returns true if the value of scope is 9 or 10.

for_user?

Determines whether the area of effect is the user. Returns true if the value of scope is 11.

for_one?

Determines whether the area of effect is one character. Returns true if the value of scope is 1, 3, 7, 9, or 11.

for_random?

Determines whether the area of effect is random. Returns true if the value of scope is 3, 4, 5, or 6.

number_of_targets

The number of targets if the area of effect is random.

for_all?

Determines whether the area of effect is everyone. Returns true if the value of scope is 2, 9, or 10.

need_selection?

Determines whether selection of the target is required. Returns true if the value of scope is 1, 7, or 9.

battle_ok?

Determines whether it may be used on the battle screen. Returns true if the value of occasion is 0 or 1.

menu_ok?

Determines whether it may be used on the menu screen. Returns true if the value of occasion is 0 or 2.

certain?

Determines whether the hit type is a certain hit. Returns true if the value of hit_type is 0.

physical?

Determines whether the hit type is a physical attack. Returns true if the value of hit_type is 1.

magical?

Determines whether the hit type is a magical attack. Returns true if the value of hit_type is 2.

Inner Class

  • RPG::UsableItem::Damage
  • RPG::UsableItem::Effect

Definition

class RPG::UsableItem < RPG::BaseItem
  def initialize
    super
    @scope = 0
    @occasion = 0
    @speed = 0
    @success_rate = 100
    @repeats = 1
    @tp_gain = 0
    @hit_type = 0
    @animation_id = 0
    @damage = RPG::UsableItem::Damage.new
    @effects = []
  end
  def for_opponent?
    [1, 2, 3, 4, 5, 6].include?(@scope)
  end
  def for_friend?
    [7, 8, 9, 10, 11].include?(@scope)
  end
  def for_dead_friend?
    [9, 10].include?(@scope)
  end
  def for_user?
    @scope == 11
  end
  def for_one?
    [1, 3, 7, 9, 11].include?(@scope)
  end
  def for_random?
    [3, 4, 5, 6].include?(@scope)
  end
  def number_of_targets
    for_random? ? @scope - 2 : 0
  end
  def for_all?
    [2, 8, 10].include?(@scope)
  end
  def need_selection?
    [1, 7, 9].include?(@scope)
  end
  def battle_ok?
    [0, 1].include?(@occasion)
  end
  def menu_ok?
    [0, 2].include?(@occasion)
  end
  def certain?
    @hit_type == 0
  end
  def physical?
    @hit_type == 1
  end
  def magical?
    @hit_type == 2
  end
  attr_accessor :scope
  attr_accessor :occasion
  attr_accessor :speed
  attr_accessor :animation_id
  attr_accessor :success_rate
  attr_accessor :repeats
  attr_accessor :tp_gain
  attr_accessor :hit_type
  attr_accessor :damage
  attr_accessor :effects
end


RPG::Skill

The data class for skills.

Superclass

  • RPG::UsableItem

Attributes

stype_id

Skill type ID.

mp_cost

Number of MP consumed.

tp_cost

Number of TP consumed

message1
message2

The use message.

required_wtype_id1
required_wtype_id2

Weapon type required.

Definition

class RPG::Skill < RPG::UsableItem
  def initialize
    super
    @scope = 1
    @stype_id = 1
    @mp_cost = 0
    @tp_cost = 0
    @message1 = ''
    @message2 = ''
    @required_wtype_id1 = 0
    @required_wtype_id2 = 0
  end
  attr_accessor :stype_id
  attr_accessor :mp_cost
  attr_accessor :tp_cost
  attr_accessor :message1
  attr_accessor :message2
  attr_accessor :required_wtype_id1
  attr_accessor :required_wtype_id2
end


RPG::Item

The data class for items.

Superclass

  • RPG::UsableItem

Attributes

itype_id

The item type ID.

  • 1: Regular item
  • 2: Key item
price

The item's price.

consumable

The truth value indicating whether the item disappears when used.

Method

key_item?

Determines whether the item type is [Key Item]. Returns true if the value of itype_id is 2.

Definition

class RPG::Item < RPG::UsableItem
  def initialize
    super
    @scope = 7
    @itype_id = 1
    @price = 0
    @consumable = true
  end
  def key_item?
    @itype_id == 2
  end
  attr_accessor :itype_id
  attr_accessor :price
  attr_accessor :consumable
end


RPG::EquipItem

A superclass of weapons and armor.

Superclass

  • RPG::BaseItem

Attributes

price

The price of the weapon or armor.

etype_id

The type of weapon or armor.

  • 0: Weapon
  • 1: Shield
  • 2: Head
  • 3: Body
  • 4: Accessory
params

The amount of parameter change. An array of integers using the following IDs as subscripts:

  • 0: Maximum hit points
  • 1: Maximum magic points
  • 2: Attack power
  • 3: Defense power
  • 4: Magic attack power
  • 5: Magic defense power
  • 6: Agility
  • 7: Luck

Definition

class RPG::EquipItem < RPG::BaseItem
  def initialize
    super
    @price = 0
    @etype_id = 0
    @params = [0] * 8
  end
  attr_accessor :price
  attr_accessor :etype_id
  attr_accessor :params
end


RPG::Weapon

The data class for weapons.

Superclass

  • RPG::EquipItem

Attributes

wtype_id

The weapon type ID.

animation_id

The animation ID when using the weapon.

Method

performance

Evaluates weapon performance. Used by the Ultimate Equipment command.

Returns the total of attack + magic defense + all parameters.

Definition

class RPG::Weapon < RPG::EquipItem
  def initialize
    super
    @wtype_id = 0
    @animation_id = 0
    @features.push(RPG::BaseItem::Feature.new(31, 1, 0))
    @features.push(RPG::BaseItem::Feature.new(22, 0, 0))
  end
  def performance
    params[2] + params[4] + params.inject(0) {|r, v| r += v }
  end
  attr_accessor :wtype_id
  attr_accessor :animation_id
end


RPG::Armor

The data class for armor.

Superclass

  • RPG::EquipItem

Attributes

atype_id

The armor type ID.

Method

performance

Evaluates armor performance. Used by the ultimate equipment command.

Returns the total of defense + magic defense + all parameters.

Definition

class RPG::Armor < RPG::EquipItem
  def initialize
    super
    @atype_id = 0
    @etype_id = 1
    @features.push(RPG::BaseItem::Feature.new(22, 1, 0))
  end
  def performance
    params[3] + params[5] + params.inject(0) {|r, v| r += v }
  end
  attr_accessor :atype_id
end


RPG::Enemy

The data class for enemies.

Superclass

  • RPG::BaseItem

Attributes

battler_name

The file name of the enemy's battler graphic.

battler_hue

The adjustment value for the battler graphic's hue (0..360).

params

Parameters. An array of integers using the following IDs as subscripts:

  • 0: Maximum hit points
  • 1: Maximum magic points
  • 2: Attack power
  • 3: Defense power
  • 4: Magic attack power
  • 5: Magic defense power
  • 6: Agility
  • 7: Luck
exp

The enemy's experience.

gold

The enemy's gold.

drop_items

The items the enemy drops. An RPG::Enemy::DropItem array.

actions

The enemy's action pattern. An array of RPG::Enemy::Action.

Inner Class

  • RPG::Enemy::DropItem
  • RPG::Enemy::Action

Definition

class RPG::Enemy < RPG::BaseItem
  def initialize
    super
    @battler_name = ''
    @battler_hue = 0
    @params = [100,0,10,10,10,10,10,10]
    @exp = 0
    @gold = 0
    @drop_items = Array.new(3) { RPG::Enemy::DropItem.new }
    @actions = [RPG::Enemy::Action.new]
    @features.push(RPG::BaseItem::Feature.new(22, 0, 0.95))
    @features.push(RPG::BaseItem::Feature.new(22, 1, 0.05))
    @features.push(RPG::BaseItem::Feature.new(31, 1, 0))
  end
  attr_accessor :battler_name
  attr_accessor :battler_hue
  attr_accessor :params
  attr_accessor :exp
  attr_accessor :gold
  attr_accessor :drop_items
  attr_accessor :actions
end


RPG::State

The data class for state.

Superclass

  • RPG::BaseItem

Attributes

restriction

Action restrictions.

  • 0: None
  • 1: Attack enemy
  • 2: Attack enemy or ally
  • 3: Attack ally
  • 4: Cannot act
priority

The state priority (0..100).

remove_at_battle_end

Removes state at end of battle (true/false).

remove_by_restriction

Removes state by action restriction (true/false).

auto_removal_timing

The timing of automatic state removal.

  • 0: None
  • 1: At end of action
  • 2: At end of turn
min_turns
max_turns

Minimum and maximum values of the number of turns the state continues.

remove_by_damage

Removes state by damage (true/false).

chance_by_damage

Chance of state being removed by damage (%).

remove_by_walking

Removes state by walking (true/false).

steps_to_remove

Number of steps until state is removed.

message1
message2
message3
message4

Messages. From the top: Ally, enemy, continuing, removing.

Definition

class RPG::State < RPG::BaseItem
  def initialize
    super
    @restriction = 0
    @priority = 50
    @remove_at_battle_end = false
    @remove_by_restriction = false
    @auto_removal_timing = 0
    @min_turns = 1
    @max_turns = 1
    @remove_by_damage = false
    @chance_by_damage = 100
    @remove_by_walking = false
    @steps_to_remove = 100
    @message1 = ''
    @message2 = ''
    @message3 = ''
    @message4 = ''
  end
  attr_accessor :restriction
  attr_accessor :priority
  attr_accessor :remove_at_battle_end
  attr_accessor :remove_by_restriction
  attr_accessor :auto_removal_timing
  attr_accessor :min_turns
  attr_accessor :max_turns
  attr_accessor :remove_by_damage
  attr_accessor :chance_by_damage
  attr_accessor :remove_by_walking
  attr_accessor :steps_to_remove
  attr_accessor :message1
  attr_accessor :message2
  attr_accessor :message3
  attr_accessor :message4
end


RPG::BaseItem::Feature

The data class for features.

Superclass

  • Object

Referrer

  • RPG::BaseItem

Attributes

code

The feature code.

data_id

The ID of the data (such as attributes or states) according to the type of feature.

value

The value set according to the type of feature.

Definition

class RPG::BaseItem::Feature
  def initialize(code = 0, data_id = 0, value = 0)
    @code = code
    @data_id = data_id
    @value = value
  end
  attr_accessor :code
  attr_accessor :data_id
  attr_accessor :value
end


RPG::UsableItem::Damage

The data class for damage.

Superclass

  • Object

Referrer

  • RPG::UsableItem

Attributes

type

The type of damage.

  • 0: None
  • 1: HP damage
  • 2: MP damage
  • 3: HP recovery
  • 4: MP recovery
  • 5: HP drain
  • 6: MP drain
element_id

The element ID.

formula

The formula.

variance

The degree of variability.

critical

Critical hit (true/false).

Method

none?

Determines whether the damage type is [None]. Returns true if the value of type is 0.

to_hp?

Determines whether there is an effect on HP. Returns true if the value of type is 1, 3, or 5.

to_mp?

Determines whether there is an effect on MP. Returns true if the value of type is 2, 4, or 6.

recover?

Determines whether there is recovery. Returns true if the value of type is 3 or 4.

drain?

Determines whether there is draining. Returns true if the value of type is 5 or 6.

sign

The damage sign. Returns -1 if recovery, otherwise returns 1.

eval(a, b, v)

Evaluates the formula. The action-side battler, target-side battler, and in-game variable array ($game_variables) are specified by a, b, and v, respectively.

Returns a negative value if recovery.

Definition

class RPG::UsableItem::Damage
  def initialize
    @type = 0
    @element_id = 0
    @formula = '0'
    @variance = 20
    @critical = false
  end
  def none?
    @type == 0
  end
  def to_hp?
    [1,3,5].include?(@type)
  end
  def to_mp?
    [2,4,6].include?(@type)
  end
  def recover?
    [3,4].include?(@type)
  end
  def drain?
    [5,6].include?(@type)
  end
  def sign
    recover? ? -1 : 1
  end
  def eval(a, b, v)
    [Kernel.eval(@formula), 0].max * sign rescue 0
  end
  attr_accessor :type
  attr_accessor :element_id
  attr_accessor :formula
  attr_accessor :variance
  attr_accessor :critical
end


RPG::UsableItem::Effect

The data class for use effects.

Superclass

  • Object

Referrer

  • RPG::UsableItem

Attributes

code

The use effect code.

data_id

The ID of data (state, parameter, and so on) according to the type of use effect.

value1

Value 1 set according to the type of use effect.

value2

Value 2 set according to the type of use effect.

Definition

class RPG::UsableItem::Effect
  def initialize(code = 0, data_id = 0, value1 = 0, value2 = 0)
    @code = code
    @data_id = data_id
    @value1 = value1
    @value2 = value2
  end
  attr_accessor :code
  attr_accessor :data_id
  attr_accessor :value1
  attr_accessor :value2
end


RPG::Enemy::DropItem

The data class for enemy [Drop Items].

Superclass

  • Object

Referrer

  • RPG::Enemy

Attributes

kind

The type of dropped item.

  • 0: None
  • 1: Item
  • 2: Weapon
  • 3: Armor
data_id

The ID of the data depending on the type of dropped item (item, weapon, or armor).

denominator

N of the probability that the item will be dropped, 1/N.

Definition

class RPG::Enemy::DropItem
  def initialize
    @kind = 0
    @data_id = 1
    @denominator = 1
  end
  attr_accessor :kind
  attr_accessor :data_id
  attr_accessor :denominator
end


RPG::Enemy::Action

The data class for enemy [Actions].

Superclass

  • Object

Referrer

  • RPG::Enemy

Attributes

skill_id

The ID of skills to be employed as actions.

condition_type

The type of condition.

  • 0: Always
  • 1: Turn No.
  • 2: HP
  • 3: MP
  • 4: State
  • 5: Party Level
  • 6: Switch
condition_param1
condition_param2

An action condition parameter. Shared by all types.

For example, if the condition is [HP], then condition_param1 will be the minimum value and condition_param2 will be the maximum value.

rating

The action's priority rating (1..10).

Definition

class RPG::Enemy::Action
  def initialize
    @skill_id = 1
    @condition_type = 0
    @condition_param1 = 0
    @condition_param2 = 0
    @rating = 5
  end
  attr_accessor :skill_id
  attr_accessor :condition_type
  attr_accessor :condition_param1
  attr_accessor :condition_param2
  attr_accessor :rating
end


RPG::Troop

The data class for enemy troops.

Superclass

  • Object

Attributes

id

The troop ID.

name

The troop name.

members

The troop members. An RPG::Troop::Member array.

pages

The battle events. An RPG::Troop::Page array.

Inner Classes

  • RPG::Troop::Member
  • RPG::Troop::Page

Definition

class RPG::Troop
  def initialize
    @id = 0
    @name = ''
    @members = []
    @pages = [RPG::Troop::Page.new]
  end
  attr_accessor :id
  attr_accessor :name
  attr_accessor :members
  attr_accessor :pages
end


RPG::Troop::Member

The data class for enemy troop members.

Superclass

  • Object

Referrer

  • RPG::Troop

Attributes

enemy_id

The enemy ID.

x

The troop member's x-coordinate.

y

The troop member's y-coordinate.

hidden

The truth value of the [Appear Halfway] option.

Definition

class RPG::Troop::Member
  def initialize
    @enemy_id = 1
    @x = 0
    @y = 0
    @hidden = false
  end
  attr_accessor :enemy_id
  attr_accessor :x
  attr_accessor :y
  attr_accessor :hidden
end


RPG::Troop::Page

The data class for battle events (pages).

Superclass

  • Object

Referrer

  • RPG::Troop

Attributes

condition

Condition (RPG::Troop::Page::Condition).

span

Span (0: battle, 1: turn, 2: moment).

list

Program contents. An RPG::EventCommand array.

Inner Class

  • RPG::Troop::Page::Condition

Definition

class RPG::Troop::Page
  def initialize
    @condition = RPG::Troop::Page::Condition.new
    @span = 0
    @list = [RPG::EventCommand.new]
  end
  attr_accessor :condition
  attr_accessor :span
  attr_accessor :list
end


RPG::Troop::Page::Condition

The data class of battle event [Conditions].

Superclass

  • Object

Referrer

  • RPG::Troop::Page

Attributes

turn_ending

The truth value indicating whether the [At End of Turn] condition is valid.

turn_valid

The truth value indicating whether the [Turn No.] condition is valid.

enemy_valid

The truth value indicating whether the [Enemy] condition is valid.

actor_valid

The truth value indicating whether the [Actor] condition is valid.

switch_valid

The truth value indicating whether the [Switch] condition is valid.

turn_a
turn_b

The a and b values specified in the [Turn No.] condition. To be input in the form A + B * X.

enemy_index

The troop member index specified in the [Enemy] condition (0..7).

enemy_hp

The HP percentage specified in the [Enemy] condition.

actor_id

The actor ID specified in the [Actor] condition.

actor_hp

The HP percentage specified in the [Actor] condition.

switch_id

The switch ID specified in the [Switch] condition.

Definition

class RPG::Troop::Page::Condition
  def initialize
    @turn_ending = false
    @turn_valid = false
    @enemy_valid = false
    @actor_valid = false
    @switch_valid = false
    @turn_a = 0
    @turn_b = 0
    @enemy_index = 0
    @enemy_hp = 50
    @actor_id = 1
    @actor_hp = 50
    @switch_id = 1
  end
  attr_accessor :turn_ending
  attr_accessor :turn_valid
  attr_accessor :enemy_valid
  attr_accessor :actor_valid
  attr_accessor :switch_valid
  attr_accessor :turn_a
  attr_accessor :turn_b
  attr_accessor :enemy_index
  attr_accessor :enemy_hp
  attr_accessor :actor_id
  attr_accessor :actor_hp
  attr_accessor :switch_id
end


RPG::Animation

The data class for animation.

Superclass

  • Object

Attributes

id

The animation ID.

name

The animation name.

animation1_name

The file name of the first animation's graphic.

animation1_hue

The adjustment value for the hue of the first animation's graphic (0..360).

animation2_name

The file name of the second animation's graphic.

animation2_hue

The adjustment value for the hue of the second animation's graphic (0..360).

position

The base position (0: head, 1: center, 2: feet, 3: screen).

frame_max

Number of frames.

frames

Frame contents. An RPG::Animation::Frame array.

timings

Timing for SE and flash effects. An RPG::Animation::Timing array.

Method

to_screen?

Determines whether the animation is to be displayed full screen. Returns true if the value of position is 3.

Inner Classes

  • RPG::Animation::Frame
  • RPG::Animation::Timing

Definition

class RPG::Animation
  def initialize
    @id = 0
    @name = ''
    @animation1_name = ''
    @animation1_hue = 0
    @animation2_name = ''
    @animation2_hue = 0
    @position = 1
    @frame_max = 1
    @frames = [RPG::Animation::Frame.new]
    @timings = []
  end
  def to_screen?
    @position == 3
  end
  attr_accessor :id
  attr_accessor :name
  attr_accessor :animation1_name
  attr_accessor :animation1_hue
  attr_accessor :animation2_name
  attr_accessor :animation2_hue
  attr_accessor :position
  attr_accessor :frame_max
  attr_accessor :frames
  attr_accessor :timings
end


RPG::Animation::Frame

The data class for animation frames.

Superclass

  • Object

Referrer

  • RPG::Animation

Attributes

cell_max

The number of cells. Equivalent to the largest cell number in the frame set.

cell_data

2-dimensional array containing cell contents (Table).

Generally takes the form cell_data[cell_index, data_index].

data_index ranges from 0 to 7 and represents a variety of information about a cell (0: pattern, 1: x-coordinate, 2: y-coordinate, 3: zoom level, 4: angle of rotation, 5: horizontal flip, 6: opacity, 7: blending mode). Patterns are 1 less than the number displayed in RPG Maker. -1 indicates that the cell is not in use.

Definition

class RPG::Animation::Frame
  def initialize
    @cell_max = 0
    @cell_data = Table.new(0, 0)
  end
  attr_accessor :cell_max
  attr_accessor :cell_data
end


RPG::Animation::Timing

The data class for the timing of an animation's SE and flash effects.

Superclass

  • Object

Referrer

  • RPG::Animation

Attributes

frame

The frame number. 1 less than the number displayed in RPG Maker.

se

The sound effect or SE (RPG::SE).

flash_scope

The flash area (0: none, 1: target, 2: screen; 3: hide target).

flash_color

The color of the flash (Color).

flash_duration

The duration of the flash.

Definition

class RPG::Animation::Timing
  def initialize
    @frame = 0
    @se = RPG::SE.new('', 80)
    @flash_scope = 0
    @flash_color = Color.new(255,255,255,255)
    @flash_duration = 5
  end
  attr_accessor :frame
  attr_accessor :se
  attr_accessor :flash_scope
  attr_accessor :flash_color
  attr_accessor :flash_duration
end


RPG::Tileset

The data class for tile sets.

Superclass

  • Object

Attributes

id

The ID of the tile set.

name

The name of the tile set.

mode

The mode of the tile set (0: Field type, 1: Area type, 2: VX compatible type).

tileset_names[index]

The file name of the graphic used as the number index (0-8) tile set.

The correspondence between numbers and sets is illustrated in the table below.

0 | TileA1 | 1 | TileA2 | 2 | TileA3
3 | TileA4 | 4 | TileA5 | 5 | TileB
6 | TileC | 7 | TileD | 8 | TileE
flags

The flags table. A 1-dimensional array containing a variety of flags (Table).

Uses tile IDs as subscripts. The correspondence of each bit is as shown below:

  • 0x0001: Impassable downward
  • 0x0002: Impassable leftward
  • 0x0004: Impassable rightward
  • 0x0008: Impassable upward
  • 0x0010: Display on normal character
  • 0x0020: Ladder
  • 0x0040: Bush
  • 0x0080: Counter
  • 0x0100: Damage floor
  • 0x0200: Impassable by boat
  • 0x0400: Impassable by ship
  • 0x0800: Airship cannot land
  • 0xF000: Terrain tag

This manual does not discuss bit operations, but they are similar to those in C. We recommend an Internet search using keywords such as "hexadecimal bit operations" when necessary.

note

The text of the note.

Definition

class RPG::Tileset
  def initialize
    @id = 0
    @mode = 1
    @name = ''
    @tileset_names = Array.new(9).collect{''}
    @flags = Table.new(8192)
    @flags[0] = 0x0010
    (2048..2815).each {|i| @flags[i] = 0x000F}
    (4352..8191).each {|i| @flags[i] = 0x000F}
    @note = ''
  end
  attr_accessor :id
  attr_accessor :mode
  attr_accessor :name
  attr_accessor :tileset_names
  attr_accessor :flags
  attr_accessor :note
end


RPG::CommonEvent

The data class for common events.

Superclass

  • Object

Attributes

id

The event ID.

name

The event name.

trigger

The event trigger (0: none, 1: autorun; 2: parallel).

switch_id

The condition switch ID.

list

A list of event commands. An RPG::EventCommand array.

Methods

autorun?

Determines whether the event is an autorun event. Returns true if the value of the trigger is 1.

parallel?

Determines whether the event is a parallel event. Returns true if the value of the trigger is 2.

Definition

class RPG::CommonEvent
  def initialize
    @id = 0
    @name = ''
    @trigger = 0
    @switch_id = 1
    @list = [RPG::EventCommand.new]
  end
  def autorun?
    @trigger == 1
  end
  def parallel?
    @trigger == 2
  end
  attr_accessor :id
  attr_accessor :name
  attr_accessor :trigger
  attr_accessor :switch_id
  attr_accessor :list
end


RPG::System

The data class for the system.

Superclass

  • Object

Attributes

game_title

The game title.

version_id

A random number used for update checks. The number changes every time data is saved in RPG Maker.

japanese

Always true in the Japanese version.

party_members

The initial party. An array of actor IDs.

currency_unit

The unit of currency.

window_tone

The window color (Tone)B

elements

A list of elements. A string array using element IDs as subscripts, with the element in the 0 position being nil.

skill_types

A list of skill types. A string array using skill type IDs as subscripts, with the element in the 0 position being nil.

weapon_types

A list of weapon types. A string array using weapon type IDs as subscripts, with the element in the 0 position being nil.

armor_types

A list of armor types. A string array using armor type IDs as subscripts, with the element in the 0 position being nil.

switches

A switch name list. A string array using switch IDs as subscripts, with the element in the 0 position being nil.

variables

A variable name list. A string array using variable IDs as subscripts, with the element in the 0 position being nil.

boat

Boat settings (RPG::System::Vehicle).

ship

Ship settings (RPG::System::Vehicle).

airship

Airship settings (RPG::System::Vehicle).

title1_name

The file name of the title (background) graphic.

title2_name

The file name of the title (frame) graphic.

opt_draw_title

The truth value of the [Draw Game Title] option.

opt_use_midi

The truth value of the [Initialize MIDI at Startup] option.

opt_transparent

The truth value of the [Start Transparent] option.

opt_followers

The truth value of the [Show Player Followers] option.

opt_slip_death

The truth value of the [K.O. by Slip Damage] option.

opt_floor_death

The truth value of the [K.O. by Floor Damage] option.

opt_display_tp

The truth value of the [Display TP in Battle] option.

opt_extra_exp

The truth value of the [Reserve Members' EXP] option.

title_bgm

The title BGM (RPG::BGM).

battle_bgm

The battle BGM (RPG::BGM).

battle_end_me

The battle end ME (RPG::ME).

gameover_me

The gameover ME (RPG::ME).

sounds

Sound effects. An RPG::SE array.

start_map_id

The map ID of the player's initial position.

start_x

The map's x-coordinate of the player's initial position.

start_y

The map's y-coordinate of the player's initial position.

terms

Terms (RPG::System::Terms).

test_battlers

Party settings for battle tests. An RPG::System::TestBattler array.

test_troop_id

The enemy troop ID for battle tests.

battleback1_name

The file name of the battle background (floor) graphic for use in editing enemy troops and battle tests.

battleback2_name

The file name of the battle background (wall) graphic for use in editing enemy troops and battle tests.

battler_name

The battler graphic file name for use in editing animations.

battler_hue

The adjustment value for the battler graphic's hue (0..360) for use in editing animations.

edit_map_id

The ID of the map currently being edited. For internal use.

Inner Classes

  • RPG::System::Vehicle
  • RPG::System::Terms
  • RPG::System::TestBattler

Definition

class RPG::System
  def initialize
    @game_title = ''
    @version_id = 0
    @japanese = true
    @party_members = [1]
    @currency_unit = ''
    @elements = [nil, '']
    @skill_types = [nil, '']
    @weapon_types = [nil, '']
    @armor_types = [nil, '']
    @switches = [nil, '']
    @variables = [nil, '']
    @boat = RPG::System::Vehicle.new
    @ship = RPG::System::Vehicle.new
    @airship = RPG::System::Vehicle.new
    @title1_name = ''
    @title2_name = ''
    @opt_draw_title = true
    @opt_use_midi = false
    @opt_transparent = false
    @opt_followers = true
    @opt_slip_death = false
    @opt_floor_death = false
    @opt_display_tp = true
    @opt_extra_exp = false
    @window_tone = Tone.new(0,0,0)
    @title_bgm = RPG::BGM.new
    @battle_bgm = RPG::BGM.new
    @battle_end_me = RPG::ME.new
    @gameover_me = RPG::ME.new
    @sounds = Array.new(24) { RPG::SE.new }
    @test_battlers = []
    @test_troop_id = 1
    @start_map_id = 1
    @start_x = 0
    @start_y = 0
    @terms = RPG::System::Terms.new
    @battleback1_name = ''
    @battleback2_name = ''
    @battler_name = ''
    @battler_hue = 0
    @edit_map_id = 1
  end
  attr_accessor :game_title
  attr_accessor :version_id
  attr_accessor :japanese
  attr_accessor :party_members
  attr_accessor :currency_unit
  attr_accessor :skill_types
  attr_accessor :weapon_types
  attr_accessor :armor_types
  attr_accessor :elements
  attr_accessor :switches
  attr_accessor :variables
  attr_accessor :boat
  attr_accessor :ship
  attr_accessor :airship
  attr_accessor :title1_name
  attr_accessor :title2_name
  attr_accessor :opt_draw_title
  attr_accessor :opt_use_midi
  attr_accessor :opt_transparent
  attr_accessor :opt_followers
  attr_accessor :opt_slip_death
  attr_accessor :opt_floor_death
  attr_accessor :opt_display_tp
  attr_accessor :opt_extra_exp
  attr_accessor :window_tone
  attr_accessor :title_bgm
  attr_accessor :battle_bgm
  attr_accessor :battle_end_me
  attr_accessor :gameover_me
  attr_accessor :sounds
  attr_accessor :test_battlers
  attr_accessor :test_troop_id
  attr_accessor :start_map_id
  attr_accessor :start_x
  attr_accessor :start_y
  attr_accessor :terms
  attr_accessor :battleback1_name
  attr_accessor :battleback2_name
  attr_accessor :battler_name
  attr_accessor :battler_hue
  attr_accessor :edit_map_id
end


RPG::System::Vehicle

The data class for vehicles.

Superclass

  • Object

Referrer

  • RPG::System

Attributes

character_name

The file name of the vehicle's walking graphic.

character_index

The index of the vehicle's walking graphic (0..7).

bgm

The vehicle's BGM (RPG::BGM).

start_map_id

The map ID of the vehicle's initial position.

start_x

The map's x-coordinate of the vehicle's initial position.

start_y

The map's y-coordinate of the vehicle's initial position.

Definition

class RPG::System::Vehicle
  def initialize
    @character_name = ''
    @character_index = 0
    @bgm = RPG::BGM.new
    @start_map_id = 0
    @start_x = 0
    @start_y = 0
  end
  attr_accessor :character_name
  attr_accessor :character_index
  attr_accessor :bgm
  attr_accessor :start_map_id
  attr_accessor :start_x
  attr_accessor :start_y
end


RPG::System::Terms

The data class for terminology.

Superclass

  • Object

Referrer

  • RPG::System

Attributes

basic

The basic status. A string array with the following subscripts:

  • 0: Level
  • 1: Level (short)
  • 2: HP
  • 3: HP (short)
  • 4: MP
  • 5: MP (short)
  • 6: TP
  • 7: TP (short)
params

Parameters. A string array with the following subscripts:

  • 0: Maximum hit points
  • 1: Maximum magic points
  • 2: Attack power
  • 3: Defense power
  • 4: Magic attack power
  • 5: Magic defense power
  • 6: Agility
  • 7: Luck
etypes

The equipment type. A string array with the following subscripts:

  • 0: Weapon
  • 1: Shield
  • 2: Head
  • 3: Body
  • 4: Accessory
commands

Commands. A string array with the following subscripts:

  • 0: Fight
  • 1: Escape
  • 2: Attack
  • 3: Defend
  • 4: Item
  • 5: Skill
  • 6: Equip
  • 7: Status
  • 8: Sort
  • 9: Save
  • 10: Exit Game
  • 11: (not used)
  • 12: Weapon
  • 13: Armor
  • 14: Key Item
  • 15: Change Equipment
  • 16: Ultimate Equipment
  • 17: Remove All
  • 18: New Game
  • 19: Continue
  • 20: Shut Down
  • 21: Go to Title
  • 22: Cancel

Definition

class RPG::System::Terms
  def initialize
    @basic = Array.new(8) {''}
    @params = Array.new(8) {''}
    @etypes = Array.new(5) {''}
    @commands = Array.new(23) {''}
  end
  attr_accessor :basic
  attr_accessor :params
  attr_accessor :etypes
  attr_accessor :commands
end


RPG::System::TestBattler

The data class for the actors used in battle tests.

Superclass

  • Object

Referrer

  • RPG::System

Attributes

actor_id

The actor ID.

level

The actor's level.

equips

The actor's equipment. An array of weapon IDs or armor IDs with the following subscripts:

  • 0: Weapon
  • 1: Shield
  • 2: Head
  • 3: Body
  • 4: Accessory

Definition

class RPG::System::TestBattler
  def initialize
    @actor_id = 1
    @level = 1
    @equips = [0,0,0,0,0]
  end
  attr_accessor :actor_id
  attr_accessor :level
  attr_accessor :equips
end


RPG::AudioFile

A superclass of BGM, BGS, ME, and SE.

Superclass

  • Object

Attributes

name

The sound file name.

volume

The sound's volume (0..100). The default values are 100 for BGM and ME and 80 for BGS and SE.

pitch

The sound's pitch (50..150). The default value is 100.

Definition

class RPG::AudioFile
  def initialize(name = '', volume = 100, pitch = 100)
    @name = name
    @volume = volume
    @pitch = pitch
  end
  attr_accessor :name
  attr_accessor :volume
  attr_accessor :pitch
end


RPG::BGM

The data class for BGM.This class has functionality for playing itself using an Audio module.

Superclass

  • RPG::AudioFile

Referrers

  • RPG::Map
  • RPG::System
  • RPG::System::Vehicle
  • RPG::EventCommand

Class Methods

RPG::BGM.last

Gets the BGM (RPG::BGM) that is currently playing.

Also saves the current playback position in the obtained object. (RGSS3)

Returns an empty object if no BGM is playing.

RPG::BGM.stop

Stops BGM playback.

RPG::BGM.fade(time)

Starts BGM fadeout. time is the length of the fadeout in milliseconds.

Methods

play([pos]) (RGSS3)

Starts the BGM playback.

The playback starting position can be specified by pos for ogg or wav files. (RGSS3)

replay (RGSS3)

Replays the BGM obtained by RPG::BGM.last.

’è‹`

class RPG::BGM < RPG::AudioFile
  @@last = RPG::BGM.new
  def play(pos = 0)
    if @name.empty?
      Audio.bgm_stop
      @@last = RPG::BGM.new
    else
      Audio.bgm_play('Audio/BGM/' + @name, @volume, @pitch, pos)
      @@last = self.clone
    end
  end
  def replay
    play(@pos)
  end
  def self.stop
    Audio.bgm_stop
    @@last = RPG::BGM.new
  end
  def self.fade(time)
    Audio.bgm_fade(time)
    @@last = RPG::BGM.new
  end
  def self.last
    @@last.pos = Audio.bgm_pos
    @@last
  end
  attr_accessor :pos
end


RPG::BGS

The data class for BGS. This class has functionality for playing itself using an Audio module.

Superclass

  • RPG::AudioFile

Referrers

  • RPG::Map
  • RPG::EventCommand

Class Methods

RPG::BGS.last

Gets the BGS (RPG::BGS) that is currently playing.

Also saves the current playback position in the obtained object. (RGSS3)

Returns an empty object if no BGS is playing.

RPG::BGS.stop

Stops BGS playback.

RPG::BGS.fade(time)

Starts BGS fadeout. time is the length of the fadeout in milliseconds.

Methods

play([pos]) (RGSS3)

Starts the BGS playback.

The starting position can be specified by pos for ogg or wav files. (RGSS3)

replay (RGSS3)

Replays BGS obtained by RPG::BGS.last.

Definition

class RPG::BGS < RPG::AudioFile
  @@last = RPG::BGS.new
  def play(pos = 0)
    if @name.empty?
      Audio.bgs_stop
      @@last = RPG::BGS.new
    else
      Audio.bgs_play('Audio/BGS/' + @name, @volume, @pitch, pos)
      @@last = self.clone
    end
  end
  def replay
    play(@pos)
  end
  def self.stop
    Audio.bgs_stop
    @@last = RPG::BGS.new
  end
  def self.fade(time)
    Audio.bgs_fade(time)
    @@last = RPG::BGS.new
  end
  def self.last
    @@last.pos = Audio.bgs_pos
    @@last
  end
  attr_accessor :pos
end


RPG::ME

The data class for ME. This class has functionality for playing itself using an Audio module.

Superclass

  • RPG::AudioFile

Referrers

  • RPG::System
  • RPG::EventCommand

Class Methods

RPG::ME.stop

Stops ME playback.

RPG::ME.fade(time)

Starts ME fadeout. time is the length of the fadeout in milliseconds.

Method

play

Starts the ME playback.

Definition

class RPG::ME < RPG::AudioFile
  def play
    if @name.empty?
      Audio.me_stop
    else
      Audio.me_play('Audio/ME/' + @name, @volume, @pitch)
    end
  end
  def self.stop
    Audio.me_stop
  end
  def self.fade(time)
    Audio.me_fade(time)
  end
end


RPG::SE

The data class for SE. This class has functionality for playing itself using an Audio module.

Superclass

  • RPG::AudioFile

Referrers

  • RPG::Animation::Timing
  • RPG::System
  • RPG::EventCommand
  • RPG::MoveCommand

Class Method

RPG::SE.stop

Stops SE playback.

Method

play

Starts the SE playback.

Definition

class RPG::SE < RPG::AudioFile
  def play
    unless @name.empty?
      Audio.se_play('Audio/SE/' + @name, @volume, @pitch)
    end
  end
  def self.stop
    Audio.se_stop
  end
end


Appendix

  • Regular Expressions
  • sprintf Format


Regular Expressions

  • Back References
  • Character Class

A list of all the regular expression characters (metacharacters) that Ruby supports is provided below.

  • Alphanumeric characters without \ are not metacharacters
  • Symbols with \ are not metacharacters

The above two rules apply to metacharacters.

  • ^

    Beginning of line. Match directly after the first character or line feed character.

  • $

    End of line. Match directly before the end of a character string or line feed character.

    p "\n".gsub(/$/, "o")     # => "o\no"

  • .

    Match any single character, excluding a line feed (when working with multi-byte characters, this refers to one character, not one byte). With the Regular Expression option m (multiple line mode. See Regular Expression Literals.), it matches any character that includes a line feed.

    p /./e =~ " A "[0,1]     # => nil

  • \w

    Alphanumeric character. The same as [0-9A-Za-z_]

    Also matches Japanese double-byte characters.

  • \W

    Non-alphanumeric character. Characters besides \w.

  • \s

    Space character. The same as [ \t\n\r\f].

  • \S

    Non-space character. Characters besides [ \t\n\r\f]

  • \d

    Number. The same as [0-9].

  • \D

    Non-number.

  • \A

    Beginning of a character string. Unlike ^, the presence of a line feed has no effect.

  • \Z

    End of a character string. Also matches the characters directly preceding a line feed if the string ends with one.

    p "\n".gsub(/\Z/, "o")     # => "o\no"

  • \z

    End of a character string. Unlike $ or \Z, the presence of a line feed has no effect.

  • \b

    A language boundary outside the specified character class. (Matches between \w and \W.) While in the specified class, it is a backspace (0x08).

  • \B

    Non-language boundary.

  • \G

    Matches (doesn't have a width) the place matched from the previous one (directly after). Matches the front position only the first time. (Same as \A)

    Can be used with scan or gsub. Use when you want to make a match after the location that was matched the previous time.

    #  Takes values from the front of the line three digits at a time (for as long as the values continue.)
str = "123456 789"
str.scan(/\G\d\d\d/) {|m| p m }

  • [ ]

    Set character class. See Character Class.

  • *

    Returns the previous expression 0 or more times. Will try to match for as long as possible.

  • *?

    Quantifiers. Returns the previous expression 0 or more times. (Shortest match.)

  • +

    Quantifiers. Returns the previous expression 1 or more times.

  • +?

    Quantifiers. Returns the previous expression 1 or more times. (Shortest match.)

  • {m}
  • {m,}

  • {m,n}

    Controls the return of the specified range (interval quantifier). Returns all of the previous regular expressions as follows:

    • m times
    • m or more times
    • m or more times, at most n times.

    Matches for {,n} or {,} will always fail.

    str = "foofoofoo"
p str[/(foo){1}/]   # => "foo"
p str[/(foo){2,}/]  # => "foofoofoo"
p str[/(foo){1,2}/] # => "foofoo"

    Regular expressions ?, *, + are the same as {0,1}, {0,} {1,}, respectively.

  • {m}?
  • {m,}?

  • {m,n}?

    Interval quantifier. Returns each of the previous regular expressions as follows:

    • m times
    • more than m times
    • more than m times, at most n times.

    and repeats. (Shortest match.)

  • ?

    Quantifiers. Returns the previous regular expression 1 or 0 times.

  • ??

    Quantifiers. Returns the previous regular expression 1 or 0 times (shortest match).

  • |

    Alternative.

  • ( )

    Regular expression grouping. The character string matched to the regular expression in parenthesis is remembered for back referencing.

  • \1, \2 ... \n

    Back reference. See Back Reference.

  • (?# )

    Comment. All characters in the parentheses are ignored.

  • (?: )

    Grouping without back reference. In other words, flexible grouping without becoming targets for \1, \2 (or $1, $2) and so on is used.

    /(abc)/ =~ "abc"
p $1
=> "abc"

/(?:abc)/ =~ "abc"
p $1
=> nil

  • (?= )

    Lookahead. Set location according to pattern. (Has no width.)

    (?=re1)re2

    The above expression is a regular expression that matches a match of both re1 and re2.

    re1(?=re2)

    The above expression is regular expression re1 that continues to the following character string matching with re2.

    p /foo(?=bar)/ =~ "foobar"      # => 0
p $&    # => "foo"    (no information about the "bar" section)

  • (?! )

    Negative lookahead. Sets a position depending on the negation of a pattern. (Has no width.)

    (?!re1)re2

    The above expression is a regular expression that does not match re1, but does match re2.

    # A three-digit number that excludes 000
re = /(?!000)\d\d\d/
p re =~ "000"   # => nil
p re =~ "012"   # => 0
p re =~ "123"   # => 0

# C identifier (A character string starting with [A-Za-z_] and continue with [0-9A-Za-z_])
/\b(?![0-9])\w+\b/

Back References

The regular expression \1 \2... \n is a back reference. It matches the character string matched in the nth parentheses (regular expression ( ) grouping).

/((foo)bar)\1\2/

The above expression is the same as the following:

/((foo)bar)foobarfoo/

Example:

re = /(foo|bar|baz)\1/
p re =~ 'foofoo'   # => 0
p re =~ 'barbar'   # => 0
p re =~ 'bazbaz'   # => 0
p re =~ 'foobar'   # => nil

The corresponding parentheses must be to the left of the back reference.

If there is a back reference in the corresponding parentheses, the match will always fail. Also, the match will always fail when a single digit back reference has no parentheses.

p /(\1)/ =~ "foofoofoo" # => nil
p /(foo)\2/ =~ "foo\2"  # => nil

While one can specify a back reference of 2 or more digits, one must be careful not to confuse it with \nnn (characters corresponding to the octal nnn) of backslash notation. If a numeric value is 1 digit, it is a back reference. When there are more than 2 digits, it will be perceived as octal code if parentheses are not used.

Also, when working with regular expressions, it is necessary to start with 0 (such as \01, etc.) when using a 1-digit code in octal. (To prevent ambiguity, there are no \0 back references.)

p   /\1/ =~ "\1"   # => nil     # back reference that doesnft use parentheses.
p  /\01/ =~ "\1"   # => 0       # octal code
p  /\11/ =~ "\11"  # => 0       # octal code

# octal code (because there are no corresponding parentheses)
p /(.)\10/ =~ "1\10" # => 0

# back reference (because there are corresponding parentheses)
p /((((((((((.))))))))))\10/ =~ "aa"  # => 0

# octal code (Though there is no such
# \08 "\0" + "8" octal code)
p /(.)\08/ =~ "1\0008" # => 0

# If you want to write numbers following a back reference,
# you have to use parentheses to group them and split them up.
p /(.)(\1)1/ =~ "111"   # => 0

Character Class

Regular class [ ] is a character class specification. One character inside [ ] will be matched.

For example, /[abc]/ matches "a", "b" or "c". You can also write character strings using "-" when characters follow the ASCII code order like this: /[a-c]/. Also, if the first character is a ^ character, one character other than the specified characters will be matched.

Any e^' not at the beginning will be matched with that character. Also, any "-" at the front or end of a line will be matched with that character.

p /[a^]/ =~ "^"   # => 0
p /[-a]/ =~ "-"   # => 0
p /[a-]/ =~ "-"   # => 0
p /[-]/ =~ "-"   # => 0

An empty character class will result in an error.

p /[]/ =~ ""
p /[^]/ =~ "^"
# => invalid regular expression; empty character class: /[^]/

The "]" at the front of a line (or directly after a NOT "^") doesn't mean that the character class is over. It is just a simple "]". It is recommended that this kind of "]" performs a backslash escape.

p /[]]/ =~ "]"       # => 0
p /[^]]/ =~ "]"      # => nil

"^", "-", "]" and "\\" (backslash) can do a backslash escape and make a match with that character.

p /[\^]/ =~ "^"   # => 0
p /[\-]/ =~ "-"   # => 0
p /[\]]/ =~ "]"   # => 0
p /[\\]/ =~ "\\"  # => 0

Inside the [] you can use character string and the same backslash notation, and also the regular expressions \w, \W, \s, \S, \d, \D (these are shorthand for the character class).

Please note that the character classes below can make a match with a line feed character, too, according to the negation (the same is true with regular expressions \W and \D.)

p /[^a-z]/ =~ "\n"    # => 0


sprintf Format

The sprintf format of Ruby is basically the same as that in C. However, there are some differences, such as no short or long modifier as in C, there is a 2-bit variable indicator (%b), and not all of the dialects of sprintf (': 3-digit separators) are supported.

A complete explanation of Ruby's sprintf format is provided below.

Below is a sprintf format form. The parts enclosed in [ ] can be omitted.

%[flag][width][.accuracy]indicator

To output '%' type '%%'.

Below is an explanation of each of the elements.

Flag

There are 5 types of flags: '#', '+', ' ' (space), '-', '0'

#

With the binary, octal, and hexadecimal indicators ('b', 'o', 'x', 'X'), "0b", "0", "0x" and "0X" are added as prefixes.

p sprintf("%#b", 10) # => "0b1010"
p sprintf("%#o", 10) # => "012"
p sprintf("%#x", 10) # => "0xa"
p sprintf("%#X", 10) # => "0XA"

For floating-point numbers ('f', 'e', 'E', 'g' and 'G') always put a "." in the output.

p sprintf("%.0f", 10) # => "10"
p sprintf("%#.0f", 10) # => "10."
p sprintf("%.0e", 10) # => "1e+01"
p sprintf("%#.0e", 10) # => "1.e+01"

For 'g', 'G', there is a leftover 0 on the end in addition to the above.

p sprintf("%.05g", 10) # => "10"
p sprintf("%#.05g", 10) # => "10.000"
+

Symbols will be attached to output character strings. In particular, a '+' symbol will be added to positive numbers. This only applies to the following numerical value indicators: 'd', 'i', 'b', 'o', 'x', 'X', 'u', 'f', 'e', 'E', 'g' and 'G'. Also, for 'b', 'o', 'x', 'X', and 'u', a '-' symbol will be added to negative numbers.

p sprintf("%d", 1)   # => "1"
p sprintf("%+d", 1)  # => "+1"

p sprintf("%x", -1)  # => "..f"  # ".." shows that f continues infinitely
p sprintf("%+x", -1) # => "-1"
' ' (space)

Same meaning as a '+' symbol, but here, a space is used in place of the '+' symbol, meaning positive. This only applies to the following numerical value indicators: 'd', 'i', 'b', 'o', 'x', 'X', 'u', 'f', 'e', 'E', 'g', 'G'.

p sprintf("%d", 1)   # => "1"
p sprintf("%+d", 1)  # => "+1"
p sprintf("% d", 1)  # => " 1"

p sprintf("%x", -1)  # => "..f"
p sprintf("% x", 1)  # => " 1"
p sprintf("% x", -1) # => "-1"
-

Output is left justified. It only has meaning if "Width" is specified.

0

If output is right justified, '0' will fill in the leftover sections in place of a blank space.

This only applies to the following numerical value indicators: 'd', 'i', 'b', 'o', 'x', 'X', 'u', 'f', 'g', 'G' (It does not apply to 'e' or 'E').

p sprintf("%010d", 10)
# => "0000000010"

Output specified together with '#' is shown below.

p sprintf("%#010x", 10)  # => "0x0000000a"
p sprintf("%#010o", 10)  # => "0000000012"
p sprintf("%#010b", 10)  # => "0b00001010"

This is the same as below.

p sprintf("%#10.8x", 10) # => "0x0000000a"
p sprintf("%#10.9o", 10) # => "0000000012"
p sprintf("%#10.8b", 10) # => "0b00001010"

Normally shown as displayed below.

p sprintf("%#10x", 10)   # => "       0xa"
p sprintf("%#10o", 10)   # => "       012"
p sprintf("%#10b", 10)   # => "    0b1010"

Width

A number string that begins with any number other than 0 is the specified width. Width displays the length of the character string produced. Contrary to the value of "Precision", which is mentioned later, only the number string of the width part is produced.

As for width specification, the length of " ", "+", "-", "0b", "0", "0x", "0X", which are presented as "Flags", is also considered.

p sprintf("%#05x", 10) # => "0x00a"

Width is a specification of the "minimum necessary width." If the resulting number string goes over the specified width, width specification is no longer valid.

If width is specified as '*', then the width value is received from an argument.

p sprintf("%10s", "foo")    # => "       foo"
p sprintf("%*s", 10, "foo") # => "       foo"

Precision

A number string that follows a "." indicates the precision (when only a "." is displayed, it is the same as ".0"). Precision means the length of a portion of numerical value strings for the following integer indicators: 'd', 'i', 'b', 'o', 'x', 'X', 'u'.

p sprintf("%10.5d", 1)  # => "     00001"
p sprintf("%#10.5x", 1) # => "   0x00001"
p sprintf("%+10.5x", 1) # => "    +00001"

This means the decimal places for the floating-point indicator 'f'.

p sprintf("%10.5f", 1)   # => "   1.00000"
p sprintf("%10.5f", 10)  # => "  10.00000"

This means the number of significant digits for floating-point indicators 'e', 'E', 'g', and 'G'.

p sprintf("%10.5e", 1)   # => "1.00000e+00"
p sprintf("%10.5e", 10)  # => "1.00000e+01"
p sprintf("%10.5g",  10)  # => "        10"
p sprintf("%#10.5G", 10)  # => "    10.000"

For character string indicators 's' and 'p', the portion which goes over the specified number within the argument character string is truncated. If width and precision values are the same, only the output for that length will be performed, no matter what the argument is.

p sprintf("%10.2s", "foo")  # => "        fo"

p sprintf("%5.5s", "foo")     # => # => "  foo"
p sprintf("%5.5s", "foobar")  # => # => "fooba"

If '*' is specified as precision, the precision value will be obtained from the argument.

p sprintf("%.5s", "foobar")    # => "fooba"
p sprintf("%.*s", 5, "foobar") # => "fooba"

Indicators

Indicators show argument pattern interpretations. They cannot be abbreviated and are divided into the following groups:

  • Indicators showing character strings: 'c', 's', 'p'
  • Indicators showing integers: 'd', 'i', 'u', 'b', 'o', 'x', 'X'
  • Indicators showing floating points: 'f', 'g', 'e', 'E', 'G'
c

Argument values 0-255 are regarded as character codes, then the corresponding characters are output. Argument conversion is attempted with the to_int method for objects other than numerical values, String, nil, true, and false.

This only applies to flag '-' and "width" specification.

s

Character strings are output.

If the argument is not a String object, the to_s method causes the object turned into a character string to be treated as an argument.

p

Object#inspect results are output.

p sprintf("%s", [1, 2, 3])      # => "123"
p sprintf("%p", [1, 2, 3])      # => "[1, 2, 3]"
d
i

An argument's numerical value is output as an integer decimal expression.

If the argument is not an integer, it will be converted to one.

u

The argument value is regarded as an unsigned integer and then output as a decimal integer.

p sprintf("%u", -1) # => "4294967295"

The above code outputs p 0xffff_ffff.to_s.

'%u' regards the argument as a fixed length integer, and

printf("%u", n)

has the same meaning as

printf("%d", n & ~(-1 << n.size*8))

for negative integer n.

b
o
x
X

Integers are output as character strings with binary, octal, hexadecimal, and hexadecimal (uppercase letters) expressions.

If the '#' flag is specified, "0b", "0", "0x", "0X" are added to the front.

If the '+' or ' ' flags are not used, ".." (if the '#' flag is used, after "0x" etc.) is added to the front of negative numbers. This means that characters of the highest-order digit continue infinitely, and negative numbers are shown in complementary numbers of 2.

p sprintf("%#b", 10)    # => "0b1010"
p sprintf("%#o", 10)    # => "012"
p sprintf("%#x", 10)    # => "0xa"

# ".." is added to # negative numbers
p sprintf("%#b", -1)    # => "0b..1"
p sprintf("%#o", -1)    # => "0..7"
p sprintf("%#x", -1)    # => "0x..f"

p sprintf("%10x", -1)   # => "       ..f"
p sprintf("%-10x", -1)  # => "..f       "

# If "precision" has been specified, ".." is not added.
p sprintf("%.10x", -1)  # => "ffffffffff"
f
e
E
g
G

'f' outputs numerical values with a decimal expression (xxx.xxx).

'e' outputs numerical values with an exponential notation (x.xxxe+xx).

When the exponent is smaller then -4, or higher than the precision, 'g' outputs the same as 'e'. In all other cases, it outputs the same as 'f'. However, 0 at the end of a decimal fraction is omitted.

Uppercase indicators 'E' and 'G' change the output alphabetic characters into uppercase letters.

p sprintf("%f", 1.0) # => "1.000000"
p sprintf("%e", 1.0) # => "1.000000e+000"
p sprintf("%g", 1.0) # => "1"

p sprintf("%f", 10.1) # => "10.100000"
p sprintf("%e", 10.1) # => "1.010000e+001"
p sprintf("%g", 10.1) # => "10.1"

p sprintf("%g", 10 ** 6)  # => "1e+006"
p sprintf("%g", 10 ** -5) # => "1e-005"

The precision default value is 6.

Argument Specification

This is not used often, so it is explained last.

nth$

Indicates that formatting of the nth argument will be performed.

p sprintf("%1$d, %1$x, %1$o", 10)
=> "10, a, 12"

p sprintf("%3$d, %2$x, %1$o", 1, 2, 3)
=> "3, 2, 1"

Used when you want to change the format according to the situation, but you do not want to change the order of the arguments.

case ENV['LC_TIME']
when /^ja_JP/
   fmt = "%1$d年%2$d月%3$d日"
else
   fmt = "%2$02d/%03$2d/%1$02d"
end

p sprintf(fmt, 1, 4, 22)
=> "04/22/01"