# gizgame/view

how a Game is seen. Play binds a Game to its art and its drawing and is the surface program; a Picture is one frame's passes; Sprites packs images for 2D; a Hud lays text and bars over the picture in units of a 720-high screen; a Chase camera follows a pose; an Animator blends a rig's clips. Each reads the World and none changes it: the rules stay in the systems. Every piece is ordinary SDK drawing (gizlang/render, draw, meshdraw, gltf) that a game may use beside these or instead of them.

```gizlang
import * as View from "gizgame/view";
```

## Types

### `Program`

```gizlang
type Program = { initialize: (input: bytes) => bytes; frame: (input: bytes) => bytes; snapshot: (input: bytes) => bytes; restore: (input: bytes) => bytes; cues?: (input: bytes) => bytes; file?: (input: bytes) => bytes; net?: (input: bytes) => bytes; show?: (submit: (packet: bytes) => void) => void; }
```

A surface program: its exports, as a page's surface (app/components/src/surface.js) and a window (gizapp/play) call
them, each bytes to bytes. CUES is optional: the sounds a frame asks for. NET is optional, for a game played on a
server: NET(MESSAGE) takes a message of the server, and NET(b"") gives the next message to send (b"" none). The host
calls it before each frame.

- `initialize`: `(arg0: bytes) => bytes`
- `frame`: `(arg0: bytes) => bytes`
- `snapshot`: `(arg0: bytes) => bytes`
- `restore`: `(arg0: bytes) => bytes`
- `cues`: `_gizlang_sdk_core.Option<(arg0: bytes) => bytes>`
- `file`: `_gizlang_sdk_core.Option<(arg0: bytes) => bytes>`
- `net`: `_gizlang_sdk_core.Option<(arg0: bytes) => bytes>`
- `show`: `_gizlang_sdk_core.Option<(arg0: (arg0: bytes) => void) => void>` — The host's way to show a picture while a call still runs: the loading screen during the art's build.

### `Art`

```gizlang
type Art<A> = (game: Game, resources: Resources, screen: Screen) => A throws string
```

The art a game draws with: built once, at the first frame, from the files the host gave (Game.file).

### `Draw`

```gizlang
type Draw<A> = (picture: Picture, art: mut A) => void throws string
```

A game's drawing of one frame: its ART into PICTURE. ART is the view's own state from frame to frame (a camera, marks that fade); the game's state stays in the World.

### `Play`

