Log inGet started
World

Deep Field

Branchmain
Branchesmain
Commit97b82cdc4f

README.md

Staging — the boat, the opening, the specimen, the resolution

This folder holds everything in Deep Field that is not a rule, a creature or a page: the launch the line comes off, the sea it sits on, the four scripted moments, and the animal in the trench the book has no plate for.

What is here

FileWhat it is
df_boot.moduleThe slice's entry point. Builds the set, registers the caption screen, hooks the four moments.
df_boat.modulebuildBoat(root) and buildSurface(parent) — the launch and the sea.
DfStaging.componentThe per-frame life: the boat rides, the rings spread, the deck lamp burns unevenly, the caption screen ticks.
df_captions.moduleScreen df-caption: the field-note caption line, and the notebook page the ending is drawn on.
df_cs_opening.moduleThe opening.
df_cs_trench.moduleCrossing 400 m — captions only, no camera taken.
df_cs_arrival.moduleThe specimen arrives.
df_cs_resolution.moduleThe plate is drawn and the specimen is named.
df_sp_apex.moduleThe specimen — the species spec Core.SPECIES_MODULES names staging.df_sp_apex.
df_stg_util.moduleQuaternions, a material cache, a primitive spawner.
df_*.materialThe set's materials.

The boat replaces the placeholder in place

The scene spawns df_boat carrying a cube. df_boot strips that cube, resets the transform the placeholder needed, and builds the real launch as its children. The scene file is never edited and df_boat keeps its identity, so anything holding that name still finds it.

The boat is 5.4 m on the waterline. Its parts are named and reachable: df_stg_hull, df_stg_topsides, df_stg_deck, df_stg_gear, df_stg_lampmast, and df_stg_deck_lamp — the globe that carries the only light above water. The gantry stands over the centre well at x = 0, z = 0, which is where the line goes down, so df_line runs through the sheave.

The surface set is df_stg_surface under df_staging_rig: one dark near-mirror plane at y = 0 and df_stg_rings, the ripples spreading off the hull. If the water slice lays its own surface, this one is the duplicate to remove — it exists so the opening has water to happen on.

The four moments

Each is a cutscene definition in its own module, so it can be watched and seeked while it is being authored:

zero cutscene play staging.df_cs_opening
zero cutscene seek 12
zero cutscene rate 0.25

They fire off Core events and never off a timer:

MomentFires on
openingphase → "opening", or the first phase → "dive" if that phase is never declared
trenchdepth whose stratum is "trench", once
arrivalsighting:begin whose speciesId is "apex", once
resolutionidentify:result with actualId == "apex" and correct, or dive:end with reason == "apex"

Each emits cutscene { name, state = "start" | "end" } and holds Core.state.cinematic true while it runs. Any of them is also a plain call:

local S = require("staging.df_boot")
S.playOpening()  S.playTrench()  S.playArrival()  S.playResolution()
S.replay()       -- arm them all again

The letterbox is a post-process pass drawn over every UI screen. The opening runs at letterbox = 0.115 and the resolution at 0.125, so anything another slice draws within ~180 px of the top or bottom edge is covered while looking perfectly correct in its own widget tree. The caption sits 237 px up from the bottom for exactly this reason.

The caption screen — df-caption

Two things live on it, never at once.

local Cap = require("staging.df_captions")
Cap.say("One line of the notebook.", 4.5, "OPTIONAL SMALL CAPS ANNOTATION")
Cap.clear()
Cap.showPlate({ node = <plate tree>, title = "Plate the last",
                latin = "The Trench · drawn from life", footer = "884 m",
                name = "Lampas abyssi" })
Cap.hidePlate()

Cap.SERIF is "EBGaramond" and Cap.SERIF_ITALIC is "EBGaramondItalic" — the two concrete faces this world's paper is set in. Core.TYPE.serif names the generic family; these are what actually resolve, and the journal and the shell should use the same two so the book reads as one book.

The specimen

Core.SPECIES.apex, from staging.df_sp_apex. It follows the species spec in game/df_core.module and adds four keys of its own:

KeyMeaning
noPlate = trueThe book ships no plate for it. Show blankPlate(size) on its page until it is identified.
nameable = trueThe player names it rather than choosing a name. Put the chosen name in Core.state.apexName (a string) and the resolution inks that; otherwise it inks defaultName.
defaultName"Lampas abyssi".
blankPlate(size)The empty ruled page. plate(size) is the inked plate and belongs only on the page after the identification lands.

It is ~13 m from the crown of the vault to the tips of its arms, against a 0.35 m moon jelly, and it lights itself: sixteen lanterns round the rim, two of them real point lights, and a red lure node out in front. It is found between 620 m and 1000 m, its holdSeconds is 70, and its shyness is zero — brightening the lamp neither frightens it nor interests it.

Two things that will cost you an hour if you do not know them

A point light with castsShadows left at its default contributes nothing at all in this scene. Every light this slice creates passes castsShadows = false explicitly. The deck lamp lit nothing whatever at intensity 400 with shadows on, and lit the whole boat at 118 with them off.

Registering a screen id that already has a ui_<id> entity can leave the old entity standing, and the stale one is what the renderer draws. The tree reads back perfectly from ui.getScreenTree while every width on screen is ignored. df_captions.register() despawns any ui_df-caption leftovers before it registers. If a screen of yours renders a tree you cannot find in your own code, look for a duplicate ui_<id> entity first.

The camera

game/DfCameraRig.component is this slice's. On top of the resting station it attends to whatever is in the water (the aim eases onto the animal and the station backs off in proportion to spec.size), closes in as depth increases, and takes a scripted move through overrideActive / overrideBlend / overridePos / overrideLook / overrideFov, plus shake and rollDeg. A full cutscene does not come through it — cutscene.play puts its own camera above every camera in the scene — so those fields are for beats that stay in the player's own view.