Actor Variables

Each actor has 16 variables (indices 0–15) that can store integer values. These are useful for tracking state, communicating between actors, and creating actor variants from a single source file.

Setting and getting variables

Use SetActorVar and GetActorVar:

Call(SetActorVar,actorID ACTOR_SELF,varIndex 0,value 1)
Call(GetActorVar,actorID ACTOR_SELF,varIndex 0,outValue LVar0)  // LVar0 = 1

Naming variables

Define an enum to give your variables readable names:

enum ActorVars {
    AVAR_Toppled     = 0,
    AVAR_ToppleTurns = 1,
};

// in EVS_Init:
Call(SetActorVar,actorID ACTOR_SELF,varIndex AVAR_Toppled,value false)

// in EVS_TakeTurn:
Call(GetActorVar,actorID ACTOR_SELF,varIndex AVAR_Toppled,outValue LVar0)
IfTrue(LVar0)
    // try to get back up instead of attacking
EndIf

Communication between actors

You can read another actor's variables by using their actor ID instead of ACTOR_SELF. This lets actors coordinate:

// parent actor stores the clone's ID when spawning it
Call(SetActorVar,actorID ACTOR_SELF,varIndex AVAR_CloneID,value LVar0)

// later, check if the clone is still alive by reading its variable
Call(GetActorVar,actorID ACTOR_SELF,varIndex AVAR_CloneID,outValue LVarA)
Call(GetActorVar,actorID LVarA,varIndex AVAR_IsClone,outValue LVar0)

See src/battle/common/actor/magikoopa.inc.c for this pattern in practice.

Formation variants

The first 4 variables (indices 0–3) can be set from the battle formation using the .var0, .var1, .var2, and .var3 fields. This lets you reuse a single actor file for different variants:

Formation MyFormation = {
    OVL_ACTOR_BY_IDX("boo", BTL_POS_GROUND_B, 10, .var0 = 0),  // normal
    OVL_ACTOR_BY_IDX("boo", BTL_POS_GROUND_C, 9, .var0 = 1),   // starts transparent
};

The actor reads the variable in its EVS_Init to configure itself:

EvtScript EVS_Init = {
    Call(BindTakeTurn,actorID ACTOR_SELF,script Ref(EVS_TakeTurn))
    Call(BindIdle,actorID ACTOR_SELF,script Ref(EVS_Idle))
    Call(BindHandleEvent,actorID ACTOR_SELF,script Ref(EVS_HandleEvent))
    Call(GetActorVar,
        actorID ACTOR_SELF,varIndex AVAR_StartTransparent,outValue LVar0)
    IfTrue(LVar0)
        Call(SetPartAlpha,actorID ACTOR_SELF,partIndex PRT_MAIN,alpha 80)
    EndIf
    Return
    End
};

This avoids duplicating actor files for minor variations.