```gizlang
class Play<A> { game: Game; resources: Resources = new Resources(); private build: Art<A>; private paint: Draw<A>; private art: A | undefined = undefined; private carrier: ((input: bytes) => bytes) | undefined = undefined; private splash: Sprites | undefined = undefined; private ring: Vec<f64> = []; private submit: ((packet: bytes) => void) | undefined = undefined; private shown: f64 = 0.0; private title: string = ""; held: bool = false; constructor(game: Game, art: Art<A>, draw: Draw<A>) { this.game = game; this.build = art; this.paint = draw; } carry(carry: (input: bytes) => bytes): Play<A> { this.carrier = carry; return this; } private picture(screen: Screen): bytes throws string { if (this.art === undefined && this.splash === undefined) { return this.loading(screen, 0.0); } if (this.art === undefined) { this.game.reading = (done: i64, total: i64): void => this.progress(screen, f64(done)/f64(Math.maxI64(1, total))); try { this.art = this.build(this.game, this.resources, screen); } finally { this.game.reading = undefined; } } let p = new Picture(this.game, screen, this.resources); p.title = this.title; let art = this.art!; this.paint(p, art); this.art = art; return p.graph.packet(this.resources, screen.measure); } private progress(screen: Screen, done: f64): void { const now = Task.now(); if (this.submit === undefined || now-this.shown <33.0) { return; } this.shown = now; try { this.submit!(this.loading(screen, done)); } catch (why) { console.error(`play: the loading screen: ${why }`); } } private loading(screen: Screen, done: f64): bytes throws string { if (this.splash === undefined) { let made = new Sprites(128); this.ring = made.ring(48); this.splash = made; } let sprites = this.splash!; const t = Task.now()/1000.0; let p = new Picture(this.game, screen, this.resources); let h = new Hud(p, sprites); let c = h.canvas; const middle = h.width*0.5; const pale = [0.93, 0.95, 1.0, 0.94]; const dim = [0.72, 0.78, 0.9, 0.5]; const accent = [0.55, 0.72, 1.0, 0.9]; const breath = 0.8+0.2*Math.sin(t*1.6); c.light(middle, h.height*0.36, h.width*0.9, [0.16, 0.24, 0.46, 0.22*breath]); c.light(middle, h.height*1.05, h.width*0.8, [0.32, 0.18, 0.12, 0.12]); if (this.title !== "") { h.center(this.title.toUpperCase(), h.height*0.42, 8.0, pale); } const y = h.height*0.42+92.0; const wide = 320.0; const left = middle-wide*0.5; const fill = Math.max(0.02, Math.min(1.0, done)); c.sprite(sprites.brush.disc, middle, y, wide, 1.5, 0.0, [1.0, 1.0, 1.0, 0.14]); c.sprite(sprites.brush.disc, left+wide*fill*0.5, y, wide*fill, 2.0, 0.0, accent, 1.0); const run = (t*0.6)%1.0; c.light(left+wide*run, y, 90.0, [0.55, 0.72, 1.0, 0.35*Math.sin(run*Math.PI)]); const x = h.width-h.margin-24.0; const ry = h.height-h.margin-24.0; const turn = t*4.0; c.sprite(this.ring, x, ry, 36.0, 36.0, 0.0, [1.0, 1.0, 1.0, 0.18]); for (const k of range(0, 3)) { const a = turn-f64(k)*0.45; c.dot(x+Math.cos(a)*17.0, ry+Math.sin(a)*17.0, 7.0-f64(k)*1.8, [accent[0], accent[1], accent[2], 0.9-f64(k)*0.3], 1.0); } h.text(`LOADING ${i64(fill*100.0) }%`, x-36.0, ry-6.0, 2.4, dim, 1.0); sprites.draw(p, c, [0.016, 0.02, 0.032, 1.0]); return p.graph.packet(this.resources, screen.measure); } initialize(input: bytes): bytes throws string { let setup: HostSetup; try { setup = Wire.decode<HostSetup>(input); } catch (e) { throw `Invalid host setup: ${e.message }`; } if (setup.title !== "") { this.title = setup.title; } return this.picture(this.game.initialize(input)); } file(input: bytes): bytes throws string { return this.game.receive(input); } frame(input: bytes): bytes throws string { return this.held ? this.still(input): this.picture(this.game.frame(input)); } still(input: bytes): bytes throws string { return this.picture(this.game.still(input)); } snapshot(input: bytes): bytes throws string { return this.game.snapshot(); } restore(input: bytes): bytes throws string { return this.game.restore(input); } cues(input: bytes): bytes throws string { return this.game.cues(); } net(input: bytes): bytes { return this.carrier === undefined ? b"": this.carrier!(input); } program(): Program { let p: Program = { initialize: (input: bytes): bytes => this.initialize(input)!, frame: (input: bytes): bytes => this.frame(input)!, snapshot: (input: bytes): bytes => this.snapshot(input)!, restore: (input: bytes): bytes => this.restore(input)!, cues: (input: bytes): bytes => this.cues(input)!, file: (input: bytes): bytes => this.file(input)! }; if (this.carrier !== undefined) { p.net = (input: bytes): bytes => this.net(input); } p.show = (submit: (packet: bytes) => void): void => { this.submit = submit; }; return p; } }
```

A Game as a surface program: its art, built at the first frame, and its drawing at each frame. A game's module
gives the surface its exports in one line each (`export function frame(input: bytes): bytes { return
play.frame(input)!; }`), and a window takes them in one (`program()`).

Opaque: create and use it through this module's functions.

### `Picture`

```gizlang
class Picture { game: Game; screen: Screen; resources: Resources; graph: Graph = new Graph(); time: f64; title: string = ""; width: f64; height: f64; passes: i64 = 0; private last: string = ""; constructor(game: Game, screen: Screen, resources: Resources) { this.game = game; this.screen = screen; this.resources = resources; this.time = game.time(); this.width = f64(screen.width); this.height = f64(screen.height); } stage(stage: Stage, camera: Camera, environment: Environment): void throws string { this.last = stage.draw(this.graph, this.screen.width, this.screen.height, camera, environment); } batch(batch: Batch2D, quads: Vec<Quad>, clear: Vec<f64> = [0.0, 0.0, 0.0, 1.0]): void throws string { const name = `canvas${this.passes }`; this.passes+ = 1; batch.draw(this.graph, quads, this.screen.width, this.screen.height, clear, name, this.last !== "", this.last === "" ? []: [this.last]); this.last = name; } }
```

