Tutorials · Navigation and AI · Chapter 8

A brain

His clips

1. In Assets, open art, right-click guard-alert.png, and choose Make Animation…. The window opens with guard-alert.png ticked, Name guard-alert, Frames a second 12.0 and Loop ticked.
2. Tick guard-idle.png and guard-step.png too. They play in name order: alert, idle, step.
3. Set Frames a second to 6: click its box once, type and press Enter. Then click Name, delete guard-alert and type guard; Enter in that box is the same as Create. Leave Loop ticked, and press Create. It writes art/guard.png, a sheet 64 by 32 holding the three pictures side by side, and art/guard.anim, with one clip called guard that plays them, 6 a second, looping.

Make Animation’s Name

What the two files it writes are called, and the one clip in them: guard gives art/guard.png, art/guard.anim and a clip guard.

Make Animation’s Frames a second

How many of its pictures that clip shows a second: at 6, each one stays a sixth of a second.

Make Animation’s Loop

Ticked, the clip starts again from its first picture when it ends; unticked, it stops on its last.

1. Select guard_corridor. In his Sprite, drag art/guard.png from Assets onto Texture, and clear Atlas Region, which says guard: click its box, delete the word and press Enter.
2. Click Add component and choose AnimatedSpriteComponent. Drag art/guard.anim from Assets onto its Animations. Clip stays idle, as it comes. Tick Frame Size.

Atlas Region

The Sprite’s Atlas Region: a named part of its Texture to draw; empty, it draws the whole picture. guard named the guard’s part of the keep’s sheet, and guard.png has no part of that name. Emptied, the Sprite holds the whole sheet, and the Animated Sprite draws one frame of it at a time.

Animations

The Animated Sprite’s Animations: the .anim file it plays, which holds the clips and names the sheet they are cut from: guard.anim.

Clip

The Animated Sprite’s Clip: the clip it plays, by name. A new one says idle, which is the guard’s standing clip once it is cut below. From the next section his graph chooses it.

Frame Size

The Animated Sprite’s Frame Size: ticked, each frame is drawn at its own size and stood on its pivot. The alert picture is 24 tall and the others 16, so ticked, the alert one stands on his feet with the mark above his head, where unticked every frame would be squeezed into the Sprite’s Size.

1. With guard_corridor still selected, double-click art/guard.png in Assets. The Sprite sheet tab opens on it; scroll over the sheet to zoom in.
2. Idle. Under Grid, set Cell to 16 and 16, Margin to 18 and 0, and Spacing to 0 and 0. Click cell 0, 0. Under Clips, press From selection, name the clip idle, set its rate to 6 fps and its loop to Loop, and press Generate 1. Press Clear.
3. Walk. Keep Cell and Margin, and set Spacing to 2 and 0: the gap the packing left between the idle and the step pictures. Drag from cell 0, 0 to cell 1, 0. Press From selection, name it walk, 6 fps, Loop, Generate 1, Clear.
4. Alert. Set Cell to 16 and 24, Margin to 0 and 0, and Spacing to 0 and 0. Click cell 0, 0. Press From selection, name it alert, 6 fps, Loop, Generate 1, Clear.
5. In the Animation tab, press Save. It writes the three clips into art/guard.anim, after the guard clip.

Cell, Margin and Spacing

The Sprite sheet tab’s grid. Cell is one frame’s size in the sheet’s pixels; Margin is where the grid starts from the sheet’s top left; Spacing is the gap between one cell and the next. The packing left 2 pixels between the pictures, so walk’s second cell starts at 36, not 34.

A frame’s pivot

The point of the frame that stands on the node, from 0 to 1 each way. A cut frame gets 0.5, 1: the middle of its bottom edge, his feet. The three pictures are all drawn standing on their bottom row, so every frame keeps it.

A graph picks his clip

