Tutorials · Physics and Mechanisms · Chapter 9

Lifts and springs

The lift shaft

1. Select knight and set his Position to 131.333, 896: the lift shaft’s floor, where chapter 8’s climb leaves him. Press F5 to play from there, and F5 again to stop. Afterwards press Ctrl+Z until it reads 48, 1792 again, or type 48, 1792 back.
2. Select tower, click + Add node and choose Node. Rename it lift_shaft. Every node in this chapter goes under it.
3. In the strip under the Viewport, keep Collision, Bodies, Triggers and Forces ticked in the Gizmos menu, as in chapter 8; Triggers draws the lift’s Area. As on chapter 8’s page, the strips here leave Collision off, so the Colliders’ green outlines are on your screen and not in them, and only the lift’s strip has Triggers on.

A spring board

1. Select lift_shaft and add a Sprite, spring_coil, at Position 196, 896. Drag art/spring-coil.png onto Texture, and set Size to 16, 20, Anchor to 0.5, 1 and Sort Layer to 1.
2. Select lift_shaft and add a Node, spring_base, at Position 196, 896: on the floor, under the coil.
3. Select lift_shaft and add a Sprite, spring_board, at Position 196, 876, on the coil’s top. Drag art/spring-board.png onto Texture, and set Size to 40, 8, Anchor to 0.5, 1 and Sort Layer to 2.
4. Click Add component and choose CharacterBodyComponent: Size 40, 8, Driven By Script. Then a ColliderComponent: Size 40, 8, Offset 0, -4.
5. Click Add component and choose JointComponent. Set Kind to Spring, type spring_base into Target, and set Length to 25, Stiffness to 0.02 and Damping to 0.05. Anchor and Target Anchor stay 0, 0: the board’s feet and the base’s point.

Kind › Spring

The Joint’s Kind for a spring: it pulls its two ends toward Length apart, a share of the way each pass, set by Stiffness, where a Distance joint holds them exactly. Pressed or stretched, it gives, and pulls back: Unity’s Spring Joint 2D, Godot’s DampedSpringJoint2D.

Length

The Joint’s Length, on a Spring: the length it pulls back toward, in world units. The board’s 25 is 5 more than the coil: at its Stiffness, the board’s own weight squashes the spring 5, so in Play it rests where it is laid, on the coil.

Stiffness

The Joint’s Stiffness, from 0 to 1: the share of the way back to its Length a Spring pulls each pass, four passes a step. At 1 it would snap straight back; the board’s 0.02 is soft, so his weight presses it 4.5 lower, and a landing much further. A new Joint’s is 0.5, far too stiff for a dip to show. A Spring and a Target read it.

Damping

The Joint’s Damping, from 0 to 1: the share of the moving end’s speed taken off each pass, so 0.1 leaves about two-thirds of it each step. With none, the board would go on bobbing; the board’s 0.05, half what a new Joint has, lets it bob back once and settle. A Spring and a Target read it.

1. Set the knight’s Position to 131.333, 896 and press F5. Hold D: he walks up to the board’s side.
2. Press Space with D still held, and let go of D as he comes over the board. He lands on it, and it dips under him and comes to rest a little lower than it lay.
3. Press Space again: a jump straight up. He lands on the board, which dips far lower, bobs back up past where it rests under him, and settles again. To see each step of it, press Pause or F6 as he comes down, then Step or F7, and watch the Play bar’s step counter. Press F5 to stop, and Ctrl+Z back to 48, 1792.

A claw and its crate

1. Select lift_shaft and add a Sprite, claw, at Position 304, 718, its top under the ceiling. Drag art/claw.png onto Texture, and set Size to 36, 28 and Sort Layer to 3. Anchor stays 0.5, 0.5: it hangs from its middle.
2. Click Add component and choose CharacterBodyComponent: Size 24, 12, Driven By Script and Gravity 0.
3. Click Add component and choose JointComponent. Set Kind to Target, Target Point to 304, 718, where it hangs, and Stiffness and Damping both to 0.3.
4. Select lift_shaft and add a Sprite, shelf_a, at Position 304, 756: Texture scaffold-plank.png, Size 48, 8, and in its Draw mode fold Draw Mode Tiled and Tile Size 48, 8. Add a ColliderComponent with Size 48, 8.
5. Right-click shelf_a and choose Duplicate. Rename the copy shelf_b and set its Position to 480, 756.
6. Right-click crate_5 in the Hierarchy and choose Duplicate. Drag the copy onto lift_shaft, rename it crate_6, and set its Position to 304, 752: on the first shelf, under the claw.
7. With crate_6 selected, click Add component and choose JointComponent. Set Kind to Fixed, type claw into Target, set Target Anchor to 0, 30, and untick Enabled.

Kind › Target

The Joint’s Kind that ties a body to a point in the world rather than to a node: it pulls the body’s Anchor toward its Target Point each pass, by Stiffness. Its Target and Target Anchor are dim. Unity’s Target Joint 2D does the same.

Target Point

The Joint’s Target Point, which only a Target reads: where it pulls to, in world units, not from any node. The claw’s 304, 718 is where it hangs as saved; claw.rgs moves the point, and the claw follows.

