Tutorials · Worlds and Levels · Chapter 12

Cause and effect

When to reach for a Signal

A lever

1. Double-click scenes/vale.ron in Assets. In Assets, click Assets in the path bar, so the script is written at the project’s top, then click Create, choose New script, type lever and press Enter. Click the Code tab, then lever.rgs in its Scripts list, replace everything in it with the script below, and press Ctrl+S. Click the Viewport tab.

/// A lever. Standing at it, the pilgrim throws it with the action key: its
/// handle swings over, and it says pulled to whoever its Signal is wired
/// to. A lever is thrown once and stays thrown. Every lever in Hollowmere
/// is this script; what each one works is the node its Signal names.
component Lever : Area {
    /// Whether the pilgrim is within reach: inside the lever's Area.
    #[readonly]
    near: bool = false,
    /// Whether it has been thrown.
    #[readonly]
    pulled: bool = false,

    fn on_enter(other: NodeId) {
        // Something has come within reach. Only the pilgrim, who is in the
        // group pilgrim, can throw it.
        if in_group(other, "pilgrim") {
            near = true;
        }
    }

    fn on_exit(other: NodeId) {
        if in_group(other, "pilgrim") {
            near = false;
        }
    }

    fn loop() {
        // The action key (E) throws it, once: its picture is flipped, so the
        // handle leans the other way, and whoever its Signal names hears
        // pulled on the next step.
        if near && !pulled && pressed("action") {
            pulled = true;
            set_flag("SpriteComponent", "flip.x", true);
            emit("pulled");
        }
    }
}

component Lever : Area, near and pulled

A script with an Area base: the lever’s Area is its reach. near is whether he is inside it, set by on_enter and cleared by on_exit; pulled is whether it has been thrown. Both are #[readonly], greyed in the Inspector, to watch.

pressed

Whether an action went down this step: action is E or Enter.

set_flag with flip.x

Ticks the Sprite’s Flip X: the picture is mirrored, and the handle leans the other way. The lever’s base is its own mirror, so only the handle moves.

emit

Says a name, pulled, to whoever the node’s Signal wires it to. They hear it on the next step, never the same one. !pulled keeps a lever from saying it twice: a lever is thrown once.

The drawbridge

1. Select buildings and click the Tilemap tab. Click ground’s row and press +: an empty layer goes in over ground and lights. Double-click its name and rename it bridge.
2. Open bridge’s gear and tick Solid. Leave the rest as a new layer comes: z 0, its eye open, One-way, Blocks nav and Occluder unticked. Paint nothing on it. Press Ctrl+S.

1. In the Hierarchy, select bridge-block, press Delete, and press Delete in the box that asks: the ravine is open.
2. In Assets, with Assets clicked in the path bar, click Create, choose New script, type drawbridge and press Enter. Click the Code tab, then drawbridge.rgs in its Scripts list, replace everything in it with the script below, and press Ctrl+S. Click the Viewport tab.
3. Select buildings, and drag drawbridge.rgs from Assets onto its Inspector: it adds Drawbridge, with nothing to set. Press Ctrl+S.

/// The drawbridge over the ravine, laid by the vale's tilemap itself. When
/// the lever by the ravine is pulled, planks are laid across, one at a
/// time, west to east, into the map's bridge layer. The layer is solid, so
/// a plank laid there can be walked on.
component Drawbridge {
    fn loop() {
        // Wait for the lever: its Signal sends pulled to this map.
        await signal("pulled");
        // Then the planks, a tenth of a second apart: the slab, tile 489,
        // into row 0, the row under the walking line, of this map's bridge
        // layer, from column 120, at the ravine's west lip, to column 129,
        // at its east. They are written out one by one because a for loop
        // runs all its turns in one step and cannot wait between them, and
        // there is no while.
        set_tile(this(), "bridge", vec2(120.0, 0.0), 489);
        await wait(0.1);
        set_tile(this(), "bridge", vec2(121.0, 0.0), 489);
        await wait(0.1);
        set_tile(this(), "bridge", vec2(122.0, 0.0), 489);
        await wait(0.1);
        set_tile(this(), "bridge", vec2(123.0, 0.0), 489);
        await wait(0.1);
        set_tile(this(), "bridge", vec2(124.0, 0.0), 489);
        await wait(0.1);
        set_tile(this(), "bridge", vec2(125.0, 0.0), 489);
        await wait(0.1);
        set_tile(this(), "bridge", vec2(126.0, 0.0), 489);
        await wait(0.1);
        set_tile(this(), "bridge", vec2(127.0, 0.0), 489);
        await wait(0.1);
        set_tile(this(), "bridge", vec2(128.0, 0.0), 489);
        await wait(0.1);
        set_tile(this(), "bridge", vec2(129.0, 0.0), 489);
        // The bridge is laid. The loop goes round and waits again, for a
        // lever that is thrown only once.
    }
}

