Ground loot and chests

Scatters loot over the map when the game starts and places chests to open: items are drawn from a weighted loot table at random places within a radius, and a chest throws a few items around it when opened.

Source: module-kits:kits/loot_ground/usage/en.mdView Markdown source

Also read offline — CLI: grip-forge docs loot-groundMCP tool: gripforge_docs { "topic": "loot-ground" }

Ground loot and chests (loot.ground) #

What it is for #

Scatters loot over the map when the game starts and places chests to open: items are drawn from a weighted loot table at random places within a radius, and a chest throws a few items around it when opened.

It needs 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: "loot.ground" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "loot.ground",
                              config: { "center": [0, 0], "radius": 139 } }

First example #

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

#[test]
fn the_first_tick_scatters_the_default_chests_and_items() {
    let mut s = session(json!({}), table());
    step(&mut s, 1);
    assert_eq!(of_kind(&s, "loot_chest").len(), 12);
    assert_eq!(of_kind(&s, "loot").len(), 96);
    let n = call(&mut s, SVC, "chests", json!([])).unwrap();
    assert_eq!(n.as_array().unwrap().len(), 12);
    let told = s
        .host
        .recorded
        .iter()
        .find(|e| e.topic == "loot.scattered")
        .unwrap();
    assert_eq!(told.payload["items"], 96);
    assert_eq!(told.payload["chests"], 12);
    // Once only.
    step(&mut s, 5);
    assert_eq!(of_kind(&s, "loot").len(), 96);
}

Settings and defaults #

Descriptions come from the kit manifest and stay in English.

SettingTypeDefaultRange or valuesMeaning
centerarray[0, 0]
radiusnumber1391–5000Loot and chests are laid within this radius of center.
itemsinteger960–1000Pick-ups laid on the ground when the game starts.
chestsinteger120–200Chests laid when the game starts.
chestItemsinteger31–12Pick-ups a chest throws out.
spacingnumber2.40–50Least distance between two things laid (best effort).
openLabelstring"Open chest"

Services, events, variables #

  • Service loot.basic: chests() → [{ entity, opened }], open(chest) → the pick-ups thrown out, scatter(n?) → pick-ups laid.
  • Events emitted:
    • loot.scattered (items, chests) — The loot of the map is laid.
    • loot.opened (chest, items)
  • Events listened to: interaction.requested
  • Verbs of the scripting layer:
    • loot_open (action) — Open a chest now.

Hooks and modding #

  • Hooks (a game or a mod can intercept them):
    • loot.drop (fields a tap may change: item, count; cancellable) — A pick-up is about to be laid at x, z (the scatter of the map or a chest opened).
    • loot.open (cancellable) — A chest is about to be opened (by the player through interact, or open()).
  • Moddable settings: center, radius, items, chests, chestItems, spacing, openLabel
  • Moddable collections: loot_table

Engines #

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

Versions #

Kit version 1.0.0.