foitin/STUDY.md

FOITIN — Digitized Fighting Game: Source Study & Assessment

Study of Bikini Karate Babes 1 (4 ISOs) + BKB2: Warriors of Elysia (installed copy), cross-referenced with the "Digitized Fighting Game Tech Report" PDF. Goal: build our own original digitized-style fighter with MODELBEAST-generated assets, architected so new characters drop in as data.

---

1. How the original games actually work (reverse-engineered from BKB2 data)

Engine: Custom C++ on Gamebryo/NetImmerse (.nif scene files), Bink video (binkw32.dll), Miles Sound System (mss32.dll). 2011-era game.exe is only 1.4MB — the game is almost entirely data, which is why it worked as a formula.

The core architecture — one video clip per move:

Data/<Character>/            ← one folder per fighter (12 in BKB2, ~75-83 moves each)
  bik/<move>.bik             ← 512×512 Bink video @ 30fps, actor pre-keyed onto white
  zon/<move>.zon             ← "BKB!ZONE": per-frame collision boxes (9 zones × 8 ints/frame)
  geo/<move>.geo             ← "BKB!GEOM": per-frame root-motion / ground-offset track
  me2/<move>.me2             ← "BKB!DAT2": move properties (frame windows, damage, links)
  csd/ fpd/ off/             ← cancel/sound/offset sidecar data
  world.nif                  ← stage scene

Verified numbers (Venus):

• 81 moves, each its own clip: idle stand (19f loop), jab handa (53f), punches handa-e, kicks kicka-…, specials spec1/2, blocks, ducks, hit reactions (bhit, lhit, bfall, bkfal…), throws, wins. ~202MB/character.
• handa.zon: magic BKB!ZONE, 53 frames, 9 collision zones per frame, each zone 8 big-endian ints (type, shape, …, x, y, w, h, flag). Hitboxes AND hurtboxes are hand-placed per frame — this was the labor bomb of the 90s pipeline.
• handa.geo: magic BKB!GEOM, 53 ints — per-frame X root position (~413px scale), i.e. baked root motion so the character slides correctly during lunging moves.
• The full-roster inventory: 3,461 .bik clips across the game (fights, UI slices, VS screens — even menu elements are positioned video slices named name-x360-y90-w256-h128.bik).

