Skip to content

Animations

Overview of the animation system in VJ Base.

Important Note

Walk frames are required for NPCs to physically move! (Unless you make your own system in Lua)

Types

The following animation types are supported by the base and define the naming schemes used by functions such as NPC:PlayAnim().

Fallback Rule

Unprefixed strings are checked as activities first. If no valid activity matches, the string plays as a sequence.

Type Prefix Movement Behavior Description Examples
Activity None Supported Plays from a sequence pool Preferred animation type. Required for core movement animations such as walking, running, and idle. ACT_HOP
31
"dance"
Sequence vjseq_ Supported Plays an exact sequence Directly plays the specified sequence instead of allowing the engine to choose from an activity. "vjseq_dance"
"vjseq_im_a_sequence"
Gesture vjges_ Unsupported Plays a layered activity or sequence Plays over the current activity or sequence when possible. Used for shooting, flinching, and small reactions. "vjges_dance"
"vjges_im_a_gesture"
Gesture-Activity vjges_ Unsupported Plays a layered activity Uses an activity's sequence pool, but plays the result as a layered gesture when possible. "vjges_dance"
"vjges_" .. ACT_HOP
"vjges_" .. 31
Gesture-Sequence vjges_vjseq_ vjseq_vjges_ Unsupported Plays a layered sequence Directly plays the specified sequence as a layered gesture. "vjges_vjseq_dance"
"vjseq_vjges_dance"

Animation Resolution Order

The following is the order of operations used by functions such as NPC:PlayAnim() when resolving animation inputs. 

%%{init: {"themeVariables": {"fontSize": "20px"}} }%%
flowchart LR
    input["Input"]
    input -->|"<b>ACT enum / number</b><br><small>ACT_HOP<br>31</small>"| playActivity["Play as ACTIVITY"]
    input -->|"<b>string</b><br><small>&quot;dance&quot;<br>&quot;vjseq_dance&quot;<br>&quot;vjges_dance&quot;<br>&quot;vjseq_vjges_dance&quot;<br>&quot;vjges_vjseq_dance&quot;<br>&quot;vjges_&quot; .. ACT_HOP<br>&quot;vjges_&quot; .. 31</small>"| hasPrefix@{ shape: "diam", label: "Has prefix?" }

    hasPrefix -->|"<b>No prefix</b><br><small>&quot;dance&quot;</small>"| validActivity@{ shape: "diam", label: "Valid activity?" }
    validActivity -->|"<b>Yes</b>"| playActivity
    validActivity -->|"<b>No</b>"| playSequence["Play as SEQUENCE"]

    hasPrefix -->|"<b>vjseq_ prefix</b><br><small>&quot;vjseq_dance&quot;<br>&quot;vjseq_vjges_dance&quot;</small>"| seqType@{ shape: "diam", label: "Has vjges_?" }
    seqType -->|"<b>No</b><br><small>&quot;vjseq_dance&quot;</small>"| playSequence
    seqType -->|"<b>Yes</b><br><small>&quot;vjseq_vjges_dance&quot;</small>"| playGestureSequence["Play as GESTURE-SEQUENCE"]

    hasPrefix -->|"<b>vjges_ prefix</b><br><small>&quot;vjges_dance&quot;<br>&quot;vjges_vjseq_dance&quot;<br>&quot;vjges_&quot; .. ACT_HOP<br>&quot;vjges_&quot; .. 31</small>"| gesType@{ shape: "diam", label: "Has vjseq_?" }
    gesType -->|"<b>Yes</b><br><small>&quot;vjges_vjseq_dance&quot;</small>"| playGestureSequence
    gesType -->|"<b>No</b><br><small>&quot;vjges_dance&quot;<br>&quot;vjges_&quot; .. ACT_HOP<br>&quot;vjges_&quot; .. 31</small>"| gesValidActivity@{ shape: "diam", label: "Valid activity?" }
    gesValidActivity -->|"<b>Yes</b>"| playGestureActivity["Play as GESTURE-ACTIVITY"]
    gesValidActivity -->|"<b>No</b>"| playGestureSequence

Reserved Activities

Reserved activities are specific activity enums used internally by the engine or VJ Base. They should only be used for their intended actions.

Table Key

✅ – Can safely translate and edit in Lua!
⛔ – Engine's control activities, do NOT translate or edit!

Name ID Description Edit Source
ACT_IDLE 1 Idle stand, sequences in the QC should be flagged with loop ✅ Engine & Lua
ACT_IDLE_ANGRY 76 Idle stand replacement when alerted with an active weapon, sequences in the QC should be flagged with loop ✅ Engine & Lua
ACT_COWER 61 Idle stand replacement when scared & hiding ✅ Lua
ACT_WALK 6 Walking movement ✅ Engine
ACT_WALK_AGITATED 84 Walking movement replacement while alerted ✅ Lua
ACT_WALK_AIM 7 Walking movement replacement while aiming a gun ✅ Engine & Lua
ACT_RUN 10 Running movement ✅ Engine
ACT_RUN_AGITATED 88 Running movement replacement while alerted ✅ Lua
ACT_RUN_AIM 11 Running movement replacement while aiming a gun ✅ Engine & Lua
ACT_RUN_PROTECTED 14 Running movement replacement when scared & hiding ✅ Lua
ACT_JUMP 30 Movement jump start ✅ Engine
ACT_GLIDE 27 Movement jump in air, played after ACT_JUMP has finished! ✅ Engine
ACT_LAND 33 Movement jump land (finish) ✅ Engine
ACT_CLIMB_UP 34 Movement climb up ✅ Engine
ACT_CLIMB_DOWN 35 Movement climb down ✅ Engine
ACT_CLIMB_DISMOUNT 36 Movement climb finish ✅ Engine
ACT_TURN_RIGHT 44 Turn right if ang <= -45 ✅ Engine
ACT_90_RIGHT 132 Turn right if ang <= -80 and ang >= -100 ✅ Engine
ACT_TURN_LEFT 43 Turn left if ang >= 45 ✅ Engine
ACT_90_LEFT 131 Turn left if ang >= 80 and ang <= 100 ✅ Engine
ACT_180_LEFT 129 Turn left if ang >= 160 ✅ Engine
ACT_INVALID -1 Used to check for invalid / non-existent animations ⛔ Engine & Lua
ACT_RESET 0 Used to force m_Activity to m_IdealActivity, bypassing the need for NPC:MaintainActivity() ⛔ Engine
ACT_DO_NOT_DISTURB 171 Keeps NPC:MaintainActivity() from overriding sequences ⛔ Engine & Lua
ACT_TRANSITION 2 For transitions between animations ⛔ Engine