Category:Auxiliary-Variable Functions (JIP)

The Auxiliary-Variables interface is a utility added by the JIP LN NVSE Plugin in Fallout: New Vegas and Command Extender in Fallout 3, and is an alternative method for dynamically storing and managing game-data. Auxiliary-Variables (abbreviated as AuxVars) are a special type of variables that, unlike generic script variables, exist in the game's memory and are not part of, and are not pre-declared in any game-script. AuxVars are created, accessed, modified and deleted using a set of script commands.

Properties

• An AuxVar is defined by a Name (string, case-insensitive) and an Object (object reference/base form) that "owns" it. This Object:Name pair must, therefore, be unique. Note that different Objects may "own" a variable with the same Name and still count as a unique pair. Any Object may "own" any number of variables.
• AuxVars can store either numeric, reference/form, or string values. They have no explicit, fixed value-type - their type changes dynamically, according to the type of value assigned to them.
• Every AuxVar is an array by default, and can be used for storing either a single, or multiple values (of mixed types).
• AuxVar functions REQUIRE passing a form so that the value can be "owned".

Duration & Accessibility

Duration:

An AuxVar's duration setting determines its "life-span", i.e. whether it is permanent or temporary. Permanent AuxVars, and any values they store, are saved with the game. In contrast, temporary AuxVars are not saved with the game. Instead, they are persistent (retain their values) for the duration of the current game session (much like constant global variables) but are discarded when the game is exited. Consider using file functions such as SetINIFloat to save information across multiple sessions.

Accessibility:

The accessibility setting determines which mods can "see" and manipulate the AuxVar. A private AuxVar is "private" to the mod it was created by, and can only be accessed/modified by scripts originating in that mod. This allows different mods to use the same variable names, associated with the same objects, without overwriting each other. A public AuxVar, on the other hand, can be accessed/modified by any mod. This is an effective method for inter-mod communication and exchange of data, without any master-dependencies.

Enabling each property is done by adding a special prefix to the AuxVar's name. The two properties, and their combinations, define four classes of AuxVars, as summarized in the following table:

Caveats:

If you are making a patch for a script that is using AuxVar functions, and that patch is an ESM/ESP, the ESM/ESP will overwritte the Mod Index of the AuxVar is attached to, and the original script will lose access to the AuxVar. So if another script within the master plugin is attempting to check the AuxVar, it will not be able to, as the Mod Index has now been overwritten.

Examples

Suppose we want to save if an actor has hit the player, and be able to request this at a later point.
We can use the "HasHitPlayer" permanent-private AuxVar name as part of the "key" required to get this information; the other "key" being the requested actor.

Then we can use the following code in an OnHit UDF to set a value on the attacking actor, using AuxiliaryVariableSetFloat:

ref rAttacker
;* ... other UDF code, need to initialize rAttacker

if (rAttacker == player)
   rAttacker.AuxiliaryVariableSetFloat "HasHitPlayer" 1
endif

We may later request the value using AuxiliaryVariableGetFloat:

ref rSomeReference
;* ... other code, need to initialize rSomeReference

int hasHit = rSomeReference.AuxiliaryVariableGetFloat "HasHitPlayer"
if (hasHit)
   ;* Do stuff
endif

The above code works as expected even if no value was previously attributed to the calling reference, because AuxiliaryVariableGetFloat returns 0 if no value was attributed to that form with that AuxVar key.

See Also

• RefMap Array (a specialized form of Auxiliary Variables)