Flashlight

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.

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

Also read offline — CLI: grip-forge docs light-flashlightMCP tool: gripforge_docs { "topic": "light-flashlight" }

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

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.

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.