1. With guard_corridor selected, click Add component and choose StateMachineComponent. Its Graph is empty. Click the Graph tab, and press New state machine. It writes art/guard.asm beside art/guard.anim, with one state, idle, playing the clip idle, and puts it in the State Machine’s Graph.
2. In the Parameters list, type alert into the name box, choose switch in the list of kinds beside it, and press Add. Its row reads alert, switch, unticked: it starts off.
3. In the row over the canvas, type walk into State and walk into Clip, and press Add state. Do the same with alert and alert. Drag the new boxes apart: walk to the right of idle, and alert below the two, between them.
4. Click the Any State box, press Link and click alert. In its row in the Transitions list, numbered 0, click Is and type alert into the box. Leave the box beside it ticked, as Is gives it, so it reads true.
5. The new arrow runs from Any State, behind idle, down to alert. Drag the Any State box down to the right of alert, level with it, so the arrow runs clear of idle. Its place is the tab’s, not the file’s: the next time the tab opens, the box is back above idle.
6. Click alert, press Link and click idle. In row 1, click Is, type alert, and untick the box, so it reads false.
7. Click idle, press Link and click walk. In row 2, click >, type speed, and set the number beside it to 5: click it once, type, Enter.
8. Click walk, press Link and click idle. In row 3, click <, type speed, and set the number to 5 the same way. Set its Blend, the box with an s after its number, to 0.1.
9. Press Save in the Graph tab’s bar, and Ctrl+S.

Graph

The State Machine’s Graph: the .asm file it runs, guard.asm. Each state plays a clip of the node’s Animated Sprite, and the arrows say when to go from one to another. The entry, idle, is where it starts.

speed

A parameter the guard’s Character Body writes on every step: how fast he moves, in world units a second. He walks at 40 and stands at 0, so 5 tells walking from standing with room to spare.

A transition’s Blend

How long, in seconds, the old clip fades into the new one when the arrow is taken. 0 is a cut, and every new arrow starts there; 0.1 softens his stop from a walk.

alert, a switch

A parameter you declared, on or off, and off as it starts. His script turns it on while he chases or searches, and off otherwise. Any State to alert takes him there from either other state the step it goes on, and alert to idle brings him back the step it goes off.

His mind, as a script

1. Click the Code tab, then guard.rgs in its Scripts list. Replace everything in it with the script below, and press Ctrl+S.

/// A guard's mind. He walks his round, corner to corner. A glimpse of the
/// thief, or a noise near enough by road, makes him suspicious: he creeps to
/// where he glimpsed her or heard it. Seen near enough to be sure, she is
/// chased at a run, and caught she is sent back to where she came in. Lost,
/// she is searched for about where he saw her last, for a while, and then he
/// goes back to his round.
enum Mode { Patrol, Suspicious, Chase, Search, Return }

