# 58k API · the kill DEF FORMAT, the READY flag, the loader (short copy of the 58k_page.js header)

Owner: KILLPAGES-A. Full docs: the headers of `58k_page.js` (the page / loader / defs) and `58k_cine.js` (the cinematic layer).

## 1 · Register a kill (any one of these works; the shell adapts them all)
```js
K58.kill({                       // native (recommended)
  w: 'smg',                      // weapon id (K40 ids; 'fists' for fists)
  id: 'autograph',               // unique inside the weapon (slug); key becomes 'smg.autograph'
  name: 'THE AUTOGRAPH',
  rarity: 'MYTHIC',              // COMMON | RARE | EPIC | LEGENDARY | MYTHIC
  needs: ['wall', 'foe2'],       // keys of K58.NEEDS (any flat wall ceiling ledge foe2 foe3 water height plat gap barrel sky face behind run stage) or free text
  arena: 'castle',               // castle | saloon | rooftops | backyard | stage (THE CINEMATIC STAGE) | any K.ARENAS key you add
  len: 9.5,                      // SCENE seconds (slow-mo / freezes are added on top by the clock)
  cam: 'bullet-ride · panels',   // the camera note on the card
  sum: 'One line: the beats in a sentence.',
  beats: [[0, 'SET-UP'], [1.2, 'FIRST HIT'], [3.0, 'X-RAY'], [8.0, 'CARD']],   // scene times, shown on the scrub track
  poster: 3.1,                   // scene time for the card thumbnail + the stage poster (optional)
  vic: 'fida',                   // optional: who dies (K.CAST key)
  by: 'B', lane: 'PRECISION + RANGE',   // optional
  script: ['1 · …', '2 · …'],    // the beat-by-beat script, shown on the IN PROGRESS card (string or array)
  ready: true,                   // <<< THE READY FLAG. false / missing = IN PROGRESS card (script + stamp, PLAY disabled)
  cam0: { x: 800, y: 520, w: 380 },
  build(s) { /* K40 Scene vocabulary + the 58k_cine.js CineScene extras (s.crash, s.panels, s.slice, …) */ },
});
K58.skin({ w: 'smg', skin: 'gold', name: '…', ready: true, build(s) {…} });   // the 7 skin kills (A only on smg)
```
Also accepted (adapters, so existing kits keep working): `K58.add(w, def)`, `K58.adopt(def)` (def.weapon = w, def.kind 'new'|'skin'),
`K58.register(key, meta, kills)`, `K58.weapon({ weapon, kills:[…], skins:[…] })`. At boot the shell also sweeps
`K40.RIF.KILLS`, `KE.PAGES`, `K58F_REG` and `KC_SMGC` for anything registered without a hook. Field aliases: `weapon`=`w`,
`beat`/`line`/`summary`=`sum`, `camera`=`cam`, `plan`/`story`=`script`, `kind:'skin'` or a non-classic `skin` = a skin kill.

Turn a kill playable later without touching the def: `K58.markReady('smg.autograph')` (or set `ready:true` and save).

## 2 · Time
Scripts run in SCENE seconds (K40). `s.slow(t, ts, ramp, hold, out)`, `s.stop(t, ms)`, `s.freeze(t, filmDur)`, `s.ramp(t0, t1, ts)`
build the FILM clock (what the viewer sees and scrubs). Call them at BUILD time (top level of build) so the scrub track
knows the length. Camera moves / overlays / cards run in film seconds. Everything is deterministic: drag-scrub works.

## 3 · Rules the shell enforces for you
- FARIS BASHA's GOLD plate is drawn by the shell, LAST, over his head, clamped in frame. Never draw your own plate.
- Word cards (`s.card`, `K.H.card`) dodge the plate automatically.
- The in-match HUD (pause, the two player cards, ROUND 3) shows for the first ~0.6 s, the kill feed + KILL CAM tag after `s.ko`.
- Layer hooks: K40's `s.drawBg / drawMid / drawTop / drawScreen` still work (assign or chain), plus `s.layer('bg'|'mid'|'top', fn)`.