Stiffness

The Joint’s Stiffness, on a Target: the share of the way to its point it pulls the claw each pass. At 0.3 the claw trails its moving point by under 2, and the crate’s weight barely sags it.

Damping

The Joint’s Damping, on a Target: the share of the claw’s speed taken off each pass. When the crate is gripped it swings up into the fingers and the two bob on the claw’s Target: at 0.3 they settle in 12 steps, against 17 with none. That bob is under a pixel, too small to see, so here Damping changes nothing you can watch; the gallery’s lamp, in chapter 14, is where it shows.

Kind › Fixed, and Enabled saved off

The crate’s own Joint, a weld to the claw, as chapter 8’s lantern has to the bob: Target Anchor 0, 30 holds the crate’s feet 30 under the claw’s middle, its top between the fingers. Saved with Enabled unticked, it holds nothing until a script ticks it. A node holds one Joint, and the claw’s is its Target, so the weld that carries the crate is the crate’s.

Gravity

The Character Body’s Gravity, on the claw: 0, so nothing but its joint holds it up or moves it. With gravity it would sag under its own weight as well as the crate’s.

1. In Assets, click Create, choose New script, type claw and press Enter. In the Code tab, replace everything in claw.rgs with the first script below, and press Ctrl+S. Make hook.rgs the same way, with the second.
2. Select claw, click Add component and choose Claw. Select crate_6, click Add component and choose Hook.
3. Select claw, click Add component and choose SignalComponent. Click the + beside Connections twice. Open [0]: Signal grip, To crate_6. Open [1]: Signal let_go, To crate_6. Press Ctrl+S.

/// The claw. The Target on this node pulls it toward its Target Point: this
/// walks that point along the rail, `from` one end `to` the other and back,
/// and tells the crate when to take hold and when to let go. Its Signal wires
/// `grip` and `let_go` to the crate.
component Claw {
    /// The end it starts from, over the first shelf.
    from: Vec2 = vec2(304.0, 718.0),
    /// The other end, over the second shelf.
    to: Vec2 = vec2(480.0, 718.0),
    /// Seconds it takes from one end to the other.
    #[suffix("s")]
    travel: f32 = 3.0,

    fn loop() {
        emit("grip");
        await wait(0.5);
        await anneal_point("JointComponent", "target_point", to, travel, .InOutSine);
        emit("let_go");
        await wait(1.0);
        emit("grip");
        await wait(0.5);
        await anneal_point("JointComponent", "target_point", from, travel, .InOutSine);
        emit("let_go");
        await wait(1.0);
    }
}

/// The crate's hook. The Fixed weld on this node hangs it from the claw; it
/// is off until the claw says `grip`, and off again when it says `let_go`.
component Hook {
    fn on_signal() {
        if heard("grip") {
            set_flag("JointComponent", "enabled", true);
        }
        if heard("let_go") {
            set_flag("JointComponent", "enabled", false);
        }
    }
}

From, To and Travel

The Claw’s three fields, drawn in the Inspector: the two ends of the rail, as vec2 points in the world, and the seconds from one to the other. #[suffix("s")] (attributes) prints the unit after Travel. From is the claw’s Target Point as saved, so it starts where it hangs.

loop with await

The claw’s loop waits as it goes: each await holds it on that line until the wait or the anneal is done, and then it carries on. While it waits it is not entered again; at its end, it starts again from the top. One time through is 9 seconds: grip, half a second, 3 seconds across, let go, a second, and the same back.

emit

Says grip or let_go to whoever the claw’s Signal wires it to, the crate, which hears it on the next step.

await wait

wait(0.5) holds the loop half a second of game time: the time the crate takes to swing up into the fingers and settle before the claw sets off.

anneal_point

Moves a pair of numbers on another component of this node to a new value over some seconds: here the Joint’s Target Point, to to in travel seconds. .InOutSine, an Easing, starts slow, runs, and slows into the end, so the crate is not jerked off the shelf. The script moves the point, never the claw.

component Hook

The crate’s script, with no base. On grip it ticks its own Joint’s Enabled with set_flag, and on let_go unticks it. heard is true on the step a name arrives.

1. Select lift_shaft and press F5. The game camera is on the knight, far below: move the pointer over the Viewport and press F to frame the whole shaft, the claw under its ceiling.
2. Watch the claw: it grips the crate and lifts it off the first shelf, carries it along to the second, lets go, and the crate drops onto the shelf. A second later it grips it again, carries it back and drops it on the first shelf. Then its script starts again from the top, for as long as the game runs. Press F5 to stop.

A piston lift