component Guard {
    /// His round's first corner.
    a: Vec2,
    /// Its second.
    b: Vec2,
    /// Its third; a round of two corners never comes here.
    c: Vec2,
    /// Its fourth.
    d: Vec2,
    /// How many corners his round has: 2 or 4.
    corners: i32 = 4,
    /// How far by road a noise can be and still be heard.
    #[suffix("u")]
    hearing: f32 = 320.0,
    /// How far he sees.
    #[suffix("u")]
    sight: f32 = 112.0,
    /// How far to either side of straight ahead he sees, in radians.
    cone: f32 = 0.6,
    /// The collision layers that hide what is behind them.
    walls: i32 = 1,
    /// How near he must see her to be sure it is her.
    #[suffix("u")]
    sure: f32 = 64.0,
    /// How fast he walks his round.
    walk: f32 = 40.0,
    /// How fast he creeps when suspicious.
    creep: f32 = 24.0,
    /// How fast he runs after her.
    run: f32 = 72.0,
    /// How long he searches, in steps.
    patience: i32 = 360,
    /// What is on his mind.
    #[readonly]
    mode: Mode = .Patrol,
    /// Whether the thief is in his cone, as this step began.
    #[readonly]
    sees: bool = false,
    /// Which way he faces: the way he last walked.
    #[hidden]
    facing: Vec2,
    /// Where he stood the step before.
    #[hidden]
    was: Vec2,
    /// Where he saw her last.
    #[hidden]
    last_seen: Vec2,
    /// The corner he is walking to, from 0.
    #[hidden]
    next: i32 = 0,
    /// Whether to set off for that corner this step.
    #[hidden]
    to_round: bool = true,
    /// Steps of searching left.
    #[hidden]
    searching: i32 = 0,

    fn on_create() {
        was = position();
        facing = vec2(0.0, 1.0);
    }

    fn loop() {
        let moved = position() - was;
        if moved.length() > 0.1 {
            facing = moved;
        }
        was = position();
        let thief = nearest("thief");
        let at = position_of(thief);
        let toward = at - position();
        // Returning, he has given up; he looks again on his round.
        sees = mode != .Return
            && thief != node(0)
            && toward.length() < sight
            && angle_between(facing, toward) < cone
            && can_see(at, walls);
        if sees {
            last_seen = at;
        }

        if mode == .Patrol || mode == .Return {
            if sees {
                mode = .Suspicious;
                set_number("NavAgentComponent", "speed", creep);
                walk_to(at);
            }
        } else if mode == .Suspicious {
            if sees && toward.length() < sure {
                mode = .Chase;
                set_number("NavAgentComponent", "speed", run);
            }
        } else if mode == .Chase {
            if !sees {
                mode = .Search;
                searching = patience;
                walk_to(last_seen);
            } else if toward.length() < 10.0 {
                emit_to("thief", "caught");
                mode = .Return;
                to_round = true;
            } else {
                walk_to(at);
            }
        } else if mode == .Search {
            searching -= 1;
            if sees {
                mode = .Chase;
                set_number("NavAgentComponent", "speed", run);
            } else if searching <= 0 {
                mode = .Return;
                to_round = true;
            }
        }

        if to_round {
            to_round = false;
            set_number("NavAgentComponent", "speed", walk);
            if next == 0 {
                walk_to(a);
            } else if next == 1 {
                walk_to(b);
            } else if next == 2 {
                walk_to(c);
            } else {
                walk_to(d);
            }
        }
        set_param_flag("alert", mode == .Chase || mode == .Search);
    }

    fn on_signal() {
        if heard("noise") && (mode == .Patrol || mode == .Return) {
            let noise = kept_point("noise", position());
            let way = road_distance(noise);
            if way >= 0.0 && way < hearing {
                mode = .Suspicious;
                set_number("NavAgentComponent", "speed", creep);
                walk_to(noise);
            }
        }
        if heard("nav:ended") {
            if mode == .Patrol || mode == .Return {
                if arrived() {
                    next += 1;
                    if next >= corners {
                        next = 0;
                    }
                }
                mode = .Patrol;
                to_round = true;
            } else if mode == .Suspicious {
                mode = .Return;
                to_round = true;
            } else if mode == .Search {
                let far = 40.0 * sqrt(random(0.0, 1.0));
                let turn = random(0.0, tau());
                let spot = last_seen + vec2(far * turn.cos(), far * turn.sin());
                if can_reach(spot) {
                    walk_to(spot);
                } else {
                    walk_to(last_seen);
                }
            }
        }
    }
}

1. With guard_corridor selected, remove his Guard with the bin icon at the right of its header. Click Add component and choose Guard.
2. Set A to 40, 232 and B to 600, 232, the two ends of his round, each box clicked once, typed into and Enter. Set Corners to 2. C and D stay 0, 0: a round of two corners never comes to them. Every other field stays as the script gives it.
3. Press Ctrl+S.

enum Mode { Patrol, Suspicious, Chase, Search, Return }

The five things on his mind, by name. Mode holds one of them, and the script compares and sets it as .Patrol, .Chase and so on. An enum is a closed list: a mode not on it cannot be written, or misspelled.

