# gizgame/rules

a game's rules as data. A map's file declares them (its "rules" field, read as Maps.fields; a mixin gives what maps share): counters, a haul of items to carry to one of the map's spots, sites that light, spawners, triggers, the HUD and the end's words. Every name of the vocabulary is a field of a typed record, so the schema refuses an unknown one at load (Maps.check); what data cannot say is a hook, an effect the game registers by name (Game.hook), and a hook that no game registered stops the load. There is no expression language: a value that changes is a Grows of a counter.

Each tick the rules run in this order: the counters' rates, the haul, the spawners, then the triggers in the file's order, each trigger's actions in their order. A touch trigger runs as the touch happens (Design.touched).

```gizlang
import * as Rules from "gizgame/rules";
```

## Types

### `Near`

```gizlang
type Near = { kind: string; spot?: string; sites?: bool; within: Grows; rate: f64; }
```

A rate that holds while an actor of KIND stands within WITHIN meters of spot SPOT, or with SITES of a lit site.

- `kind`: `string`
- `spot`: `_gizlang_sdk_core.Option<string>`
- `sites`: `_gizlang_sdk_core.Option<bool>`
- `within`: `M189.Grows`
- `rate`: `f64`

### `Counter`

```gizlang
type Counter = { name: string; start?: f64; min?: f64; max?: f64; rate?: Grows; near?: Near; far?: f64; best?: string; }
```

A number of the match, NAME: START at a new match, kept within MIN and MAX. It changes RATE a second (Grows), or NEAR's
rate while its actor stands near; a haul whose farthest item lies past FAR meters slows its rate as much (60: as far
as that). BEST keeps its "low" or "high" over matches (a record): the HUD shows it as NAME's best.

- `name`: `string`
- `start`: `_gizlang_sdk_core.Option<f64>`
- `min`: `_gizlang_sdk_core.Option<f64>`
- `max`: `_gizlang_sdk_core.Option<f64>`
- `rate`: `_gizlang_sdk_core.Option<M189.Grows>`
- `near`: `_gizlang_sdk_core.Option<M198.Near>`
- `far`: `_gizlang_sdk_core.Option<f64>`
- `best`: `_gizlang_sdk_core.Option<string>`

### `Item`

```gizlang
type Item = { name: string; at: Vec<f64>; thing?: string; size?: f64; }
```

An item of a haul: its NAME, where it waits (AT: x, z on the ground), and the THING it is drawn as, SIZE meters tall
(1); without a thing it is the haul's SHARD, named ECHO ("{0}": its name).

- `name`: `string`
- `at`: `Vec<f64>`
- `thing`: `_gizlang_sdk_core.Option<string>`
- `size`: `_gizlang_sdk_core.Option<f64>`

### `Haul`

```gizlang
type Haul = { by: string; items: Vec<Item>; to: string; count: string; take?: f64; reach?: f64; lift?: f64; shard?: string; echo?: string; spray?: string; color?: Vec<f64>; }
```

A haul: an actor of kind BY takes one of ITEMS within TAKE meters (2.4) while it carries none, and lays it within
REACH meters (4.5) of spot TO, where it rests; each item at rest adds one to counter COUNT. A waiting item floats LIFT
meters up (1.1) and SPRAY's particles rise from it in COLOR; they burst as an item is taken and as one rests.

- `by`: `string`
- `items`: `Vec<M198.Item>`
- `to`: `string`
- `count`: `string`
- `take`: `_gizlang_sdk_core.Option<f64>`
- `reach`: `_gizlang_sdk_core.Option<f64>`
- `lift`: `_gizlang_sdk_core.Option<f64>`
- `shard`: `_gizlang_sdk_core.Option<string>`
- `echo`: `_gizlang_sdk_core.Option<string>`
- `spray`: `_gizlang_sdk_core.Option<string>`
- `color`: `_gizlang_sdk_core.Option<Vec<f64>>`

### `Sites`

