# gizgame/sequence

a cinematic as data, cut as a film is (Unreal's Level Sequencer, a director's shot list). Its CAST are kinds that move along paths of marks, ride one another and play clips, whole or in the upper body; its SHOTS are cameras that move through views (in the world, or in an actor's frame as it moves) and cut from one to the next; its BEATS sound, speak lines (with the speaker's face) and shake; its CAPTIONS, BARS and FADES go over the picture. A map's file holds one (Map3D sequence): the Game plays it from the start of play (direct), and the view draws its acts and sees through its cameras (gizgame/view). Every value is a function of the time into it, so a frame of any time is the same frame (a recording, a scrub).

```gizlang
import * as Sequence from "gizgame/sequence";
```

## Types

### `Mark`

```gizlang
type Mark = { t: f64; at: Vec<f64>; yaw?: f64; }
```

Where a player is T seconds in: AT (x, y, z meters; with two numbers x and z on y 0), facing YAW (radians). Between
two marks that both give a yaw it turns from the one to the other (it may back away); elsewhere it faces the way it
goes, where it stopped the way it came, and before it first moves the yaw of the nearest mark that gives one.

- `t`: `f64`
- `at`: `Vec<f64>`
- `yaw`: `_gizlang_sdk_core.Option<f64>`

### `Act`

```gizlang
type Act = { t: f64; clip?: string; once?: bool; rate?: f64; upper?: string; at?: string; }
```

What a player does from T seconds in: CLIP with its whole body (once when ONCE, at RATE; "" goes back to the gait its
motion chooses), or UPPER once in its upper body, from its spine up, over what the rest does. An UPPER AT another
player (its name) is a stroke at it: the hands reach toward it in the stroke's middle, and its blade clashes there.

- `t`: `f64`
- `clip`: `_gizlang_sdk_core.Option<string>`
- `once`: `_gizlang_sdk_core.Option<bool>`
- `rate`: `_gizlang_sdk_core.Option<f64>`
- `upper`: `_gizlang_sdk_core.Option<string>`
- `at`: `_gizlang_sdk_core.Option<string>`

### `Player`

```gizlang
type Player = { name: string; kind: string; rides?: string; path?: Vec<Mark>; acts?: Vec<Act>; }
```

One of the cast: NAME, an actor of KIND that goes along its PATH and does its ACTS. One that RIDES another player
(its name) sits on it (Game.mount) and goes where it goes.

- `name`: `string`
- `kind`: `string`
- `rides`: `_gizlang_sdk_core.Option<string>`
- `path`: `_gizlang_sdk_core.Option<Vec<M206.Mark>>`
- `acts`: `_gizlang_sdk_core.Option<Vec<M206.Act>>`

### `View`

```gizlang
type View = { t: f64; eye: Vec<f64>; look: Vec<f64>; from?: string; at?: string; fov?: f64; }
```

A camera's key T seconds in: its EYE and where it LOOKs (meters), through FOV radians (1.05 when none). With FROM
the eye is in that player's frame (x right, y up, z ahead of its feet), with AT the look is in that player's frame:
the camera moves with them. FROM or AT may name two players, "A+B": the frame of the pair, at their middle, x from
A toward B and z square to that line, so a two-shot keeps its side of the line as the two wheel about each other.

- `t`: `f64`
- `eye`: `Vec<f64>`
- `look`: `Vec<f64>`
- `from`: `_gizlang_sdk_core.Option<string>`
- `at`: `_gizlang_sdk_core.Option<string>`
- `fov`: `_gizlang_sdk_core.Option<f64>`

### `Shot`

```gizlang
type Shot = { t: f64; views: Vec<View>; ease?: bool; shake?: f64; grade?: Grade; }
```

A shot: from T seconds in until the next one's T, a camera that moves smoothly through its VIEWS, easing in and out
of the shot when EASE, shaking by SHAKE meters as a hand holds it, under its own GRADE. A cut goes from shot to shot.

- `t`: `f64`
- `views`: `Vec<M206.View>`
- `ease`: `_gizlang_sdk_core.Option<bool>`
- `shake`: `_gizlang_sdk_core.Option<f64>`
- `grade`: `_gizlang_sdk_core.Option<gizlang_meshdraw.Grade>`

### `Beat`

```gizlang
type Beat = { t: f64; by?: string; line?: string; cues?: Vec<Cue>; }
```

What happens T seconds in: BY (a player) says LINE (Soundtrack.lines, with its face) and its CUES happen to it
(a sound, a shake, a burst: Kind cues).

- `t`: `f64`
- `by`: `_gizlang_sdk_core.Option<string>`
- `line`: `_gizlang_sdk_core.Option<string>`
- `cues`: `_gizlang_sdk_core.Option<Vec<M195.Cue>>`

### `Caption`

```gizlang
type Caption = { t: f64; until: f64; text: string; by?: string; }
```

Words shown from T to UNTIL seconds in, said BY a name shown before them.

- `t`: `f64`
- `until`: `f64`
- `text`: `string`
- `by`: `_gizlang_sdk_core.Option<string>`

### `Fade`

```gizlang
type Fade = { t: f64; until: f64; from: f64; to: f64; }
```

Black over the picture from T to UNTIL seconds in, from FROM to TO (0 none, 1 black).

- `t`: `f64`
- `until`: `f64`
- `from`: `f64`
- `to`: `f64`

### `Speed`

```gizlang
type Speed = { t: f64; until: f64; rate: f64; }
```