component Drawbridge and await signal

A script with no base, on the map’s node. signal("pulled") waits until that name reaches this node: the lever’s Signal will send it here.

set_tile and this

Paints a tile, by its number, into a cell of a layer of a map, from the next step: here the slab, #489, the one the hut’s step is painted with, into row 0 of this map’s bridge layer, columns 120 to 129, x 1920 to 2080. this() is the node the script is on, the map.

await wait

Waits that many seconds, then goes on with the next line: a plank each tenth of a second. A wait counts down a step of 1/60 s at a time, and six steps leave a sliver of the tenth still to run, so it runs out on the seventh: the planks are 7 steps apart.

Why the planks are written out

A for runs all its turns in one step and cannot wait between them, and there is no while. A field counting the columns, a plank each turn of loop(), would come round a step later each turn.

Writing tiles while the game plays

set_tile and clear_tile change a map’s cells for the run only: the map’s file, in the editor and in an export, and the scene the next time it is entered, are as painted. Here bridge stays empty in the file.

1. Select vale, press + Add node and choose Sprite: the menu opens on Add child of vale. Rename it bridge-lever, and type its Position 1872, 0.
2. In its Sprite, drag art/lever.png onto Texture, type Size 16, 16, its own, and Anchor 0.5, 1, so it stands on its foot, and set Sort Layer to Props.
3. Press Add component and choose AreaComponent. In its Shape, type Size 24, 32 and Offset 0, -16, and leave the Area’s Layer and Mask as they come, pilgrim, as his: x 1860 to 1884, y -32 to 0, his reach.
4. Drag lever.rgs from Assets onto its Inspector: it adds Lever, Near and Pulled greyed.
5. Press Add component and choose SignalComponent. Press the + beside Connections: a row, [0]. Open it, type pulled into Signal, and for To click it and choose buildings from the list, or drag buildings from the Hierarchy onto it. Press Ctrl+S.

The Signal’s Connections

The names this node says, and who hears each: a row a name and a hearer. + adds a row; its arrows move it, and its bin takes it off. A name with no hearer, or a hearer with no name, is a row still being typed, and draws no wire.

The connection’s Signal and To

Signal is the name, as the script says it, pulled. To is the node that hears it, chosen from the list or dragged from the Hierarchy. The scene keeps the node by its number, not its name.

1. Select bridge-lever, press Frame, and pick 25% from the zoom menu at the Viewport’s foot.

1. Click Gizmos at the Viewport’s foot.

A Signal’s wires

While a node with a Signal is selected, the Viewport draws an arrow from it to each node it names, and over the arrow’s middle the names that travel it, in the order of its rows. They follow the nodes in Play too. A hearer that is not in the scene draws none: Problems says so.

The Gizmos menu’s Signals

Draws a selected node’s wires; untick it to hide them. Ticked as it comes.

1. Press Run game: it runs the startup scene, the vale. Walk him east to the lever, and on past it.

1. Close the game’s window, or press Stop game, which stands where Run game was while it runs. Then press Run game again, walk him to the lever, stop on it and press E.

Two artifacts

1. In Assets, with Assets clicked in the path bar, click Create, choose New script, type crack and press Enter. Click the Code tab, then crack.rgs in its Scripts list, replace everything in it with the script below, and press Ctrl+S. Click the Viewport tab.

/// A cracked block in a wall. It is a scene tile: the map places one on
/// every cell painted with it. When a block is struck and goes, the block
/// above it comes down too, and that one brings down the next, up the wall.
component Crack {
    fn on_destroy() {
        // The map this block stands in: the nearest node in the group map.
        let map = nearest("map");
        // The cell above this one, 16 up, is cleared on the cracked layer.
        // Its block goes the same way, and tells the one above it in turn.
        clear_tile(map, "cracked", cell_at(map, position() - vec2(0.0, 16.0)));
    }
}

A scene tile’s farewell, on_destroy

Runs once, as the node goes. A scene tile’s node goes when its cell is emptied or painted over, so a block’s farewell runs when the block is struck or cleared.

nearest

The nearest node in a group, as the step began: here map, which halls joins below, so each block finds the map it stands in.

clear_tile, cell_at and position

clear_tile empties a cell of a layer of a map; cell_at is the cell a point in the world falls in; position() is where this node is. Here the cracked cell 16 above the block: the block above goes the same way, and tells the one above it in turn.

1. Double-click scenes/crypt.ron in Assets and press Ctrl+S. Choose File → New scene: an empty scene takes the crypt’s place.
2. Press + Add node and choose Sprite. Rename it crack. In its Sprite, drag art/crack.png onto Texture, type Size 16, 16, its own, and set Sort Layer to Ground. Leave Anchor at 0.5, 0.5: a scene tile’s node stands on its cell’s middle.
3. Press Add component and choose ColliderComponent. Type its Size 16, 16; leave its Offset at 0, 0 and Solid ticked.
4. Drag crack.rgs from Assets onto its Inspector: it adds Crack.
5. Right-click crack in the Hierarchy and choose Save as artifact…. In the save dialog, open the artifacts folder and save the file as crack.artifact.

