MegaJam playbook (read this first)
What is installed right now: CAPABILITIES-NOW.md (same folder) is the source of truth. It is a live scan of all three machines; where this playbook disagrees with it on versions, compilers or tools, CAPABILITIES-NOW.md wins. C++ builds also run on tower 2 (see studio-pipeline/tools/queue/TOWER2-UE-BUILD.md).
Built Sat 2026-11-14 03:4x ET from prep/, research/, spoiled/, game/devlog/, METHODS.md, LESSONS.md, STANDARDS.md and CONTINUITY.md. Each line is one lesson, with its source file. Traps come before methods in every group. Short source names live in lab\megajam (prep, research, game\devlog, spoiled) or studio-pipeline\docs (METHODS, LESSONS) or lab (STANDARDS, CONTINUITY).
Refreshed every 2 hours by the knowledge keeper. New lesson of your own? Put it in game\devlog\failures.md or decisions.md with the time from date; it gets folded in here. Note: docs\BLENDER-53.md does not exist yet. Blender 5.3.0 is installed on the laptop and tower 1 (tower 2 still has 5.2.1, rollout in progress; CAPABILITIES-NOW.md, 03:41). Each pipeline switches to 5.3 only after a smoke test; 5.2.x stays as the fallback (decisions.md Sat 03:22).
0. Rules that bind every worker
- American English in everything you write (color, gray, center, realize, license). Studio rule from Don, 2026-11-14.
- Game text is in the voice of its era; see spoiled/ship/VOICE-GUIDE.md when it lands (Don, 2026-11-14).
- Start of any big push: inventory installed tools live with studio-pipeline tools/ops/inventory.py, never from notes. We ran Blender 5.2.1 from memory while 5.3 was available (coordinator, 2026-11-14).
-
Time: run
datein the same call as any log or board write. Guessed times were wrong by up to 1 h 25 min (failures.md). -
Commit by explicit paths. Never
-a,-A,.. A commit swept up another ticket's half-written C++ (notes.md Fri 13:25; LESSONS L-GIT-1). -
Delete only your own folder, by exact path. No wildcard deletes, even in your own files: workers did it twice (failures.md Fri 19:20). No
pkill -f, notaskkill /IM; stop by PID (LESSONS L-QUEUE-9). - Own scratch subfolder per agent; never write one folder above your cwd (LESSONS, scratch hygiene).
- One GPU job per machine; read the lock first (laptop lab\.gpu.lock, towers ~/studio-ai/.gpu.lock). Only the owner removes a lock. Check for stale game exes and stray editors by process before taking it (failures.md Thu 09:19, notes.md Thu 04:59).
- Same error twice: stop, write it in failures.md, report (GLASS-BOX.md s2).
- A report is not a result. Say a job ran only if a tool result this turn shows it; DONE.json means done, exit 0 does not (LESSONS L-VERIFY-1, L-VERIFY-2).
- Nothing reaches Don before a fresh-eyed review against STANDARDS.md; no placeholder art ever; no em or en dashes; nothing may read as AI-written (STANDARDS.md header, Art director).
- Brief every helper with: lock path, scratch folder, explicit commit paths, the check, and the no-wildcard-delete rule with its reason (failures.md Fri 19:36, LESSONS L-OPS-6).
- Check that a brief's input files exist before starting; write briefs from WORLD.md, not from file names (decisions.md Sat 03:00).
- Parallel workers on one area: the lead writes CLAIMS.md BEFORE the second worker starts. Two agents built the same hall without it (failures.md Sat 02:25).
- The Agent tool blocks the lead until the helper returns. For true background work use background shell commands (failures.md Sat 00:29, 02:22).
- Model by job: Sonnet for tickets with a check, Opus for scoped features and review, Fable only on Don's word (trials.md; METHODS "Which Claude model builds").
1. Shell and path traps (hit 10+ times)
-
Bash heredocs and sed eat backslashes (
\bbecame a backspace byte;\r,\fturned to control chars). Write .py, .ps1, .sh and patch files with the Write tool, then scan for control chars (failures.md; heredoc-backslash memory). - Run packaging and UE scripts from PowerShell with quoted paths; bash mangled -Out and -File paths and the zip step reported "0 MB OK" (failures.md Thu 06:20).
-
Git Bash rewrites
/Game/...args toC:/Program Files/Git/Game/...: set MSYS_NO_PATHCONV=1 and MSYS2_ARG_CONV_EXCL=* (failures.md Fri 11:36; LESSONS L-PATH-2). -
Windows python cannot open
/c/...paths. Pass forward-slash paths to-script; backslashes made\ta tab (failures.md Thu 09:14). -
Tower 2 ssh shell is PowerShell: no
cd /d x && tar; use Set-Location; scripts need-ExecutionPolicy Bypass; for odd commands use-EncodedCommand(base64 UTF-16LE) (failures.md Thu 13:30; MCP-RUNBOOK). - Verify hashes in Python; a bash loop over sha256.txt printed 28 false MISMATCH lines (failures.md Thu 18:33).
-
tar -amakes a tarball named .zip. Zip in plain Node or ffmpeg-free tools and rununzip -t(LESSONS L-DEPLOY-7). -
Queue job text: pass paths as arguments, never paste a Windows path into a Python string (
\rdied in 7 s) (failures.md Thu 00:52).
2. Unreal Engine 5.9: MCP and scripting
-
Traps
-
bThrottleCPUWhenNotForeground=Falseonly works in Config/DefaultEditorSettings.ini (330 ms down to 12 to 40 ms per call) (MCP-RUNBOOK). - A modal dialog freezes every MCP call; HTTP 502 means crash. If calls time out, look at the screen first. Keep dialogs closed during runs (MCP-RUNBOOK; freebies-and-tools).
- "Not run: the Unreal Editor is running a slow task" is not failure: wait and retry up to 60 s. After a restart it can last 27 min (MCP-RUNBOOK; failures.md Thu 16:18).
- Claude Code gives up on an MCP call at about 120 s: run packaging, captures, mass imports as scripts (MCP-RUNBOOK).
-
Never send MCP calls in parallel.
returnValue trueis not proof: read state back (UNREAL-AGENT). -
execute_pythonreturns only the last expression;print()returns nothing. End the script with the string to report (failures.md Thu 21:20). -
CaptureViewport: pass real annotations or it fails;
{}turns the overlay on; 557 KB per call, milestones only (MCP-RUNBOOK). - 5.9 tool surface is list_toolsets, describe_toolsets, describe_tools, call_tool (PascalCase tools, camelCase args); 5.8 scripts fail. Use mcp_smoke59.py (MCP-RUNBOOK).
-
Live Coding does not pick up new UFUNCTIONs; restart is a human step. A leftover editor with Live Coding blocks builds: add
-NoHotReloadFromIDE(and-ubtargs="-NoHotReloadFromIDE"for RunUAT) (UNREAL-AGENT; failures.md Thu 04:05). -
Python:
unreal.Rotator(a,b,c)is (roll, pitch, yaw), use keywords. Structs take no constructor kwargs, useset_editor_property.unreal.Colorchannel order bit us (lights blue, exposure crept). Log engine-side values, not inputs (LIPSYNC; failures.md Thu 17:35, Fri r3). -
-nullrhicannot compile materials: they render gray in game and package. Use-AllowCommandletRenderingwithout-nullrhifor content commandlets, or a renderer session (CLOTH; failures.md Fri 14:17). -
Skeletal FBX export asserts under -nullrhi; use
-RenderOffscreen(ASSET-PIPELINES). - Interchange glTF imports zero static meshes headless: convert to one joined FBX in Blender first (failures.md Fri r3). Embedded FBX textures fail: put textures beside the FBX (ASSET-PIPELINES). Imports nest at /Game/Props/name/StaticMeshes/name.
-
Interchange with save off saves only meshes; keep save on (failures.md Fri 23:35).
save_assetskips undirtied packages: callo.modify()first, thensave_asset(path, False)(failures.md Fri 03:17). -
get_editor_subsystem(StaticMeshEditorSubsystem)is None headless; instantiate it directly.-ExecutePythonScriptin -game quits when the script returns; use-ExecCmds="py path"(failures.md Fri 23:35; CLOTH). -
Delete before overwrite: AnimSequence export and
new_levelrefuse existing paths; build each run into a fresh versioned folder (LIPSYNC; CLOTH). - Material compiled to default with no error: Custom node inputs whose names differ only by case collide; PreSkinnedPosition is not readable in pixel shaders (failures.md Fri 23:35). Subsurface Opacity runs backwards: 1 is solid (failures.md Fri 19:59). Failed materials draw gray and every other check passes: grep the log for "Failed to compile" and look at one frame (LESSONS L-ART-11).
- A StaticMeshActor root is Static and will not attach to a socket; set Movable first (failures.md Thu 18:24).
- Windows throttles an unfocused game (14 to 30 fps against 101) and unfocused UE mutes itself; check focus before blaming performance or silence (MCP-RUNBOOK; VIDEO).
- DLSS and trademark credits are barred by jam rule 7(d): use TSR (decisions.md Sat 02:54).
-
-
Sequencer and animation
- A section longer than its clip restarts the clip; rate-scale (0.85) to fill. Overlapping sections do not blend linearly: bake root alignment into aligned clip copies. Ease durations are in ticks, not frames. Motion on MetaHuman lives in the pelvis, root is identity (notes.md Thu 11:26, Thu 11:50, Fri 05:50).
- Animation reaches a MetaHuman only through Sequencer tracks (LESSONS L-ART-13). Inertialization and motion matching need an AnimBP that owns the pose (METHODS Directed action).
-
get_bone_pose_for_timereturns stored pelvis offset (0, 0.62, 12.8) cm on Rex; measure the constant per clip and add it back (decisions.md Fri 07:30). Measure one bone in the packaged game before any offline bake (timing.md Fri 11:31). - A take that declares lights deletes the level's untagged sun and sky: declare sun, sky and lamps per take, only DIR_<id> lights get replaced (failures.md Thu 14:16).
- Exposure: auto exposure is off. Calibrate by mean luma, not by feel (failures.md Thu 09:23). Judge frames by numbers from in-engine shots (-KKShotAt); desktop captures read 0.55x when a Windows prompt dims the screen (notes.md Thu 17:40).
-
Methods
-
Start the MCP editor:
UnrealEditor.exe proj -ModelContextProtocolStartServer -ModelContextProtocolPort=8000; port 8001 for a second project. First start 70 s, later 15 to 19 s; 128 toolsets. Ping with mcp_client.py before work; no retry loops (MCP-RUNBOOK; UNREAL-AGENT). - One agent drives the editor; others hand it tickets. Logic is planned in text and built by Python editor scripts kept in git (RISKS; UNREAL-AGENT).
- Save every 10 minutes by explicit paths. MCP down over 30 min: switch to Python and command-line builds (UNREAL-AGENT).
- Level metrics: capsule r34 hh88, walk 500, step 45, door 120x230, corridor 200 (LEVEL-CONTRACT). Block out from primitives, name actors, capture after each step, one fix then recapture.
-
Headless stage run:
UnrealEditor-Cmd.exe proj -run=pythonscript -script=f -unattended -nosplash -nopause -nullrhiis 15 to 20 s a stage on tower 2 (CLOTH). - The packaged game's own log is the truth: log joints, pelvis deltas and cooked-log greps (GLASS-BOX.md s8).
- Crowds: skeletal extras to about 20, then AnimToTexture with Nanite off or Mass. Chaos caches misbehave in packaged builds: author offline, play keys (METHODS Cloth and crowd; Directed action).
-
Start the MCP editor:
3. Unreal project setup and packaging
-
Traps
- Do not disable default-on plugins (AndroidFileServer, NNE): project stops being content-only. On 5.9, ModelContextProtocol is on by default; a TargetAllowList entry for it flips the project to code (MCP-RUNBOOK).
- Hand-made projects default to SM5: cold launch froze 40 to 60 s. Set D3D12TargetedShaderFormats SM6 (4 to 6 s) (MCP-RUNBOOK).
- Set GameDefaultMap, TransitionMap and ServerDefaultMap or the cook pulls /Engine/Maps/Entry (MCP-RUNBOOK).
- AllToolsets pulls GameFeatures: GameFeatureData asset manager rule must be bIsEditorOnly=True or the package fires an ensure at startup (MCP-RUNBOOK).
- The editor writes a random SecurityToken into DefaultEngine.ini; pin the section to a placeholder so the key scan stays green (MCP-RUNBOOK).
- MovieRenderPipeline with TargetAllowList Editor cooks without its module (UAT exit 25); NNEDenoiser in DirectoriesToNeverCook also exits 25: disable the plugin instead (failures.md Thu 05:04, Thu 06:09).
- MetaHuman plugins enabled for game: empty level zipped 1,223 MB. Never-cook rules for the tracker, CoreTech and denoiser models plus NNEDenoiser off gave 290 MB (notes.md Thu 06:20). Per-character Common copies add about 41 MB each; build B and C into A's Common folder (failures.md Fri 03:25).
- Three untrimmed characters zipped 1,304 MB, almost all textures; hair is 6 MB a character. Cap textures by group (Project01..05) plus device profile MaxLODSize, not baked Max Size (notes.md cast 3, Fri 08:45).
- The size script counted MiB: 911 MB zip was 955 MB decimal against a 950 MB cap. Name the unit (notes.md Thu 19:55).
-
UE-411525:
-NoCleanStagecan ship stale content. Use-Cleanfor final builds (MCP-RUNBOOK). - Texture audit passed but the packaged log showed the costume master drawing default material. Grep the packaged log for shader-map and default-material lines every build (notes.md Thu 20:00).
- Copy the full voice manifest into the package; a hand copy missed a bark (failures.md Fri 12:50).
- First launch from a new folder: closing waits 30 to 120 s on PSO compiles; keep a title screen up. Always smoke the final zip from a fresh folder (MCP-RUNBOOK).
- Derived data cache goes cold after an engine or driver update: cold fill 44 to 73 min, warm 99 to 187 s (MCP-RUNBOOK).
- Windows firewall and PickerHost prompts belong to Don; never touch security dialogs. Repackage to a known folder to avoid them (notes.md Thu 17:40; failures.md Fri 13:12).
- Delete unused Fab or starter content before the final cook; anything referenced gets cooked. Never copy Saved, Intermediate or DerivedDataCache to another machine (MCP-RUNBOOK).
-
Methods
-
Packaging: RunUAT BuildCookRun
-cook -stage -pak -iostore -compressed -archive -nodebuginfo -applocaldirectory AppLocalDependencies(package.ps1). Pass-EngineDirfor 5.9 (laptop D:\Epic_Games\UE_5.9\UE_5.9, tower 2 C:\Program Files\Epic Games\UE_5.9) (MCP-RUNBOOK). - Hair in a packaged build needs a C++ project, built on the laptop or on tower 2 (both have MSVC 14.44 since Sat 03:30; TOWER2-UE-BUILD.md), editor-only flags removed from the cooked MetaHuman plugins, LiveLink, HairStrands and ChaosClothAsset enabled for game (decisions.md Thu 05:14; METHODS MetaHuman hair).
-
Gate:
pkg_smoke.ps1 -Profile jam|ultra, jam gate 940 MB fails the build; builds go to D:\megajam\builds\<name> (notes.md Thu 20:22). Jam 857.6 MB, ultra 1617.3 MB. - smoke.ps1 -Zip: extract, launch windowed, wait for LoadMap, exit 0, no new Saved\Crashes, no fatal or ensure. Run a packaged bot loop on every build and count Error lines (0 expected) (MCP-RUNBOOK; notes.md Fri 01:47).
- Timings: laptop clean Development 175 s build plus 37 s zip; cached cook 35 to 67 s; first cook 444 to 525 s (MCP-RUNBOOK; failures.md).
- Ship Development as the jam page asks (Shipping is about 65 MB smaller, fallback only). Package an empty project at hour 2 and every evening: a failed package stops the line (MCP-RUNBOOK; GLASS-BOX.md s9).
- Masters stay full quality; caps live only in package profiles (METHODS Directed action).
- Lumen and VSM cost GPU only. AI meshes at 500k+ triangles bloat Nanite; decimate before import. Default settings must hold 60 fps at 1080p on tower 2's W6600 (MCP-RUNBOOK; RISKS).
-
Packaging: RunUAT BuildCookRun
4. Blender (5.3.0 on laptop and tower 1, 5.2.1 on tower 2 until the rollout lands)
-
Traps
-
Cycles cannot read baked images still in memory (magenta three times): save and load fresh. In Blender 5
use_nodessilently skipped a fix (timing.md Fri 21:10). -
5.2
libraries.loadcrashes until the view layer is updated; removing loaded dummy materials crashes too (timing.md Fri 23:06). - Mix node socket names repeat across types: link by identifier (Factor_Float, A_Color) and print enabled inputs (LESSONS, Mix node).
-
Noise Texture W input exists only in 4D mode (failures.md Fri 13:15). quadriflow_remesh is CANCELLED under
-b. Bake to Keyframes fails headless: key from the point cache (METHODS). - BVH import never shrinks the scene range: clips came out padded to 8.3 s. Trim to the action. Do not change a BVH bone's rotation_mode (failures.md Thu 09:10, Thu 12:10).
- FBX scale: unit scale 0.01 plus FBX_SCALE_NONE, export in centimeters; Unreal FBX enters Blender under a 0.01 empty (failures.md Thu 08:30; ASSET-PIPELINES).
- Blender IK constraints break on UE skeletons imported from FBX (30 cm errors); use analytic two-bone IK (METHODS Directed action).
-
Auto-Rig Pro Smart needs a 3D viewport, not
-b: run windowed with a VIEW_3D override (about 35 s) (LESSONS L-OPS-14). ARP constraints are parent-space: read back the evaluated world matrix (L-ART-34). - Baking on bodies 17 percent too small made hits miss by 20 to 32 cm: bake on the real bodies (notes.md Fri 12:05).
- Voxel remesh deletes thin TRELLIS shells (timing.md Sat 00:40). Weld at 1 mm merged a thin blade and shredded fingers: render a close-up sheet of hands and held items after any mesh fix (LESSONS L-ART-24).
- EEVEE: 48 samples with screen-space raytracing on 900 glossy links took 13 to 15 s a frame; blended translucent membranes made frames 5 to 10x slower (failures.md Fri 15:20). Cycles with volume haze cost 7 to 9 s a frame; a swarm shot took 2 h 45 against 150 min estimated (timing.md Fri 19:48).
- Judge a bake under the final lights; preview lights 8x too hot read pink (timing.md Fri 23:42). A flipped cross-section was visible only in the render: look at frames (timing.md Fri 20:25).
- 8-bit normal maps terrace gentle slopes; NaN from sin() of a tiny negative poisoned a VAT (timing.md Fri 21:30, Sat 00:40).
- Scripted modelling tops out at a toy for organic creatures; use klein to image-to-3D then Blender cleanup (decisions.md Fri 21:31). Hand-modelled first-person gloves read terrible: use the First Person template arms (decisions.md Fri 23:48).
-
Cycles cannot read baked images still in memory (magenta three times): save and load fresh. In Blender 5
-
Methods
- Tower 2 CPU builds, rigs and renders Blender in seconds (kit 8 s, creature plus bake 2 min). Keep look iteration there; Cycles finals go to tower 1 via the queue (Cycles HIP on tower 2 is 36 to 47 s a frame) (timing.md Fri 13:35; METHODS).
- Generated prop clean-up: weld 0.1 mm, drop pieces under 0.5 percent, decimate, smart UVs, Cycles bake 2048 base plus normal, FBX LOD0 and LOD1 (METHODS Images, beef prop).
- Skin generated humanoid onto Manny's 88 bones by nearest-surface weight transfer (mj_skin_to_manny.py, 4 s, A-pose needed). Count unweighted verts after every bind; run an arms-only leak test (ASSET-PIPELINES; METHODS Rigging).
- Blender and ffmpeg are run-only tools (GPL/LGPL): never bundle them or GPL add-ons; output is ours (LICENSES-COMMERCIAL).
- blender-mcp is fine for easy scene jobs (4 calls, 20 to 45 s), weak at posing and keying (METHODS Operations).
5. Image generation and image-to-3D
-
Traps
- ComfyUI TRELLIS.2 template ships "Switch to Trellis2" off, which silently runs Pixal3D (EU-gated). Turn it on (ASSET-PIPELINES).
- Memory: closed crate at remesh 768 OOM'd twice on 24 GB; props default upsample 1024, remesh 512. Never decimate the GLB afterwards (baked textures streak); decimate to 16k with a 1024 bake inside the graph (ASSET-PIPELINES; LESSONS L-ART-5).
- Soft piles and sacks collapse (hay, teddy bears, sandbags). Hard props kept 24 of 30. Build soft things in Blender (notes.md Thu 06:03; LESSONS).
- TRELLIS invents the back and fuses many-legged shapes (up to 12,701 open edges) and hands (fused slabs). Background and look only; hero rigs are built (METHODS Images; LESSONS L-ART-31, L-ART-44).
- Expect 1 clean of 3 on awkward shapes (boots). Check mirrored boots for the wrong foot (notes.md Thu 15:28; LESSONS L-ART-42).
- Heat weighting on TRELLIS meshes can succeed and weight nothing: count unweighted vertices (LESSONS L-ART-21).
- klein turns framing words into frames: say "clean full frame, no vignette"; one clause lost most of a round. Style key images as reference did not tighten palette: lock style with words and seeds (LESSONS L-ART-47; timing.md Fri 17:09; ASSET-PIPELINES).
- BiRefNet masks can come back inverted: the border decides (ASSET-PIPELINES).
- Licenses: FLUX.2 klein 4B (Apache) only; 9B and dev are non-commercial. RMBG-2.0 CC BY-NC. Hunyuan3D outputs banned (EU, UK, South Korea). nvdiffrast is non-commercial: ship only ComfyUI-route outputs. Marigold IID output limits: use PBRify (ASSET-PIPELINES; LESSONS L-LIC-2).
- Image-to-3D lost side by side to hand-built models in the Twist test: use for filler and background (SOURCED-ASSETS).
- Critic passes prove nothing (Haiku scored 6 to 7 everywhere): strict rubric, thinking off, 1200+ tokens, calibrate against Don (LESSONS L-JUDGE-5).
- Original design sheets by Don are people-only references: never into img2img, TRELLIS or IP-adapter (PIVOT.md).
-
Methods
- klein 4B, 4 steps, cfg 1, euler: 3 to 7 s a take. Prop route: klein still on plain white, 3 views x 4 seeds, TRELLIS.2 (80k faces on best view), clean, thicken, decimate to about 19k, bake. Pick by white-background check (ASSET-PIPELINES; METHODS Images).
- Edit route (instructed klein edit) beat regenerating for one-detail fixes; upscale a still with klein edit at 2048, about 15 s (timing.md Fri 17:25; METHODS Images).
- Prop costs 2.5 to 7.5 min, humanoid 2.5 min, texture set 25 s on the A5000; rescale to real size with pivot at bottom center. Creatures start from a plant object plus a verb; never resemble a known monster (ASSET-PIPELINES; LESSONS L-ART-47).
- Textures: PBRify Remix (CC0) gives DirectX normal, roughness, height in 5 s. Tiling: partial repaint 0.75 denoise, 22 percent band; always view 2x2. Palette gate: Lab k-means dE under 15 on look, over 25 reject (ASSET-PIPELINES).
- Generate props flat-lit with no cast shadows so Lumen lights them; one post volume and one grade tie the look (ASSET-PIPELINES).
- Submit a few-second image step as its own short queue job; one sat 58 min behind audio (LESSONS L-ART-46).
6. Wan video and other video
- Wan 2.2 is crude and caps near 480p: not for playable beats or fights. Use for in-world screens with no people or faces (decisions.md Sat 01:13, Thu 04:00).
- Wan ignores "fixed camera" about half the time; held props reshape; a wide gap between two stills cuts instead of morphing. Never ask for text; prompt era and view (period vans need body words) and burn clocks in engine (METHODS Video; decisions.md Sat 01:39).
- Recipe: Wan 2.2 I2V A14B fp8 from a klein still, 480x624 or 640x480, 81 frames, 20 steps, cfg 3.5, 11 to 12 A5000 minutes a clip, low priority. Loop: crossfade last 17 into first 17 (METHODS Video).
- Wan Animate 2 copies weak takes and keeps the reference body size; video route for fighters scored 4 (LESSONS L-ART-27, L-ART-36).
- Never run Wan beside Ollama gpt-oss on the laptop: hard crash (LESSONS L-QUEUE-18).
-
ffmpeg mux with open
apadand-shortesthung 83 min and blocked the queue. Useapad=whole_dur,-t, and wrap intimeout(failures.md Fri 19:46). - OBS: never kill it (Safe Mode dialog next start); stop by hotkey and WM_CLOSE; hold hotkeys about 250 ms; record from Don's interactive desktop, not an agent session (8 to 20 fps otherwise). ffmpeg NVENC needs driver 610+ (laptop has 580.92) (VIDEO).
- Check the first take's audio is above -60 dB max, and ffprobe length and a first-second frame in every record script (VIDEO; LESSONS L-VERIFY-14).
- Final encode: libx264 crf 18 slow, loudnorm I=-14, aac 192k 48 kHz, faststart; 1080p, 30 to 60 s (VIDEO; PRODUCTION).
- Film look: seeded camera shake baked to keys; grain and halation in house or ffmpeg; path tracer needs hardware RT and fireflies survive the denoiser (research/cinematic.md). Real-ESRGAN (BSD-3) and RIFE (MIT) usable; check each weight's license.
7. Audio (MOSS, voices, Sonniss, music)
-
Traps
- Sonniss GDC license: mixed layers only, never raw files, never AI input (no CLAP indexing, no training), no resale. Only our mixed renders may ever leave the studio (LICENSES-COMMERCIAL; SOURCED-ASSETS).
- Sonniss bundles sit behind Cloudflare: do not bypass; use the official torrent to a short root (D:/s) (decisions.md Fri 22:09). Pixabay and Mixkit ban bots; Mixkit music not allowed in games (LICENSES-COMMERCIAL).
- MOSS-SoundEffect: Apache-2.0 per audio.md, but v2 ships a Tencent VAE with EU, UK, South Korea exclusion. Fine for the jam; resolve before any sale. Credit line: "MOSS-SoundEffect v2.0 by OpenMOSS (Apache-2.0)" (LICENSES-COMMERCIAL vs audio.md).
- Stable Audio is off for the jam: needs "Powered by Stability AI", rule 15d bars trademarks. MMAudio, TangoFlux, XTTS-v2, F5-TTS non-commercial; YuE, DiffRhythm, Spark-TTS, Fish, IndexTTS2, VibeVoice restricted (SUBMISSION-KIT; ASSET-PIPELINES).
- Maya1 output needs "Built with Llama" credit; license unresolved for sale (decisions.md Thu 14:26; LICENSES-COMMERCIAL). Chatterbox adds an inaudible Perth watermark.
- Voice models that go flat or drift: Dia (weakest, glues the anchor onto takes), MeloTTS, Zonos, Nano, MOSS-TTS. Chatterbox holds one voice best, Maya1 won emotional lines. Compare each new voice to every cast voice (similarity under 0.3) (ASSET-PIPELINES; METHODS Voices; LESSONS L-AUDIO-11).
- ACE-Step accepts "Bb major" but not "B flat major": HTTP 400 swallowed by the wrapper. A batch that makes nothing must print why (failures.md Thu 18:45).
- Music loops: 20 s failed seam checks; generate about 1.2x loop length, loop 30 s or more. A loop can hide a level hole near -45 dBFS at the wrap (ASSET-PIPELINES; LESSONS L-AUDIO-10).
- LUFS is unreliable under 3 s: judge max momentary with 1.5 LU tolerance. Pedalboard Limiter adds make-up gain; a len() on stereo silenced a mix: check numbers, not ears (LESSONS L-AUDIO-2; timing.md Fri 14:46).
- Whisper: map number words to digits in WER; hangs on roars and grunts (skip); set cpu_threads 12 (1 s a clip against 8 s); use librosa pyin, not YIN, on gravelly voices (failures.md Thu 12:47, Thu 14:24; METHODS Voices PA).
- Never run aes_score.py as a script while another agent holds the laptop lock: it clears locks it thinks stale. Import Critic instead (METHODS Audiobox).
- Critics cannot judge stylized synth; Don's blind ear decides. Code-built sounds lost to MOSS on all four tested (METHODS SFX MOSS).
- Unfocused UE mutes itself; first packaged tests ran silent. A room opens only when every sound and line exists (VIDEO; STANDARDS Audio).
- The Dailies board rejects MP3: post audio as MP4 (notes.md Thu 04:00).
-
Methods
- MOSS-SoundEffect v2.0 default: long descriptive prompt, 100 steps, cfg 4.0, sigma shift 5.0, bf16, seeds 101 to 104, about 26 s a take on tower 1; venv in studio-ai/moss-sfx, py 3.12, torch 2.9.0+cu128. Score 150 x CLAP + 3 x mean(PQ, CE), best of 3, then a blind reel (METHODS SFX MOSS; research/audio.md). Layering Sonniss under MOSS won the blind test 3 of 4 (decisions.md Sat 01:05).
- Voices: Kokoro reference, 3 Chatterbox takes, Whisper word check, master -16 LUFS (-18 per decisions) peak -1 dBFS, 48 kHz mono. Kokoro on CPU is fast (8.5 s audio in 1.7 s), needs no lock; espeak-ng runs at generation only, never bundled (ASSET-PIPELINES; LIPSYNC).
- Footsteps from real recordings per surface; UI blips from code or Kenney (CC0); Freesound filter CC0 and save each page (ASSET-PIPELINES; SOURCED-ASSETS).
- Monster voice: Maya1 tags and short UPPERCASE lines, pitched copies, MOSS roar underneath. PA announcer: intercom chain (hp 300 Hz, band 300 to 3400, slap echoes) (METHODS Voices).
- Overgenerate, auto-QA, curate, present blind with picks in a separate message (position bias: Don chose A 6 of 8). Don listens before ship; the builder never heard the picks (LESSONS L-AUDIO-8; timing.md Fri 14:46).
- Quiet beds at -26 LUFS under shots; audio needs a user gesture on iOS web builds (STANDARDS Audio).
8. MetaHuman, cloth, lipsync, motion
-
Traps
- Epic terms: never give MetaHuman frames to any AI model (critics, director, video, upscaler). Judge by Don or numeric checks; workers refuse to view them. Broken twice already (decisions.md Thu 17:12; STANDARDS Continuity).
- Never delete a loaded MetaHuman build folder and rebuild into it: shared hair materials lose textures and everyone goes bald. Build into a never-used folder; search references before deleting a cast asset (failures.md Thu 07:55; notes.md Thu 13:50).
- "Cannot break link ... Face_ControlBoard_CtrlRig" on every build is Epic's and harmless; do not chase it. A rig request right after another returns in 0.3 s with 0 assets: rerun alone (failures.md Thu 07:55, 11:07).
- SceneCapture does not draw groom strands reliably; judge hair in MRQ or game camera, and packaged frames. Hair vanished in the packaged exe until the C++ route (decisions.md Thu 09:00; HANDOFF).
- MEDIUM draws hair cards; build HIGH for strand hair in MRQ. Moustache bind in Python crashed twice: rebuild on tower 2 (notes.md Thu 11:28; decisions.md Sat 01:58).
- Body constraints set by script read back at preset values: set Height, Waist, Chest, Hip together or Fat 7.0 collapses height (failures.md Thu 08:52).
- Costume masters need the skeletal mesh usage flag; hair dye would not take gray after two tries: change the design (decisions.md Thu 09:00; failures.md Sat 01:57).
- Built body has no torso or neck (hidden-face removal): export the uncut body to drape costumes (failures.md Thu 12:05). Loose clothes need real garment meshes, not body shells (LESSONS L-ART-43).
- Stock SKM_Face has no post-process AnimBP: assign ABP_Face_PostProcess or the mouth stays shut (LIPSYNC). Plugin folder MetaHumanAnimator is named MetaHuman in .uproject (LIPSYNC).
- Legacy sequence capture speckles frames on tower 2; use MRQ with TSR, 8 temporal samples, 48 warm-up frames (LIPSYNC). One-camera 1280x720 MRQ jobs avoid GPU reset (failures.md Thu 16:18).
- Lip solve drops the clip tail (40 to 70 ms): pad the 16 kHz copy with 150 ms silence (failures.md Thu 21:10). Mouth leads sound 20 to 60 ms (notes.md).
- Chaos Cloth Asset garments drop from a Blueprint-only package; classic Chaos Cloth packages but needs hand painting. Measure cloth on a quiet machine (69 ms busy, 30 ms quiet) (CLOTH).
- Auto physics asset on a MetaHuman body is too fat for cloth: use PA_Mannequin by bone names (CLOTH).
- Armpit and crotch creases fool inside-body ray tests: use a parity test in every pose; poke-through under 3 cm accepted (failures.md Thu 17:59; notes.md Thu 19:20).
-
Methods
- Cast by lineup; extras at LOW in 1 to 2 min each; about 5 min a character by script on tower 2 in an open, signed-in editor. About 170 MB zip per full MetaHuman at MEDIUM. Content/KKCast (2.2 GB) is not in git: keep the tower 1 tar (HANDOFF; notes.md Thu 19:01).
- Lip sync: Kokoro or Chatterbox voice, ffmpeg 16 kHz mono for the solve, MetaHuman Animator audio solve commandlet, head movement Disabled, MRQ. About 2 s a line (LIPSYNC).
- Cloth: DataflowScriptingSubsystem builds the Chaos Cloth Asset, Selection_v2 sets Max Distance. About 0.25 ms per 1000 particles per iteration step; budget MaxNumIterations (CLOTH).
- Kimodo: SOMA77 export, standard_tpose=True, text max 300 frames. Rank all takes by hips height and gag checks (head below hips for a tumble); a gate that passes standing still is wrong. Constrained first and last frames close seams to 0.0 cm (METHODS Motion; failures.md Thu 13:41; GLASS-BOX.md s4).
- Retarget: Blender BVH to FBX, UE IK Retargeter to the MetaHuman rig, twist upper arm and thigh, joint_limits.py zero violations, head-aim step, 360 body check before Don sees it. toyxyz retargeter is the fallback (METHODS Retargeting; LESSONS L-ART-28).
- Kimodo SMPLX-RP is non-commercial; only SOMA-SEED or SOMA-RP. Banned motion sources: AMASS chain, Bandai Namco, LAFAN1, GVHMR, WHAM. Free and clean: 100STYLE, Rokoko (baked only), Quaternius, KayKit, Mesh2Motion (research/motion.md).
- Hand-on-prop moves (cart vault, rope) fail Kimodo: key them in Blender. Kimodo hands have no finger motion: pose library plus contact curl (METHODS Directed action).
- Every fix ends with a whole-shot side-by-side by a fresh reviewer; if not better, revert (METHODS butcher; LESSONS guards).
9. Queue, machines and tower 2
-
Queue
-
Push the commit to origin first, then submit; towers fetch from origin (failures.md Thu 00:05). Job specs run in a fresh worktree: no
cd ~/NEWBOY; take paths from STUDIO_AI (LESSONS L-QUEUE-7). -
Name
run_onfor every job: the default sent everything to tower 1 and left the 4090 and tower 2 idle (decisions.md Thu 02:10; LESSONS megajam night 1). Read ROSTER.md and registry/TOOLS.md before planning. - High priority does not preempt: sfx-4 sat 2 h 35 behind a 2 h 45 Cycles job. Cap jobs by wall clock (timing.md Fri 23:13).
- Downloads go in cpu jobs, never GPU jobs (60 GB held the GPU 3.4 h). Do not name a script after a package it imports (chatterbox.py deadlocked 4 h) (LESSONS L-QUEUE-6, L-QUEUE-19).
- Never POST /free or unload models while another job runs; no keep_alive 0 before every Ollama call. byok-watch.timer loaded a model without the lock: unload before each TRELLIS stage (LESSONS L-QUEUE-5; ASSET-PIPELINES).
- Estimates run 2 to 4x high on generation (16 GPU hours estimated, 45 min taken); queue wait, not GPU time, dominates tickets. Size from measured rates and run CPU Blender paths in parallel (failures.md Thu 00:52; timing.md Fri 14:57).
- Batches finish in minutes, so an hourly check idles GPUs: queue at least an hour of work per machine per check (notes.md Thu 03:06).
- Critics (Qwen3-VL) and ComfyUI cannot share tower 1's card: run critics between batches (ASSET-PIPELINES). Local critics first, Claude reviews only what passes (GLASS-BOX.md s2).
- Laptop on battery runs the 4090 about 4x slower: stay plugged in and keep its GPU for the editor (ASSET-PIPELINES).
- Towers never commit to main; game repos on towers are read-only clones (LESSONS L-GIT-7). Big transfers in 2 GB batches with a manifest; verify by hash (L-OPS-13).
-
Push the commit to origin first, then submit; towers fetch from origin (failures.md Thu 00:05). Job specs run in a fresh worktree: no
-
Tower 2 (Threadripper 24 threads, AMD W6600, no CUDA; has VS Build Tools and MSVC 14.44 since Sat 03:30)
- Cannot run Kimodo or CUDA tools, can now compile C++ (MSVC 14.44; TOWER2-UE-BUILD.md), cannot show a game window over ssh. Code-project packaging on tower 2 is new and unproven here (check TOWER2-UE-BUILD.md); copy the zip back to the laptop and smoke it there (MCP-RUNBOOK).
-
Reach it through tower 1 (ssh studio-tower2); if silent, check
ip -4 -br addr show enp179s0on tower 1 (HANDOFF). Its agent starts at logon: a reboot drops it from the queue (LESSONS). - The tower 2 editor is shared (KKCast, other sessions). Ask first; restore the open level and save it before any stage script. A restart cost 27 to 40 min (failures.md Thu 16:18, Thu 17:59; GLASS-BOX.md s5).
- Its fps and render times mean nothing while another session uses the W6600. WSL has no numpy or Pillow: install by script file (timing.md Fri 21:10; failures.md Thu 04:58).
- Good jobs for it: golden packaging, headless import checks, MRQ renders with -RenderOffscreen, CPU Whisper and loop checks, Blender CPU builds, bot QA on the packaged game (ASSET-PIPELINES; GLASS-BOX.md s2).
-
Timing
- Take 1.2 to 2x off batch and generation estimates; expect looks and engine rounds to add 1.2 to 2.2x. Scope changes mid-run stretch tickets most; fold notes in before the next round (timing.md).
- Plan-first pays: one bone-length check saved 2 h of a bake that would have missed by 20 cm. Put a planner step before long engine tickets (timing.md Fri 11:16).
- Quota pace: three or four workers under the pace line; over by 3 points two workers plus Haiku; over by 6 the director alone (GLASS-BOX.md s7; usage-pace.md).
10. Submission, licenses and Glass Box
-
Traps
- Pre-jam content is ineligible (rule 7h): only tools, configs and scripts before Nov 12 00:00. Nothing from Heist or Late Checkout ships (RISKS).
- Sourced assets (Fab, Megascans, Mixamo, fonts, library sounds) are unscored (rule 15c) and must be listed; our generated assets are ours and scored. Anything seen over a second should be ours (SOURCED-ASSETS; research/motion.md).
- No trademarks in credits except the Unreal logo (rule 15d): in-game credits name people and licenses only; tools and brands go on the itch page (STANDARDS Contest).
- Fab items flagged "usage with AI: No" stay out of the project entirely (see section 11); Megascans free ended 2024-12-31; Fab EULA bars extraction: ship only inside the packed build. Epic's free animation packs are flagged AI: No (SOURCED-ASSETS; HANDOFF).
- Generated images invent brand marks: check every sign, poster and texture for lettering. Real product names bar use (STANDARDS; freebies-and-tools).
- Teen 13+: no nudity, no animal cruelty; food gore only (sauce, dough, grease) (STANDARDS Content).
- Deadline: itch shows 01:59 UTC Nov 16 = 8:59 PM ET Nov 15. Our target is Sun 4 PM ET. Don submits himself; agents never log in, accept terms or type passwords (SUBMISSION-KIT; RISKS).
- Upload can fail Sunday: Draft page Friday, golden upload Saturday so Sunday is a swap; keep zip, video and text on a USB stick (RISKS).
-
Methods
-
Zip
BYOKGames_GameName.zip, packaged folder only, double-click exe runs; SmartScreen note on the itch page. Checklist twice: Sun 12:30 on the RC, Sun 3 PM from a logged-out browser with hash match (SUBMISSION-KIT). - Accessibility before submission: flash check (a FAIL blocks the build), subtitles with speaker on a backing box, remappable controls, reduce motion, controller plus touch plus keyboard (STANDARDS Accessibility; LESSONS L-TASTE-8).
-
Glass Box is the most winnable modifier: log every decision, failure and asset (prompt, model, seed, license) in assets.jsonl through asset_log.py; transcripts stay out of git (they hold keys and paths); gitleaks
--redactbefore publishing (PLAYBOOK.md in prep; LOGGING). - Credit every third-party asset, CC0 included, with a registry line (source, author, license, date read); credits screen is built from it (CREDITS.md; LESSONS L-LIC-3).
- Paused for the jam, re-enable Nov 16: laptop nightly studio jobs, tower 1 byok-watch.timer; pause Windows Update on both machines (README; RISKS).
-
Zip
11. Prep-chat facts (Nov 11 to 12, from the prep chat's own record)
Sources: lab/megajam/HANDOFF.md (the hand-off table and numbered rules) and lab/motiongen (study, best-takes, UE59-STUDIO-TRIALS.md).
- Fab items flagged "usage with AI: No" (Epic's free animation packs) stay OUT of the project entirely. Settled by the director 2026-11-14, HANDOFF.md rule 8 stands: our pipeline runs AI critics on frames and AI motion tools, so "in game but never fed to a model" is too easy to break. (HANDOFF.md)
- MetaHuman hair, brows and moustache render in the editor but vanished in a Blueprint-only packaged exe (face mesh gets no skin cache). Likely fix: a code project packaged with a compiler (CLOTH.md; laptop or tower 2). Judge faces only from packaged frames. Lip sync did not drive the face in the editor's sequence preview. (HANDOFF.md)
- About 170 MB of zip per full MetaHuman at MEDIUM; HIGH looked the same in close-up. Plan one hero face and find out what a second character shares before adding one. (HANDOFF.md)
-
After a tower 1 reboot its second port (enp179s0) needs Don to reconnect it by hand, or tower 2 is unreachable (it is reached through tower 1). Check
ip -4 -br addr show enp179s0on tower 1 first. (HANDOFF.md, status table) -
The laptop UE 5.9 root is nested:
D:\Epic_Games\UE_5.9\UE_5.9. Scripts default to 5.8 folders, so pass-EngineDir(HANDOFF.md; MCP-RUNBOOK). -
Director tool (
prep/scripts/director/, SCRIPT-FORMAT.md): slow motion stretches the timeline and drifts later cues, so keep slow motion after the last cue until fixed; no fail branches are built; the timing bots assume zero-cost human timing. (HANDOFF.md) - Backlot: never opened or copied during the build; nothing from it ships or goes into the Glass Box release. Its lab page is behind a pass-code gate that must be removed after the jam (lab\site, lab.json; Don has the code). (HANDOFF.md)
-
blender-mcp (an LLM drives Blender):
D:\studio-ai oolslender-mcp, attached to a portable Blender 5.2.2; driverlab/blender-talk/scripts/driver.py. Good at rooms, lights and camera moves in 20 to 45 s; weak at posing and keying, so key those by hand or script. (hub note, 2026-11-14; METHODS Operations) - The laptop nightly jobs are paused on purpose until Mon Nov 16; do not re-enable them and do not report them as broken. (hub note; README.md)
- An open editor dialog (Save Content, import options, plugin prompts) freezes unreal-mcp: every call times out until someone closes it. Look at the screen first. (MCP-RUNBOOK)