The film's clock from T to UNTIL seconds of film runs at RATE of the wall's: under 1 a slow motion, near 0 a
hit-stop.

- `t`: `f64`
- `until`: `f64`
- `rate`: `f64`

### `Sequence`

```gizlang
type Sequence = { length: f64; cast: Vec<Player>; shots: Vec<Shot>; beats?: Vec<Beat>; captions?: Vec<Caption>; fades?: Vec<Fade>; bars?: f64; speeds?: Vec<Speed>; }
```

A cinematic of LENGTH seconds: its CAST, its SHOTS (in order of their times), its BEATS, its CAPTIONS, its FADES and
BARS (the letterbox: the picture's width over its height between them, 2.39 a film's; none: the whole screen), and
its SPEEDS (in order of their times; every time of the film is film time, timeAt).

- `length`: `f64`
- `cast`: `Vec<M206.Player>`
- `shots`: `Vec<M206.Shot>`
- `beats`: `_gizlang_sdk_core.Option<Vec<M206.Beat>>`
- `captions`: `_gizlang_sdk_core.Option<Vec<M206.Caption>>`
- `fades`: `_gizlang_sdk_core.Option<Vec<M206.Fade>>`
- `bars`: `_gizlang_sdk_core.Option<f64>`
- `speeds`: `_gizlang_sdk_core.Option<Vec<M206.Speed>>`

### `Placed`

```gizlang
type Placed = { at: Point3; yaw: f64; velocity: Point3; }
```

Where a player is and how it moves: AT facing YAW, going at VELOCITY (meters a second).

- `at`: `gizlang_geometry.Point3`
- `yaw`: `f64`
- `velocity`: `gizlang_geometry.Point3`

### `Doing`

```gizlang
type Doing = { clip: string; began: f64; once: bool; rate: f64; upper: string; uppered: f64; aimed: i64; }
```

What a player does now: CLIP ("" its gait), begun BEGAN seconds in, once when ONCE, at RATE; UPPER in its upper body,
UPPERED seconds into it ("" none), AIMED at that player (-1 none).

- `clip`: `string`
- `began`: `f64`
- `once`: `bool`
- `rate`: `f64`
- `upper`: `string`
- `uppered`: `f64`
- `aimed`: `i64`

### `Role`

```gizlang
type Role = { player: i64; }
```

An actor of a sequence's cast: the PLAYER it plays (its index).

- `player`: `i64`

### `Ground`

```gizlang
type Ground = (x: f64, z: f64) => f64
```

The ground's height at x, z: where a mark or a view of two numbers stands.

## Functions

### `timeAt`

```gizlang
function timeAt(sequence: Sequence, wall: f64): f64
```

The film time of SEQUENCE WALL seconds after it starts: the wall's own, but slower through each of its speeds. The
one clock of a film: its cast, its cameras, its beats and its captions all read it.

Effects: fail, alloc.

### `now`

```gizlang
function now(game: Game, sequence: Sequence): f64 throws string
```

The film time of SEQUENCE in GAME now: its wall seconds of play, less those that hit-stops held (Cue stop), at its
speeds (timeAt). Its cast, cameras, beats and captions all read it.

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

### `runtime`

```gizlang
function runtime(sequence: Sequence): f64
```

The wall seconds SEQUENCE lasts: its length, longer by its slow spans.

Effects: fail, alloc.

### `playerOf`

```gizlang
function playerOf(sequence: Sequence, name: string): i64
```

The player of SEQUENCE named NAME: its index, -1 for none.

Effects: fail.

### `placed`

```gizlang
function placed(sequence: Sequence, p: i64, t: f64, ground: Ground = flat): Placed
```

Where player P of SEQUENCE is at T: on its path, or where the one it rides is. A path of marks of two numbers goes
on the GROUND.

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

### `doing`

```gizlang
function doing(sequence: Sequence, p: i64, t: f64): Doing
```

What player P of SEQUENCE does at T (Doing).

Effects: fail, alloc.

### `shotAt`

```gizlang
function shotAt(sequence: Sequence, t: f64): i64
```

The shot of SEQUENCE at T: its index, -1 before the first.

Effects: fail, alloc.

### `cameraAt`

```gizlang
function cameraAt(sequence: Sequence, t: f64, ground: Ground = flat): { camera: Camera; grade?: Grade; } | undefined
```

The camera of SEQUENCE at T, and its shot's grade: the shot's views, each eye and look where it is at T (a view in a
player's frame moves with that player, which stands on the GROUND), on a smooth curve through their times; none
before its first shot.

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

### `darkAt`

```gizlang
function darkAt(sequence: Sequence, t: f64): f64
```

How black the picture of SEQUENCE is at T (Fade), 0 to 1.

Effects: fail, alloc.

### `captionAt`

```gizlang
function captionAt(sequence: Sequence, t: f64): Caption | undefined
```

The caption of SEQUENCE shown at T, if any.

Effects: fail, alloc.

### `direct`

```gizlang
function direct(game: Game, sequence: (game: Game) => Sequence | undefined throws string): void
```

GAME plays the sequence that SEQUENCE gives for its map (none: nothing): at each start of its map the cast comes
where its paths begin, riders on their mounts; in play each tick puts each where its path is and does the beats
whose time came. A map's file with a sequence is played so by gizgame/maps charted.

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

## Constants

### `Cast`

```gizlang
const Cast = component<Role>("gizgame.Cast", { player: 0 })
```

The component of the cast (Role).

