# asc_clock — ASCENSION: the shared clock
The finale's spine. One pure function of part-local `t` produces every number
that crosses between the part's eight aspects. **Nothing else in ASCENSION
reads raw `t`, wall time or a frame counter** — the orchestrator evaluates this
module once per frame and hands the resulting table to every aspect hook.
Eight aspects reading the same numbers resolve into one scene. Eight aspects
each keying off their own idea of the beat do not. That is the entire reason
this module exists.
## How you use it
Your hook is handed the bus. It is the third argument, always:
```lua
function M.update(ctx, st, ck, dt)
entity(st.id).localPosition = ctx.at(0, ck.seedY, 0) -- yes
-- local phase = t / 1.25 -- no. never.
end
```
`build(ctx, st, ck)` and `enter(ctx, st, ck)` get it too, evaluated at t = 0.
To read it outside the update chain, `asc_clock.current()` returns the last
published bus (`nil` before the part's first frame).
## The bus — the brief's §3, and nothing else
Top level is exactly the §3 contract. Every value is hard-clamped to its
stated range; a curve can be retuned but it cannot escape its bounds.
| field | range | what it is |
|---|---|---|
| `t` | 0 … 35 | part-local seconds |
| `bar` | 0 … 28 | `t / 1.25`, float. `floor(bar)` is the bar index |
| `phase` | 1 … 7 | `floor(bar/4) + 1` |
| `sunElev` | 4 … 12 | degrees above horizon |
| `sunAzim` | 118 | degrees. Constant for the whole part |
| `sunInt` | 0 … 12 | sun intensity, engine units. Already multiplied by `worldLight` |
| `sunColor` | `{r,g,b}` | linear |
| `skyMix` | 0 … 1 | 0 = full daylight gradient, 1 = flat void black |
| `depth` | 1 … 0 | camera submersion. 1 at y = −4.2, 0 at y ≥ 0, crosses 0 at t = 5.000 exactly |
| `alt` | −4.2 … 900 | camera altitude in units |
| `rise` | 0 … 1 | column raise envelope. 0 before 2.50, 1 at 12.50 |
| `colTopY` | 0 … 900 | column top height, units |
| `strike` | 0 … 1 | bolt envelope. Impulses on the resolved cue and at +3 / +6 beats, 12-frame decay each |
| `flicker` | 0 … 1 | residual column glow, 11 Hz, live from the strike to 25.0, amplitude 1 → 0.25 |
| `ignite` | 0 … 1 | fire coverage on the column's top 200 u. 0 → 1 across 25.000 → the opening |
| `apex` | 0 … 1 | seed-opening envelope. 1 on the opening cue, 0 by 27.500 |
| `ringR` | 0 … 600 | additive shell radius in units. Passes the locked camera (116.3 u) at t ≈ 26.9 |
| `seedY` | −4.2 … 780 | seed world Y, units |
| `seedInt` | 0 … 2000 | seed point-light intensity |
| `worldLight` | 1 … 0 | **global light authority.** 1.0 until 27.5, 0.0 at 30.0, stays 0 |
| `expEV` | −1.4 … +1.2 | exposure offset, EV |
| `cue` | integer | index into the composed cue track: how many cues have passed |
| `band` | `{sub,low,mid,high}` | STFT band levels, 0 … 1, raw |
| `flux` | 0 … 1 | spectral flux, raw |
`worldLight` is the most consequential number in the part. **Every light you
create multiplies by it**, including yours. It is how the seed's opening takes
the daylight with it, and from t = 30.000 nothing in the scene is lit — only
emissive.
## `aux` — §5 / §6 values, not the §3 contract
Several aspects would otherwise re-derive the palette and the light table by
hand and drift apart. Those live under `ck.aux`, which is derived, documented
here, and equally a pure function of `t`:
`sunDir` · `skyZenith` · `skyHorizon` · `skyMid` · `skyVoid` · `skyCeil` ·
`horizonTight` · `midUp` · `zenRate` · `antiSun` · `sceneExposure` ·
`gradeSat` · `gradeBri` · `ambInt` · `ambColor` · `bloomThreshold` ·
`bloomContribution` · `letterbox` · `phraseMix` · `phraseFrom` · `phraseTo` ·
`strikeT` · `openT` · `cueKind` · `cueT` · `globalT` · `handoffNdc` ·
`handoffHex` · `barNum` · `pointAmp` · `quality` · `autoLadder` · `frameMs` ·
`gpuMs` · `shadowStrength` · `sunDiscScale` · `emberLights` · `dustLitByFire` ·
`typeReveal` · `typeGlow` · `torTrack` · `torTrackN` · **`torSpinAccum`** ·
**`torTear`**
The last two are TORNADO's amendments, added under §8's append-only right and
read by that aspect alone.
`torSpinAccum` (0…27.5) is **∫ `torSpin` dt in REVOLUTIONS** — the rotational
twin of `windAccum`, and it exists for the same reason. `torSpin` is an angular
RATE, and a fill shader handed a rate has to integrate it to get an angle;
integrating per frame would make every seek a different tornado, which §5 forbids
in as many words. It is a cumulative table built once at module load and sampled
at `t`, so the column's rotation is a pure function of `t` and a held frame is
byte-identical however often it is captured.
`torTear` (0…1) is the collapse's loss of **axis**, which `ignite` does not
carry. `ignite` falling 1.00 → 0.25 → 0 across 25.0 → 28.2 is the fire going out
TOP-DOWN — the same fire front that swept up on ignition, sweeping back down.
`torTear` is the other half: how far the three flame ropes have separated from
the axis and drifted downwind. The two are genuinely independent, and `ignite`
alone cannot tell t = 12 (rising through 0.1) from t = 27.8 (falling through
0.1), which are not the same picture at all.
`skyVoid` is the colour `skyMix` folds the gradient **toward**. §3 calls
skyMix's far end "flat void black" without saying what black; §5 rule 2 does:
"Every dark value carries blue. Void is `#03080C`, never `#000000`, until
t = 33.75." So the void is on a curve — §5 P4's flat `#060A12` while the world
still has light in it, `#03080C` once the world is out, real black only across
t 33.75 → 34.00 — and any aspect that folds something toward the void folds it
toward this, not toward a constant of its own.
`skyMid` is the crossover colour §5's two ends need between them, solved by
`asc_palette` against rule 1's two failure conditions. **An aspect drawing its
own sky-adjacent medium should read this rather than average the two ends** —
averaging them is what puts a neutral on screen, and the proof is in
`asc_palette`'s README.
### The sky rows are DISPLAY values. Everything else on the bus is linear.
`skyZenith` / `skyHorizon` / `skyMid` / `skyVoid` are **sRGB display fractions**
— exactly what §5 wrote — and `M.C` / `sunColor` / `ambColor` are **linear**.
That split is not an inconsistency, it is the two kinds of surface:
**LIT surface → linear.** Use `M.C`, or `Palette.hexL("#…")`. The render and the
tonemap decide what the value becomes, which is the point of authoring in
linear, and §5's header ("convert to linear at load") is the whole instruction.
**EMISSIVE surface that fills frame → display.** A sky dome, a volume's emission
term, a full-screen pass: §5's hex is what the pixel must READ AS, and getting
there means inverting the post chain. Do not hand-roll that. `asc_palette` owns
it: `ceilFor`, `invAces`, `unSaturate`, and the ramp. The dome shader
(`preseed/shaders/asc_sky`) is the worked example — it blends in display space
and applies the inverse once at the end.
Three numbers on the bus exist so a consumer can do that without re-deriving
anything:
- **`sceneExposure`** — everything multiplicative between a scene value and the
tonemap's input (`BASE_EXPOSURE · 2^expEV · gradeBri`). Divide by it.
- **`gradeSat`** — the colorGrade pass's saturation, to un-apply.
- **`skyCeil`** — the brightest display value an emissive sky-scale element may
ask for, derived from §2's bloom threshold and this frame's exposure. §6 lets
exactly one element per bar exceed 1.0 linear and the sky is never it. Scale the
**whole triple** to fit the ceiling, never each channel — a per-channel clamp
pulls the brightest channel toward the others and walks the colour off its hue
family.
Feeding a dark palette row as plain linear loses it outright: ACES's slope near
zero is 0.03/0.14, so `#060A12` arrives at 0.0018 and leaves at 0.0004, a ninth
of one 8-bit step. Measured, that came back 82 % literal `#000000`.
### The palette gate
`asc_clock.checkPalette()` replays the dome's blend law against the triples the
dome actually receives at each of the sixteen judged timestamps and reports §5's
two hard rules as numbers. Run it after changing any curve that touches the sky.
| detector | budget | now |
|---|---|---|
| magenta family (green below both others) | 0.00 % | 0.00 % at all 16 |
| (max−min)/max < 0.25 | ≤ 2 % | 0.00 % at 11, 1.09–1.39 % at 5 |
| (max−min) ≤ 20 | ≤ 2 % | 0.00 % at 11, 0.39–1.80 % at 5 |
The magenta budget is zero because that family is exactly avoidable. The
low-saturation budgets are not zero and cannot be: §5's two ends have a
display-space chord that passes within one unit of the achromatic axis, so some
sample on any continuous ramp between them sits near neutral. `asc_palette`'s
README carries the arithmetic and the on-screen figures, which are larger than the
function's because a level camera compresses many screen rows into a small range
of elevation near the horizon.
`phraseMix` is the phrase-boundary cross-fade: it runs 0 → 1 across the 0.75 s
centred on each boundary (t = 5, 10, 15, 20, 25, 30) and reads 1 everywhere
else, so a grade owner can lerp `phraseFrom` → `phraseTo`.
`M.C` on the module is §5's palette, authored in sRGB hex and converted to
linear once at load. Use it rather than re-typing a hex string.
## The two cue-fired events
The strike and the seed's opening fire off the **score**, not a timer.
`resolveCues()` snaps their nominal beats (15.000 and 26.250) onto the nearest
cue within ±0.30 s, once, at part build, preferring the kinds that carry a
downbeat. Against the current score they resolve to a `kick` at 15.000 and a
`motif` at 26.250 — exactly on the beat, and now genuinely tied to the audio:
if the composer moves the drop, the image moves with it.
The envelope around the resolved instant is a pure function of `t`, so a held
preview frame stays byte-identical however many times you capture it.
## The ENDCARD handoff
`asc_clock.handoff()` returns everything that crosses the part boundary:
```lua
{ ndc = { 0.0, 0.060 }, hex = "#FFF0C8", color = { … linear … } }
```
Two numbers and a colour. No buffer, no texture, no starfield.
## The debug overlay
Off by default. It prints the whole bus on screen, live, so you can check your
curves against the spine's. `require` is environment-local, so an `execute`
call gets its own copy of this module and cannot reach the running part's —
arm it through the engine-global request instead:
```lua
require("preseed.asc.asc_clock").requestOverlay(true) -- and (false) to clear
```
The part picks it up within a quarter of a second. Once it is up,
`ui.getScreenTree("asc_clock_bus")` reads the printed values back, so the
overlay is a readout as well as a picture. It costs no measurable frame time
while on, and nothing at all while off.
## §10's cut ladder — read `aux.quality`, never decide for yourself
§10 fixes six cuts in a strict order and assigns them to no aspect. There is
**one** position, it is on the bus as `ck.aux.quality` (0 = nothing cut, 6 =
every rung spent), and the rule is: if your system is named at or at a lower
rung than the live position, drop to your cut setting. Nobody negotiates and
nobody measures their own cost.
```lua
if ck.aux.quality >= 3 then steps = 30 else steps = 40 end -- rung ③
```
`M.CUT_LADDER` is the ordered list. The position moves **automatically**, and it
moves on the only signal that is both correct and affordable.
**Not the frame delta.** Wall-clock frame-to-frame time is work plus however long
the engine waited to present, and on this machine that is 99 ms of present/idle
vsync wait around 4 ms of real work. An earlier pass drove the ladder from it,
spent all six rungs within seconds of boot and never gave one back, because the
release threshold is a frame time a compositor-throttled window cannot reach.
`profiler frame`, the tree that does separate work from pacing, costs 39 ms per
sample — twice the budget it would protect.
**`profiler gpu`.** It reads resolved GPU **timestamp queries** out of a ring the
renderer already fills, is compositor-independent by construction, and measures
at **0.21 ms** per call. Sampled once every 30 frames it costs 3.5 µs a frame —
0.02 % of budget. Its header line carries the attributed pass total, which is the
number §10's own table is written in.
The ladder arms on a five-sample median at or above **15.5 ms**, spends **one**
rung at a time in §10's order, and gives a rung back only after four consecutive
samples at or under **13.0 ms**, so it cannot oscillate. Both numbers are on the
bus: `aux.gpuMs` (GPU timestamps, the ladder's signal) and `aux.frameMs`
(wall-clock, including vsync wait, labelled for what it is).
`asc_clock.setQuality(n)` still overrides by hand, and `setAutoLadder(false)`
pins it — a measurement can be wrong and a director cannot be argued with.
`asc_clock.sampleCost()` takes one sample on demand and returns
`{ gpuMs, frameMs, quality, auto, ladder }`, for the moment a cost claim has to be
backed by an artifact rather than by prose.
**No rung on §10's ladder touches §10's never-touch list, and that is checkable
rather than asserted.** The list is the column's LIGHT march, camera motion blur,
the type's legibility and the sun's shadow cascades. The six rungs are the fire
volume's resolution and step count, the ember point lights, the column far
shell's VIEW steps, the cloud deck's step count, the SPH particle count and DOF
quality. The two column entries are different marches.
## World conventions
Published on the module so nobody re-types them: `BAR` `BEAT` `DURATION`
`BARS` `SUN_AZIM` `LETTERBOX` `COL_BASE_R` `COL_WAIST_R` `COL_WAIST_Y`
`ANVIL_R` `ANVIL_Y0` `ANVIL_Y1` `COL_TOP` `SEED_LEN` `SEED_START_Y`
`SEED_TOP_Y` `CAM_TOP_Y` `CUT_T` `MAX_POINT_LIGHTS` `MAX_PARTICLES`.
## What `expEV` is for
§3 gives it the range −1.4 … +1.2 and §4 fixes two keys: 0 at t = 27.500 and −1.4
four bars later. What the positive headroom is FOR is fixed by §6 and §2 together,
and it is not a look.
§5's bright phrases ask the sky for `#FF9A5A` and `#FFC98A`, whose brightest
channel is display 1.0, and the scene-linear value that lands on display 1.0 is
7.24 — five times §2's bloom threshold. Exposure is what divides the value the sky
has to ask for: at `expEV = +1.2` the horizon arrives at 1.35 linear, under the
threshold, and reads within 4/255 of its hex. At `expEV = 0` the ceiling lands
27/255 short and §5's row is unreachable.
So `expEV` is high exactly where §5's palette is bright — +1.2 across the breach
(t 5–12.5) and the breakout (t 23–26.25), 0 through the blackout, down to −1.4 as
the world goes out. **It is also the part's only real exposure move**: the sky
cancels it (the sky lands on §5 whatever it does), so from the blackout's 0.0 to
the breakout's +1.2, every element that is not the sky gets 1.2 stops brighter.
That is §8 H4's "the eye should have to adjust", as a number.
## Owns
- every scalar on the bus and the keyframes behind it
- the STFT binding and the cue-track resolution
- the phrase-boundary cross-fade — both the weights and the values
(`aux.gradeSat` / `aux.gradeBri`), because `aux.sceneExposure` is `gradeBri`
times the tonemap's exposure and two files cannot own half a product each
- the §5 palette → display seam (`asc_palette`) and the gate over it
- the ENDCARD handoff
- the debug overlay
- §10's cut-ladder position and the GPU signal that moves it
## Does not own
Any visual element. This module spawns nothing and draws nothing but the
overlay.
·computeshader · born here
# asc_pyre
ASCENSION's fire tornado, filled one invocation per voxel into a 128 × 256 × 128
emissive volume and raymarched by `preseed.volume`.
## The rotation
Three things make the column read as turning, and all three have to be present.
1. Every noise field is sampled in a cylindrical frame whose angular coordinate
is advanced by the accumulated spin in revolutions, so the surface moves
between frames. The advance is **differential** — faster at the inner radii —
which is the vortex's own shear.
2. The frame is **twisted with height**, so every feature is a helix in a frozen
frame: at the waist radius a feature leans about 50° off vertical, and the
lean grows with radius so the wind tightens toward the silhouette edge.
3. The noise is strongly **anisotropic** — five times longer along the axis than
around it *before* the twist — because shearing something already long is
what produces a long thin diagonal ribbon rather than a slightly tilted lump.
On top of those, an **integer number of angular lobes** carries the read through
the raymarch. A volume is integrated along a chord that crosses many azimuths,
and the average of a helix is not a helix; a `sin(N·a)` term survives it, is
continuous across `atan2`'s branch cut, and — evaluated on the outer shell, where
a dense medium's near wall carries the radiance — arrives on screen as the
banding the eye reads as a wound surface.
The spin angle arrives as a cumulative table sampled at `t`, so the whole fill is
a pure function of `t` and a held frame is identical however often it is taken.
## The profile
The **body** is monotone-narrowing root to tip: a root swell that has decayed by
the bottom 30 u (an absolute height, not a fraction of the column's), the waist,
then a steady thinning to two thirds of it at the top. The **skirt** is a
separate wide, low, ragged, wind-blown term in the bottom 26 u and never enters
the body's silhouette. The **anvil** is a separate cap whose radius is capped
*below* the root swell, offset downwind by more than half its own radius and
stretched along the wind — a sheared anvil rather than a radially symmetric cap.
## Fire, dust and the collapse
`ignite` is the fraction of the column height that is burning, measured from the
root, so one scalar carries both the 0.30 s root-to-tip ignition and the top-down
collapse. Below the front the same volume is emissive **hot dust**, brighter than
the murk behind it rather than a hole in it; the anvil is always dust with an
amber belly where the fire below reaches it.
`tear` throws the three ropes off the axis on 120°-separated bearings, lifts them
into their upper reach, and kills everything else; the ropes carry their own fire
so they go out as flame rather than as smoke.
## Colour
`cLow` / `cMid` / `cUp` / `cCore` / `cDust` / `cSkirt` arrive as **scene-linear
radiance** that the engine's ACES fit maps onto the accent row, scaled by the
display ceiling the post chain delivers and divided by the frame's own
`sceneExposure`. Dimming is a **mix toward a darker authored ember**, never a
multiply: the tonemap is compressive in red and near-linear in blue, so a scaled
`#FF7A22` comes back a scarlet and a ramp authored in display ratios comes back
neutral. Nothing here is white; the hottest value is `#FFF0C8`.
## Density
Density is occlusion, and the composite is `scene*(1−a) + rgb`, so a term
carrying more density than emission is a hole in the frame. The lanes between the
angular bands go to **zero**, not to a floor, so the scene behind shows through
and the frame keeps something dark to read the fire against. Density fades out
over the last 7 u above the sand, so the column dies *into* the surface instead
of ending on the volume's floor slab, and it fades around the camera — tightly
while the column is whole, widely during the collapse, when the crane is inside
the box.
RGB is emission, alpha is density. `U` carries 41 f32s and the index list is in
the shader's header.