Tutorials · Worlds and Levels · Chapter 11

In the dark

When to reach for a Sprite Mask

The dark

1. Double-click scenes/crypt.ron in Assets. Select camera, and in its Camera type Background as the table below gives it. Press Ctrl+S.

The Camera’s Background

The colour the view is cleared to before anything is drawn, typed in linear light as every colour is. In a lit room it is drawn under the room’s ambient light, as the walls are.

The crypt’s east

1. Select halls and click the Tilemap tab. Click ground’s row, then the stone row in the Terrains band: it lights, armed.
2. In the Tools band, set Size to 2. With Erase, drag down the halls’ east wall from cell 100, -12 to 100, -2: the eraser clears columns 100 and 101 from row -12 to -1, and lays the floor and the ceiling it leaves again with their edges.
3. Set Size in the Tools band back to 1.
4. With Rect, lay the rest from the table below, each from one corner cell to the other. The stair is three Rects: one cell, then a column of two, then a block three high.

1. Click #47 in the picker and press Set in the Variety band. Click #49, press Set again, then Add #49; do the same for #50 and #51. Type 7 in Seed.
2. With Fill, click the ceiling at cell 100, -15, then the floor at 220, -2, the stair’s middle row, which joins it.

1. Click #62, the planks, in the picker: picking a tile lets go of the set, and the brush is back on one tile. With Rect, fill the door’s gap, from cell 210, -3 to 211, -1.
2. Click #63, the planks with the keyhole, and with Brush click cell 210, -2: the west column’s middle row, the side he comes to.
3. Click back’s row. With Pick, click the halls’ wet back wall at cell 99, -1: the picker holds #58. With Rect, lay it behind the opened wall, from 100, -12 to 101, -1.
4. Click #61, the dressed stone, and lay it behind the gallery, from 102, -12 to 131, -1.
5. With Pick, click the first hall’s back wall at cell 1, -12: #48. Lay it with a Rect behind each stretch in the table below. Press Ctrl+S.

1. Select crypt-bounds and press Fit to tilemap in its Confiner again. Press Ctrl+S.

The murals’ sheet

1. Double-click art/murals.png in Assets: the Sprite sheet tab opens on it. Pick 200% from the zoom menu at the tab’s foot to see it whole.

1. In the Grid band, type Cell 64 and 48, and leave Margin and Spacing at 0: three cells across, one a panel.
2. Click the first cell, the hut. Under Regions, type hut in the box beside Name it, and press Name it. Do the same for the second, vale, and the third, bell.

The lantern

1. In the crypt, select pilgrim, press + Add node and choose Sprite Mask: the menu opens on Add child of pilgrim. Rename it lantern.

1. Type lantern’s Position 8, -28: his raised hand.
2. In its SpriteMaskComponent, drag art/reveal.png from Assets onto Texture: the first row goes. Type Size 128, 128 and Alpha Cutoff 0.35, and set Sort Layer to Ground. Leave Anchor at 0.5, 0.5, Channel at 0 and Enabled ticked, as they come.
3. 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 lantern and press Enter. Click the Code tab, then lantern.rgs in its Scripts list, replace everything in it with the script below, and press Ctrl+S. Click the Viewport tab.
4. Drag lantern.rgs from Assets onto lantern’s Inspector: it adds Lantern. Press Ctrl+S.

/// The lantern the pilgrim holds up in the dark. Its light shows what is
/// painted on the walls near him, and it breathes: the light it throws
/// grows and shrinks, over and over, for as long as he carries it.
component Lantern {
    fn loop() {
        // Over a little more than a second the light grows, easing in and
        // out: a lower Alpha Cutoff counts more of the lantern's soft edge
        // as inside it, so more of the wall shows.
        await anneal_number("SpriteMaskComponent", "alpha_cutoff", 0.25, 1.2, .InOutSine);
        // Then it shrinks again, a little past where it began, and the loop
        // goes round once more.
        await anneal_number("SpriteMaskComponent", "alpha_cutoff", 0.45, 1.2, .InOutSine);
    }
}

The Sprite Mask’s Texture

The picture whose shape it writes. Only its alpha is read, never its colour; empty, it writes nothing, and the Problems tab says so.

The Sprite Mask’s Size and Anchor

How big its picture is laid, in world units, and where its node stands in it: 0, 0 the top left corner, 0.5, 0.5 the middle, as it comes. The lantern lays the 64-pixel reveal at 128, two units a pixel, centred on his hand. In the Viewport the anchor is a ring at the node, which its hover names Anchor: drag it with the Select tool, Q, to slide the picture about its node. Under the Move tool, W, the ring sits under the gizmo’s middle square, which takes the drag.

The Sprite Mask’s Channel

Which of the eight channels, 0 to 7, it writes. Two masks on one channel add up, so a room lit by three lanterns is one channel; masks that must keep apart, as the lantern and the keyhole below, take one each. 0 as it comes.

The Sprite Mask’s Alpha Cutoff

How opaque a pixel of its picture must be to count as inside: the soft edge is cut hard where its alpha crosses this. 0.5 as it comes. Laid at 128, the reveal’s alpha falls evenly from 1 at its middle to 0 at 64 units out, so 0.35 cuts a disc of radius (1 − 0.35) × 64, 41.6 units, about his hand. A higher cutoff, a smaller disc.

The Sprite Mask’s Sort Layer

Where it is drawn among the sprites, as a sprite’s Sort Layer is. A mask is drawn before the sprites on its own layer that read it, so it goes on theirs: the lantern on Ground, with the murals, though he is on Figures. On a later layer than its readers, it would come too late for them.