One frame's picture: its passes in order, each drawn over the one before. TIME is the simulation's, between ticks.

- `game`: `Ref<M183.Game>`
- `screen`: `M183.Screen`
- `resources`: `gizlang_render.Resources`
- `graph`: `gizlang_render.Graph`
- `time`: `f64`
- `title`: `string` — The game's title, as the host named it.
- `width`: `f64` — The surface's size in pixels.
- `height`: `f64`
- `passes`: `i64` — The 2D passes drawn so far (batch).
- `last`: `string`

### `Sprites`

```gizlang
class Sprites { brush: Brush; private atlas: Atlas; private batches: Vec<Batch2D> = []; private used: i64 = 0; private pass: i64 = -1; private most: i64; constructor(size: i64 = 256, most: i64 = 6000) throws string { let atlas = new Atlas(size, size); this.brush = brush(atlas); this.atlas = atlas; this.most = most; } add(pixels: bytes, width: i64, height: i64): Vec<f64> throws string { return this.atlas.add(pixels, width, height); } ring(size: i64 = 48): Vec<f64> throws string { return this.atlas.add(ring(size), size, size); } canvas(picture: Picture, width: f64, height: f64): Canvas2D throws string { return new Canvas2D(picture.screen.width, picture.screen.height, width, height, this.brush); } draw(picture: Picture, canvas: Canvas2D, clear: Vec<f64> = [0.0, 0.0, 0.0, 1.0]): void throws string { if (picture.passes <= this.pass) { this.used = 0; } if (this.used === this.batches.length) { this.batches.push(new Batch2D(picture.resources, this.atlas.pixels, this.atlas.width, this.atlas.height, this.most, false)); } this.pass = picture.passes; picture.batch(this.batches[this.used], canvas.quads, clear); this.used+ = 1; } }
```

Images packed in one atlas with the brush's glow and disc, and the batches that draw them. Add every image before
the first draw, which uploads the atlas.

- `brush`: `gizlang_draw.Brush`
- `atlas`: `gizlang_draw.Atlas`
- `batches`: `Vec<gizlang_draw.Batch2D>`
- `used`: `i64`
- `pass`: `i64`
- `most`: `i64`

### `Hud`

```gizlang
class Hud { canvas: Canvas2D; width: f64; height: f64 = 720.0; margin: f64 = 32.0; private time: f64; private picture: Picture; game: Game; constructor(picture: Picture, sprites: Sprites) throws string { const width = 720.0*picture.width/Math.max(1.0, picture.height); this.picture = picture; this.game = picture.game; this.time = picture.time; this.width = width; this.canvas = sprites.canvas(picture, width, 720.0); } text(text: string, x: f64, y: f64, size: f64, color: Vec<f64>, align: f64 = 0.0): void { this.canvas.text(text, x, y, size, color, align); } left(text: string, y: f64, size: f64, color: Vec<f64>): void { this.canvas.text(text, this.margin, y, size, color, 0.0); } right(text: string, y: f64, size: f64, color: Vec<f64>): void { this.canvas.text(text, this.width-this.margin, y, size, color, 1.0); } center(text: string, y: f64, size: f64, color: Vec<f64>): void { this.canvas.text(text, this.width*0.5, y, size, color, 0.5); } pulse(color: Vec<f64>, rate: f64 = 3.0): Vec<f64> { return [color[0], color[1], color[2], color[3]*(0.6+0.4*Math.sin(this.time*rate))]; } faded(color: Vec<f64>, fade: f64): Vec<f64> { return [color[0], color[1], color[2], color[3]*Math.max(0.0, Math.min(1.0, fade))]; } bar(x: f64, y: f64, width: f64, height: f64, fill: f64, color: Vec<f64>, back: Vec<f64> = [0.0, 0.0, 0.0, 0.5]): void { const f = Math.max(0.0, Math.min(1.0, fill)); const disc = this.canvas.brush.disc; this.canvas.sprite(disc, x, y, width, height, 0.0, back); this.canvas.sprite(disc, x-width*0.5*(1.0-f), y, width*f, height, 0.0, color, 1.0); } panel(title: string, color: Vec<f64>, lines: Vec<string>, prompt: string, at: f64 = 0.3): void { const pale = [1.0, 0.95, 0.88, 0.9]; let y = this.height*at; this.center(title, y, 11.0, color); y+ = 96.0; for (const line of lines) { this.center(line, y, 3.5, pale); y+ = 40.0; } if (prompt !== "") { this.center(prompt, y+24.0, 4.0, this.pulse(pale)); } } over(camera: Camera, at: Point3): Point2 | undefined throws string { const p = transformed(view(camera, this.picture.screen.width, this.picture.screen.height), at); if (p.z <0.0 || p.z> 1.0 || Math.abs(p.x)> 1.0 || Math.abs(p.y)> 1.0) { return undefined; } return { x: (p.x+1.0)*0.5*this.width, y: (1.0-p.y)*0.5*this.height }; } marker(uv: Vec<f64>, camera: Camera, at: Point3, size: f64, color: Vec<f64>): void throws string { const p = this.over(camera, at); if (p !== undefined) { this.canvas.sprite(uv, p!.x, p!.y, size, size, 0.0, color, 1.0); } } draw(sprites: Sprites): void throws string { sprites.draw(this.picture, this.canvas); } }
```