BKB1 discs: Discs 1–3 are InstallShield cabs (extractable with unshield if we ever want BKB1's 19-character data), Disc 4 carries the v1.08 patched BKB.exe. Not needed — BKB2's installed data is the better, complete reference.

What the formula gets right (why it's worth cloning):

1. Character = folder of clips + frame-indexed metadata. Adding a fighter = adding data, zero code.
2. Frame-indexed everything: collision, root motion, damage windows all keyed to video frame N.
3. Uniform base mechanics (the Mortal Kombat doctrine): shared move vocabulary across the roster (handa…hande, kicka…, bhit, bfall…) means the engine treats every character identically.

What it gets wrong (what we fix):

• 30fps and a 53-frame jab (1.77s!) — floaty, non-competitive feel. Modern standard: 60fps ticks, jab = 4-8f startup.
• White-keyed 512×512 video → halo edges, no lighting interaction, fixed camera scale.
• Hand-drawn hitboxes per frame — thousands of hours of labor we can automate.

---

2. Level of detail needed (the real answer)

Per-character clip budget — the minimum viable move set is ~30 clips, not 80

Category	Clips	Notes
Locomotion	6	idle loop, walk fwd/back, jump (up/fwd/back can share), duck
Defense	3	stand block, crouch block, block-stun
Normals	8	4 punches + 4 kicks (standing/crouching mix)
Specials	3–4	the character's identity moves
Reactions	6	head hit, body hit, low hit, knockdown fall, ground, get-up
Throw	2	throw + being-thrown
Ceremony	3	intro, win, dizzy
Total	~30–32	BKB's ~75 includes redundant variants + mirrored versions

At 60fps with modern pacing, average clip ≈ 30–60 frames → ~1,200–1,800 unique frames per character. That's the asset bill per fighter.

Per-move metadata (one JSON per move, replaces .zon/.geo/.me2)

{
  "name": "jab", "input": "LP", "damage": 30,
  "startup": 5, "active": [5, 8], "recovery": 14,
  "cancels": ["special", "super"], "onBlock": -2, "onHit": 3,
  "rootMotion": [0, 0, 2, 4, 4, 2, 0],
  "boxes": { "auto": true, "hitFrames": {"5-8": [{"bone": "handR", "r": 28}]} }
}

The one big modernization: auto-hitboxing

Run DWPose/RTMPose skeleton estimation over every rendered frame → generate per-frame capsule hurtboxes from joint positions automatically. Hand-author only the hit boxes (active frames of attacks), which is ~4 frames per attack. This deletes 95% of the 90s labor. It's also the same DWPose stack the MODELBEAST gen pipeline already uses for pose conditioning — one skeleton pass serves both generation and collision.

---

3. Recommended architecture for FOITIN

Asset strategy: 3D-first, rendered to digitized sprites ("3D digitized")

Instead of filming actors (BKB) or pure image-to-image chains (fragile identity), build each fighter as a textured 3D character and render the digitized look:

MODELBEAST pipeline per character:
1. FLUX + character LoRA        → master identity portrait(s)
2. Hunyuan3D-2.1 / TRELLIS      → textured, rigged-ready 3D mesh (GLB)
3. Auto-rig + mocap clips        → the SHARED move library (30 clips, retargeted per character)
4. Fixed orthographic camera     → render 60fps PNG frames + normal-map pass + depth pass
5. DWPose over renders           → auto hurtbox capsules per frame
6. Pack: WebP/basis atlas + JSON → drop-in character folder

Why this beats video capture and beats pure 2D generation:

• One mocap library, every character. Retarget the same 30 clips to each new rig — a new fighter costs one mesh + one retarget + one render batch (hours on MODELBEAST, not weeks).
• Perfect frame consistency, perfect alpha (no chroma halo), free normal maps → dynamic stage lighting on sprites (the 2.5D look the tech report describes).
• The 3D source stays in the vault: cinematic camera moves for supers, restyling, re-rendering at any resolution later. Character-specific signature moves are just extra clips in that character's folder.

Engine: Godot 4.x

Matches the tech report's recommendation and our needs: deterministic fixed-tick _physics_process, AnimatedSprite2D + normal maps + canvas shaders, exports to desktop AND HTML5/WASM (partly.party-friendly). Combat core = finite state machine + input-buffer reading numpad-notation motions, fixed 60Hz tick decoupled from render. Design it deterministic-from-inputs on day one so rollback netcode stays possible.

Character folder spec (the BKB idea, modernized)

characters/<name>/
  manifest.json          ← display name, stats, move list, palette variants
  portrait.png  select.webm
  moves/<move>/
    frames.atlas.webp    ← packed sprite frames (+ normals.webp, optional)
    data.json            ← frame windows, damage, boxes, root motion
  audio/                 ← per-move whoosh/hit/voice
source/<name>/           ← (not shipped) GLB mesh, LoRA, mocap retargets, render scenes

Engine scans characters/* at boot → roster builds itself. That is the "add characters as I make them" requirement solved — same as BKB's per-character folders, but self-describing.

---

4. Effort assessment

Phase	Work	Scale
1. Combat core	FSM, input buffer, fixed tick, box collision, training-mode hitbox viewer	the hard code; small but must be exact
2. Shared move library	~30 mocap/hand-keyed clips, named vocabulary (BKB-style)	one-time cost, reused forever
3. Pipeline scripts	mesh→rig→retarget→render→pose→pack, one command per character	MODELBEAST jobs
4. First 2 fighters + 1 stage	proves the loop end-to-end	the real milestone
5. Roster growth	new character = new mesh through the pipeline	marginal cost ≈ hours

Verdict: very buildable. The genre's whole trick is that the engine is small and dumb while the data is rich — a 1.4MB exe ran BKB2. Our advantages over 2002: free auto-hitboxing via pose estimation, free asset generation via MODELBEAST, 60fps with no ROM limits, and a 3D source of truth the originals never had. The two things that will make or break it are feel (frame data tuning — steal MK's uniform-mechanics doctrine and modern startup timings, not BKB's) and identity consistency (solved by going through 3D rather than per-frame image generation).

Original assets only — BKB data stays as reference for formats/mechanics study, nothing ships.