GizStackGizStack
View .mdOpen in ChatGPTOpen in Claude

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