# 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):

```text
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.

```rust
#[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.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `center` | array | `[0, 0]` |  |  |
| `radius` | number | `139` | 1–5000 | Loot and chests are laid within this radius of center. |
| `items` | integer | `96` | 0–1000 | Pick-ups laid on the ground when the game starts. |
| `chests` | integer | `12` | 0–200 | Chests laid when the game starts. |
| `chestItems` | integer | `3` | 1–12 | Pick-ups a chest throws out. |
| `spacing` | number | `2.4` | 0–50 | Least distance between two things laid (best effort). |
| `openLabel` | string | `"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.