Commands' return values

A command can be an action, for instance: picture_show which is only displaying a picture. But a command can also return an information, for instance: mouse_x will return the mouse's X position.

A command can be assigned

There are several types for return's values. Most of commands returning informations, return them as integers. Thus they can be assigned to a variable. For instance: V[1] = mouse_x. Commands returning true or false can be assigned to switches (true means that the switch is active, false means that it is disabled). They also can be directly used in an expression, such as a condition. For instance: If Script : mouse_x > 15 or If Script : actor_has_weapon?(1). Conventionally, a command returning true or false ends with a question mark (?).

Commands returning arrays

It happens that a command returns a data's structure which is much more complicated than a simple value. Indeed, it is possible to return an array of data. A data's array is, as its name tells it, a value which contains many others, indexed by an integer. An array always start at the index 0 and ends at the index corresponding to is length minus 1. They are several ways to retrieve informations stored in an array.

Retrieving array's length

They are two ways to retrieve the length of an array. The first one is through the command length(array), which returns the length of the given array. The second one is proper to Ruby: array.length. You are able to choose the one that suits you best.

Retrieving a specific element stored in an array

As for the length, it is also possible to retrieve an element which is placed at a specific index. Whether using the command get(array, index) which returns the value stored at the given index in the array (don't forget that the array starts at 0, so the first value is placed at the index 0); or the Ruby method: array[index].

Summary

Let's take a command which returns an array as an example:

actor_armors(id)

Returns the array containing the IDs of armours equipped by the hero referenced by the given ID.

Name|Type|Description --- | --- | --- id|Fixnum|Actor's ID

We will store the array returned by actor_armors(1) in the local variable SV[1]:

• SV[1] = actor_armors(1)

Here are four equivalent ways to retrieve the array's length:

• SV[1].length
• length(SV[1])
• length(actor_armors(1))
• actor_armors(1).length

And here are four equivalent ways to retrieve the array's first element:

• SV[1][0]
• get(SV[1], 0)
• actor_armors(1)[0]
• get(actor_armors(1), 0)

Concrete example

Let's imagine that we want the hero n°1 to tell every armours that he has equipped. Here is corresponding event code:

Technically, we initialize the variables. The variable n°1 willl store the array containing all the equipped amours' IDs. The variable n°2 will store the array's length. The variable n°3 initializes a counter (which will help us to iterate over the array, retrieving all armours one per one). Then, we will loop until the counter equals the array's length, and retrieve each element thanks to the command get and the counter. Finally, we use the amours relative commands to get the desired informations.