```gizlang
type Sites = { count?: i64; kind: string; size?: f64; lying?: bool; solid?: f64; lamp?: string; lampSize?: f64; ring?: Circle; scatter?: Vec<f64>; by?: string; reach?: f64; pay?: string; cost?: f64; lit?: string; flame?: Flame; light?: Vec<f64>; sparks?: string; spark?: Vec<f64>; }
```

Sites that light: COUNT of them (the haul's items), each thing KIND (SIZE meters, LYING, SOLID) with thing LAMP
(LAMP_SIZE) beside it. They stand on a RING about a spot, facing it, or SCATTER[0] to SCATTER[1] meters about the
middle, a little off even angles (by the map's number). An actor of kind BY lights one within REACH meters (2.8) while
value PAY is at least COST, which it pays; with no PAY, site N lights as the haul's item N rests. Counter LIT counts
the lit, and the triggers when "lit" run. A lit site burns: its FLAME, a LIGHT (r, g, b, range) over it, and SPARKS
of that particle kind in SPARK's color. A Near or a Shelter with SITES is near any lit one.

- `count`: `_gizlang_sdk_core.Option<i64>`
- `kind`: `string`
- `size`: `_gizlang_sdk_core.Option<f64>`
- `lying`: `_gizlang_sdk_core.Option<bool>`
- `solid`: `_gizlang_sdk_core.Option<f64>`
- `lamp`: `_gizlang_sdk_core.Option<string>`
- `lampSize`: `_gizlang_sdk_core.Option<f64>`
- `ring`: `_gizlang_sdk_core.Option<M198.Circle>`
- `scatter`: `_gizlang_sdk_core.Option<Vec<f64>>`
- `by`: `_gizlang_sdk_core.Option<string>`
- `reach`: `_gizlang_sdk_core.Option<f64>`
- `pay`: `_gizlang_sdk_core.Option<string>`
- `cost`: `_gizlang_sdk_core.Option<f64>`
- `lit`: `_gizlang_sdk_core.Option<string>`
- `flame`: `_gizlang_sdk_core.Option<M198.Flame>`
- `light`: `_gizlang_sdk_core.Option<Vec<f64>>`
- `sparks`: `_gizlang_sdk_core.Option<string>`
- `spark`: `_gizlang_sdk_core.Option<Vec<f64>>`

### `Circle`

```gizlang
type Circle = { spot: string; radius: f64; }
```

A circle of RADIUS meters about spot SPOT.

- `spot`: `string`
- `radius`: `f64`

### `Flame`

```gizlang
type Flame = { thing: string; at: f64; size: Vec<f64>; count?: i64; }
```

COUNT flames (1) of thing THING, AT meters over the site: the first SIZE (width, height) meters, each next a quarter
smaller and a third of the first's height higher.

- `thing`: `string`
- `at`: `f64`
- `size`: `Vec<f64>`
- `count`: `_gizlang_sdk_core.Option<i64>`

### `Glow`

```gizlang
type Glow = { kind: string; by: string; thing: string; lift?: f64; color?: Vec<f64>; }
```

A glow over the first actor of KIND: thing THING LIFT meters up, and a light of COLOR (r, g, b) that grows with value
BY (as an ember's warmth with the embers carried).

- `kind`: `string`
- `by`: `string`
- `thing`: `string`
- `lift`: `_gizlang_sdk_core.Option<f64>`
- `color`: `_gizlang_sdk_core.Option<Vec<f64>>`

### `Spawner`

```gizlang
type Spawner = { kind: string; count: Grows; within: f64; near: f64; from: string; clear?: f64; pace?: Grows; shelter?: Shelter; trail?: string; color?: Vec<f64>; }
```

A spawner: COUNT actors of KIND (Grows) live, each new one within WITHIN meters of an actor of kind FROM and at least
NEAR from it, CLEAR meters away from the shelter and the haul's items. Their brain's speed is PACE (Grows). With
SHELTER, they hunt no one while the FROM actor stands in it, and are pushed out of it. TRAIL particles of its kind
follow each, in COLOR.

- `kind`: `string`
- `count`: `M189.Grows`
- `within`: `f64`
- `near`: `f64`
- `from`: `string`
- `clear`: `_gizlang_sdk_core.Option<f64>`
- `pace`: `_gizlang_sdk_core.Option<M189.Grows>`
- `shelter`: `_gizlang_sdk_core.Option<M198.Shelter>`
- `trail`: `_gizlang_sdk_core.Option<string>`
- `color`: `_gizlang_sdk_core.Option<Vec<f64>>`

### `Shelter`

```gizlang
type Shelter = { spot?: string; sites?: bool; within: Grows; }
```

Where spawned actors may not go: within WITHIN meters (Grows) of spot SPOT, or with SITES of a lit site.

- `spot`: `_gizlang_sdk_core.Option<string>`
- `sites`: `_gizlang_sdk_core.Option<bool>`
- `within`: `M189.Grows`

### `Test`

```gizlang
type Test = { name: string; atLeast?: f64; atMost?: f64; all?: bool; }
```

A counter test: it holds when counter NAME is at least AT_LEAST, at most AT_MOST, or (ALL) at least the haul's item
count.

- `name`: `string`
- `atLeast`: `_gizlang_sdk_core.Option<f64>`
- `atMost`: `_gizlang_sdk_core.Option<f64>`
- `all`: `_gizlang_sdk_core.Option<bool>`

### `Touch`

```gizlang
type Touch = { kind: string; by: string; }
```

A touch: an actor of kind BY hurts one of kind KIND.

- `kind`: `string`
- `by`: `string`

### `When`

```gizlang
type When = { start?: bool; touch?: Touch; counter?: Test; taken?: bool; rested?: bool; lit?: bool; ended?: string; every?: f64; }
```

What starts a trigger, one of: START (play begins), TOUCH, COUNTER (once its test holds, then again only after it
stops holding), TAKEN and RESTED (an item of the haul), LIT (a site), ENDED ("won" or "lost": each tick after), EVERY seconds.
A take is a touch: TOUCH with BY the taker.

- `start`: `_gizlang_sdk_core.Option<bool>`
- `touch`: `_gizlang_sdk_core.Option<M198.Touch>`
- `counter`: `_gizlang_sdk_core.Option<M198.Test>`
- `taken`: `_gizlang_sdk_core.Option<bool>`
- `rested`: `_gizlang_sdk_core.Option<bool>`
- `lit`: `_gizlang_sdk_core.Option<bool>`
- `ended`: `_gizlang_sdk_core.Option<string>`
- `every`: `_gizlang_sdk_core.Option<f64>`

### `Change`

```gizlang
type Change = { name: string; add?: f64; to?: f64; }
```

A change of counter NAME: ADD to it, or SET it to TO.

- `name`: `string`
- `add`: `_gizlang_sdk_core.Option<f64>`
- `to`: `_gizlang_sdk_core.Option<f64>`

### `Despawn`

```gizlang
type Despawn = { kind: string; rate?: f64; burst?: Burst; color?: Vec<f64>; }
```

Actors of KIND go out, each at RATE a second (none: at once), each in a BURST of COLOR.

- `kind`: `string`
- `rate`: `_gizlang_sdk_core.Option<f64>`
- `burst`: `_gizlang_sdk_core.Option<M189.Burst>`
- `color`: `_gizlang_sdk_core.Option<Vec<f64>>`

### `Do`

```gizlang
type Do = { cues?: Vec<Cue>; on?: string; change?: Change; end?: string; drop?: bool; despawn?: Despawn; banner?: f64; play?: string; gone?: bool; record?: string; hook?: string; }
```

An action, one of: CUES on the trigger's subject (the hurt one, the carrier, the first actor of kind ON), a counter
CHANGE, END the game "won" or "lost", DROP the carried item back where it waited, DESPAWN, the BANNER for its seconds,
PLAY a sound, the SUBJECT gone (GONE), a RECORD of counter's best, or the game's HOOK by name.

- `cues`: `_gizlang_sdk_core.Option<Vec<M189.Cue>>`
- `on`: `_gizlang_sdk_core.Option<string>`
- `change`: `_gizlang_sdk_core.Option<M198.Change>`
- `end`: `_gizlang_sdk_core.Option<string>`
- `drop`: `_gizlang_sdk_core.Option<bool>`
- `despawn`: `_gizlang_sdk_core.Option<M198.Despawn>`
- `banner`: `_gizlang_sdk_core.Option<f64>`
- `play`: `_gizlang_sdk_core.Option<string>`
- `gone`: `_gizlang_sdk_core.Option<bool>`
- `record`: `_gizlang_sdk_core.Option<string>`
- `hook`: `_gizlang_sdk_core.Option<string>`

### `Trigger`

```gizlang
type Trigger = { name: string; when: When; do: Vec<Do>; }
```

A trigger: when WHEN, its DO in order.

- `name`: `string`
- `when`: `M198.When`
- `do`: `Vec<M198.Do>`

### `Show`

```gizlang
type Show = { line?: Line; meter?: Gauge; banner?: Banner; rings?: bool; score?: bool; wave?: bool; best?: bool; lives?: Lives; crosshair?: bool; markers?: f64; sites?: bool; }
```

A HUD widget, one of: a LINE at a corner ("left" or "right", ROW) of TEXT (a template), a METER of a counter, the
BANNER, RINGS over the waiting items and the goal, the SCORE and its combo, the WAVE, the BEST score, the LIVES, a
CROSSHAIR, MARKERS over the actors (their lift), and rings over the unlit SITES. A template reads "{NAME}" as a counter's value, "{NAME:clock}" as
minutes and seconds, "{NAME:best}" its best, and the words "{map}", "{about}", "{items}", "{carried}" (the item
carried) and "{last}" (the last at rest); IF names a counter ("NAME", or "NAME:best") that must not be 0 for the line
to show.

- `line`: `_gizlang_sdk_core.Option<M198.Line>`
- `meter`: `_gizlang_sdk_core.Option<M198.Gauge>`
- `banner`: `_gizlang_sdk_core.Option<M198.Banner>`
- `rings`: `_gizlang_sdk_core.Option<bool>`
- `score`: `_gizlang_sdk_core.Option<bool>`
- `wave`: `_gizlang_sdk_core.Option<bool>`
- `best`: `_gizlang_sdk_core.Option<bool>`
- `lives`: `_gizlang_sdk_core.Option<M198.Lives>`
- `crosshair`: `_gizlang_sdk_core.Option<bool>`
- `markers`: `_gizlang_sdk_core.Option<f64>`
- `sites`: `_gizlang_sdk_core.Option<bool>`

### `Lives`

```gizlang
type Lives = { kind: string; icon?: string; }
```

The lives left: one ICON each for the hits of the actor of KIND.

- `kind`: `string`
- `icon`: `_gizlang_sdk_core.Option<string>`

### `Line`

```gizlang
type Line = { where: string; row: i64; text: string; size?: f64; color?: Vec<f64>; if?: string; }
```

A line of text: TEXT (a template) at row ROW of the side WHERE ("left" or "right"), SIZE high, of COLOR, shown
only while the value IF names is above 0.

- `where`: `string`
- `row`: `i64`
- `text`: `string`
- `size`: `_gizlang_sdk_core.Option<f64>`
- `color`: `_gizlang_sdk_core.Option<Vec<f64>>`
- `if`: `_gizlang_sdk_core.Option<string>`

### `Gauge`

```gizlang
type Gauge = { name: string; label: string; full?: Vec<f64>; low?: Vec<f64>; }
```

A meter of counter NAME over its max, with LABEL and colors FULL and LOW.

- `name`: `string`
- `label`: `string`
- `full`: `_gizlang_sdk_core.Option<Vec<f64>>`
- `low`: `_gizlang_sdk_core.Option<Vec<f64>>`

### `Banner`

```gizlang
type Banner = { text?: string; under?: string; first?: string; firstUnder?: string; zero?: string; }
```

The banner: TEXT and UNDER, or FIRST and FIRST_UNDER before any item rests (with ZERO, while that value is 0); with
no TEXT, the match's (banner).

- `text`: `_gizlang_sdk_core.Option<string>`
- `under`: `_gizlang_sdk_core.Option<string>`
- `first`: `_gizlang_sdk_core.Option<string>`
- `firstUnder`: `_gizlang_sdk_core.Option<string>`
- `zero`: `_gizlang_sdk_core.Option<string>`

### `Words`

```gizlang
type Words = { won: string; lost: string; wonLine?: string; lostLine?: string; }
```

The words of the end: WON and LOST, then the line under them, WON_LINE or LOST_LINE (templates).

- `won`: `string`
- `lost`: `string`
- `wonLine`: `_gizlang_sdk_core.Option<string>`
- `lostLine`: `_gizlang_sdk_core.Option<string>`

### `Where`

```gizlang
type Where = { edges?: Edges; scatter?: Scattered; spot?: string; }
```

Where an actor enters, one of: the arena's EDGES, SCATTERed about an actor, or at a SPOT.

- `edges`: `_gizlang_sdk_core.Option<M198.Edges>`
- `scatter`: `_gizlang_sdk_core.Option<M198.Scattered>`
- `spot`: `_gizlang_sdk_core.Option<string>`

### `Edges`

```gizlang
type Edges = { away?: string; clear?: f64; spread?: f64; }
```

At the 2D arena's edges, at least CLEAR units from actors of kind AWAY, heading in within SPREAD radians (edges).

- `away`: `_gizlang_sdk_core.Option<string>`
- `clear`: `_gizlang_sdk_core.Option<f64>`
- `spread`: `_gizlang_sdk_core.Option<f64>`

### `Scattered`

```gizlang
type Scattered = { within: f64; from?: string; near?: f64; above?: f64; }
```

Within WITHIN meters of an actor of kind FROM, at least NEAR from it (scatter), only where the land stands more
than ABOVE meters high (over a sea).

- `within`: `f64`
- `from`: `_gizlang_sdk_core.Option<string>`
- `near`: `_gizlang_sdk_core.Option<f64>`
- `above`: `_gizlang_sdk_core.Option<f64>`

### `Wave`

```gizlang
type Wave = { kind: string; count: Grows; at: Where; clear?: string; first?: f64; rest?: f64; speedup?: f64; sound?: string; }
```

Waves of KIND: COUNT of them (Grows; by "wave": the wave's number) AT each wave, once its team (or CLEAR) is gone;
the first after FIRST seconds, each next REST after; SPEEDUP adds to every drift each wave; SOUND sounds.

- `kind`: `string`
- `count`: `M189.Grows`
- `at`: `M198.Where`
- `clear`: `_gizlang_sdk_core.Option<string>`
- `first`: `_gizlang_sdk_core.Option<f64>`
- `rest`: `_gizlang_sdk_core.Option<f64>`
- `speedup`: `_gizlang_sdk_core.Option<f64>`
- `sound`: `_gizlang_sdk_core.Option<string>`

### `Kin`

```gizlang
type Kin = { kind: string; count: Grows; at: Where; }
```

Actors of KIND kept at COUNT (Grows) while the match plays, each new one AT.

- `kind`: `string`
- `count`: `M189.Grows`
- `at`: `M198.Where`

### `Rules`

```gizlang
type Rules = { hint?: string; counters?: Vec<Counter>; haul?: Haul; spawners?: Vec<Spawner>; sites?: Sites; glow?: Glow; waves?: Wave; keeps?: Vec<Kin>; match?: Bout; triggers?: Vec<Trigger>; hud?: Vec<Show>; words?: Words; }
```

A map's rules, as the type says each part: its HINT (the banner's line at the start, "{hint}"). A world file's rules
hold for each map whose file has none. A spot the rules name is one of the map's spots (Map3D spots).

- `hint`: `_gizlang_sdk_core.Option<string>`
- `counters`: `_gizlang_sdk_core.Option<Vec<M198.Counter>>`
- `haul`: `_gizlang_sdk_core.Option<M198.Haul>`
- `spawners`: `_gizlang_sdk_core.Option<Vec<M198.Spawner>>`
- `sites`: `_gizlang_sdk_core.Option<M198.Sites>`
- `glow`: `_gizlang_sdk_core.Option<M198.Glow>`
- `waves`: `_gizlang_sdk_core.Option<M198.Wave>`
- `keeps`: `_gizlang_sdk_core.Option<Vec<M198.Kin>>`
- `match`: `_gizlang_sdk_core.Option<M189.Bout>`
- `triggers`: `_gizlang_sdk_core.Option<Vec<M198.Trigger>>`
- `hud`: `_gizlang_sdk_core.Option<Vec<M198.Show>>`
- `words`: `_gizlang_sdk_core.Option<M198.Words>`

### `Fields`

```gizlang
type Fields = { rules?: Rules; }
```

What a map's file holds of rules: a game's own fields (Game.world takes their schema, Json.schema<Fields>).

- `rules`: `_gizlang_sdk_core.Option<M198.Rules>`

## Functions

### `rulesOf`

```gizlang
function rulesOf(game: Game): Rules | undefined throws string
```

The rules of the map GAME is on: none on a map walked freely.

Effects: fail, read, write, console, io, alloc.

### `bestOf`

```gizlang
function bestOf(game: Game, name: string): f64 throws string
```

The best kept of counter NAME (0: none yet).

Effects: fail, read, write, console, io, alloc.

### `spotOf`

```gizlang
function spotOf(game: Game, name: string): Point3 throws string
```

The map's spot NAME (the first of its spots), on the ground.

Effects: fail, read, write, console, io, alloc.

### `items`

```gizlang
function items(game: Game): Vec<Item> throws string
```

The items of the map's haul.

Effects: fail, read, write, console, io, alloc.

### `nameOf`

```gizlang
function nameOf(game: Game, n: i64): string throws string
```

The name of item N, said in the game's language: its own, or its shard's echo.

Effects: fail, read, write, console, io, alloc.

### `carried`

```gizlang
function carried(game: Game): i64 throws string
```

The item carried now (-1: none).

Effects: fail, read, write, console, io, alloc.

### `told`

```gizlang
function told(game: Game, text: string): string throws string
```

TEXT with its "{...}" words read (a template of the HUD and the end's words).

Effects: fail, read, write, console, io, alloc.

### `ruled`

```gizlang
function ruled(game: Game, kinds: Vec<string> = [], given?: Rules): Game
```

GAME with the rules of each map's file: the counters, the haul, the spawners and the triggers, its end's words, and
the scene's sites, items and HUD (scene). On a map with no rules none of it runs. KINDS names every kind a spawner of
any map may make, so their brains take its pace and shelter. GIVEN are the rules as a value, as a program writes them
in Gizlang: they hold for each map whose files give none.

Effects: fail, read, write, console, io, alloc.

### `scene`

```gizlang
function scene(game: Game): (map: i64, data: Map3D) => Scene3D throws string
```

The worlds of GAME's maps with their rules (Maps.charted): a map's file, and on a map with rules its sites,
items and HUD; a map without them shows the banner.

Effects: fail, alloc.

### `hud`

```gizlang
function hud(game: Game): Widget
```

The HUD of the rules of the map GAME is on, as one widget (a 2D game's Stage2D hud; a 3D one's is its scene's).

Effects: fail, alloc.

