About Script Variables

[DCurrent]

I've noticed some confusion about variable scopes and types, so here is a quick rundown to help ameliorate that.

Local/Inline Variables

Inline variables are variables you define inside a given function without specifying the scope. It's technically correct to call them local variables, but just to avoid confusion with "localvars" (see below), we refer to them as inline. They are unique to that function and only that function. Inline vars are destroyed as soon as the function is finished.

function somefunction()
{
     int name = value;
}

Local Variables

Local vars can be a little confusing to understand, but they are quite powerful once mastered and are often much better suited for the job than global vars. A local variable is global to all functions within a given individual script instance, and remains persistent until the script is destroyed. For those familiar with object oriented programming, local vars could be considered analogous to class variables.

For example, if you declare a local var in one entity's animation script, that variable is now available to all functions inside that entity's animation script. Since animation scripts stay loaded as long as the entity does, the script var will then remain until the entity is removed from play, even after the function that declared it finishes.

In practical terms, local vars are ideal for transferring information between functions in a script without using tons of parameters or global level variables. They also are perfect for temporary storage of information across multiple instances of a function(s). The best part is that you don't have to worry about clean up since the engine will do it for you.

main()
{
    /* Set local var. */
    hello();

    /* Print local var to log. */
    print_log();
}

function hello()
{
     setlocalvar("test_localvar", "Hello world!");
}

function print_log()
{
     void test = getlocalvar("test_localvar");

     /* Print "Example: Hello world!" to log. */
     log("\n Example: " + test);

}

OpenBOR script includes several predefined local vars. One of the more common examples is getting the entity that called an animation script:

function somefunction()
{
     void entity = getlocalvar("self");
}

Scriptvars

setscriptvar(<key>, <value>)
getscriptvar(<key>)

Scriptvars are depreciated as of OpenBOR version 3.902. They are now simply wrappers for the localvar() functions and should not be used.

Entityvars

setentityvar(<entity>, <key>, <value>)
getentityvar(<entity>, <key>)

Entity variables are attached to an entity pointer. They occupy the global scope, and so are available to any function, anywhere, anytime. This makes them invaluable for storing information about a given entity, for adding special effects, binds, and so on. Entity vars remain until the entity is killed (as in removed from play, not just dead). It's important to note that while all entities in play have unique pointers, once an entity is removed its pointer address may be reused for new entities. This means you need to be careful to avoid dangling pointers to old entity vars in your scripts - you might accidentally reference the new entity.

function somefunction()
{
     void entity  = getlocalvar("self");

     setentityvar(entity, "birthdate", "2004-01-01");
}

Globalvars

setglobalvar(<key>, <value>)
getglobalvar(<key>)

As the name implies, global vars occupy the global scope. They are tied to nothing aside from the <key> used to identify them, and once defined, they are available to all functions in all scripts at all times. Global vars are even persistent through game saves, so turning off the engine is not always enough to get rid of them. This later caveat can be very powerful if used correctly, but if not accounted for it could introduce serious bugs into your scripts.

Global vars are extremely potent and versatile, but you should think of them as a last resort rather than a go to. It is best practice to limit yourself to the scope you absolutely need for a given task, and save global vars for the jobs only they can do.

Indexdvars

setindexedvar(<key>, <value>)
getindexedvar(<key>)

Indexed vars are depreciated as of OpenBOR version 3.902. They are now simply wrappers for the globalvar() functions and should not be used.

 

[DCurrent]

Updated to reflect changes made in OpenBOR version 3.902.

DC