Extract Claude-of-Duty procedural primitives into a reusable R3F game toolkit (harvest-not-embed)

[TortoiseWolfe]

Epic. Harvest reusable, asset-free procedural primitives from Matt Shumer's MIT Claude-of-Duty into a ScriptHammer game toolkit — the substrate for a future "prototype your own game demo" capability. Feasibility spike done 2026-08-05 (full CoD source read, 9 parallel subsystem readers).

The one finding that decides everything: harvest, don't embed

CoD is a genuinely modular, MIT, three-only, 100%-procedural (zero art/audio assets) mini-engine (~65k LOC) with a service-locator + event-bus contract and no cross-subsystem imports. But it runs its own imperative render loop + kernel, and ScriptHammer is React-Three-Fiber (React owns the loop). Two loops can't share one canvas.

So we do not embed the engine — we harvest its framework-agnostic procedural primitives (the asset-free, hard-to-build things that make quick 3D prototypes painful) and let R3F + drei + @react-three/postprocessing own the render/post layer. The harvest is a "procedural game toolkit for R3F."

Extract / Adapt / Skip

Tier	Subsystem	Verdict	Why
⭐	materials (4.2k LOC)	EXTRACT	Procedural PBR forge → plain THREE.Material/Texture; triplanar (no UVs), needs renderer only at bake time. "Single most valuable extract."
⭐	physics (5.6k)	EXTRACT (thin adapter)	Dependency-free BVH + swept-capsule character controller — copies nearly as-is. Directly serves #226.
⭐	audio (4.2k)	EXTRACT	Pure Web Audio leaf layer, drops in verbatim, zero r180→r184 deltas.
	core (1k)	ADAPT/split	Keep rng (seedable PRNG), EventBus, QUALITY_PRESETS; discard the kernel (fights R3F).
	player (3.3k)	ADAPT/split	Keep springs.js (177 LOC — camera feel/recoil/shake); skip the FPS controller.
	sky (3.3k)	ADAPT	Procedural sky + IBL, no HDRI → <ProceduralSky> (drop volumetrics). Beats drei <Sky>/<Environment>.
	fx (6.7k)	ADAPT	GPU particle system + atlas baker (verify r184 shader chunks); skip FPS content.
	render (5.8k)	SKIP	R3F/drei/postprocessing already are this; salvage env.js IBL + glsl.js only.
	weapons + ai + world + ui (30k)	SKIP	FPS app layer → reference for #226. Pull out world/util.js + weapons/geometry.js (plain-three geometry builders).

Net Tier-1 harvest ≈ 13–16k LOC of asset-free, framework-agnostic primitives.

Integration paradigm (the one rule)

R3F owns the <Canvas> renderer + rAF loop. Adapt each primitive to it: materials bake off-screen (save/restore render target); physics runs a fixed-step tick in useFrame writing transforms onto R3F meshes; springs live in useFrame; rng/eventbus are plain modules; audio is a small hook. Do NOT lift render/core.engine (two-loops-fighting-one-canvas trap).

Tasks

• Walking skeleton (do first, in a git worktree): vendor physics/{math,surfaces,character,bvh} + player/springs, wire a capsule controller into /game/3d (WASD + pointer-lock) on a BoxGeometry floor skinned with one materials surface. Proves r180→r184, static-export ssr:false, and the ⭐ materials + ⭐ physics pieces at once. Gate: pnpm run type-check + "Validate Component Structure" green, WebGL FallbackPanel intact.
• Extract materials forge (Tier-1 ⭐).
• Extract audio leaf layer (Tier-1 ⭐).
• Extract core gems (rng, EventBus, QUALITY_PRESETS) + player/springs + geometry builders.
• Adapt sky → <ProceduralSky>; adapt fx particle core.
• Vendor under a clearly-attributed dir (e.g. src/lib/cod/) with CoD's MIT LICENSE/NOTICE retained.

Relationships

• Lands on closed [Feature] 047 Three.js Game #48 (the existing /game/3d ssr:false island).
• Unblocks the controller half of Chatt diorama: add FPS / first-person 'ground game' mode (paintball, football, Civil War reenactment, militia war-games) #226 (milsim FPS) independent of its Chatt diorama: buildings render ON the river — layers are NOT aligned (verification methodology also broken) #225 geodata blocker; CoD weapons/ai are a reference, not a lift.
• Supersedes the legacy good_prompt_bad_prompt FPS-placeholder prompt ([Gap-Audit] 029 SEO Editorial Assistant: technical.ts test coverage + import-bundle conflict UX + offline autosave #38, being closed).
• Answers Chatt diorama: add FPS / first-person 'ground game' mode (paintball, football, Civil War reenactment, militia war-games) #226's open "template-capability vs. separate app?" → toolkit = template capability; games (milsim, GrimGlow) = forks that consume it.

Deferred — Phase 2 (not this epic)

The gauntlet-loop "game-demo generator" (a parameterized skill: game-spec in → scaffolded playable demo out, polished by the gauntlet loop). Design it after this toolkit exists, seeded by these primitives. Only its optional save/share features would touch Supabase; the toolkit + prototype layer is 100% client-side.

Attribution: Claude-of-Duty is MIT (Matt Shumer). All extracted code retains its license/NOTICE.