Tutorials · Animation and Cutscenes · Chapter 5

Orders from a script

An attack key

1. Choose View → Input map…. With no input map saved yet, the window starts on six actions of its own, left, right, up, down, jump and action, which nothing in this show reads. Select each of the six in turn and press Remove.
2. Type attack into New action and press Add. With attack selected, press Record a control and press J. Press Record a control again and press X.
3. Press Save, and close the window. It writes input.ron into the project.

Press

What a control does with the key. A Press counts on the step the key goes down, which is what pressed asks about, and not again until it has come up and gone down again. Holding J does not slash twice.

Triggers in the graph

1. Select knight and click the Graph tab. It shows knight.asm.
2. In the Parameters list, type hurt into the name box, choose trigger in the list of kinds beside it and press Add. Do the same for slash. Both rows read trigger, lowered.
3. In the row over the canvas, type hurt into State and hurt into Clip, and press Add state. Do the same with slash and slash. Drag the two new boxes to the right of the others, where no arrow crosses them.
4. Click the Any State box, press Link and click hurt. In the Transitions list, the new row, Any State to hurt, goes at the end: its number, at the row’s left, reads 7. While Any State is selected the list shows only its own arrows, and the number is the arrow’s place in the whole list. Choose Trigger in its row and type hurt in the name box under it. Press the up arrow at the row’s left until the number at its left reads 0.
5. Click Any State again, press Link and click slash. Choose Trigger and type slash. Press its up arrow until its number reads 1.
6. Click slash, press Link and click idle. Choose Finished and set its Blend, the box with an s beside the names, to 0.05. Click hurt, press Link and click idle. Choose Finished; its blend stays 0.
7. Press Save.

Trigger

A kind of parameter, and a kind of condition. A trigger is raised from a script with trigger, and it stays raised for one step: whichever edge reads it takes it, and after that step it is gone, whether an edge took it or not. An edge whose condition is Trigger holds on the step the named trigger is up.

Any State

The dashed box. An edge from it can fire in every state but the one it enters, so hurt can be raised from idle, run, air or land without an edge from each.

Parameters

The list at the right of the graph. A parameter is a value a condition reads. grounded, speed, velocity_x and velocity_y are the body’s, marked the body, and hurt and slash are yours: declared, they read lowered, which is what a trigger is until it is raised.

The knight’s orders

1. Select knight, press Add component and choose AreaComponent. Set the Shape’s Size to 12 and 30, and its Offset to 0 and -15: the same box as his Character Body, standing on his feet. Leave Solid unticked: an Area is felt, never bumped into.
2. Under Groups, type knight and press Enter.
3. In Assets, press Create, choose New script, type knight, and press Enter. In the Code tab, replace everything in knight.rgs with the script below, and press Ctrl+S.

/// The knight's orders: J or X slashes, unless he is hurt. The spikes hurt
/// him, and not again until his hurt clip has played out; its recoil frame
/// lifts him by the number it carries.
component Knight : Area {
    /// Whether his hurt clip is still playing.
    #[hidden]
    hurting: bool = false,

    fn while_in() {
        if in_group(other, "spikes") && !hurting {
            hurting = true;
            trigger("hurt");
        }
    }

    fn on_signal() {
        if heard("frame:recoil") {
            set_number("CharacterBodyComponent", "velocity.y", -heard_value("frame:recoil"));
        }
        if heard("finished:hurt") {
            hurting = false;
        }
    }

    fn loop() {
        if pressed("attack") && state() != "hurt" {
            trigger("slash");
        }
    }
}

1. Select knight, press Add component and choose Knight. Its one field, hurting, is hidden: the script keeps it, and it starts false.

component Knight : Area

A script with an Area base: it goes on a node that has an Area, and it hears what that Area meets. while_in runs on every step that another Area is still overlapping it, with that Area’s NodeId as other.

in_group

Whether the node it is given was in the group as the step began. in_group(other, "spikes") is true while the Area that is overlapping the knight’s belongs to a node in the group spikes. It is how a script tells what it has met.

trigger

Raises the named trigger for this node’s graph on the next step, and it is gone after that step. trigger("hurt") is what the Any State edge to hurt waits for.

on_signal and heard

on_signal runs on a step when a signal has reached this node. heard("frame:recoil") is true on that step if the signal was that one. Several signals can reach a node on one step, and the script asks about each.

frame:recoil

The signal a frame’s Trigger track raises: frame: and the track’s name. It arrives the step the clip shows that frame. hurt’s recoil track is on its frame 1, carrying 220, the number you gave it in chapter 4.

heard_value

The number the signal carried: 220 for frame:recoil, and 0 if the signal carried none or was not heard.

set_number

Writes a number onto another component on this node. "velocity.y" reaches the y part of the Character Body’s velocity. Down counts as positive, so -220 is up, at 220 units a second: a hop of about a dozen units, which is what the hurt’s lift is.

finished:hurt

The signal a clip raises the step it plays out: finished: and the clip’s name. The script clears hurting on it, which is how it knows the hurt is over.

loop

Runs on every step while the node exists. The knight’s asks there whether attack went down, since pressed is true for one step only.

state

The name of the state the graph was in as the step began: hurt, idle, or air/rise inside a sub-graph. It is empty if the node has no graph.

pressed

Whether the action went down on this step. pressed("attack") is true on the one step J or X goes down.