1. Select lift_shaft and add a Sprite, piston_shaft, at Position 568, 896. Drag art/piston-shaft.png onto Texture, and set Size to 8, 224, Anchor to 0.5, 1 and Sort Layer to -1; in its Draw mode fold, Draw Mode Tiled and Tile Size 8, 64. It reaches up to the upper hall’s floor.
2. Select lift_shaft and add a Node, piston_base, at Position 568, 910.
3. Select lift_shaft and add a Sprite, lift, at Position 568, 910. Drag art/piston-head.png onto Texture, and set Size to 48, 14, Anchor to 0.5, 1 and Sort Layer to 2. Its deck’s top lies flush with the floor.
4. Click Add component and choose CharacterBodyComponent: Size 48, 14, Driven By Script, Gravity 0. Then a ColliderComponent: Size 48, 8, Offset 0, -10, the deck.
5. Click Add component and choose JointComponent. Set Kind to Slider, type piston_base into Target, and set Axis to 0, -1. In the Limits fold tick Use Limits, leave Min at 0 and set Max to 224. In the Motor fold tick Use Motor, and set Speed to -60 and Max Step to 2.
6. Click Add component and choose AreaComponent. Open its Shape and set Size to 24, 30 and Offset to 0, -29: half the deck’s width, over it. Click the button beside Mask, untick World and tick Knight.

Kind › Slider

The Joint’s Kind for a rail: it holds its Anchor on a line through the Target’s point along Axis, with no end of its own, and lets it slide. Use Limits gives it ends; a motor drives it. Unity’s Slider Joint 2D, with its motor and its limits.

Axis

The Joint’s Axis, on a Slider: the way it runs, and the way its limits and motor count. 0, -1 is up, so the lift’s Min and Max are heights over its base and a positive Speed drives it up.

Use Limits, Min and Max

The Joint’s limits, on a Slider: how far along its Axis from its Target it may be. Min 0 is its foot, the deck flush with the lift shaft’s floor; Max 224 is the rise to the upper hall’s floor, where the deck is flush with that. The motor stops it at either end.

Use Motor

The Joint’s Use Motor, in its Motor fold: ticked, the Slider drives itself along its Axis at Speed, once a step. Only a Slider reads it, and a motor never drives past the limits: run into Min or Max, it stops there. It comes unticked.

Speed

The Joint’s Speed, the motor’s, in units a second along Axis: a negative one drives the other way. The lift’s -60 drives it down, so with nobody on it it stands parked at Min. lift.rgs turns it to 60 while he rides, 1 a step at 60 steps a second. A new Joint’s is 60.

Max Step

The Joint’s Max Step, in world units: the most the motor moves the body in one step, whatever Speed asks. The lift’s 2 is twice a step at its Speed, so it never holds the lift back; it is there for a Speed typed wrong, as the try-it below shows. A new Joint’s is 4.

1. In Assets, click Create, choose New script, type lift and press Enter. In the Code tab, replace everything in lift.rgs with the script below, and press Ctrl+S.
2. Select lift, click Add component and choose Lift. Press Ctrl+S.

/// The piston lift. With the knight on its deck it rises; with nobody on it,
/// it sinks back to the floor. The motor on its Joint does the moving, and
/// stops at the Joint's limits: this only turns it round, by the sign of the
/// motor's Speed.
component Lift : Area {
    /// How many things its Area notices on the deck.
    #[readonly]
    riders: i32 = 0,
    /// How fast it goes, up or down.
    #[suffix("u/s")]
    speed: f32 = 60.0,

    fn on_enter() {
        riders += 1;
        set_number("JointComponent", "motor_speed", speed);
    }

    fn on_exit() {
        riders -= 1;
        if riders == 0 {
            set_number("JointComponent", "motor_speed", -speed);
        }
    }
}

component Lift : Area

A script with an Area base, like chapter 8’s ring pull: it hears what comes onto the deck and goes off it. Its Riders counts them; its own speed field, drawn as Speed in u/s, is how fast to drive, 60.

set_number

Writes a number onto another component on this node: set_number("JointComponent", "motor_speed", speed) sets the Joint’s Speed to 60, up, when he comes on, and the last one off sets it to -60, down. The script never moves the lift. It only turns the motor round, and the motor and the limits do the rest.

1. Set the knight’s Position to 131.333, 896, then select lift, so the Inspector shows its Joint while the game runs, and press F5.
2. Hold D and Space together: a running jump that clears the spring board and lands him beyond it. Keep holding D, and let go as he comes to the middle of the deck.
3. The lift rises with him, and its Joint’s Speed has turned positive: up. It stops with its deck flush with the upper hall’s floor. Hold A: he walks off onto that floor, and the lift sinks back to the shaft’s floor. Press F5 to stop, and Ctrl+Z back to 48, 1792.

1. Select lift and type 6000 over its Joint’s Speed of -60: up, a hundred times what was meant.
2. Select lift_shaft and press F5. Move the pointer over the Viewport and press F to frame the shaft: the game camera is on the knight, far below. With nobody on it the motor drives the lift up at once, but only 2 a step, its Max Step, not 100, and it still stops at Max, in under two seconds. Press F5 to stop.
3. Select lift and set its Joint’s Speed back to -60.

The way up

1. Set the knight’s Position to 131.333, 896 and press F5.
2. Hold D and Space together: he runs, jumps clear over the spring board and lands beyond it. Keep D held and let go on the deck’s middle.
3. Ride it up. At the top, hold A: he walks off onto the upper hall’s floor, west of H5. Press F5 to stop, and Ctrl+Z back to 48, 1792.

The board, the claw and the lift

Check it works