## 4 · Files + loading
- `58k_<weapon>.html` loads the K40 engine, `58k_cine.js`, then (via `K58.load`) the SHARED kits in order
  (`58k_slice.js` …: missing ones are skipped quietly), then the lane files (`58k_w_smg_skins.js`, `58k_w_smg_b.js` … `_f.js`),
  then boots `58k_page.js`. Every defined kill shows as a card at once; IN PROGRESS until `ready: true`.
- Add a shared kit: append its file name to `K58.SHARED` in `58k_page.js` (A) or ask the coordinator.

## 5 · THE 3-PART FILM (REDO ROUND): gameplay lead-in → kill-cam trigger → the kill → exit
Every kill now plays as one film: A · GAMEPLAY (the real game HUD + controls, AUTO zoom, normal fighting, ends on the
killing hit) → B · KILL CAM TRIGGER (hit-stop freeze at the kill's frame 0, bars in, HUD out, KILL CAM stamp, grade) →
C · YOUR KILL (scene t 0 .. def.len, unchanged) → EXIT (bars out, HUD back, ROUND OVER, in the real arena).
The shell builds A automatically from your kill's frame-0 positions; tune it with `def.lead` (all optional):
```js
lead: {
  off: false,            // true = no gameplay lead-in (the trigger + exit still play)
  dur: 2.4,              // scene seconds of gameplay before the killing hit (1.2 .. 4)
  style: 'advance',      // 'advance' | 'retreat' | 'trade' | 'chase' | 'brawl' (auto from the distance if omitted)
  a: { from: 620, dx: -120, jump: -1.4 },        // killer: absolute start x, OR dx from his frame-0 x; a jump at scene t
  v: { from: 980, dx: 90, weapon: 'pistol', fights: 'shoot', jump: -1.0 },
                         // victim: start, his lead-in weapon ('pistol', 'ar', 'pump' … or null = fists; knocked out
                         // of his hand by the killing hit), fights: 'shoot' | 'punch' | 'dodge' | 'run' | 'none'
  kill: 'burst',         // the killing hit: 'shot' | 'burst' | 'punch' | 'kick' | 'swing' | 'cast' (default by weapon)
  hp: 118,               // Faris's HP when the kill cam triggers (the HUD bar + number; max 150)
  arena: 'castle',       // realm kills: the REAL arena the gameplay happens in (your realm arena comes after the crossing)
  cam: 'auto',           // or {x, y, w}: a fixed gameplay camera
  mode: 'DEATHMATCH', timer: 42,                // the round header
  trig: 0.85,            // film seconds of the trigger freeze
  exit: 2.2,             // scene seconds of the exit after def.len
  script(s, A, V, T0) {} // your own lead-in instead of the auto one: schedule at NEGATIVE scene times from T0 (= -dur)
                         // to 0; land the killing hit at about -0.05. Bodies must end at their frame-0 positions.
}
```
Scene hooks for the trigger + exit:
- `s.trig` = `{ t: 0, film: 0.85 }`: during the trigger the SCENE TIME IS FROZEN at 0, so animate set pieces on FILM time:
  `s.fspan(0, s.trig.film, (u, view) => …)` (u 0..1 over film seconds; works in any freeze). KIT-WORLD's s.inkIn does this.
- `s.onTrigger(fn(view, s))`, `s.onExit(fn(view, s))`; `s.exitT` = def.len (the exit starts there: ink your set pieces out).
- `s.deathCrack(t, { at, dur: 1.6, tilt, keep })` -> `{ t, film }`: THE DEATH-REALM SIGNATURE (time freezes, the colour drains
  to black and white from the hit, only blood + the gold name keep colour, a black-red crack splits the frame). KIT-WORLD's
  crossing starts after it. `s.setArena(key)` / `s.setArenaAt(t, key)` switch the arena (realm and back).
- The scrub track shows the parts as segments (GAMEPLAY · KILL CAM · KILL · ROUND OVER); PLAY starts from gameplay, a
  SKIP TO KILL chip jumps to the trigger. Your `beats` / `poster` stay in kill scene time, as before.