1. Select theatre, press + Add node and choose Sprite. Rename it spikes, set its Position to 720 and 288, and under Groups type spikes and press Enter.
2. In its Sprite, drag art/spikes.png from Assets onto Texture, and set Size to 32 and 12, Anchor to 0.5 and 1 and Sort Layer to 4.
3. Press Add component and choose AreaComponent. Set the Shape’s Size to 28 and 6, and its Offset to 0 and -3: a box over the lower half of the picture, a little in from each side, so a jump that grazes the tips does not hurt.
4. In the Hierarchy, drag spikes up until it sits just under platform.

Groups

Names on a node, shown as tags by its name. A node can be in several. A group is how a script knows what it has met: knight, spikes and, from chapter 4, blade.

Size and Offset

An Area’s Shape: the box it covers, in world units, Size wide and tall, with its centre Offset from the node. The knight’s 12 by 30 at 0, -15 stands on his feet. The spikes’ 28 by 6 at 0, -3 covers the lower half of their 32 by 12 picture, a little in from each side.

A lever that opens the trapdoor

1. Copy the two sounds above into audio, and press Refresh in Assets.
2. Select lever, press Add component and choose AreaComponent. Set the Shape’s Size to 16 and 28, and its Offset to 0 and -14.
3. Press Add component and choose SignalComponent. Press the + beside Connections, open the new row, set Signal to pulled and To to trapdoor. The row remembers the trapdoor itself, so renaming it later does not break the row.
4. Press Add component and choose AudioSourceComponent. Leave Bus on Sfx and Autoplay off. Press the + beside Triggers, open the new row, set Name to click and Clip to metalClick.ogg.
5. In Assets, press Create, choose New script, type lever, and press Enter. In the Code tab, replace everything in lever.rgs with the script below, and press Ctrl+S. Then select lever, press Add component and choose Lever.

/// The lever. The knight's blade pulls it, once: it clicks, and tells
/// whoever the scene connected to it that it was pulled.
component Lever : Area {
    /// Whether it has been pulled.
    #[hidden]
    pulled: bool = false,

    fn on_enter(other: NodeId) {
        if in_group(other, "blade") && !pulled {
            pulled = true;
            play_sound("click");
            emit("pulled");
        }
    }
}

on_enter

Runs once, on the step another Area starts overlapping this one, with that Area’s NodeId. The blade’s Area is live only on the slash’s hitbox frames, so it enters the lever’s when the swing reaches it, and that is the moment the lever is pulled.

play_sound

Plays the clip a trigger of this node’s Audio Source is named for: play_sound("click") plays metalClick.ogg, the Clip of the row named click. It is the same list the frame events used in chapter 4.

emit

Tells whoever the scene connected: a Signal row with this name, pulled, on this node, sends it to the node in its To. The trapdoor hears it on the next step, never in the same one, so neither needs to know about the other.

Signal and To

A row of the Signal component’s Connections: the name of what this node emits, spelled as the script emits it, and the node that hears it. A node can have several rows, and several can share a name: chapter 6 adds two more pulled rows.

1. Select trapdoor, press Add component and choose PropertyAnimationComponent. Click the Animation tab, then its Properties mode, and press New property clips. It writes scenes/trapdoor.propanim and sets the component’s Clips to it.
2. Press + and name the new clip open. Switch Record on: from now on, a value you change in the Inspector is keyed into the open clip, at the playhead, and the trapdoor itself is not changed.
3. Set the time box, 0.00 s, beside the Play and Stop buttons, to 0.35, the playhead, and set Rotation in the Inspector to 83.08, a little more than a quarter turn. A row, rotation, appears with a key at 0.35, and the Inspector and the Viewport show the pose. The clip is 0.35 seconds long, the time of its last key.
4. Set the playhead to 0. A track holds its first key’s value until the playhead reaches it, so Rotation reads 83.08. Set it to 0: the second key. Switch Record off.
5. In the rotation row, choose Eased in the first list and OutBounce in the second. A recorded track starts as Linear.
6. Press Capture RESET. The mode adds a clip called RESET with one key at 0, holding the rotation the scene gives the trapdoor, 0, whatever the playhead says.
7. In the component, set Clip to open and Looping to Once. Playing stays off: the clip waits for its script.
8. Press Add component and choose AudioSourceComponent. Press the + beside Triggers, open the new row, set Name to open and Clip to impactPlank_medium_000.ogg.
9. In Assets, press Create, choose New script, type trapdoor, and press Enter. In the Code tab, replace everything in trapdoor.rgs with the script below, and press Ctrl+S. Then select trapdoor, press Add component and choose Trapdoor, and press Ctrl+S.

/// The trapdoor. When the lever is pulled it stops holding anything up and
/// drops open with a bang.
component Trapdoor {
    fn on_signal() {
        if heard("pulled") {
            set_flag("ColliderComponent", "solid", false);
            play_property_clip("open");
            play_sound("open");
        }
    }
}

set_flag

Writes a tick box of another component on this node. set_flag("ColliderComponent", "solid", false) unticks the trapdoor’s Solid: from the next step nothing stands on it.

play_property_clip

Plays one of this node’s Property Animation clips from its start, the one already playing or one that has finished too. It does not need Playing on: the call starts the clip.

OutBounce

An ease that settles with decaying bounces, like something dropped on a floor: it reaches the last key early, falls back from it and reaches it again, each bounce smaller. The lid hits the pit’s wall, bounces up a little, and settles on 83.08 degrees at 0.35 seconds.

Check it works