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).
import * as Rules from "gizgame/rules";Types
Near
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:stringspot:_gizlang_sdk_core.Option<string>sites:_gizlang_sdk_core.Option<bool>within:M189.Growsrate:f64
Counter
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:stringstart:_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
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:stringat:Vec<f64>thing:_gizlang_sdk_core.Option<string>size:_gizlang_sdk_core.Option<f64>
Haul
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:stringitems:Vec<M198.Item>to:stringcount:stringtake:_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
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:stringsize:_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
type Circle = { spot: string; radius: f64; }A circle of RADIUS meters about spot SPOT.
spot:stringradius:f64
Flame
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:stringat:f64size:Vec<f64>count:_gizlang_sdk_core.Option<i64>
Glow
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:stringby:stringthing:stringlift:_gizlang_sdk_core.Option<f64>color:_gizlang_sdk_core.Option<Vec<f64>>
Spawner
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:stringcount:M189.Growswithin:f64near:f64from:stringclear:_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
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
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:stringatLeast:_gizlang_sdk_core.Option<f64>atMost:_gizlang_sdk_core.Option<f64>all:_gizlang_sdk_core.Option<bool>
Touch
type Touch = { kind: string; by: string; }A touch: an actor of kind BY hurts one of kind KIND.
kind:stringby:string
When
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
type Change = { name: string; add?: f64; to?: f64; }A change of counter NAME: ADD to it, or SET it to TO.
name:stringadd:_gizlang_sdk_core.Option<f64>to:_gizlang_sdk_core.Option<f64>
Despawn
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:stringrate:_gizlang_sdk_core.Option<f64>burst:_gizlang_sdk_core.Option<M189.Burst>color:_gizlang_sdk_core.Option<Vec<f64>>
Do
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
type Trigger = { name: string; when: When; do: Vec<Do>; }A trigger: when WHEN, its DO in order.
name:stringwhen:M198.Whendo:Vec<M198.Do>
Show
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
type Lives = { kind: string; icon?: string; }The lives left: one ICON each for the hits of the actor of KIND.
kind:stringicon:_gizlang_sdk_core.Option<string>
Line
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:stringrow:i64text:stringsize:_gizlang_sdk_core.Option<f64>color:_gizlang_sdk_core.Option<Vec<f64>>if:_gizlang_sdk_core.Option<string>
Gauge
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:stringlabel:stringfull:_gizlang_sdk_core.Option<Vec<f64>>low:_gizlang_sdk_core.Option<Vec<f64>>
Banner
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
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:stringlost:stringwonLine:_gizlang_sdk_core.Option<string>lostLine:_gizlang_sdk_core.Option<string>
Where
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
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
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:f64from:_gizlang_sdk_core.Option<string>near:_gizlang_sdk_core.Option<f64>above:_gizlang_sdk_core.Option<f64>
Wave
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:stringcount:M189.Growsat:M198.Whereclear:_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
type Kin = { kind: string; count: Grows; at: Where; }Actors of KIND kept at COUNT (Grows) while the match plays, each new one AT.
kind:stringcount:M189.Growsat:M198.Where
Rules
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
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
function rulesOf(game: Game): Rules | undefined throws stringThe rules of the map GAME is on: none on a map walked freely.
Effects: fail, read, write, console, io, alloc.
bestOf
function bestOf(game: Game, name: string): f64 throws stringThe best kept of counter NAME (0: none yet).
Effects: fail, read, write, console, io, alloc.
spotOf
function spotOf(game: Game, name: string): Point3 throws stringThe map's spot NAME (the first of its spots), on the ground.
Effects: fail, read, write, console, io, alloc.
items
function items(game: Game): Vec<Item> throws stringThe items of the map's haul.
Effects: fail, read, write, console, io, alloc.
nameOf
function nameOf(game: Game, n: i64): string throws stringThe 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
function carried(game: Game): i64 throws stringThe item carried now (-1: none).
Effects: fail, read, write, console, io, alloc.
told
function told(game: Game, text: string): string throws stringTEXT with its "{...}" words read (a template of the HUD and the end's words).
Effects: fail, read, write, console, io, alloc.
ruled
function ruled(game: Game, kinds: Vec<string> = [], given?: Rules): GameGAME 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
function scene(game: Game): (map: i64, data: Map3D) => Scene3D throws stringThe 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
function hud(game: Game): WidgetThe 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.