Launch pad (launch.pad) #

What it is for #

Sends big one-shot projects from a pad, such as a rocket or an expedition: a launch is a document with a cost, a flight time and what it does on arrival, like changing a world counter or running actions.

It needs inventory.items, game.engine; installing it brings them in.

Turn it on #

Install the kit in a project, then change a setting (the values shown are its defaults):

gripforge_gamekit_install   { project_id: "gkp_…", id: "launch.pad" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "launch.pad",
                              config: { "padLabel": "Use {name}", "padReach": 6 } }

First example #

<!-- test: kits/game_engine/host/tests/launch_pad.rs::a_launch_is_paid_flies_and_acts_on_arrival --> This is the body of the passing test a_launch_is_paid_flies_and_acts_on_arrival; the helper functions it calls are defined at the top of the same test file.

#[test]
fn a_launch_is_paid_flies_and_acts_on_arrival() {
    let mut s = session();
    let pad = call(&mut s, L, "placePad", json!([[0, 0, 0]]));
    assert_eq!(
        call(&mut s, L, "launch", json!(["probe", pad]))["reason"],
        json!("cost")
    );
    call(&mut s, "inventory.items", "give", json!(["fuel", 5]));
    assert_eq!(
        call(&mut s, L, "launch", json!(["probe"]))["reason"],
        json!("pad")
    );
    assert_eq!(
        call(&mut s, L, "launch", json!(["probe", pad])),
        json!({ "ok": true })
    );
    assert_eq!(
        call(&mut s, "inventory.items", "count", json!(["fuel"])),
        json!(3)
    );
    // The craft is still climbing: the pad is busy.
    assert_eq!(
        call(&mut s, L, "launch", json!(["probe", pad]))["reason"],
        json!("busy")
    );
    assert_eq!(s.host.state.get("launch.flights"), Some(&json!(1)));
    let save = s.apply(&json!({ "op": "save" })).unwrap();
    assert_eq!(save["kits"][L]["flights"][0]["launch"], json!("probe"));
    s.apply(&json!({ "op": "reload" })).unwrap();
    let told = step(&mut s, 40);
    assert!(told.contains(&"launch.arrived".to_string()), "{told:?}");
    assert_eq!(call(&mut s, L, "launched", json!(["probe"])), json!(1));
    // The multiplier is held before the amount is pushed: 4 × 2.
    assert_eq!(
        call(&mut s, "world.stages", "value", json!(["oxygen"])),
        json!(8)
    );
    assert_eq!(s.host.state.get("launch.total"), Some(&json!(1)));
    assert_eq!(call(&mut s, L, "current", json!([])), Json::Null);
}

Settings and defaults #

Descriptions come from the kit manifest and stay in English.

Services, events, variables #

• Service launch.pad: launches(), launch(id, pad?) → { ok, reason? }, flights(), launched(id), open(pad) / close() / current(), unlock(id), unlocked(id), placePad(at, yaw?).
• Events emitted:
  • launch.started (launch, pad, craft, seconds) — The cost was taken and the craft lifts off.
  • launch.arrived (launch, count) — The flight ended: its effects apply.
  • launch.failed (launch, reason) — reason: unknown, locked, cost, busy, once, pad, or the reason of the tap of launch.start that cancelled it (default refused).
  • launch.unlocked (launch)
• Events listened to: interaction.requested, entity.spawned, game.phase
• Variables:
  • launch.open (boolean) — Launch screen open
  • launch.flights (number) — Crafts in flight
  • launch.total (number) — Launches arrived
• Verbs of the scripting layer:
  • start_launch (action) — Send a launch from a script: no cost, no pad needed.
  • unlock_launch (action) — Reveal a locked launch.
  • launched (condition) — At least count (1) launches of that kind have arrived.

Hooks and modding #

• Hooks (a game or a mod can intercept them):
  • launch.start (fields a tap may change: seconds; cancellable) — A launch is about to leave (launch(id, pad), the launch screen, start_launch): after the checks unknown, locked, once, pad, busy and cost, before the cost is taken.
  • launch.unlock (cancellable) — A locked launch is about to be revealed (unlock(id), unlock_launch).
• Moddable settings: padLabel, padReach, liftoffSeconds, liftoffHeight
• Moddable collections: launches
• Components: launch_pad

Engines #

Declared targets: web, rust. gripforge kit api launch.pad lists the exact settings and services of your version.

Versions #

Kit version 1.1.1.