1. In Assets, with Assets clicked in the path bar, click Create, choose New script, type grate and press Enter. Click the Code tab, then grate.rgs in its Scripts list, replace everything in it with the script below, and press Ctrl+S. Click the Viewport tab.

/// A gate's grate. When its lever is pulled, it rises out of the way, up
/// in front of the stone over the gate, and stays up.
component Grate {
    /// Whether it has risen. A grate opens once.
    #[readonly]
    open: bool = false,

    fn loop() {
        // Its lever's Signal sends pulled here. Heard, the grate slides up
        // by its own height, 64, over a second, easing in and out.
        if !open && heard("pulled") {
            open = true;
            await anneal_by(vec2(0.0, -64.0), 1.0, .InOutSine);
        }
    }
}

component Grate, open and heard

A script with no base. heard("pulled") is true on a step that name reached this node; open keeps the grate from rising twice.

anneal_by

Moves this node by a distance over the seconds it is given, along a curve: up 64, the grate’s own height, over a second, easing in and out.

1. Choose File → New scene: an empty scene takes its place, without asking, and the unsaved copy of crack goes with it.
2. Press + Add node and choose Node. Rename it gate.
3. Select gate, press + Add node and choose Sprite: the menu opens on Add child of gate. Rename it lever, type its Position -32, 0, and build it as bridge-lever was built: its picture, its AreaComponent and Lever. Leave its Signal for now.
4. Select gate again, press + Add node and choose Sprite. Rename it door. In its Sprite, drag art/grate.png onto Texture, type Size 16, 64 and Anchor 0.5, 1, and set Sort Layer to Props.
5. Press Add component and choose ColliderComponent. Type its Size 16, 64 and Offset 0, -32: x -8 to 8, y -64 to 0. Drag grate.rgs onto its Inspector: it adds Grate.
6. Select lever, add its SignalComponent, press +, type pulled into Signal, and choose door for To.
7. Right-click gate in the Hierarchy, choose Save as artifact…, and save it in artifacts as gate.artifact.
8. Double-click artifacts/gate.artifact in Assets. The editor asks Save the open scene?: press Discard. The artifact opens as a scene of its own. Select lever, press Frame, and pick 400% from the zoom menu.

Save as artifact…

In a node’s right-click menu in the Hierarchy: writes the node and everything under it into a file, an artifact, and puts a copy of that file in its place, as one step to undo. A copy follows its artifact; what is changed on a copy, its name among them, is the copy’s own.

One artifact’s lever names its own door

Inside the artifact the lever’s To is the artifact’s door. Each copy dropped into a scene is numbered afresh, and its lever’s To is its own copy’s door: two copies, two levers, each opening its own grate.

1. Double-click scenes/crypt.ron in Assets to go back to the crypt.

The crypt’s map

1. Select halls and click the Tilemap tab. Click tile #59, the cracked block, in the picker, and drag artifacts/crack.artifact from Assets onto Scene’s slot in the Tile band.

1. Click ground’s row and press +, and rename the new layer cracked. Leave it as it comes, not Solid: each block stops him with its own Collider.
2. With #59 held, draw a Line up column 132, from cell 132, -12 to 132, -1: twelve blocks, x 2112 to 2128, y -192 to 0.
3. Click ground’s row, then the stone row in the Terrains band, armed. With Rect, lay the stone over each gate in the table below, from the ceiling’s underside down to y -64, over the two columns its grate will stand across.

1. Click torches’ row and tile #57, the torch’s bracket, in the picker: the brush is on tiles again. With Brush, click cell 135, -6: x 2160 to 2176, y -96 to -80. Press Ctrl+S.

1. Press F5: Play runs the open scene. Select mural-3, press Frame, and pick 200% from the zoom menu.

The strike

1. Press F5 again to stop. Select halls, and in its Node’s Groups type map and press +: crack.rgs’s nearest("map") finds the map by it.
2. Double-click pilgrim.rgs in Assets. In the Code tab, replace its first two lines, its /// comment, with the three below.

/// The pilgrim in the crypt. Down drops him through a ledge he stands on,
/// a tile that hurts sends him back to the checkpoint, and the action key
/// strikes the wall in front of him, which breaks a cracked block.

1. At the end of loop(), after the hazards’ if, add the strike below, and press Ctrl+S. Click the Viewport tab.

        // The action key (E) strikes the wall just ahead of him: the cell 20
        // east of his feet and 4 above them. A cracked block there, tile 59
        // on the cracked layer, breaks into rubble, tile 60.
        if pressed("action") {
            let ahead = cell_at(node(map), position() + vec2(20.0, -4.0));
            if tile_at(node(map), "cracked", ahead) == 59 {
                set_tile(node(map), "cracked", ahead, 60);
            }
        }

