# Flashlight (light.flashlight)

## What it is for

Gives the player a flashlight to switch on and off: a beam that lights what it points at, a battery that drains while it is on, batteries to find in the world and a flicker when it runs low.

It needs `input.actions`, `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: "light.flashlight" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "light.flashlight",
                              config: { "item": "", "batteryItem": "battery" } }
```

## First example

The kit has no dedicated test yet; this installs it and sets two of its settings to their defaults.

```text
gripforge_gamekit_install   { project_id: "gkp_…", id: "light.flashlight" }
gripforge_gamekit_configure { project_id: "gkp_…", id: "light.flashlight",
                              config: { "item": "", "batteryItem": "battery" } }
```

## Settings and defaults

Descriptions come from the kit manifest and stay in English.

| Setting | Type | Default | Range or values | Meaning |
|---|---|---|---|---|
| `item` | string | `""` |  | Item the player must hold to have the flashlight; empty: always carried. |
| `batteryItem` | string | `"battery"` |  | Item that recharges it (picked up in the world, used from the bag or swapped in when empty). |
| `batterySeconds` | number | `120` | 1–36000 | Seconds of light from a full battery. |
| `batteryCharge` | number | `1` | 0–1 | Charge one battery brings (added to what is left, capped at 1); 1: a battery refills it. |
| `startCharge` | number | `1` | 0–1 |  |
| `autoSwap` | boolean | `true` |  | When the battery dies and the bag holds a battery, it is swapped in at once. |
| `lowAt` | number | `0.2` | 0–1 | Below this charge the light flickers, more and more. |
| `range` | number | `14` | 1–100 |  |
| `angle` | number | `28` | 5–85 | Half-angle of the beam (degrees). |
| `intensity` | number | `3` | 0–5000 |  |
| `color` | string | `"#fff1d6"` |  |  |
| `glow` | number | `0.6` | 0–1 | Light level on the player while it is lit: how visible a lit flashlight makes them. |
| `beam` | number | `0.8` | 0–1 | Light level at the source of the beam, fading to 0 at its range. |
| `height` | number | `1.4` | 0–3 | Height of the lamp above the feet. |

## Services, events, variables

- Service `light.flashlight`: on(), lit() (on and not flickering out), toggle(on?) → boolean, charge() 0–1, setCharge(v), owned(), reload() → boolean (one battery item), batteries(), lightAt(point) → 0–1.
- Events emitted:
  - `flashlight.toggled` (`on`)
  - `flashlight.low` (`charge`) — The charge fell under lowAt: it starts flickering.
  - `flashlight.empty` — The battery died with no battery to swap in: the light went out.
  - `flashlight.recharged` (`charge`, `batteries`, `source`) — A battery was put in.
  - `flashlight.refused` (`on`, `reason`) — A tap of the hook flashlight.toggle refused the switch (on: what was asked); the light stays as it was.
- Events listened to: `inventory.used`
- Variables:
  - `flashlight.on` (boolean) — Flashlight on
  - `flashlight.battery` (number) — Battery (%)
  - `flashlight.batteries` (number) — Spare batteries
  - `flashlight.flicker` (boolean) — Flickering out now
  - `flashlight.owned` (boolean) — Has the flashlight
- Verbs of the scripting layer:
  - `set_flashlight` (action) — Switch the flashlight on or off.
  - `charge_flashlight` (action) — Set the battery charge (0–1).
  - `flashlight_on` (condition) — The flashlight is on.
- Input actions: `flashlight`

## Hooks and modding

- Hooks (a game or a mod can intercept them):
  - `flashlight.toggle` (cancellable) — The light is about to be switched on or off (on: the state asked) by the player (reason input), a set_flashlight action (action) or toggle() (service); charge is the battery (0–1), batteries the…
  - `flashlight.recharge` (fields a tap may change: `amount`; cancellable) — A battery is about to be put in: amount is the charge it brings (batteryCharge), added to charge and capped at 1; batteries counts the bag before the battery leaves it.
- Moddable settings: `item`, `batteryItem`, `batterySeconds`, `batteryCharge`, `startCharge`, `autoSwap`, `lowAt`, `range`, `angle`, `intensity`, `color`, `glow`, `beam`, `height`

## Engines

Declared targets: `web`, `rust`. `gripforge kit api light.flashlight` lists the exact settings and services of your version.

## Versions

Kit version 1.1.0.