The heads-up display over a picture, in units of a screen 720 high: x runs from 0 to `width` (720 times the
surface's aspect), y from 0 at the top to 720. Sizes are the text's dot in those units. CANVAS is open for anything
else.

- `canvas`: `gizlang_draw.Canvas2D`
- `width`: `f64`
- `height`: `f64`
- `margin`: `f64` — The margin of text at the edges.
- `time`: `f64`
- `picture`: `Ref<M192.Picture>`
- `game`: `Ref<M183.Game>` — The game drawn.

### `Follow`

```gizlang
type Follow = { back: f64; up: f64; ahead: f64; lift: f64; stiffness: f64; fov?: f64; far?: f64; }
```

How a Chase camera follows: BACK meters behind and UP above the target, looking AHEAD meters past it at LIFT
above it, reaching where it should be at STIFFNESS (higher is tighter), through FOV radians.

- `back`: `f64`
- `up`: `f64`
- `ahead`: `f64`
- `lift`: `f64`
- `stiffness`: `f64`
- `fov`: `_gizlang_sdk_core.Option<f64>`
- `far`: `_gizlang_sdk_core.Option<f64>`

### `Chase`

```gizlang
class Chase { rig: Follow; floor: (x: f64, z: f64) => f64; private eye: Point3 = point3(0.0, 0.0, 0.0); private looking: Point3 = point3(0.0, 0.0, 0.0); private time: f64 = -1.0; private frame: f64 = -1.0; private seen: Point3 = point3(0.0, 0.0, 0.0); private aimed: Point3 = point3(0.0, 0.0, 0.0); private snap: bool = true; constructor(rig: Follow, floor: (x: f64, z: f64) => f64) { this.rig = rig; this.floor = floor; } private toward(eye: Point3, looking: Point3, time: f64, stiffness: f64, shake: f64): Camera { if (time !== this.frame) { this.snap = this.frame <0.0 || time <this.frame || time-this.frame> 0.5; this.time = this.frame; this.frame = time; this.eye = this.seen; this.looking = this.aimed; } const k = this.snap ? 1.0: 1.0-Math.exp(-Math.min(0.1, time-this.time)*stiffness); let seen = lerp(this.eye, eye, k); seen.y = Math.max(seen.y, this.floor(seen.x, seen.z)+1.2); this.seen = seen; this.aimed = lerp(this.looking, looking, k); const jolt = shake*0.25; return { eye: point3(seen.x+Math.sin(time*53.0)*jolt, seen.y+Math.cos(time*47.0)*jolt, seen.z), target: this.aimed, fov: this.rig.fov ?? 1.05, near: 0.1, far: this.rig.far ?? 300.0 }; } follow(target: Point3, yaw: f64, time: f64, shake: f64 = 0.0, pitch: f64 = 0.0): Camera { const ahead = facing(yaw); const r = this.rig; const level = Math.cos(pitch); const rise = Math.sin(pitch); return this.toward(point3(target.x-ahead.x*r.back*level, target.y+r.up-r.back*rise, target.z-ahead.z*r.back*level), point3(target.x+ahead.x*r.ahead*level, target.y+r.lift+r.ahead*rise, target.z+ahead.z*r.ahead*level), time, r.stiffness, shake); } orbit(center: Point3, radius: f64, height: f64, speed: f64, time: f64): Camera { return this.toward(point3(center.x+Math.cos(time*speed)*radius, center.y+height, center.z+Math.sin(time*speed)*radius), center, time, 1.0, 0.0); } }
```

A camera that follows a target smoothly from frame to frame, and starts over where time jumps (a restore). FLOOR
keeps the eye above the ground.

- `rig`: `M192.Follow`
- `floor`: `(arg0: f64, arg1: f64) => f64`
- `eye`: `gizlang_geometry.Point3`
- `looking`: `gizlang_geometry.Point3`
- `time`: `f64`
- `frame`: `f64`
- `seen`: `gizlang_geometry.Point3`
- `aimed`: `gizlang_geometry.Point3`
- `snap`: `bool`

### `Animator`

```gizlang
class Animator { rig: Gltf.Rig; fade: f64; private clip: string; private leaving: string; private weight: f64 = 0.0; private stride: f64 = 0.0; private began: f64 = 0.0; private last: f64 = -1.0; constructor(rig: Gltf.Rig, clip: string, fade: f64 = 0.2) { this.rig = rig; this.clip = clip; this.leaving = clip; this.fade = fade; } play(clip: string, rate: f64, time: f64, once: bool = false): Vec<Vec<Matrix4>> throws string { const step = this.last <0.0 ? 0.0: Math.max(0.0, Math.min(0.1, time-this.last)); this.last = time; this.stride+ = step*rate; if (clip !== this.clip) { this.weight = clip === this.leaving ? 1.0-this.weight: 1.0; this.leaving = this.clip; this.clip = clip; this.began = this.stride; } this.weight = Math.max(0.0, this.weight-step/Math.max(0.001, this.fade)); const at = once ? Math.min(this.stride-this.began, this.rig.length(clip)*0.999): this.stride; const from: Gltf.Fade | undefined = this.weight> 0.0 ? { clip: this.leaving, time: this.stride, weight: this.weight }: undefined; return this.rig.palettes(clip, at, from); } done(): bool throws string { return this.stride-this.began> = this.rig.length(this.clip)*0.999; } }
```

A rig's clips as a character shows them: the clip it plays, blended from the one before over FADE seconds, its
time running at the rate the game gives (so feet do not slide). A clip played ONCE (an attack, a fall) starts from
its beginning and holds its last pose.

- `rig`: `gizlang_gltf.Rig`
- `fade`: `f64`
- `clip`: `string`
- `leaving`: `string`
- `weight`: `f64`
- `stride`: `f64`
- `began`: `f64`
- `last`: `f64`

### `Cast`

```gizlang
class Cast { stage: Stage; name: string; rig: Gltf.Rig; private animators: Vec<Animator> = []; constructor(stage: Stage, name: string, rig: Gltf.Rig, most: i64, clip: string) throws string { this.stage = stage; this.name = name; this.rig = rig; for (const at of range(0, most)) { stage.model(`${name }${ at }`, rig.parts, 1); this.animators.push(new Animator(rig, clip)); } } stand(slot: i64, at: Point3, size: f64, yaw: f64, clip: string, rate: f64, time: f64, once: bool = false): void throws string { const k = slot%this.animators.length; const palettes = this.animators[k].play(clip, rate, time, once); this.stage.pose(`${this.name }${ k }`, this.stage.fit(`${this.name }${ k }`, at, size, yaw), palettes); } animator(slot: i64): Animator { return this.animators[slot%this.animators.length]; } }
```

Up to MOST characters of one rig on a stage, each its own copy of the model bent by its own Animator: a crowd of one
kind, such as the soldiers of a match or a village's folk. A game gives each character a slot (a player's number, an
entity's index) and draws it with stand.

- `stage`: `gizlang_meshdraw.Stage`
- `name`: `string`
- `rig`: `gizlang_gltf.Rig`
- `animators`: `Vec<Ref<M192.Animator>>`

### `Art2D`

```gizlang
class Art2D { sprites: Sprites; ring: Vec<f64>; private images = new Map<string, Vec<f64>>(); constructor(sprites: Sprites) throws string { this.sprites = sprites; this.ring = sprites.ring(48); } load(game: Game, name: string): void throws string { if (this.images.has(name)) { return; } const image = Image.rgba(Image.decode(game.file(name), 4096)); this.images.set(name, this.sprites.add(image.pixels, image.width, image.height)); } image(name: string): Vec<f64> throws string { const uv = this.images.get(name); if (uv === undefined) { throw `No image ${name }:  name it in the stage or a look`; } return uv!; } }
```

The art of a game drawn by play2D: the sprites, each image the stage named or a kind's look shows, by file name,
and a ring for a crosshair.

- `sprites`: `Ref<M192.Sprites>`
- `ring`: `Vec<f64>`
- `images`: `_gizlang_sdk_collections.Map<string, Vec<f64>>`

### `Layer2D`

```gizlang
type Layer2D = (picture: Picture, canvas: mut Canvas2D, art: Art2D) => void throws string
```

A part of a 2D picture: drawn into the arena's CANVAS (under or over the actors), or into the HUD.

### `Widget`

```gizlang
type Widget = (hud: Hud, art: Art2D) => void throws string
```

### `Stage2D`

```gizlang
type Stage2D = { atlas?: i64; most?: i64; images?: Vec<string>; clear?: Vec<f64>; under?: Layer2D; over?: Layer2D; shake?: f64; crosshair?: bool; hud?: Vec<Widget>; }
```

How play2D draws a game in its arena (Game.arena): an atlas of ATLAS pixels for MOST quads a frame, the IMAGES the
layers use besides the looks, CLEAR under all, UNDER before the actors (a backdrop) and OVER after them and the
particles. SHAKE is the units the view moves per second of the match's shake. CROSSHAIR draws the aim. HUD is the
widgets of the still display, over which play2D draws the title, pause and end panels by itself.

- `atlas`: `_gizlang_sdk_core.Option<i64>`
- `most`: `_gizlang_sdk_core.Option<i64>`
- `images`: `_gizlang_sdk_core.Option<Vec<string>>`
- `clear`: `_gizlang_sdk_core.Option<Vec<f64>>`
- `under`: `_gizlang_sdk_core.Option<(arg0: Ref<M192.Picture>, arg1: mut gizlang_draw.Canvas2D, arg2: Ref<M192.Art2D>) => void throws string>`
- `over`: `_gizlang_sdk_core.Option<(arg0: Ref<M192.Picture>, arg1: mut gizlang_draw.Canvas2D, arg2: Ref<M192.Art2D>) => void throws string>`
- `shake`: `_gizlang_sdk_core.Option<f64>`
- `crosshair`: `_gizlang_sdk_core.Option<bool>`
- `hud`: `_gizlang_sdk_core.Option<Vec<(arg0: Ref<M192.Hud>, arg1: Ref<M192.Art2D>) => void throws string>>`

## Functions

### `constructor`

```gizlang
constructor(game: Game, art: Art<A>, draw: Draw<A>)
```

GAME, drawn with the ART that its first frame builds and the DRAW of each frame.

### `constructor`

```gizlang
constructor(game: Game, screen: Screen, resources: Resources)
```

An empty picture of GAME on SCREEN, its passes made of RESOURCES.

Effects: fail, read, write, alloc.

### `constructor`

```gizlang
constructor(size: i64 = 256, most: i64 = 6000) throws string
```

An atlas of SIZE by SIZE pixels for at most MOST quads a frame.

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

### `clock`

```gizlang
function clock(seconds: f64): string
```

Minutes and seconds of SECONDS, as a clock shows them: 3:07.

Effects: fail, alloc.

### `constructor`

```gizlang
constructor(picture: Picture, sprites: Sprites) throws string
```

A display over PICTURE that draws with the brush of SPRITES (draw).

Effects: fail, read, write, alloc.

### `constructor`

```gizlang
constructor(rig: Follow, floor: (x: f64, z: f64) => f64)
```

A camera of RIG over the ground FLOOR gives at X, Z.

Effects: fail, read, write, alloc.

### `constructor`

```gizlang
constructor(rig: Gltf.Rig, clip: string, fade: f64 = 0.2)
```

RIG, starting with CLIP.

Effects: fail, read, write, alloc.

### `constructor`

```gizlang
constructor(stage: Stage, name: string, rig: Gltf.Rig, most: i64, clip: string) throws string
```

Declares MOST copies of RIG's model as NAME0, NAME1, ... on STAGE, each starting with CLIP.

Effects: fail, read, write, alloc.

### `particles3D`

```gizlang
function particles3D(game: Game, stage: Stage): void throws string
```

GAME's particles on STAGE: each kind is a model of the same name (Stage.add), placed at its size, turning.

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

### `particles2D`

```gizlang
function particles2D(game: Game, canvas: mut Canvas2D): void throws string
```

GAME's particles on CANVAS: a glow in each one's color and a bright core, fading out.

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

### `constructor`

```gizlang
constructor(sprites: Sprites) throws string
```

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

### `play2D`

```gizlang
function play2D(game: Game, stage: Stage2D): Play<Art2D>
```

A 2D game drawn from its kinds' looks with nothing of its own but STAGE.

Effects: fail, read, write, alloc.

### `panels`

```gizlang
function panels(hud: Hud, title: string, help: Vec<string> = []): void throws string
```

The flow's panels over HUD: the title (TITLE, the lines of HELP and the keys that start), the pause, and the end with
the score.

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

### `scoreboard`

```gizlang
function scoreboard(): Widget
```

The score at the top left, six digits, and its combo beside it.

Effects: fail, alloc.

### `waveboard`

```gizlang
function waveboard(): Widget
```

The wave at the top right.

Effects: fail, alloc.

### `best`

```gizlang
function best(): Widget
```

The best score at the bottom left.

Effects: fail, alloc.

### `lives`

```gizlang
function lives(kind: string, icon: string): Widget
```

One image ICON for each hit left of the first actor of KIND, at the bottom right.

Effects: fail, alloc.

### `banner`

```gizlang
function banner(title: string = ""): Widget
```

The wave's number in the middle as it begins, and TITLE under the first.

Effects: fail, alloc.

## Methods

### `Play.carry`

```gizlang
carry(carry: (input: bytes) => bytes): Play<A>
```

CARRY takes the host's messages of a game played on a server (net; Net.Session carry gives one).

### `Play.initialize`

```gizlang
initialize(input: bytes): bytes throws string
```

The first frame, at the host's size and with the device's features: the loading screen, titled with the
setup's `title` when the host gives one.

### `Play.file`

```gizlang
file(input: bytes): bytes throws string
```

An asset file before initialize: its name, a newline and its bytes.

### `Play.frame`

```gizlang
frame(input: bytes): bytes throws string
```

One host frame: its input, the fixed ticks it covers, and the picture.

### `Play.still`

```gizlang
still(input: bytes): bytes throws string
```

One picture of the World as it is, with no tick: a held frame, or a page's change of view.

### `Play.snapshot`

```gizlang
snapshot(input: bytes): bytes throws string
```

The whole simulation: the World, its pending input and its tick.

### `Play.restore`

```gizlang
restore(input: bytes): bytes throws string
```

Replaces the simulation with a snapshot of this game; another schema or rate is refused first.

### `Play.cues`

```gizlang
cues(input: bytes): bytes throws string
```

The sounds of the ticks since the last call.

### `Play.net`

```gizlang
net(input: bytes): bytes
```

One message of the server (INPUT), or the next one to send (b"": b"" none), for a game played on a server.

### `Play.program`

```gizlang
program(): Program
```

The exports as one record, for a window (gizapp/play host).

### `Picture.stage`

```gizlang
stage(stage: Stage, camera: Camera, environment: Environment): void throws string
```

STAGE drawn from CAMERA under ENVIRONMENT.

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

### `Picture.batch`

```gizlang
batch(batch: Batch2D, quads: Vec<Quad>, clear: Vec<f64> = [0.0, 0.0, 0.0, 1.0]): void throws string
```

QUADS drawn with BATCH: over the passes before it, or on CLEAR when it is the first.

Effects: fail, read, write, alloc.

### `Sprites.add`

```gizlang
add(pixels: bytes, width: i64, height: i64): Vec<f64> throws string
```

Packs straight RGBA8 PIXELS of WIDTH by HEIGHT: where they are, for Canvas2D.sprite.

Effects: fail, read, write, alloc.

### `Sprites.ring`

```gizlang
ring(size: i64 = 48): Vec<f64> throws string
```

A ring SIZE pixels across, for a marker or a crosshair.

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

### `Sprites.canvas`

```gizlang
canvas(picture: Picture, width: f64, height: f64): Canvas2D throws string
```

A canvas over PICTURE of WIDTH by HEIGHT logical units, fitted to the surface.

Effects: fail, read, write, alloc.

### `Sprites.draw`

```gizlang
draw(picture: Picture, canvas: Canvas2D, clear: Vec<f64> = [0.0, 0.0, 0.0, 1.0]): void throws string
```

CANVAS drawn into PICTURE: over its passes, or on CLEAR as its first. A picture may take several canvases, such
as a world that shakes and a display that does not.

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

### `Hud.text`

```gizlang
text(text: string, x: f64, y: f64, size: f64, color: Vec<f64>, align: f64 = 0.0): void
```

TEXT at X, Y of SIZE in COLOR, its left (ALIGN 0), middle (0.5) or right (1) at X.

Effects: fail, read, write, alloc.

### `Hud.left`

```gizlang
left(text: string, y: f64, size: f64, color: Vec<f64>): void
```

TEXT at the left margin.

Effects: fail, read, write, alloc.

### `Hud.right`

```gizlang
right(text: string, y: f64, size: f64, color: Vec<f64>): void
```

TEXT at the right margin.

Effects: fail, read, write, alloc.

### `Hud.center`

```gizlang
center(text: string, y: f64, size: f64, color: Vec<f64>): void
```

TEXT in the middle.

Effects: fail, read, write, alloc.

### `Hud.pulse`

```gizlang
pulse(color: Vec<f64>, rate: f64 = 3.0): Vec<f64>
```

COLOR with its alpha pulsing at RATE, as a prompt to press a key blinks.

Effects: fail, read, alloc.

### `Hud.faded`

```gizlang
faded(color: Vec<f64>, fade: f64): Vec<f64>
```

COLOR at FADE of its alpha.

Effects: fail, alloc.

### `Hud.bar`

```gizlang
bar(x: f64, y: f64, width: f64, height: f64, fill: f64, color: Vec<f64>, back: Vec<f64> = [0.0, 0.0, 0.0, 0.5]): void
```

A bar WIDTH by HEIGHT centered at X, Y, filled to FILL (0 to 1) from the left in COLOR over BACK.

Effects: fail, read, write, alloc.

### `Hud.panel`

```gizlang
panel(title: string, color: Vec<f64>, lines: Vec<string>, prompt: string, at: f64 = 0.3): void
```

A panel in the middle: TITLE large in COLOR, the LINES under it, and a PROMPT that blinks.

Effects: fail, read, write, alloc.

### `Hud.over`

```gizlang
over(camera: Camera, at: Point3): Point2 | undefined throws string
```

Where the world point AT shows under CAMERA, in the HUD's units; undefined behind the camera or off screen.

Effects: fail, read, alloc.

### `Hud.marker`

```gizlang
marker(uv: Vec<f64>, camera: Camera, at: Point3, size: f64, color: Vec<f64>): void throws string
```

Sprite UV of SIZE in COLOR over the world point AT under CAMERA, when it is in view: a marker on a goal.

Effects: fail, read, write, alloc.

### `Hud.draw`

```gizlang
draw(sprites: Sprites): void throws string
```

The HUD drawn with SPRITES over the picture.

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

### `Chase.follow`

```gizlang
follow(target: Point3, yaw: f64, time: f64, shake: f64 = 0.0, pitch: f64 = 0.0): Camera
```

The camera behind TARGET, which looks along YAW and up by PITCH radians (a mouse look's), at TIME; SHAKE jolts
it. A look up lowers the eye and raises its aim about the target, as a third-person camera swings.

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

### `Chase.orbit`

```gizlang
orbit(center: Point3, radius: f64, height: f64, speed: f64, time: f64): Camera
```

The camera circling CENTER at RADIUS and HEIGHT, a turn in 2 pi / SPEED seconds, as a title shows a world.

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

### `Animator.play`

```gizlang
play(clip: string, rate: f64, time: f64, once: bool = false): Vec<Vec<Matrix4>> throws string
```

The joint palettes at TIME of CLIP, which runs at RATE times its own speed, looping unless ONCE.

Effects: fail, read, write, alloc.

### `Animator.done`

```gizlang
done(): bool throws string
```

Whether a clip played once has reached its end.

Effects: fail, read, alloc.

### `Cast.stand`

```gizlang
stand(slot: i64, at: Point3, size: f64, yaw: f64, clip: string, rate: f64, time: f64, once: bool = false): void throws string
```

Draws character SLOT standing on the ground at AT, SIZE meters tall, facing YAW, playing CLIP at RATE (once when
ONCE) at TIME.

Effects: fail, read, write, alloc.

### `Cast.animator`

```gizlang
animator(slot: i64): Animator
```

The Animator of SLOT, to ask whether its clip played once is done.

Effects: fail, read.

### `Art2D.load`

```gizlang
load(game: Game, name: string): void throws string
```

Packs the image file NAME (PNG or JPEG) of GAME once.

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

### `Art2D.image`

```gizlang
image(name: string): Vec<f64> throws string
```

Where image NAME is in the atlas.

Effects: fail, read, alloc.

