Phase Kit

As we said before, Phases are the central piece for animations, and thanks to how they are stored, they need their own special case on Animation Kits. So, that leads us to the Phase Kit.

A Phase Kit, is nothing more but a collection of Phases that are going to be inserted inside a Stage. Let’s create one as an example.

---@class DS_PhaseKit
---@field stage string
---@field stage_module string | nil
---@field phases DS_PhasePrint[]
---@field roads DS_RoadPrint[]

---@class DS_PhasePrint
---@field id string
---@field ignition boolean | nil
---@field animx string[]
---@field events DS_AnimEvent[][] | nil
---@field effects (fun(actor: DS_AnimActor))[][] | nil

local anim_kit = {
    VERSION = 1,
    module = "your_unique_name",
    --- First we need create a `stage` where we can store our `phases`.
    stages = {
        {
            id = "test_stage",
            tags = {
                "test",
            },
            pawns = {
                {
                    animtype = "player",
                    is_female = true,
                    pos_offset = {x = 0.0, y = 0.0},
                    angle_offset = 0.0,
                }
            }
        }
    },
    phase_kits = {
        {
            -- The name of the stage we are targeting.
            stage = "test_stage", 
            -- optional. In case you are targeting a stage from another module.
            stage_module = "your_unique_name",
            phases = {
                {
                    id = "phase_1",
                    -- optional. Tells the bus to start in this phase.
                    ignition = true,
                    -- The list of animations to be played.
                    -- The actor 1 will play the first animation,
                    -- the actor 2 will play the second, and so on.
                    animx = { 
                        "Bob_Your_Animation_Name",
                    },
                    -- optional. Our effects, in this case we aren't using any.
                    effects = nil, 
                    -- optional. Our events.
                    events = {
                        {
                            name = "EVENT_NAME",
                            time_trigger = 0.5,
                        }
                    }
                },
                {
                    id = "phase_2",
                    animx = {
                        "Bob_Your_Other_Animation",
                    }
                }
            },
            -- Roads in PhaseKits don't need to have their type set.
            roads = {
                {
                    from = { id = "phase_1" },
                    to = {id = "phase_2"},
                    animx = nil,
                    conditions = {
                        function (animbus)
                            return animbus.phase_loops >= 2
                        end
                    }
                },
                {
                    from = { id = "phase_2" },
                    to = {id = "phase_1"},
                    animx = nil,
                    conditions = {
                        function (animbus)
                            return animbus.phase_loops >= 2
                        end
                    }
                }
            }
        }
    }
}

return anim_kit

Okay, that’s a lot to tackle, let’s try analyzing this carefully.

In here we are first creating a Stage so we have where to put our Phases. Next in out kit we created at phase_kits we specify which Stage we are aiming for, and in this case it the one we created, test_stage. We also can point which module we are referencing, which deserves its own section later, so we won’t explain much of it. Just keep in mind that it searches which module the Stage is in.

Then, in that phase_kit we create our Phases that will be inserted on the Stage. phase_1 and phase_2. We can notice that phase_1 has an ignition value set to true. That tells the bus to prioritize it, and begin the scene through it.

Next, we created the Roads for our Phases with a simple looping condition. In here, these Roads will make the scene switch between the two Phases every time the animation loops 2 times.

You can create multiple kits inside a phase_kits. With each aiming at an specific Stage.

These things often can become complicated, so it’s recommended to have a visual grasp on what you have in mind at hands.