From Platinum Arts Sandbox Free 3D Game Maker
References are stored separately of cube script and are defined as a stack of hashtables that can be arbitrarily incremented and decreased. The depth is typically 1 unless a script is executing or things are being run inside a r_stack block.
References are the system that exposes a lot of functionality as well as providing a relatively fast and type-safe means for creators to script assorted interactions in their games.
As a general rule, a reference must be defined (or registered) before it can be set or searched for. There are two ways to register a reference. The first is using r_registerref and the second using r_registertemp. Both behave exactly the same except for one difference, r_registertemp only searches the top level for a matching reference as opposed to the whole stack, otherwise they both create one at the top level if one isn't found. Due to this behaviour, you can shadow variables quite easily and painlessly and allows us to use self and actor as reference for just about every script call.
The references can reference just about anything in the RPG, the current official list is as follows. Note that volatile references are cleared at the start of every update due to the volatile nature of what they reference.
- Equipment (volatile)
- Victim Effect (volatile)
- Area Effect (volatile)
In addition the following list should be considered reserved, you may use them for other purposes but we really do not recommend this for obvious reasons.
- player - the player
- curmap - the current map
- hover - the current hover target
- talker - who the player is currently talking to
- actor - generally something that sent a signal to the entity in the self reference
- self - something executing a script, typically due to to receiving a signal fro mactor
Nearly all scripts in the RPG are defined as a signal to either the script on the mapscript subtypes. The signals can have just about any name, there are several loosely reserved names the engine will call periodically but the creator has completely free reign on what he wants to name his signals and what he wants and when alongside those the game call.
Signals are sent to everything by default unless a specific target is specified. Signals called periodically by the game are as follows
- update - sent to everything every update
- collide - sent to every pair of entities that collided in an update
- hit - sent when something is hit by another's attack
- interact - typically sent when you press the E key while having a hover target
- death - sent to an entity when it does
- level - sent to an entity when it gains a level
- equip - send to the item when an entity equips it
- load - sent to the map when it's initialised
- spawn - sent to an entity when it's created
- attack - sent when an entity attacks
This list is subject to change in the future
Context sensitive values
When some conditions are met or certain signals are sent, global variables are set for it to use.
friendly - notes whether or not the attack was friendly
script/signal status effect