cutsceneplugin

A scene played from a cue file: camera shots, bars, a fade to black and lines of text, directing the rows it casts.

#Putting it in a scene

List it after render3d and before chasecamera3d and ui. The scene's sim lists the cutscene and mark kinds from #plugins/cutscene/cutscene.sim.ts. cutscene is built from the ground's height, cutscene(height), where height(w, x, z) is the ground's height over a truth: pass terrain3d's server half, or () => 0 for a flat scene. The scene holds one cutscene actor, whose prefab is {}, and one mark actor for each named spot.

"plugins": ["loader", "scenemanager", "player", "terrain3d", "render3d", "cutscene", "chasecamera3d", "ui"],
"world": {
  "loader": { "assets": { "intro": { "type": "json", "url": "/games/mygame/assets/intro.json", "preload": true } } },
  "cutscene": {
    "script": "intro",
    "kinds": ["villager"],
    "settle": 0.5,
    "tremor": [[0.02, 31], [0.02, 37], [0.01, 43]],
    "mods": { "play": "audio", "land": "terrain3d" }
  },
  "ui": {
    "panels": {
      "cutscene.top": { "anchor": "top", "size": [640, 60], "layer": 10 },
      "cutscene.bottom": { "anchor": "bottom", "size": [640, 60], "layer": 10 },
      "cutscene.veil": { "anchor": "center", "size": [640, 360], "layer": 11 },
      "cutscene.line": { "anchor": "bottom", "at": [0, -70], "size": [600, 40], "layer": 12 }
    },
    "styles": {
      "cutscene.bars": { "color": 0 },
      "cutscene.veil": { "color": 0 },
      "cutscene.line": { "fontSize": 16, "fill": "#ffffff" }
    }
  }
},
"prefabs": {
  "cutscene": {},
  "mark": { "name": "gate", "at": [12, 0, -4] }
}

The cue file is the loader json entry that script names:

{
  "end": 12, "go": "arena", "arrive": [1],
  "reach": 1.5, "stop": 0.3, "head": 1.6, "fov": 55, "pace": 1.4, "limit": 20,
  "cast": { "elder": { "kind": "villager", "name": "Edda" } },
  "cues": [
    { "at": 0, "do": "bars", "on": true, "over": 0.5 },
    { "at": 0, "do": "shot", "name": "wide", "pos": [0, 6, 20], "look": "elder", "over": 0 },
    { "at": 1, "do": "walk", "who": "elder", "to": "gate", "gear": "walk" },
    { "at": 1, "do": "wait", "who": "elder" },
    { "at": 1, "do": "say", "who": "elder", "text": "Follow me.", "for": 3 },
    { "at": 4, "do": "shot", "name": "close", "pos": [0, 0.2, 2.5], "look": "elder", "fov": 40, "over": 2, "follows": "elder", "frame": "body" }
  ]
}

#Properties

The scene's numbers

Read from world.cutscene. A child scene inherits them from the manager scene.

The cue file

Every number is required and is held to the range below. Lengths are metres and times are seconds.

Cues

A cue's fields depend on its do. A field ending in ? may be left out.

Targets

A target (to, pos, look, where) is a cast name, a mark's name, or a point [x, z] or [x, up, z], up metres above the ground there. A cast name is looked for before a mark's. Every name must be a cast member or a mark. Everything stands on the scene's ground, and a point's height is the ground's as it is now, so ground raised under a mark or a shot raises it with it. A cast member is its feet for a walk, a face and a sound, and its head, head above its feet, for a shot's pos and look. A mark is { name, at }, at a point, and does nothing else.

Two clocks

The row's e is the elapsed time and always advances: shots, fades, bars, shakes and lines run on it, so a dolly keeps moving through a wait. The cue clock t advances unless a wait holds it, and a cue fires on the first step t reaches its at, in at order, cues with one at in the order written. A wait with nothing to wait for passes at once. So e − t is the time every wait so far has held. A walk is done within its reach or stop of its target, or limit seconds after it began. Fades and bars ramp in a straight line from where they stood to their target. A dolly eases with the smoothstep k²(3 − 2k), the position moving along a line, the facing turning the short way and the field of view blending.

Start, skip and end

