Commands principles

Commands' principle is definitely the biggest part of this wiki. Through these commands the make will be able to overcome RPGMaker's constraints.

What is a command ?

Typically, a command is nothing more than an action which can:

• return a value (for instance, an event's coordinates)
• do some stuff (for instance, deleting a picture)
• do some stuff and return something

Command's taxonomy

A command is referenced by its name. It is usually used in scripts' calls but can also be used in scripts. They are several ways to call a command:

• command(:command_name, arg1, arg2, etc.)
• cmd(:command_name, arg1, arg2, etc.)
• c(:command_name, arg1, arg2, etc.)
• Command.command_name(arg1, arg2, etc.)
• command_name(arg1, arg2, etc.) : only in script's call

The first syntaxes allow commands to be accessible from any scripts (if the last ones permit it).

The last one is only usable in scripts' call (in an event). As the commands have been designed to be used only in scrips' call, this is this last syntax which is used in the documentation.

Now, if you want to use a RME command in one of your scripts, it's up to you to choose the syntax that you prefer above the first four.

Documentation's usage

All commands are referenced in the documentation available here and are organised by categories. Each command is formally described.

Command's arguments

A command can take several arguments (or none). If a command does not take any argument, it is necessary to use () at the end of the command.

For instance, the command mouse_x, which returns the mouse's X position, does not require any arguments, thus we are totally able to do V[1] = mouse_x (rather than V[1] = mouse_x()) to assign the current mouse's X position to the variable n°1.

The fact of assigning a value as an argument is usually call "passing x as an argument". Arguments have different data's types and these types are referenced in the documentation.

Here are the types that you can see:

Type	Description
:Fixnum	It represents integers from - infinite to + infinite (1, 10, -7000 for instances). This is the most common argument's type.
:Float	It represents any floating numbers.
:String	It represents a sequence of characters. Strings must be surrounded with single quotes (') or double quotes (") (for instances, both 'dog' and "cat" are valid).
:Boolean	It can be true (like activated) or false (like disabled)). A command which needs a boolean as an argument can therefore take a (local) switch instead of true or false.
:Symbol	It is a word prefixed with :; for instances: :dog or :cat. Usually, when a command need a Symbol argument, the list of available symbols is specified in the documentation. They are widely used to reference keyboard's or mouse's key.
:Tone	It represents a tone, we advise you to use the command tone(r, v, b, g) in order to generate a tone that you will then pass as an argument.
:Color	It represents a colour, we advise you to use the command color(r, v, b, a) in order to generate a colour that you then pass as an argument.
:Selector	It is a construction that allows to select several events at once. Selectors are described here.

Optionnal arguments

An optionnal argument is an argument which has a defaut value. Thus, it is not mandatory to specify such argument (if you don't want to modify its value).

Inside the documentation, optional arguments are prefixed with an asterisk (*).

For instance, let's imagine this command:

a_command(a, b, c, *d, *e, *f)

a, b and c are mandatory arguments. d, e and f are optional arguments.

So, we can use this command in different ways:

• a_command(thingy, whatsit, whatever) and arguments d, e and f will take their default values.
• a_command(thingy, whatsit, whatever, gizmo) and arguments e and f will take their default values.
• a_command(thingy, whatsit, whatever, gizmo, oojamaflip) and argument f will take its default value.
• a_command(thingy, whatsit, whatever, gizmo, oojamaflip, thingamajig) and no default value will be used.

It is strictly forbidden to use the default value of e, if we want to specify the value of f. However, don't panic ! The documentation will alaways specify the default value for each of these optional arguments.

How to read a documented command

Let's take the command picture_show as an example (because she is quite lengthy and use several types of arguments !).

picture_show(id, name, *x, *y, *origin, *zoom_x, *zoom_y, *opacity, *blend_type)

Display a picture on screen

Name|Type|Description --- | --- | --- id|Fixnum|Picture's ID name|String|Picture's name (without extension) *x|Fixnum|Picture's X position (by default: 0) *y|Fixnum|Picture's Y position (by default: 0) *origin|Fixnum|Picture's origin (0=Top left hand corner, 1=centered, [x, y]=oriented around the point (x, y)) (by default: 0) *zoom_x|Fixnum|Zoom on picture's width (by default: 100; for 100%) *zoom_y|Fixnum|Zoom on picture's height (by default: 100; for 100%) *opacity|Fixnum|Picture's opacity (by default: 255) (it goes from 0 up to 255) *blend_type|Fixnum|Blending mode (0=Normal, 1=Addition, 2=Substraction) (by default: 0)

We can see that the mandatory arguments are id and name. So, in order to display the picture "lol.png" as picture n°1; we will do: picture_show(1, "lol").

Now, let's see several cases:

• picture_show(1, "lol", 10, 20) Displays the picture n°1, with the file named "lol", 10 pixels from the left edge and 20 pixels from the top edge of the screen.
• picture_show(1, "lol", 10, 20, 1) Quite the same thing as above, excepting the fact that the picture will be placed relatively to its center (origin = 1).
• picture_show(1, "lol", 10, 20, [10, 10]) Here, the picture's origin won't be neither the top left hand corner nor the center, but the given point whose coordinates are [10, 10]. If the picture's length is about 30*40px, it is possible to take the bottom left hand corner as the origin: [0, 40]; or the top right hand corner: [30, 0]; or typically any point. Really convenient !
• picture_show(1, "lol", 10, 20, 0, 100, 84, 220, 1) There all the parameters are used: picture's origin will be its top left hand corner, it will be displayed with all its width (zoom_x = 100) but only 84% of its height (zoom_y = 84), its opacity will be 220 (a bit transparent) and its blending mode will be the addition (blend_type = 1).

Particular arguments

Usually, the argument's type's annotation gives limited informations. That is clearly visible with the case of :Fixnum arguments; because the range of valid values is not the same, depending on cases:

• When an opacity is expected, the value has to be contained between 0 (transparent) and 255 (totally opaque).
• When a blend_(mode/type is expected, they are 3 values available: 0 (normal), 1 (addition) and 2(substraction).
• When a zoom is expected, the value has to be contained between 0 and 100 (that's a percentage).
• When a speed is expected, negative numbers correspond to the opposite direction (for instance, in order to have a rotation in the clockwise direction, the speed has to be positive; if the speed is negative, the rotation will be made in the counter-clockwise direction).

Commands returning values

It exists a certain amount of commands which return values (for instance: mouse_x and mouse_y), these commands can be directly assigned to a variable (or a local variable, or tags), you can also use them to build expressions.

For instances: V[1] = mouse_x, or If script : mouse_x > 3.

Commands which return booleans (true or false) can be directly used in an expression ou can be assigned to switches (or local switches), for instance: S[1] = pixel_in_picture?(1, mouse_x, mouse_y) or If script : pixel_in_picture?(1, mouse_x, mouse_y).

Commands returning arrays

Certain commands return arrays. These commands are a bit particular to handle. For instance: the command actor_armors(acteur_id), will return an array containing all the hero's equipped armours' indexes. You are always able to know the length (or size) of an array thanks to the standard command: length(array) and retrieves what is contained in a specific cell of the array thanks to the standard command: get(tableau, cell_index).

Conclusion

Commands are RME's core, they allow to do complex actions that would be hard to do in common Event-Making. Some uses are visible (in french) on the Biloucorp's page through ludic tutorials :) (these tutorials are formerly written for the Event Extender but they are compatible with RME).