Defining Instruction Macros

Instruction macros are pseudo Instruction's that, instead of inserting themselves into the Chapter's instructions upon being added to a Chapter, will instead programmatically insert multiple instructions into the current chapter. They are added to a storyboard in the exact same way regular Instructions are.

They are created with Ponder.API.NewInstructionMacro instead of Ponder.API.NewInstruction.

They only have one method:

InstructionMacro:Run(Chapter chapter, table parameters)

Ran when chapter:AddInstruction(macroName, parameters) is called. The 2nd argument of AddInstruction is directly passed into the 2nd argument of InstructionMacro.Run.

ℹ While it is not required, the standard Ponder sets is to store macros in the instructions_cl/macros/ folder. However, they can be anywhere inside of instructions_cl/ and still work fine.

---

An example macro (Multi-Parenting)...

local MultiParent = Ponder.API.NewInstructionMacro("MultiParent")

function MultiParent:Run(chapter, parameters)
    local length = parameters.Length or 1
    local timeForEachClick = length / (#parameters.Children + 1)
    chapter:AddInstruction("ShowToolgun", {Length = timeForEachClick, Tool = "Multi-Parent"})
    local tAdd = 0
    for _, child in ipairs(parameters.Children) do
        chapter:AddInstruction("MoveToolgunTo", {Time = tAdd, Target = child, Easing = parameters.Easing})
        tAdd = tAdd + timeForEachClick
        chapter:AddInstruction("ClickToolgun", {Time = tAdd, Target = child})
        chapter:AddInstruction("ColorModel", {Time = tAdd, Target = child, Length = 0.1, Color = Color(100, 255, 100, 190)})
    end

    chapter:AddInstruction("MoveToolgunTo", {Time = tAdd, Target = parameters.Parent, Easing = parameters.Easing})
    chapter:AddInstruction("ClickToolgun", {Time = tAdd + timeForEachClick, Target = parameters.Parent})
    for _, child in ipairs(parameters.Children) do
        chapter:AddInstruction("ColorModel", {Time = tAdd + timeForEachClick, Target = child, Length = 0.1, Color = Color(255, 255, 255, 255)})
    end
    chapter:AddInstruction("HideToolgun", {Time = tAdd + timeForEachClick + 0, Length = timeForEachClick})

    return tAdd + timeForEachClick
end

... and an example showing how this macro gets called in a Storyboard:

chapter2:AddInstruction("MultiParent", {
    Children = {"Gun"},
    Parent = "TurretTrun",
    Easing = math.ease.InOutQuad
})