Actors & Pawns

Before we get deep into the system, and untangle how all this works under the hood. It is VERY important to differentiate what our main performers for our system are responsible for. Which are Actor and Pawn.

Pawns

Pawns are essentially the blueprint of what we expect for a character to be. What they are like? Are they female? Which type of character are they? Zombie, Player or Animal? What offset do they have? These are all the questions that a Pawn should answer. Without them we would need to guess what type of character is allowed under a certain scene, and create extra code just to figure out in real time. The Pawn saves us from doing that.

A Pawn is also pure data. They don’t have any imbued function in them whatsoever.

Structure of a basic Pawn:

---@class DS_AnimPawn
---@field is_female boolean
---@field has_penis boolean | nil
---@field active boolean | nil
---@field pos_offset DS_AnimPosOffset
---@field angle_offset number
---@field animtype string

---@class DS_AnimPosOffset
---@field x integer
---@field y integer

local pawn = {
    is_female = false,
    has_penis = false,
    active = true,
    pos_offset = { 0.0, 0.0 },
    angle_offset = 0.0,
    animtype = "player",
}

Anim Types

A Thing to note, the value animtype refers to the main AnimSet of a given character. This is mainly important when dealing with animals, as even if their class is all IsoAnimal, they use different types of AnimSets like pig or cow.

Actors

Now, Actors are the REAL deal. Unlike Pawn, an Actor is an object interlinked with a character instance from the game. They have helper functions that allow you to play characters animations, and apply an offset to them if inserted. They are also the main objects that an AnimBus carries over. We haven’t explained what the AnimBus is yet, but keep in mind that Actor is the main object most of the time.

Here’s the public values you can expect from an Actor:

---@class DS_AnimActor : ISBaseObject
---@field character IsoGameCharacter
---@field online_id number        Will match the online_id of DepravedSense not Zomboid own online_id
---@field is_female boolean
---@field has_penis boolean
---@field active boolean
---@field character_type string
---@field animtype string
---@field animbus_reference DS_AnimBus | nil
---@field animbus_id string
---@field in_animbus boolean
---@field bus_seat integer
---@field speed number
---@field max_speed number        Default: 1
---@field speed_drain_rate number Default: 0.008

There may have other private values here, but its best that you check the Actor module code for reference of its functions at “lua/DepravedSense/AnimGraph/Actor.lua”

Active or Passive

You may notice that both Actor and Pawn have an active value on them. This value determines if a character is active or passive on the animation system. They are responsible for telling how much control an Actor has over a scene. An active Actor has complete control, it can dictate the speed of a scene, and decide which direction the animation should go. Passive Actors don’t do much, and they are often at mercy of active Actors. However they still posses some control in very specific circumstances, like struggle for example.

WARNING: Keep in mind that once an Actor is created, the character attached to it will essentially be locked in place every time the Actor updates. So, don’t go around and create Actors like there is no consequences.