The Sprite Mask’s Enabled

Whether it writes its channel at all. Unticked, it writes nothing: a sprite reading it from the inside shows nowhere, and one reading it from the outside everywhere. Ticked as it comes; the keyhole below waits unticked, for a script to tick it.

component Lantern and loop

A script with no base: it goes on any node. loop() runs again each time it ends, for as long as the game runs.

anneal_number and await

Eases a number field of another component on this node towards a value, over the seconds it is given, along a curve: here the Sprite Mask’s alpha_cutoff, its Alpha Cutoff, to 0.25 over 1.2 seconds, then back to 0.45. await waits for each to finish before the next line, so the two take turns.

.InOutSine

A curve that starts slowly, speeds up, and slows again as it arrives: the light swells and settles, and never jumps.

The murals

1. Select crypt, press + Add node and choose Sprite: the menu opens on Add child of crypt. Rename it mural-1, and type its Position 1712, -48.
2. In its Sprite, drag art/murals.png onto Texture, type hut in Atlas Region, and type Size 64, 48, the region’s. Leave Anchor at 0.5, 0.5, and set Sort Layer to Ground.
3. Tick Mask: its Channel reads 0 and Inside is ticked, as ticking gives them. The lantern’s second row goes.
4. Select crypt again and make mural-2 the same way, at Position 1872, -48, showing vale; then, with crypt selected once more, mural-3 at Position 2032, -48, showing bell. Press Ctrl+S.

The Sprite’s Mask, Channel and Inside

Mask ticked makes the Sprite read a channel rather than draw everywhere. Channel is which, 0 to 7, 0 as ticking gives it. Inside, ticked as ticking gives it, draws the Sprite only where the channel is written; unticked, only where it is not. Each mural reads the lantern’s 0 from the inside, so it shows inside the lantern’s light and nowhere else.

What a mask clips

The sprites that read its channel, and nothing else. A tile never reads a mask: the gallery’s back wall is drawn whole round the lantern, and only the murals are cut.

1. With scenes/crypt.ron open, press F5: Play runs the open scene. Walk him east along the halls, jumping the pool and the pit with Space, into the gallery, and stop him under the second mural.

The keyhole and the bell

1. Select crypt, press + Add node and choose Sprite Mask. Rename it keyhole, and type its Position 3368, -16: the middle of the foot of the cell painted #63.
2. In its SpriteMaskComponent, drag art/keyhole.png onto Texture, type Size 8, 16 and Anchor 0.5, 1, set Sort Layer to Props, and untick Enabled. Leave Alpha Cutoff at 0.5.
3. Type its Channel 1.

1. Press Add component and choose AreaComponent. In its Shape, type Size 48, 48 and Offset -24, -8: x 3320 to 3368, y -48 to 0, the floor before the door.
2. In Assets, with Assets clicked in the path bar, click Create, choose New script, type keyhole and press Enter. Click the Code tab, then keyhole.rgs in its Scripts list, replace everything in it with the script below, and press Ctrl+S. Click the Viewport tab.
3. Drag keyhole.rgs from Assets onto keyhole’s Inspector: it adds Keyhole.

/// 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.
component Keyhole : Area {
    fn on_enter(other: NodeId) {
        // Something has come to the door. Only the pilgrim, who is in the
        // group pilgrim, peers through.
        if in_group(other, "pilgrim") {
            // 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);
        }
    }
}

component Keyhole : Area

A script with an Area base, as chapter 10’s waymark: on_enter runs when another Area comes into the keyhole’s, and on_exit when one leaves it, each with that one’s node as other. His body carries an Area of its own.

set_flag

Writes true or false onto another component on this node: here the Sprite Mask’s enabled, its Enabled, on while he stands at the door and off when he steps back.

in_group

Whether a node is in a group: only the pilgrim, in pilgrim, peers through.

1. Select keyhole, press + Add node and choose Sprite: the menu opens on Add child of keyhole. Rename it bell-view, and type its Position 0, -12: the middle of the keyhole’s round head, 3368, -28 in the world.
2. In its Sprite, drag art/bell.png onto Texture, type Size 8, 8, a quarter of the bell’s own, and set Sort Layer to Props. Tick Mask, type its Channel 1, and leave Inside ticked. The keyhole’s row goes.

1. Select crypt, press + Add node and choose Sprite. Rename it bell, and type its Position 3552, -128, over the landing. In its Sprite, drag art/bell.png onto Texture, type Size 32, 32, its own, and set Sort Layer to Props.
2. Select bell, press + Add node and choose Shape: the menu opens on Add child of bell. Rename it bell-rope, and type its Position 0, 16, the bell’s lip. In its Shape type Size 2, 64 and Anchor 0.5, 0, set Color to the signposts’ wood, as the table below gives it, and Sort Layer to Props. Leave Outline at 0.
3. Select bell again and add a second Shape, bell-chain, at Position 0, -16, the bell’s crown. Type Size 2, 80 and Anchor 0.5, 1, set Color as the table below gives it, and Sort Layer to Props. Leave Outline at 0. Press Ctrl+S.

The Shape’s Anchor

Where the node stands in the Shape, 0, 0 its top left corner: 0.5, 0 hangs the rope from the middle of its top edge, so it runs down from the lip; 0.5, 1 stands the chain on the middle of its foot, so it runs up from the crown.

1. Press F5 and walk him east, past the gallery and through the dark, to the tower door.

1. Press F5 again to stop.

The crypt’s east, in nodes

Check it works