Deep Field
README.md
ui/shell — the authored screens
Slice presentation. Five screens, one owner each, all laid out for the
1080x1440 portrait frame: the title, the field card, the HUD, the held line
and the two end cards.
| Screen id | Module | What it is |
|---|---|---|
df-title | df_screen_title | The illustration, the name, and the two things you can do |
df-howto | df_screen_howto | The field card that teaches the lamp trade-off in one read |
df-hud | df_screen_hud | The instruments: depth gauge, lamp dial, attention, the sighting |
df-pause | df_screen_pause | The held line, and the dive so far |
df-end | df_screen_end | The lamp is out, or the specimen is named |
How it runs
ui.shell.df_boot is the boot module the scene entrypoint calls. It starts
ui.shell.df_shell — the state machine that owns which screen is on the glass
— and spawns one entity, df_shell_ui, carrying DfShell.component. The
component exists only because a UI callback is delivered to onCallback on a
component or a scene entrypoint and nowhere else; it forwards the tick and the
callback into the module and holds no state of its own.
df_shell_style is the shared look (palette, faces, rule, keycap, paper card,
glass pane, action, stat row, motion) and df_shell_art is the drawn work.
What this slice listens for and what it asks for
It follows these events, all of them core-loop's:
phase—titleshows the title,dive/journalshow the HUD,opening/resolutionclear the glass for the staging slice's captions,endshows the end card.dive:end { reason }— shows the end card.reason = "apex"resolves the game (the specimen is named); anything else ends the dive.stratum:unlocked— rebuilds the gauge so the new band lights.
It emits three requests. They are requests, not facts: this slice does not own the phase, so it asks and core-loop decides.
ui:begin {}— the player pressed Begin the dive.ui:pause { paused }— the player held or released the line.ui:quit { reason }— the player chose to haul in.
ui:begin has a fallback. If nothing has moved Core.state.phase off
"title" 0.7 s after the request, the shell moves it itself, so the title
screen's only button always does something whether or not core-loop is in the
world yet. When core-loop handles ui:begin, the fallback never fires.
Reaching the screens by playing
Everything is reachable from the keyboard and the mouse; no execute call is
needed to show a screen.
| From | Action | To |
|---|---|---|
| title | click Begin the dive, or SPACE / ENTER | HUD |
| title | click How to read the water, or H | field card |
| field card | click Lower the lure, or SPACE | HUD |
| field card | click Back, or ESC | title (or the held line) |
| HUD | ESC | held line |
| held line | click Resume, or ESC / SPACE | HUD |
| held line | click Field procedure | field card |
| held line | click Haul in and end the dive | end card |
| end card | click the primary button, or SPACE / ESC | title |
W S Q E belong to the lure and J to the journal; the shell never
takes them.
Two things that shape every screen here
An svg widget draws in an element capture but not on the glass. Every
drawing in this slice is therefore either an image of an imported .svg
asset (art/*.svg, registered as textures — df_shell_art.REF names them) or
drawn in CSS. The lamp dial is a conic gradient plus a rotated bar, the lure
bead on the gauge is a glowing disc, and the book's mark is a rotated square
(S.lozenge). df_shell_art.regenerate() rewrites the .svg assets from the
generators in that module, so the art stays authored in code.
Motion is off unless the simulation is running. Edit mode pauses time, so
an entrance animation holds its first keyframe forever — and that keyframe is
opacity: 0, which makes the whole screen invisible. Every animation comes
from S.riseIn / S.fadeIn / S.breathe, and S.setMotion(false) turns all
three into nil in one call. The shell drives it from whether it is ticking
live, and rebuilds the screens that carry entrances when it changes.
Layout notes worth keeping
- A wrapping label needs its width on the container, and that container
must not centre-align it: a centred parent makes the label hug its content
and collapse to one glyph per line. Centre the text with
textAlign. - An empty flex child grows to absorb a column's leftover space however
tall it is declared, so vertical rhythm is
marginTop, never a spacer box. - The HUD is composed of absolutely-positioned bands over a root that carries
only a size and
position— no background, no overflow. That is the one configuration whose layout has held steady here.