tile_at and node

tile_at is the tile painted in a cell of a layer, as the step began: its number, 0 for an empty cell. node(map) is the map the script’s Map row picked, halls, as the calls take it.

set_tile over a scene tile

Painting #60 over a cracked block’s cell takes the block away: its node goes, and its farewell runs.

1. Press F5, walk him east to the cracked wall until it stops him, and press E.

Two gates

1. Press F5 again to stop. Select halls, and drag artifacts/gate.artifact from Assets into the Viewport: a copy of the gate lands where you drop it. Type its Position 2272, 0.
2. In the Inspector’s Name row, rename it gate-1. Select its lever and rename it gate-1-lever, and its door, gate-1-door.
3. Select gate-1 itself, not its door, and drop gate.artifact again. Type its Position 2768, 0, and rename it and its two gate-2, gate-2-lever and gate-2-door. Press Ctrl+S.

A drop

An artifact dragged from Assets into the Viewport makes a copy of it where it lands. The copy goes into the selected node’s parent, at the head of its list: each gate lands in crypt, and the second over the first.

A member renamed, an override

A copy’s nodes follow the artifact, but a name typed in the Inspector’s Name row is the copy’s own, an override, and so is a Position typed: the Hierarchy marks each with a dot after its name. A member renamed in the Hierarchy instead, its row double-clicked, keeps its name the same way.

1. Press F5, walk him east, strike the cracked wall down with E, and walk on to gate-1’s lever. Press E there.

The tower door

1. Press F5 again to stop. Select crypt, press + Add node and choose Sprite: the menu opens on Add child of crypt. Rename it tower-lever, type its Position 3328, 0, and build it as every lever, its Signal’s To keyhole.
2. Double-click keyhole.rgs in Assets, replace everything in it with the script below, and press Ctrl+S. Click the Viewport tab.
3. Select keyhole: its Keyhole has a Map row now, empty. Click it and choose halls. Press Ctrl+S.

/// The keyhole in the tower's door. While the pilgrim stands before the
/// door he peers through it, and the bell beyond shows in the keyhole's
/// shape. When he steps away, the keyhole is only a keyhole again. When the
/// tower lever is pulled, the door is taken away, and with it the keyhole.
component Keyhole : Area {
    /// The crypt's tilemap, whose ground layer holds the door.
    #[node_path]
    map: i32 = 0,

    fn on_enter(other: NodeId) {
        // Something has come to the door. Only the pilgrim, who is in the
        // group pilgrim, peers through, and only while the door is there:
        // while the cell the keyhole is in still holds the keyhole's planks,
        // tile 63. The keyhole hangs from the cell's foot, so its cell is the
        // one 8 above it.
        let cell = cell_at(node(map), position() - vec2(0.0, 8.0));
        if in_group(other, "pilgrim") && tile_at(node(map), "ground", cell) == 63 {
            // The keyhole's mask is switched on, so what lies behind the
            // door shows in its shape.
            set_flag("SpriteMaskComponent", "enabled", true);
        }
    }

    fn on_exit(other: NodeId) {
        // The pilgrim steps back from the door: the mask is switched off,
        // and the bell is hidden again.
        if in_group(other, "pilgrim") {
            set_flag("SpriteMaskComponent", "enabled", false);
        }
    }

    fn loop() {
        // The tower lever's Signal sends pulled here. Heard, the door's six
        // cells are cleared from the ground layer: the keyhole's cell and the
        // one beside it, east, on the keyhole's row and the rows above and
        // below it. The keyhole is switched off, for there is nothing left
        // to peer through.
        if heard("pulled") {
            let keyhole = cell_at(node(map), position() - vec2(0.0, 8.0));
            for row in -1..2 {
                for column in 0..2 {
                    clear_tile(node(map), "ground", keyhole + vec2(column, row));
                }
            }
            set_flag("SpriteMaskComponent", "enabled", false);
        }
    }
}

#[node_path] and map

A field the Inspector shows as a node picker, Map: the map whose cells the keyhole reads and clears. Nothing picked is 0, nobody.

The keyhole’s cell

The keyhole hangs from its cell’s foot, so its cell is the one 8 above its node. On entering, it switches on only while that cell still holds #63.

heard in loop()

True on the step the tower lever’s pulled reaches the keyhole: then the door’s six cells, the keyhole’s, the one east of it, and those above and below both, are cleared from ground, and the mask is switched off.

1. Press F5 and walk him east, striking the wall and throwing each gate’s lever as before, to the tower lever at the door. Press E there.

1. Press F5 again to stop.

The levers and what they work

Check it works