A, B, C, D and Corners

His round, as corners in world units, in order, and how many of them he walks: 2 or 4. He walks from one to the next, and from the last back to A. The corridor guard’s two are the corridor’s ends; the hall guard’s four are hall_round’s corners. Corners default to 0, 0, and Corners to 4.

Sure

How near he must see her to be sure it is her and chase: 64 world units, four tiles. Further away, still in his Sight of 112, she is a glimpse, and he only creeps.

Walk, Creep and Run

His three paces, in world units a second, which his script writes onto his Nav Agent’s Speed: 40 on his round, as before; 24, slow and wary, when suspicious; 72 in a chase. She runs at 70, so he gains on her by two units a second.

Patience

How long he searches, in steps: 360, six seconds at sixty steps a second. Chapter 9 hands this to a Timer.

Mode

What is on his mind: read-only, greyed in the Inspector, and live while the game plays. Select a guard in Play and watch it change.

set_number

Writes a number onto another component on this node: set_number("NavAgentComponent", "speed", run) sets his Nav Agent’s Speed to his Run, from the next step on. The script changes his pace this way whenever his mode changes.

set_param_flag

Sets a switch his State Machine reads, from the next step. The last line of his loop sets alert on every step: on while he chases or searches, off otherwise. It is the one thing his script tells his graph.

        // Returning, he has given up; he looks again on his round.
        sees = mode != .Return
            && thief != node(0)
            && toward.length() < sight
            && angle_between(facing, toward) < cone
            && can_see(at, walls);
        if sees {
            last_seen = at;
        }

        if mode == .Patrol || mode == .Return {
            if sees {
                mode = .Suspicious;
                set_number("NavAgentComponent", "speed", creep);
                walk_to(at);
            }

        } else if mode == .Suspicious {
            if sees && toward.length() < sure {
                mode = .Chase;
                set_number("NavAgentComponent", "speed", run);
            }

        } else if mode == .Chase {
            if !sees {
                mode = .Search;
                searching = patience;
                walk_to(last_seen);
            } else if toward.length() < 10.0 {
                emit_to("thief", "caught");
                mode = .Return;
                to_round = true;
            } else {
                walk_to(at);
            }

        } else if mode == .Search {
            searching -= 1;
            if sees {
                mode = .Chase;
                set_number("NavAgentComponent", "speed", run);
            } else if searching <= 0 {
                mode = .Return;
                to_round = true;
            }

        if to_round {
            to_round = false;
            set_number("NavAgentComponent", "speed", walk);
            if next == 0 {
                walk_to(a);
            } else if next == 1 {
                walk_to(b);
            } else if next == 2 {
                walk_to(c);
            } else {
                walk_to(d);
            }
        }
        set_param_flag("alert", mode == .Chase || mode == .Search);

    fn on_signal() {
        if heard("noise") && (mode == .Patrol || mode == .Return) {
            let noise = kept_point("noise", position());
            let way = road_distance(noise);
            if way >= 0.0 && way < hearing {
                mode = .Suspicious;
                set_number("NavAgentComponent", "speed", creep);
                walk_to(noise);
            }
        }
        if heard("nav:ended") {
            if mode == .Patrol || mode == .Return {
                if arrived() {
                    next += 1;
                    if next >= corners {
                        next = 0;
                    }
                }
                mode = .Patrol;
                to_round = true;
            } else if mode == .Suspicious {
                mode = .Return;
                to_round = true;
            } else if mode == .Search {
                let far = 40.0 * sqrt(random(0.0, 1.0));
                let turn = random(0.0, tau());
                let spot = last_seen + vec2(far * turn.cos(), far * turn.sin());
                if can_reach(spot) {
                    walk_to(spot);
                } else {
                    walk_to(last_seen);
                }
            }
        }
    }

sqrt

The square root of a number; 0 for a negative one. 40.0 * sqrt(random(0.0, 1.0)) is a distance from 0 to 40 that falls as often near the rim of the disc as near its middle, so his spots spread over the whole disc instead of bunching at its centre.

tau

One full turn, in radians: about 6.283. random(0.0, tau()) is a direction, any way round.

.cos() and .sin()

The cosine and sine of an angle in radians: vec2(far * turn.cos(), far * turn.sin()) is the point far away in the direction turn. With 0 along +x and a quarter turn straight down, as chapter 7’s angles are.

1. Press F5. Select guard_corridor, and in the Inspector type guard into the search box at its top and press Enter, so only his Guard shows. In Play, press Enter after typing in a box: while it has the cursor, W, A, S and D type into it as well as walking her. Wait: he walks east along the corridor into the view about eight seconds in, Mode Patrol.
2. Walk the thief onto the carpet in front of him. Sees ticks, Mode reads Suspicious and he slows; nearer, Chase, the red mark over his head, and he runs.
3. Press F5 again to stop.

The hall guard too

1. Select guard_hall. Click Add component and choose CharacterBodyComponent. Set its Size to 8, 6, Motion Mode to Floating, Driven By to Script, and Layer to 2 (untick the box labelled 0, tick the one labelled 1), as chapter 6 did for the corridor guard.
2. Click Add component and choose NavAgentComponent. Set Speed to 40, tick Face Walk and untick Use Links. Target, Moving and Arrive Distance stay as they come.

1. With guard_hall selected, remove his PathFollowComponent with the bin icon at the right of its header. The row leaves the Problems tab. hall_round stays, the drawing of his round.
2. Under Groups, type guards into Add group and press Enter; then ears, Enter.
3. In his Sprite, drag art/guard.png onto Texture and clear Atlas Region.
4. Click Add component and choose AnimatedSpriteComponent. Drag art/guard.anim onto Animations, and tick Frame Size.
5. Click Add component and choose StateMachineComponent. Drag art/guard.asm from Assets onto its Graph: the one graph serves both guards.
6. Click Add component and choose Guard. Set A to 56, 72, B to 264, 72, C to 264, 168 and D to 56, 168: hall_round’s four corners, in its order. Corners stays 4.
7. With guard_hall selected, press + Add node, choose Sprite, and rename it cone_hall. Set its Position to 0, -8; drag art/cone.png onto Texture; set Size to 112, 154, Anchor to 0, 0.5 and Sort Layer to 1. Click Add component and choose Cone: the corridor guard’s cone, for him.
8. Select guard_corridor, and under Groups add guards. He is in ears already, since chapter 6.
9. Press Ctrl+S.

Speed, Face Walk and Use Links

The hall guard’s Nav Agent, as the corridor guard’s: Speed 40 until his script changes it, Face Walk ticked so he faces his walk, Use Links unticked so the hole is not his way to the cellar.

Groups guards and ears

Both guards are in both. ears is the group the pots tell of a noise, from chapter 6; guards is the one chapter 9’s bell calls.

Caught

1. In Assets, press Create, choose New script, type thief, and press Enter. In the Code tab, replace everything in thief.rgs with the script below, and press Ctrl+S.
2. Select thief, click Add component and choose Thief. Its one field, start, is hidden.
3. Press Ctrl+S.

/// The thief. Caught by a guard, she is put back where she came in.
component Thief {
    /// Where she starts again when she is caught.
    #[hidden]
    start: Vec2,

    fn on_create() {
        start = position();
    }

    fn on_signal() {
        if heard("caught") {
            move_to(start);
        }
    }
}

start

Where she stood as the game began, kept by on_create, which runs once, on her first step. Hidden: nothing to type.

move_to

Puts this node at a point, in world units, at once: no walk, no wall in the way. move_to(start) takes her from the guard’s hands to the gate in one step.

caught

The signal a guard sends with emit_to("thief", "caught") when he is within 10 of her. She hears it on the next step, so she is moved one step after he comes within 10 of her.

What the chapter set

Check it works