User variable

User variables are special variable fields that can be created in an actor's DECORATE and used for various scripting purposes. Contrarily to the args, user variables are guaranteed not to be used by any pre-existing feature, so they can be used without risk of conflict with obscure functions.

Usage

A user variable must be declared in an actor's code with a line of this form:

var int user_<name>;
var float user_<name>;

Floating point and string variables are not supported at the moment. Note that the declaration ends with a semicolon. All user variable names are prefixed with "user_" to prevent any risk of conflict with future features.

Both ACS and DECORATE support handling of floating-point user variables. While GetUserVariable is capable of retrieving non-user variables including strings and names, SetUserVariable is still restricted to user variables of int or float only.

It is also possible to declare arrays, using the square bracket notation to indicate a size:

var int user_<name>[<size>];

For example:

var int user_foo;
var int user_bar[42];

This creates the user_foo variable and the user_bar array with 42 elements, accessible in DECORATE expressions through user_bar[0] to user_bar[41].

Conditions

Several conditions apply when working with user variables, due to the complexity of certain actor classes.

• Weapon
  • The player itself must have the user variables. Defining the user variables is completely unnecessary on weapons as they are never stored.
  • Weapons may set the user variables on the player via DECORATE or ACS.

• CustomInventory
  • Pickup or Use states both work.
  • If the item is solely developed for A_GiveInventory functionality and similar only, defining the user variable first is not needed. Only the receiver needs it defined.
  • If the receiver does not have the variable defined, it will log a console message notifying the player it does not exist.
  • User defined variables on inventory items will only affect the item itself until picked up; everything afterwards affects only the receiver. As such, if the actor is missing the variable used by CustomInventory, it will also log a message about missing user variables.

• Both
  • User vars can be stored, but not retrieved, directly through DECORATE. User variables stored through decorate via weapons or custominventory are set upon the owner itself (weapons set on players specifically). ACS must be used upon the calling actor instead.

Examples

This former human can shoot up to five rockets. Once it runs out of rockets, it then falls back to using its standard rifle attack.

ACTOR SpecialZombieMan : ZombieMan
{
    var int user_rockets;

    States
    {
    Spawn:
        POSS A 0 NoDelay
        { // See anonymous functions.
            user_rockets = 5;
        }

    Idle:
        Goto Super::Spawn

    Missile:
        POSS E 10 A_FaceTarget
        POSS F 8
        {
            If(user_rockets > 0)
            {
                A_CustomMissile("Rocket");
                user_rockets--;
            }
            Else
            {
                A_PosAttack;
            }
        }
        POSS E 8
        Goto See
    }
}

See also

• DECORATE expressions
• A_SetUserVar and A_SetUserArray
• GetUserVariable and SetUserVariable
• GetUserArray and SetUserArray