The scene starts when a game rule calls the closed act start, or on the row's first step when the cue file's auto is true, or when the row's starts is true, on the first step every cast member's row is there. It does nothing while the scene runs or once it is done, so a scene plays once. On starting, each cast member is matched to its row, its direct is set to {} and the clocks go to 0. A cast member's row must come after the cutscene row.

The open act skip lets any seat skip the scene for every seat. On the next step the row plays the scene through to its end. It steps every step while a walk runs and settle seconds of steps of each quiet stretch (the steps after the last one a cue fired on, up to the next cue, the line going while a wait holds on it, or the end), and leaps the rest of the stretch without stepping the cast. A scene whose quiet stretches all fit in settle leaves the cast exactly where a played one would. A longer one leaves the cast as it stood settle seconds into each stretch. No sound or voice is raised while it plays through, and music is set as played.

At the end the row is done, the line, walks, faces and waits are cleared, and direct is null on the cast, so control returns. With go, every row of the kinds kinds names is sent go(go, ...arrive), after a skip too.

The row

The cutscene row carries only what changes. A rule can read it.

What a cast kind provides

A kind named in kinds carries a name and obeys direct in its tick. Its step reads no other cast member's fields, so the order the cast steps in changes nothing.

#Methods

Acts

Of the cutscene row. A rule calls them with w.call.

start( )

Starts the scene. Closed, so only a game's rule calls it.

skip( )

Skips the scene for every seat while it runs. Open, so any seat may send it.

Rules

From #plugins/cutscene/cutscene.sim.ts.

longest( file ) : number

The most seconds of e a cue file can play: its end, plus at each wait the longest it can hold, a walk's limit or a line's for.

check( name, file )

Throws a sentence naming the file and the cue for a cue file the row cannot play.

placed( p, height ) : [x, y, z]

The world point of a point [x, z] or [x, up, z] on the ground whose height is height(x, z).

rooted( q, height ) : [x, up, z]

The point [x, up, z] of a world point q: the reverse of placed.

pose( d, rows, height ) : { pos, quat, fov } | undefined

Takes the cutscene row's data d and the rows as they stand. Gives the camera the row's shot draws, before any shake: a position, an orientation as a quaternion [x, y, z, w] and a field of view in degrees. Undefined with no shot, or while a member the shot names has no row.

view( to, cast, rows, height ) : { pos, quat, fov } | undefined

The camera of one shot held still: to is { pos, look, fov, head, follows?, frame? }, the fields of a shot cue with the cue file's head, and cast the row's cast names to ids, which stay on the row after the end. Undefined while a member it names has no row. A title's look carries the last shot on with it once the scene is done.

shaken( d, tremor ) : [x, y, z]

The shake's offset at the row's e, from the row's data d and the scene's tremor.

On the page

Through plugins.cutscene.

eye( ) : { pos, dir }

Where render3d's camera stands and its world −z direction. Call it after the first tick.

close( )

Gives the camera claim back, as the scene ending would.

The camera, the bars, the veil and the line

While the scene runs a shot, the page claims render3d's camera each frame and places it at the row's pose with the shake added, setting its field of view. It is the same on every seat and every frame the same rows are drawn: nothing eases and no clock of the page's is read, and a seat that arrives during a shot draws it from its first frame. It takes the camera from nobody. While another driver holds it, it places nothing and claims the camera again the first frame it is free. It places nothing on a frame whose rows lack a member the shot names. When the scene is done or skipped it gives the camera back the field of view it had when it took it. The scene needs render3d with a camera.

The bars, veil and line are drawn through ui while the scene runs, each only while it has something to show. A scene that shows none of them needs none of the panels, and no ui.

#Mods

Name them in world.cutscene.mods.

• audio
  play: sounds a sound cue and a say cue's voice, as play(w, cue, at?, from?): the cue at the point at, or from the row from, or with neither at no place. A scene that names no play plays no sound: its cues fire and nothing is heard.
• terrain3d
  land: the ground the page stands on, with height(x, z), and optionally prepare(x, z) and unprepare(). A prepare cue's point is handed to the land once, so it is made ready where the next cut lands, and let go when the scene stops. Without land the ground is flat at 0. The page places nothing while the land has no ground yet. A scene that names a land must list its plugin.

#In the guide