# PORT BRIEF: the rules every porter keeps (coordinator, 29 Oct 00:00). READ FULLY BEFORE PORTING ANYTHING.

The user, 28 Oct ~23:40-00:00:
- "port kills in batches ... fair for everyweapon too, excluded thing not build yet. rework will now done directly when porting"
- "make sure quality is meeets, build it exactly like we see or even better of that but never less than that"
- "anything causing too much lage or perfomance issue, jst do something better efficient"
- "ALWAYS keep in mind of all our rules"
- "dont forget our cinematic rules etc too. also go parrlel as u want and as much we capable of, make things fast, but not compramising any step"

## 0. Where things are
- **Plan and tracking:**
  - the plan: `_tools/coord/PORT_BATCHES.md`;
  - the tracker page: `65_port_batches.html`;
  - state: `_tools/coord/port_batches.json`. Only the coordinator ticks, via `_tools/port_batches_gen.py`.
- **Architecture and how to port one kill:** `_tools/coord/PORT_ARCH.md`.
- **The gate:** `_tools/PORT_GATE.md` (parity, perf, 18 arenas, the look, edge cases, cosmetics, the coordinator's look).
- **House rules:**
  - `_tools/58k_BRIEF.md`;
  - the user's taste: `_tools/coord/USER_TASTE.md`;
  - STYLE 3: `_tools/coord/STYLE3_REALISM.md` + `~/.claude/skills/style3-realistic-kill/SKILL.md`.

## 1. Quality: the page is the floor, never the ceiling
- **Port exactly what the page shows NOW, or better.**
  - "Now" means the page with every 28 Oct central fix on (section 4).
  - "Better" means fewer bugs, smoother motion, cleaner silhouettes. It never means a different concept, choreography or ending.
- **The cinematic rules are part of "what we see".** Keep each of them exactly:
  - eased speed ramps (never hard jumps): fast motion 1.5-2x, super slow 0.05-0.12x on the 1-2 key moments only, snap back to 1x on the payoff;
  - the slow-mo SOUND on every slow-mo: low-pass ~300-500 Hz, pitch down ~6-10 semitones, long reverb, a whoosh in, an optional heartbeat, a hard cut back to full spectrum on the snap;
  - the grade: CINEMA teal-orange + contrast, SLOWMO_COLD in slow-mo, the 1-2 frame IMPACT_SPLIT, light grain, a gentle vignette;
  - the layered MULTICAM panels: straight edges, thin dark gutters, slide in/out, ≤ ~1.2 s;
  - realCam handheld drift (no shake);
  - mocap motion, with foot locks and weight transfer;
  - the anticipation → snap → hold rhythm (THE X movement bar).
- **The STYLE never changes:**
  - **Bodies:** no faces ever (blank glossy heads), no bones (the SPINE RIP is the only exception), no organs, nothing painted on bodies, no rings or circles as effects.
  - **Gore:** the old game's look (teardrop blood, wet splats, glossy pools, pulsing spurts, the radial pop, round wet caps on cuts, limb-off + spray). Death is the soul rise.
  - **The gore ladder:** each level has its own ending in the same timing; XT is visibly the strongest; LOW and VL never get a head explosion and are alive by design.
  - **Nothing over a head:** no prop, limb, plate, effect or text crosses any fighter's head or face. The gold FARIS BASHA plate is never covered, clipped or dimmed.
  - **Weapons:** held correctly in every frame (blade forward from the fist, two hands accounted for, no gun hug, low back quiver). Dropped weapons land flat.
  - **Camera:** wide. Zoom floor 320, punch-ins ≤ 0.5 s. The final is wide at roll 0 with both full bodies, the floor and headroom.
  - **No on-screen words during the action** (the word cards are off; a kill's own in-world signs stay).
  - **Motion:** no slide, pop, float, sink, walking in place, rubber limbs or 2D flips.
- **Fighters and arenas:** fighters wear their REAL gameplay cosmetics and the film plays on the REAL arena art. Only the page's grade sits on top.

## 1b. WEAPON RULE (user 29 Oct, _tools/coord/WEAPON_RULE.md)
- A weapon the game has is the game's own weapon in every frame (K.drawWeaponAt / the body's held weapon; the game look). It drops and flies with physical arcs that land flat (the game player hands it to item physics).
- A weapon or weapon-like prop the game doesn't have is ink-cast (K.inkCast, the OFFERED HAND ink look).
- The audit is _tools/coord/WEAPON_AUDIT.md. A kill's FIX step isn't ticked until its weapon lines are converted.

## 2. Performance wins over parity (user 26 Oct: "so laggy"; for all low / medium / high devices)
- **Hard budgets on the Mac player at LOW, MED and HIGH, and with -perfslow 6:**
  - frame p95 ≤ 16.7 ms, max ≤ 33 ms;
  - begin ≤ 16.7 ms;
  - 0 B GC per frame in steady state;
  - no hitch at the film's start or end.
- **Optimise the implementation first:** cache, pool, bake settled blood, batch, run small fx at half rate. Everything goes through the FILM QUALITY caps: extras are MED+, multicam insets are a snapshot or off at LOW.
- **If something is still heavy, build a more efficient equivalent that LOOKS the same.** Cut a visual only when a tier's budget can't be met any other way, and say so on the sheet.

## 3. FIXABLE / REWORK / NEW-FLAGGED kills
- **Fix them during their port, first on the page and then in the game, so the page stays the reference.** The fix notes are on the tracker (from `_tools/coord/verify/<weapon>.md`, the 28 Oct strict re-checks and builder STATE files).
- **Page fixes follow the old page rules:**
  - shared files only under flock58;
  - `node --check` before every swap;
  - motionQA at 0 FAIL at g5 and g0, with the strict faceless check. **Run it ON THE VM** (29 Oct: the Mac is the bottleneck, 8 GB RAM and swapping):
    - `bash _tools/vm_motionqa.sh <key> [more keys] --gore 5,0` pushes your changed page files to the VM mirror (rsync, no delete, so no wait for the 60 s autosync), runs the same strict `motionqa.cjs` there (at most 2 page Chromes on the VM, fewer while its players run; it waits by itself), and copies `<key>.qa.png/.json/.txt` back to `/Volumes/Workspace/Scratch/qa/g5/` and `/g0/` (one gore: straight into `--out`, default `/Volumes/Workspace/Scratch/qa`). It prints the same report. Exit 1 = a FAIL.
    - Every motionqa flag passes through: `--page 58k_x.html`, `--pre 'K58.X=false'` (A/B a valve), `--th k=v`, `--lead 1`, `--strip 10`, `--out dir`.
    - Review strips: `bash _tools/vm_motionqa.sh --strip <key> <t0> <t1> [--n 8] [--gore 5] [--pre ..] [--w 480]` writes `<out>/<key>.strip_<t0>-<t1>_g<gore>.png` (frames evenly from t0 to t1, film time on each).
    - Local renders (`bash _tools/render_slot.sh node _tools/motionqa.cjs <key>`, `node _tools/qa_strip.cjs ...`) only when the VM is down, and never while the Mac's swap is over 5 GB;
  - one render at a time.
- **REWORK means a real rebuild of what's broken.** Keep the concept when it works; otherwise bring a REPLACE plan to the coordinator before building.

## 4. The 28 Oct central page fixes the game must match
GAIT58, TRIGSETTLE58, RESUMESETTLE58, PULLSIDE58, GRIPSIDE58, CASTELBOW58, CASTBACK58, DIEPOSE58, SHORTANG58, LIMBOFF58, WLOAD58, BACKPACK58, FLAT58, PYR58, WORDS58 (off), plus the STYLE 3 grade crossfade string fix. The foundation stream ports these into the game engine before batch 1. Porters rely on them and don't re-implement them per kill.

## 5. Kill endings (user 28 Oct: "text covering animation ending ... too much time for the gloat ... too much waiting idle time")
- **ALL AFTER (page 56):** no kill-cam UI text during the action, then one recap card after the film, beside the winner. The gloat uses the EDGE COLUMN.
- **Timing targets:**
  - the recap card and the picked gloat start ≤ 0.3 s after the film's last motion;
  - ROUND OVER comes ≤ 1.0 s after the gloat ends, or ≤ 1.0 s after the film if there is no gloat;
  - no other idle hold.
- **The foundation stream owns this.** Porters only check that their kill's ending lands clean under it.

## 6. Parallel work without breaking anything
- **Unity:** one Unity at a time on the Mac, through `locked.sh`, shared with the online-features session. Never wrap build_test.sh in locked.sh. Heavy builds and labs can go to the bashatest VM.
- **Git:**
  - each porter works only in its own worktree and branch;
  - `git add <paths>` only, plain commit messages;
  - no push, no merge into v4, no destructive git;
  - the coordinator merges a batch only after the user's OK.
- **Machine and conduct:**
  - load: park at a 5-min load > ~35 or memory free < ~25 %;
  - headless Chrome only (`--headless=new`, private profile);
  - never pkill/killall; kill only your own PIDs;
  - never print keys;
  - no store builds;
  - delete files only with python on absolute paths, never `rm -rf`.

## 7. Report per kill (to the coordinator)
`key | NAME | batch | fix done (if any) | parity 6/6 (poses / rng / blood / region SSIM) | perf L/M/H/slow p95-max-begin-GC | arenas 18/18 + zone | look notes | edge cases | sheet path`
Include:
- a side-by-side strip (page vs game) at gore 5 and gore 0;
- the 6 finals;
- the 18-arena contact sheet.

The coordinator reviews every frame before ticking.