菜单
Use when adding or modifying DungeonEngine content (items, affixes, weapons, enemies, bosses, enemy roles, skills, materials, levels) or generating assets, and to check known pitfalls/gotchas before touching combat, loot, networking, split-screen, or entity handles.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/edrethardo/game --skill engine-how-to命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | engine-how-to |
| description | Use when adding or modifying DungeonEngine content (items, affixes, weapons, enemies, bosses, enemy roles, skills, materials, levels) or generating assets, and to check known pitfalls/gotchas before touching combat, loot, networking, split-screen, or entity handles. |
Recipes for extending the DungeonEngine and the known gotchas to avoid. Extracted from
CLAUDE.md, whose slim core keeps build + architecture + directory map + conventions.
Reference material (types/constants, game loop, data lifecycles, JSON schemas, networking,
debug keys) lives in the engine-reference skill.
tools/gen_mesh.py, textures via tools/gen_texture.py, skins via tools/gen_skin.py, skill icons via tools/gen_skill_icons.py. Run tools/build_assets.py to rebuild all assets. Never hand-author .obj or .png files — the tools ensure correct format, naming, and sizing.tools/gen_steam_capsules.py → store/steam/*.png at Steam's exact sizes. It composites a key-art background with the re-drawn gold/red wordmark (the shipped logo_*.png are baked on black and won't composite). Capture real "hero shots" in-engine with F8 (F10 hides the HUD, F2 noclip frames; writes screenshot_*.png to the CWD) and pass them: --landscape <png> --portrait <png>. To skip the menu when capturing, launch with the CLI flags (engine-reference → "CLI launch options"), e.g. DungeonEngine --host --new sorcerer lands straight in-game. With no shots it falls back to the logo's own dungeon scene art (gen_logo.draw_scene_art, refactored to be text-free) so the full set always emits at logo quality. Not part of build_assets.py (release/marketing task, run on demand)._NN suffix is the gen_texture.py SEED, not the size (most use seed 42 → stone_wall_42.png, but stone_wall_moss_7.png is seed 7). Unlike meshes, generated PNGs ARE committed. A new tile needs: a generator + registry rows in gen_texture.py, a row in build_assets.py's textures list, and (if the engine uses it) a materials.json entry.assets/materials.json): each entry has id (must match array index), name, optional texture (path under assets/textures/), optional tint [r,g,b,a]. Material 0 is the default fallback. Code looks up by name via MaterialSystem::getIdByName.assets/meshes/*.obj): triangulated, +Y up, units in metres. Loaded at engine init by name into the Engine::m_meshDefs registry; mesh 0 is always a unit cube fallback. Names referenced from JSON (item mesh field, enemy meshName).assets/shaders/*.{vert,frag}): basic is the lit textured shader for level/entities/items. unlit is for HUD/billboards. debug for DebugDraw. vignette (reuses unlit.vert) is the fullscreen radial red damage vignette drawn in Engine::renderPostOverlays via drawScreenQuad; intensity rides in the quad's alpha and the fragment shader does the corner-weighted falloff — it never flashes (photosensitivity-safe).assets/audio/sfx_*.wav, 44100 Hz / 16-bit / mono; gitignored, regenerated). Source pool = CC0 packs in build/audio_cache/ (populate with tools/fetch_audio.py --cache-only). Two generation paths: tools/fetch_audio.py auto-maps every SfxId from the packs by keyword + a fixed per-sound pitch, and tools/gen_audio.py is the procedural (sfxr-style) fallback. To hand-pick the 15 weapon/reload sounds, use tools/pick_sfx.py — a local web app (Python stdlib http.server; needs only numpy/scipy/ffmpeg) that ranks candidates per slot (keyword + acoustic features: duration/brightness/attack/transients), auditions them with a full effect chain (pitch, stretch, gain, reverb, lowpass, trim), and on save writes the chosen WAV plus a git-tracked manifest tools/sound_selection.json. python3 tools/pick_sfx.py --apply re-renders every manifest slot headlessly. fetch_audio.py is manifest-aware: it skips the hand-picked slots (never keyword-maps or pitch-shifts them) and self-applies the manifest via pick_sfx.py --apply in a final Phase 4 — so a single fetch_audio.py run yields correct sounds and committing tools/sound_selection.json is all that's needed for hand-picks to ship un-pitched everywhere (incl. CI) (--apply needs only ffmpeg — numpy/scipy are lazy-loaded for ranking only). gen_audio.py --all likewise skips manifest slots (explicit --type <slot> still regenerates one). The engine loads sfx_<name>.ogg before .wav, so the tool deletes any shadowing .ogg when it writes a slot.New item: use the dedicated create-item skill (items.json append-only discipline, def-shape recipes — gear vs unrollable/sentinel/consumable, icon + tooltip wiring, MAX_ITEM_DEFS cap, despawn rules). Short version: append to assets/config/items.json (NEVER insert — defId is the array index and is saved in ItemInstance), generate any new mesh via the asset tools + register in asset_manifest.h AND build_assets.py, cap is MAX_ITEM_DEFS (224).
New pet consumable: use the dedicated create-pet skill (petSummon def → summon path → follow AI → net use-path → beacon/icon; per-enemy pets are generated from enemies.json and pinned by a sync test).
New affix type: use the dedicated create-affix skill (enum → loader → recalculateStats → consumption → affixes.json sync chain).
New weapon: use the dedicated create-weapon skill (items.json + generated mesh/skin/material; or a new WeaponSubtype + firing behavior).
New enemy type: use the dedicated create-enemy skill — it covers the full pipeline (generated mesh + skin via the Python tools, material, kMeshes registration, the enemies.json entry, and the behavioral gimmick incl. adding a new EnemyRole). Don't hand-roll the steps here.
New boss: use the dedicated create-boss skill (bosses.json: floor/roles/personality/skill/projectile/loot; optional dedicated mesh + limb config).
New enemy role: covered by the create-enemy skill's gimmick path (new EnemyRole constant + u8→u16 widening + parseRole mapping + behavior branch in enemy_ai_roles.cpp).
New skill: use the dedicated create-skill skill (SkillId → SkillDef → loader → tryActivate branch → optional per-tick → skills.json → HUD icon → granting legendary item).
New quest (an act beat). Quests are authored C++ data, not JSON — Quest::QUESTS[] in
game/quest_def.h, with the rules in the pure game/quest_state.h. The recipe:
QuestDef row. Never insert, never resort. A row's POSITION is its slot in
Quest::Progress::state[] and its bit in the derived completion mask, so moving a row silently
reassigns every saved hero's progress. The table is walked in order by the road, the Journal and
giverOutstanding, so append in the order the quest is meant to be reached.zoneFloor (which zone it belongs to — Quest::forZone/indexForZone key off
it, so exactly one quest per zone), name, blurb (the one-line chat offer), narration (the
Journal body — unbounded, the panel word-wraps it), giverIdx into GIVERS[], and up to
MAX_OBJ (4) objectives.TALK. Every quest opens by speaking to somebody, and it gives the
Journal a first row that is true the moment the quest is known. It is pinned by test — and it is
never a prerequisite: reevaluate() excludes TALK from the completion test, so the quest
completes on its DEED alone. Do not "fix" that. There is no walk-back in this design, the onward
gate reads quest completion, and the act soak's bot cannot talk to anyone — a blocking TALK seals
the road for every bot and for any player who does not return to the hub.CLEAR_ZONE (polled off the live entity pool), SLAY (hooked at handleDeathPreamble, the one
choke every death funnels through), REACH (zone entry), ACTIVATE (N world fixtures, stored as
a bitmask). ZoneRoute::linkOpen gates the onward road on the host zone's quest, so a trigger
nothing implements SEALS the act for anyone playing that commit — this was actually done once and
had to be reverted. "every quest's deed trigger is one the engine can satisfy" in
tests/game/test_quest_state.cpp now fails the build instead.Quest::satisfy
already handles any BOOLEAN trigger generically (it matches on trigger kind and writes
required), so a counting/accumulating one needs its own, the way noteActivate sets a bit; and
a ZoneRoute::Task plus a branch in () so the BOT
can complete it — with no task it falls to , whose next hop from the zone you are standing
in is NONE, so reports no goal and the driver logs STRANDED and ends the run. The
Journal needs nothing: it prints and appends whenever
. Prefer composing shipped triggers.New material: edit assets/materials.json. ID must equal array index. Look up at runtime by name with MaterialSystem::getIdByName. Tint blends with sampled texture color (1,1,1,1 = unmodified).
Armor visuals on the player body (inspect screen). Equipped armor renders on the class body mesh in the Character inspect screen (T or K / LB++) via Engine::submitPlayerEquipment(). Each armor ItemDef resolves to a per-tier mesh at init: armorTierFromMaterial() maps the material name suffix (_light / _medium / _heavy) to ArmorTier::LIGHT/MEDIUM/HEAVY, and the matching ItemDef.tierMeshId is filled by ItemLoader::resolveVisuals. The 3-D model render path lives in engine_render_character.cpp::renderInspectModelToFbo() — it creates an offscreen FBO (square, same aspect as the panel), renders via the normal Renderer::submit/flush pipeline with a standalone orbit camera (yaw driven by mouse drag / right-stick), then composites the result into the 2-D overlay in renderCharacterInspect(). FBO size is platform-gated: kInspectFboSize = 320 on __SWITCH__ (weaker GPU), 512 on desktop — the panel upscales either way so quality loss is minimal. The camera projection aspect is always 1.0 regardless of the FBO size; only the pixel dimensions change.
New Steam achievement: use the dedicated create-achievement skill (trigger design around what each machine knows, event-driven vs 1 Hz polled unlock, generated 64×64 achieved/locked icon pair via tools/gen_achievement_icons.py, DEPLOYMENT.md row, the mandatory build-steam compile check, and the partner-site define/upload/publish steps).
New level layout: LevelGen::generate (world/level_gen.cpp) is the production path — pass a seed, grid dimensions, and a LayoutStyle. Five structural styles exist (BSP_ROOMS classic, CAVERN cellular-automata cave, GAUNTLET serpentine arena chain, HUB central chamber + spoke vaults + ring, VERTICAL_HALL the two-story "Stacked Loop" — a Quake location-based topology (NOT one arena): nine distinct areas in a 3×3, stacked across two stories and circled by a route that spirals up/down. Four CORNER ground rooms (cover pillars), four MID-SIDE CELL_PLATFORM BALCONIES @ 3 m (walk on / walk under the arcade), and a central open VOID every balcony overlooks + drops into. A PINWHEEL of four graduated-slab RAMPS climbs each corner→balcony; two CATWALKS cross the void (one intact, one broken-jump) so the upper story loops too; JUMP-PADS fling you up. Spawn/exit on opposite sides AND stories (coin-flip ascend/descend); the lower story is one fully-connected floor so reachability is guaranteed. floor-6+ non-boss; carveVerticalHall records the four ramps as StoryPortals for the cross-story enemy chase + the sniper nests, --vhall dev door; FOUR_STORY the four-story "Descent" MAZE — a braided recursive-backtracker maze (3-wide corridors, 1-cell walls, ~34% wall) carved ONCE as full-height CELL_SOLID and shared by all four stories (L0 + slabs @ 3/6/9 m), so each level is the same labyrinth at a new height. Descent is one-way through the floor and the drop/jump split is DERIVED from movement physics (6 m/s → 2.4 m jump reach, 0.6 m body): ≥2-cell DROP HOLES are uncrossable = a committed one-story fall, 1-cell JUMP GAPS are crossable, dead-end JUMP PADS lift ~2 stories. portalCount stays 0 (no ramps/stairs). Hole density thins with depth (18/12/7%). Express shafts are impossible by construction: a hole is punched at level L only where the slab at L+1 is intact, so the GRID is the ledger and the rule can't drift. Spawn L3 one corner, exit L0 diagonally opposite; --fourstory dev door); LevelGen::pickLayoutStyle(dungeonSeed, floor) picks one per floor with per-tier weights (floors 1-3 always classic; caves peak in Spider Caverns, gauntlets in Hellforge, hubs in Catacombs). Adding a style: write a carve<Style>(grid, rng, result) that emits rectangular DungeonRooms + corridor addAdjacency links, dispatch it in generate, add a weights column, and let the shared finalizeDungeon handle spawn/exit/bbox-adjacency (pass forcedSpawn/forcedExit only for a style with a mandatory flow, like the gauntlet's start→end). : rooms are RECTANGLES fully inside the 1-cell border (every consumer — enemy/chest/boss/light/portal placement — reads room rects and centers, and — on a style with interior walls a naive rect centres on a wall surprisingly often, so snap the rect onto known-open geometry; VERTICAL_HALL scattered a cover PILLAR onto a room centre and FOUR_STORY centred rooms on maze walls, both caught only once they were added to ); everything must be reachable from spawn; carve ONLY through with integer/compare-only math — and host + client must carve bit-identical grids from the shared seed; a degenerate carve (<5 rooms) falls back to BSP deterministically inside . pins all of this per style — run it before anything else. is a hardcoded fallback. Hand-authored levels can be loaded via () but no level JSON files ship by default.
Adding vertical variety (raised floors, tiers, jump-ledges). A cell's floorHeight (quarter-units, ×0.25 = m) raises its walkable floor; Collision::moveAndSlide snaps a body up onto a higher floor as it walks, so a plain raised floor is walkable at any height (unlimited walk-up — good for tiers/ramps/daises the boss + enemies traverse). Two supports make this usable: (1) the mesher (level_mesh.cpp) now emits the vertical riser face between two OPEN cells of different floorHeight (drawn once, by the higher cell, toward each lower open neighbour) — without it a raised platform is a floating quad with a gap at its edge; and (2) a CELL_LEDGE flag (level_grid.h) marks a raised floor as jump-only: Collision::overlapsLedgeAbove (used in player AND entity moveAndSlide) treats it as a wall when the body's feet are more than STEP_UP_HEIGHT (0.4 m, collision.h) below its floor, so you must JUMP onto it (the 0.8 m apex clears ~0.75 m ledges). Enemies never jump → a CELL_LEDGE is always a wall to them, so use it ONLY where enemies shouldn't follow (the PvP arena — buildArenaLevel's raise() lambda) and use plain raised floors for boss-arena tiers (enemies follow, no cheese). CELL_LEDGE is opt-in per cell, so every existing level + every walkable tier stays on the unlimited walk-up path — zero regression. Pinned by tests/world/test_collision_push.cpp (overlapsLedgeAbove grounded-blocked / mid-jump-allowed / plain-floor-never-gated). Traps: the A* pathfinder + clearance field are 2-D and DON'T know about ledges, so an enemy would path toward a CELL_LEDGE and stall at its base (fine in the enemy-free PvP arena; don't drop a CELL_LEDGE into an enemy's route); and don't raise the cell a boss/portal/prop is pinned to (its Y is stamped from the base floor).
Jump pads (CELL_JUMPPAD, Quake/Combat-Hall launchers). A third opt-in flag (level_grid.h, 1 << 4) turns a walkable floor cell into a launch pad: Collision::onJumpPad detects a body RESTING on it (any overlapped pad cell whose floor is within STEP_UP_HEIGHT at/below the feet), and at the end of both moveAndSlide overloads — after the floor snap sets onGround — a grounded body on a pad has its velocity.y replaced with JUMPPAD_LAUNCH (17 m/s, apex ~3.6 m; collision.h) and onGround cleared. You can't stand on a pad — you get flung and air-steer the arc (horizontal velocity is rewritten from input every tick in applyMovement, so full air control composes; a directional pad wouldn't — the boost would be overwritten next tick). Why it needs zero wire change / no PROTOCOL bump — the key insight: the launch is a pure velocity.y impulse exactly like the jump, and moveAndSlide is the ONE choke every movement path funnels through (local prediction engine_update.cpp, the server's per-input remote drain via a temp Player in serverNetPre, AND reconcile replay). SnapPlayer carries posY + onGround (not velY), and the trigger is deterministic geometry identical on client and server, so a client predicts its own launch, the server produces the same posY, reconcile agrees (self-correcting within a tick like any impulse — never rubber-bands), and observers see the arc via posY interpolation. Pads are PvP-only (enemies never jump → a pad in an enemy route is a dead end; boss arenas use plain walkable tiers). Local launch SFX (SkillId-free — reuses SfxId::SKILL_DASH) fires in engine_update.cpp by detecting the fresh velocity.y crossing of JUMPPAD_LAUNCH after moveAndSlide. Pad cells render distinctly via a floorMaterialId (the arena_pad glowing material) — no mesher change (a pad is just a CELL_FLOOR cell; risers between a raised pad ring and its neighbours draw like any tier). Pinned by ( detect/plain/below-feet + launches / plain-floor-doesn't).
Two-story cells (CELL_PLATFORM) — the rules that keep them honest. (0) A slab may ONLY
sit over a floorHeight-0 ground story: a platform over a RAISED floor freezes bodies on those
cells solid (measured twice building the arena Pit — 116 telemetry samples, 2 distinct
positions, with and without CELL_LEDGE on the cell). No shipped level combines the two; use a
raised LEDGE walkway where a deck-over-raised-ground shape is wanted. (1) A platform cell must keep CELL_FLOOR — its ground story is real and walkable; setting CELL_LEDGE on it would wall off the arcade beneath. (2) Adjacent slab tops may differ by at most 1 qu (0.25 m) where players walk between them — a bigger step reads as a wall (overlapsPlatformBand). Slab STAIRS are just graduated platHeight runs. (3) Never put a CELL_JUMPPAD on or under a slab — on top it launches over the arena walls; underneath it bounces the body against the underside forever. (4) Any code that means "the floor under THIS body" must call effectiveFloorHeight(x,z,feetY), never getFloorHeight — the raw getter is the ground story and will teleport-snap a balcony walker down (or an arcade walker up). (5) World-item ground snapping and enemy AI still read the base floor by design — don't put loot or PvE fights on platforms until those consumers are converted.
HUD::StatusEffect row to the statuses[] array in engine_hud.cpp (label, colour, timer — a timer of 0 hides it), and (2) append its 8x8 glyph in the SAME position to the icons[] table in hud_status.cpp. Get the order wrong and the HUD shows the wrong icon for the effect — a silent, purely visual lie that nothing catches. A static_assert pins the table against STATUS_ICON_COUNT. The art is generated, never hand-written: author it as ASCII in tools/gen_status_icons.py (. = transparent, 1-4 = palette shades, row 0 = top) and re-run it (or tools/build_assets.py, which invokes it). The script emits src/renderer/status_icons_data.h — icons AND palettes together, so art and colour cannot drift apart — and validates the art (wrong row count, wrong width, bad pixel char, or an entirely empty icon all fail loudly rather than shipping a blank box). Unlike assets/meshes/*.obj, this header IS committed, so it can't vanish on CI.The Autoplay bot (--autoplay, or the main-menu row) plays a lane-0 singleplayer run by injecting
synthetic input at the ACTION layer, not the wire. The flow, per sim tick, all in
engine_autoplay.cpp: Engine::updateAutoplay(dt) → (1) m_autoplayControl.tick(humanActivity, uiOpen, dt)
runs the takeover/resume latch; (2) if the bot is in control and botMayAct(), buildBotView()
snapshots live state into a pure Autoplay::BotView (self / effective weapon / nav flow-field +
per-style vertical goal / nearest hostiles with WORLD-ONLY LOS); (3) Autoplay::decide(view) (the pure
brain, composing doctrine+combat+nav) returns a BotIntent; (4) driver backstops adjust it
(loot-settle dwell, low-HP globe detour, descend pulse, a stalled-fight break-off, the exit-progress
watchdog, and the escalating geometry escape: nudge → 8-dir search → A* leg); (5) applyBotIntent writes yaw/pitch and arms the held
GameActions via Input::setBotHeld. To CHANGE bot behavior, edit the pure core (src/game/autoplay_*)
and add a TEST_CASE on a hand-built BotView (they're engine-free) — tests/game/test_autoplay_*.cpp
tests/world/test_autoplay_nav.cpp. The doctrine (how a build cell fights) is the doctrineFor table;
the priority order is in brain.cpp (survive > fight > descend > travel). Add a new synthetic action by
just setBotHeld-ing it in applyBotIntent — it flows through the human consumer automatically.
v1 scope, honestly: flat floors (rooms/cavern/gauntlet/hub) run unattended for every
archetype. The stacked (VERTICAL_HALL/FOUR_STORY) and lava floors route correctly and never leave
the bot permanently wedged, but they are dense and vertical — traversal there can be slow and a hard
floor may not complete quickly (VH balcony story-routing oscillates on some seeds). Bench a bot change
on a flat floor for the regression and on --vhall/--fourstory/--lava for the limits.Autoplay pitfalls:
--bot-walk is a NETCODE probe, not this bot. It injects deterministic movement on the WIRE
(NetInput) for divergence testing and is DEAD in singleplayer. Autoplay injects at the ACTION layer
(Input::setBotHeld → checkActionRaw) so it drives the real human code paths in SP. Don't confuse them.GameAction::PICKUP, never by writing m_descendRequested. updatePlayerPickup
resets that flag every tick and re-derives it from the button's tap/hold arbitration — a direct write is
erased. And a CONTINUOUS hold fires Interact::poll exactly once (it latches consumed) and a HOLD
reaches a shrine sharing the exit's interact range before the exit, so the driver must PULSE PICKUP
(Autoplay::descendPulseHeld) — one cycle spends the shrine, the next descends. A plain hold wedges the
bot beside a used shrine forever (it never releases, so the latch never clears).WeaponDef::range is 0 for EVERY projectile weapon. items.json authors baseRange only for
melee and hitscan; wands/bows/staves/crossbows carry a projectile SPEED instead (the shot flies until it
hits or its 3 s lifetime expires — the tooltip even prints "Proj Speed", not "Range"). The bot's whole
doctrine is ×weaponRange, so feeding the raw 0 in collapses the engagement band to zero and the bot
can NEVER fire a caster/archer weapon — it just backpedals and dies (the "sorcerer stuck on floor 1"
bug). Always fill BotView.weaponRange through Autoplay::botWeaponRange(range, projSpeed).applyBotIntent must gate on Autoplay::aimOnTarget(actualYaw, actualPitch, in.aimYaw, in.aimPitch, melee) — the actual (post-stepAngle) aim vs the intent. Arming FIRE straight off
in.fire sprays every wall the crosshair is still sweeping across ("ranged is shooting through walls":
22% of shots blocked by geometry, mean yaw error 27°). The tolerance is squeezed from both sides — it
must exceed the ease's steady-state tracking lag + wobble (~0.078 rad) or a strafing enemy MUTES the
bot, and MELEE needs the separate wide/pitch-free tolerance because its swing is a 70° HORIZONTAL cone.The balance lab (tests/balance/, spec: docs/superpowers/specs/2026-07-22-balance-lab-design.md) models typical-equipment player power against the enemy/boss curves by driving the REAL engine code — ItemGen drops, BuildScore scoring, Inventory equipping, the GameConst spawn multipliers — per (difficulty, floor, build cell). Its always-on sanity pins run with the normal test suite; the full sweep is env-gated:
BALANCE_REPORT=out.csv ./build/tests/dungeon_tests -tc="*balance report*"
python3 tools/balance_chart.py out.csv -o out.html # CSV → one-page HTML curve report
tests/balance/balance_lab.h — DROPS_PER_FLOOR (12), WINDOW_FLOORS (4), TRIALS (200), and columnClass (the representative class per damage column: SORCERER magic / WARRIOR melee / MARKSMAN ranged). They are declared model assumptions, not engine truth — the header documents the reasoning behind each; tune them there (with the why) if the model drifts from real play, never by patching engine constants to make a chart look right.game/weapon_dps.h, shared with build_score.h), Combat::armorMitigation (inline in combat.h), kClassDefs (game/class_defs.cpp), and enemyTierForFloor (enemy_def.h, shared with the spawner). Never re-inline any of them into a single caller — a private copy is exactly the scorer-drift bug the 2026-07-22 loot fixes cleaned up: the lab and the engine silently computing different numbers from the "same" formula.REQUIREs in tests/balance/test_balance_lab.cpp — one why-comment per number, the game_constants.h discipline — so CI fails when a content or constant change knocks a floor out of band."typical gear: every build cell fields a weapon from mid-game windows"). That pin FAILING is the feature working, not test noise — the lab's first run caught levels 39-50 shipping no non-legendary wand (fixed by adding the Void Scepter). Run the pins before shipping the content, and fix the content gap, not the pin.The BOMBER death blast is XZ-only, on purpose. engine_death.cpp's suicide explosion (3.5 m,
damage * 3.25) ignores vertical separation. That is required for FLYING bombers — a Plague Bat
hovers 1.5-2.5 m above its target by design, so a 3D distance test would make it whiff the player it
just dived at. The accepted cost is that on VERTICAL_HALL / FOUR_STORY a suicider can catch a player
through a floor from the storey below. Known and deliberately unfixed (Aaron, 2026-07-29); switching
to a 3D test without special-casing flyers would silently disable flying bombers entirely.
A multi-story cell has N slabs — a scalar read of it is a phantom. Anything that inspects
CELL_PLATFORM must loop platformCount() and use the INDEXED getters. The single-slab reads
(highest top, lowest underside) describe a phantom full-height band that walls off the legal
standing space between two slabs; the rising head-clamp must take a running MIN over qualifying
undersides (last-wins pops a body under L1 through onto L2); a descending raycast must walk tops
top-down and, when a higher top's crossing lands out-of-cell, CONTINUE to the next slab rather
than dropping to the base floor (otherwise a shot threading a drop-hole snaps to the ground). And
pick the right authorer: setPlatform (replace) for every legacy single-slab writer — they
genuinely double-write cells, so addPlatform would fabricate a phantom slab there and the
determinism memcmp would NOT catch it (both peers generate the same wrong geometry).
MAX_ENTITIES is WIRE layout, not just a memory budget. WorldSnapshot carries
SnapEntity[MAX_ENTITIES] and delta-encodes one "unchanged" bit per pool slot, so changing it
changes the packet layout and REQUIRES a PROTOCOL_VERSION bump. Keep the bitmask width DERIVED
(ENTITY_MASK_BYTES), never a literal: a mask narrower than the pool silently no-ops for the high
slots, which can never be marked unchanged and are therefore resent every tick forever. That exact
bug shipped once already (a 64-bit mask over a 128 pool ≈ 123 KB/s of avoidable resend).
The entity pool is shared, and spawns fail SILENTLY when it's full. Decorations, friendly NPCs, boss adds, pets, summons and breeders all draw from it alongside floor enemies. An area-driven per-room enemy count applied across a multi-story floor will quietly eat the pool — the four-story floor seeded 92 enemies and hit 122/128 on its first boot, starving everything spawned after it. Reserve headroom in and check spawn return values.
Engine::zoneBotGoalengine_autoplay_zone.cppTRAVELzoneBotGoalObjectiveDef::textn/requiredrequired > 1buildZoneLevel, never in
spawnZoneContents. The builder runs BEFORE LevelMeshSystem::buildAll and the spawner AFTER,
so a pad cleared in the spawner behaves as floor while still RENDERING as rock. Anchor on ROOM
CENTRES (zoneAnchorRoom/zoneRoomCentre) — every layout style guarantees those open and
connected, while a fraction of the grid can land in rock. Check the anchors do not collide with
the zone's waypoint or POI mouth: the interact scan ranks a gate above a fixture, so a fixture
sharing a cell with one can never be used and the quest can never complete. The fixture itself
should ride the sentinel path (a new *_ID below CAIRN_STONE_ID), which buys spawning,
replication, server-side validation and the despawn exemption for free.MAX_QUESTS (32) or MAX_OBJ (4) casually — both are SERIALIZED sizes in the v7
per-player tail, so either costs a SAVE_VERSION bump plus another pair of legacy readers,
forever. MAX_QUESTS <= 64 is static_asserted because completion travels as a u64.GiverDef row (hubFloor 98 = the town, 61 = Null Terminus) plus a spawn in
that hub. Spawn givers on EVERY PEER, not host-only: Entity::questGiver is a pool field
absent from SnapEntity, so a snapshot-replicated giver reaches a guest with questGiver == 0xFF
and never shows a prompt. Both hubs are deterministic geometry both peers already rebuild, and
talking changes no world state, so a local spawn is correct and costs no wire change.tests/game/test_quest_state.cpp — it lints the authored table (a narration, a TALK
opener, a SLAY target that names a real enemy, a giver whose quests are all in its own act) and
then the state machine. tests/game/test_zone_route.cpp pins that no gate can strand a
character across the whole quest order; run it too, since a new quest changes that order.kAllStylesGenRNGcos/sin/transcendentals, libm results differ across platformsgeneratetests/world/test_level_gen.cppLevelGen::generateTestDungeonLevelLoader::loadFromJsonworld/level_loader.htest_collision_push.cpponJumpPadmoveAndSlideTARGET_LOS_GRACEAIM_DEADZONE_RADstepAngleFIRE_ALIGN_RADAIState::DORMANT
EnemyRole::AMBUSH wakes ONLY when a player is in range and nobody is watching, and
Combat::applyDamage returns early on one so it cannot be shot awake. It is NOT filtered out of
buildBotView's target list, so the bot aims at it (pinning it asleep) and fires for zero damage —
a standoff that by construction cannot clear. The driver's 3 s look-behind (turn 180°, one-shot per
stuck episode) is what breaks it; anything that suppresses the look-behind, or that keeps the bot facing
a stalled target, brings the wedge back.updateFloorDoor descends inside
2 m (Autoplay::DESCEND_RADIUS); the exit-wedge remedy used to plant the bot at 2.5 m holding
PICKUP, and since standing still is itself "no progress" the remedy re-armed forever (73 s frozen beside
an open exit). Any new "stop and hold interact" backstop must gate on Autoplay::DESCEND_STOP_M (1.9 m)
or keep WALKING IN — never park outside the radius.Raycast::cast, never CombatQuery::raycast. The combat raycast
sweeps world AND entities and reports only the NEAREST hit, so an enemy standing in front of a wall
makes the nearest hit an ENTITY and the wall stops counting as an occluder — the bot sees and shoots
through solid geometry. Same trap in any new "can the bot see X" test: bodies must not hide walls.engageMin is a movement rule, not a fire rule. Fire needs only LOS + dist <= engageMax×range;
a target inside the kite floor is shot at WHILE the bot backs off. Re-adding a dist >= engageMin
term to the fire gate re-creates the swarmed-caster livelock. The driver's inBandFight stall signal
must track the same gate or the standoff detector goes blind to point-blank fights.BotView.castableSkill[] mirrors the REAL gates
(handleClassSkillActivation + SkillSystem::tryActivate): slot has a skill, unlocked at the
EFFECTIVE floor (currentFloor + difficulty*50), energy pool ≥ energyCost (BLOOD_NOVA pays HEALTH),
and GameConst::cooldownReady against m_classSkillStates[slot].lastActivationTick. Add a gate to the
real path and this mirror must follow, or the bot burns its slot selection on a no-op.flowDirection returns {0,0,0} BOTH at the exit (byte 0xFE)
and on an unreachable cell (0xFF); read the raw byte (atExit/flowValid in BotView) to tell
"arrived" from "stuck" — a zero heading alone can't.buildBotView runs BotView.flowDir through Autoplay::stepAllowed
(the hazard veto: off-map / wall / grounded-in-lava) before the brain ever sees it — heading first,
then ±45°, else zero (boxed in; the stuck-override recovers). Know its scope: it covers the
TRAVEL heading ONLY. applyBotIntent vetoes nothing — the FIGHT branch's kite/close/strafe movement
and the driver's escape/nudge headings are separate (the escape backstop calls stepAllowed itself;
FIGHT deliberately does not). So a new nav source (a detour, a waypoint) must either fold into
flowDir before that veto or call stepAllowed itself. (Balcony-edge drops are intentional traversal
the veto deliberately does NOT cover; those are the driver's story-routing job.)(0,0,-1) (player.cpp), so dirToAim inverts as
yaw = atan2f(-dir.x, -dir.z) (matches engine_arena.cpp). Aiming with a naive atan2(z,x) points the
bot 90°/180° off.PlayerInventory's untouched default is Moderate/Melee for every class, so before the seed
Auto-Equip handed a Sorcerer a sword. enterAutoplayRun(freshCharacter) writes
Autoplay::defaultCellForClass(m_playerClass) only when the run started a NEW hero (threaded from
GameStart::NEW_GAME / !m_menu.p1Continue) — re-seeding a Continue would silently re-gear a build
its player deliberately picked in the inventory grid. The class→column table is EXPLICIT on purpose:
ClassDef::preferredWeapon can't separate Magic from Ranged (Sorcerer and Ranger are both
PROJECTILE). Adding a player class means adding its row — the default: arm falls back to
Melee, which is silent and wrong for a caster.subState/case ids downstream
(the play-style chooser sits at subState 23/24 precisely because 21/22 were already taken).spawnFloorEnemiesA jump pad's strength is per-cell (GridCell::jumpPadQ), not the global JUMPPAD_LAUNCH.
Existing maps tune their balcony heights to the global's 3.6 m apex, so raising it globally breaks
them; author a stronger pad on the cell instead (0 = use the global). Collision::jumpPadSpeed is
story-aware — it compares the feet against effectiveFloorHeight, because with the old base-floor
read a pad sitting on ANY slab story could never fire at all.
A walkable hazard must be distinguishable on the MINIMAP, not just in 3-D. CELL_LAVA carries
CELL_FLOOR (that is what makes it walkable), so the minimap painted a lava lake the same grey as
safe stone and would have routed the player straight into it. Any new walkable-but-dangerous cell
needs its own branch in minimap.cpp BEFORE the generic floor branch.
A theme that edits GEOMETRY must respect the styles it lands on. Hellforge melts every interior
wall to lava, which is fine on a flat style and destructive on a stacked one: CELL_PLATFORM slabs
are only added to non-solid cells, so melting the walls punches a hole to lava through every upper
story. applyLavaTheme is gated on !usesBalconyEndpoints(style) for exactly that reason. Check
what a global retheme does to EVERY style that can roll on those floors.
A cell FLAG is not a skin, and on a stacked floor the visible surface is the SLAB, not the floor.
CELL_JUMPPAD only makes a cell launch you; it does not make it look like anything. Both the Descent
and the Stacked Loop shipped pads that were invisible — the Descent even carried a comment claiming
the glow came from arena_pad while assigning the ordinary floor material. And skinning
floorMaterialId alone is only half a fix: a body standing on L1/L2/L3 sees platMaterialId[i]
(the slab top), so an upper-story pad stays invisible. applyJumpPadSkin in startGame now skins
the floor AND every slab top by NAME, for every style, after the carve and before the mesh build
(level_gen deals in numeric material ids and has no MaterialSystem dependency). Size matters too:
a 1x1 pad in a 3-wide corridor is unspottable — the Descent's fill their whole 3x3 dead-end node.
An XZ-only overlap test is a story-blind test. overlapsAnyObstacle (the player-vs-entity gate in
moveAndSlide) ignored Y "because entities don't block jumping". Harmless while every floor was one
story; on a stacked floor it means an entity standing on ANY story blocks the player on EVERY story.
On FOUR_STORY — four stories over one 44x44 footprint with ~110 entities — something is nearly always
directly below you, so XZ movement was refused while the Y axis stayed free: the player could jump
but could not walk, from the moment they spawned. Blocking must depend on actually sharing space.
(Adding the Y test does NOT let you hop enemies on flat ground: a 0.8 m jump apex against a 1.8 m
body still overlaps. pushPlayerFromEntities was already a full 3-D AABB test and was fine.) When you
add verticality, audit EVERY 2-D overlap/query for the same assumption.
Enemy density is per-STORY, not per-floor. A stacked floor has ~4× the walkable area, so matching a flat floor's total count makes each story feel empty.
Making ONE consumer story-aware while others read the same RAW state is the inverse story-blind
bug. The world-item render fix resolved a drop's DRAWN position through effectiveFloorHeight
(so balcony loot stopped rendering under the slab) — but the STORED WorldItem.position kept the
raw death Y, and interact/pickup/auto-loot all measure that stored Y against
INTERACT_VERTICAL_REACH (2 m). An enemy killed AIRBORNE (a flying bat at 1.5-3 m, a
pad-launched or vaulting chaser mid-arc) produced loot whose model drew ON the floor at your feet
while every grab path refused it — "I can see the item models but not the pickup tooltip", with
auto mode masking it by silently skipping the same items. The fix: WorldItemSystem::spawn snaps
the STORED position onto its supporting surface (same effectiveFloorHeight read the renderer
uses), so all consumers agree by construction — and every drop call site must pass the grid
(a nullptr grid stores the raw Y verbatim). Pinned by the spawn-snap case in
tests/game/test_pet_item.cpp. When you make a read path story-aware, fix the DATA it reads,
not just that one reader.
snapEntityToFloor is STORY-AWARE now (uses effectiveFloorHeight, not raw getFloorHeight) — gated by CELL_PLATFORM, not by layout. It was made two-story-aware for VERTICAL_HALL so enemies climb ramps, stand under balconies, and drop off edges. On a cell with no slab it's identical to before (zero regression), so single-story floors are untouched. But the gate is "does this cell have a platform", not "is this a vertical hall": if you stamp CELL_PLATFORM onto ANY floor (a new style, a boss arena, a prop), enemies there instantly become story-aware too — they'll try to stand on / walk under it. That's usually what you want, but the cross-story CHASE (climbing after the player) only fires when DungeonResult.portals is non-empty (only carveVerticalHall fills it), so a platform without a recorded ramp portal is a place enemies can be ON but won't route UP to — a one-way-up dead end for AI, like a pad/ledge. Record a StoryPortal for every ramp you want enemies to climb. Two functions changed in lockstep (enemy_ai.cpp snapEntityToFloor(Entity&) and the Collision::snapEntityToFloor(Vec3&,…) twin ensureNotInWall calls) — keep them identical.
Player gravity is integrated in EXACTLY ONE place — Collision::moveAndSlide. For a long time it was ALSO applied inside applyMovement (player.cpp, velocity.y -= 20*dt every airborne tick), and since PlayerController::update/updateNetPlayerFromInput run applyMovement and THEN moveAndSlide every tick, gravity landed twice → the felt gravity was -40 while the GRAVITY constant said -20, so the jump reached ~0.8 m / 0.4 s instead of the 1.6 m / 0.8 s the JUMP_SPEED/GRAVITY pair described. It never surfaced as a co-op mismatch because all four paths (SP, client prediction, server drain, reconcile replay) double-count identically — a bug that's invisible precisely because it's consistent. The fix removed the applyMovement copy and set GRAVITY = -40 (single-applied) to keep the same arc. If you touch jump/fall feel, change JUMP_SPEED/GRAVITY in world/collision.h — never re-add a gravity term to applyMovement. The arc is pinned by tests/game/test_jump.cpp (apex = v²/2|g|, airTime = 2v/|g|).
Jump uses coyote-time + jump-buffering, and the two grace timers ride the full local-prediction + netcode chain. The decision logic is the pure JumpAssist::resolve (game/jump.h, tested) — refill coyote on the ground, arm the buffer on a press, fire when a buffered press meets coyote/ground, consume both so one press = one jump. The JumpAssist::JumpState lives on both Player (local prediction via applyMovement) and NetPlayer (server remote sim), mirrored in both syncLocalPlayerToNetPlayer and syncNetPlayerToLocalPlayer (engine.cpp) so the client's rollback-replay — which seeds a scratch NetPlayer from m_players[slot] — starts its timers from the live prediction. It is deliberately NOT on the wire and needs no seedRemoteView/writeBackRemoteView mirror (those views never run applyMovement) and no SnapPlayer field: a jump is an IMPULSE, so its result (velocity.y) is already replicated, and a rare timer disagreement at a reconcile boundary self-corrects within the 0.1 s window instead of rubber-banding. This is the opposite of the continuous-buff rule below (a speed buff MUST ride NetPlayer + the snapshot) — know which kind you're adding.
assets/meshes/*.obj is GITIGNORED — a mesh missing from tools/build_assets.py DOES NOT EXIST on CI or in any release build. Meshes are built, never committed. So the failure mode is: you generate foo.obj by hand while developing, add {"foo", "assets/meshes/foo.obj"} to the engine's table, forget build_assets.py — and it works perfectly forever on your machine and is absent everywhere else. The loader used to skip a failed mesh in total silence, so the shipped game just drew a 0.3-scale fallback cube. Both the loot goblin and the shrine reached one commit short of shipping model-less this way. The mesh table now lives in src/engine/asset_manifest.h (shared data, not an inline table) and three things enforce it: build_assets.py's verify_manifest() hard-fails the asset build if the engine names a mesh it does not generate — comparing against the files that run actually wrote, not what is on disk, because a stale local .obj is precisely what masks this; tests/engine/test_asset_manifest.cpp pins the C++-side invariants (no duplicate names — a dupe silently shadows, since lookup is by name — and the table fitting MESH_DEF_CAPACITY, since an overflow makes the load loop break and drop the table's TAIL); and a failed load is now a LOG_ERROR. Adding a mesh means editing asset_manifest.h AND build_assets.py. Either alone now fails loudly.
No entity may end a tick inside a wall — a direct write to Entity.position MUST validate against geometry. Routine enemy movement (entityMoveAndSlide), the squad/separation pushes, and the champion blink all test Collision::entityOverlapsGrid (or run ensureNotInWall) before committing, so they crowd a body up to a wall but never into one. The paths that DON'T are the bug factory: a summoner reviving a corpse that died flush against a wall (ensureNotInWall can be defeated in a tight spot), and the boss leash-clamp / walk-home that snap position to a point on the leash circle to catch knockback/teleport overshoot. Because there will always be one more such path, EnemyAI::update ends with a wall-ejection safety net: after every position write this tick, any active entity whose capped nav footprint (navExtents, not full halfExtents) overlaps solid geometry is ejected via ensureNotInWall (flyers keep their Y). This is the enemy counterpart to the PLAYER's per-tick wall push-out (engine_update.cpp) — enemies simply never had one. Two rules follow: (1) it uses navExtents deliberately, to AGREE with entityMoveAndSlide's corner-slip tolerance — an oversized boss clips a wall FACE with its full AABB to avoid wedging in a 1 m corridor, and ejecting on the full box would re-wedge it; a normal enemy has navExtents == halfExtents and is guaranteed never embedded. (2) It's authoritative-only (EnemyAI::update never runs on a CLIENT); the fix rides the next snapshot. If knockback or a new ability writes position directly, you don't have to remember the net — but you DO have to keep the net's footprint honest. Pinned by tests/world/test_collision_push.cpp (ensureNotInWall ejects an embedded body, and never nudges one that's already clear — the anti-jitter property).
Every "what am I pointing at?" consumer must read Engine::resolveInteractTargets — never run its own scan. That one resolver is the single source of truth for the aimed item/shrine/chest/mimic/exit (st.itemIdx etc.), and host pickup, the client's CL_PICKUP_ITEM (by uid), and the on-screen prompts all act on it. Whenever a second scan exists, the two drift and the game picks up something other than what the prompt named — because the algorithms differ in every axis that matters (eye vs feet origin, 3D vs horizontal-only dot, Interact::inReach's grab-radius+cone vs a fixed dot/distance threshold, dot − 0.1·dist +legendary-bonus scoring vs raw max-alignment, and the loot-ownership window). This has bitten twice: the shrine prompt (pure proximity while activation needed aim) and the item-pickup name prompt (its own eye-origin scan in renderInteractionPrompts). If you add an interactable or a prompt, resolve it in resolveInteractTargets and READ the result — a for-loop over m_worldItems in a prompt or a pickup path is the smell.
Anything spawning a WorldItem must sit BELOW WorldItemSystem::init(m_worldItems) in startGame. That reset used to run ~30 lines after spawnFloorShrines, so every shrine was created, logged ("Shrine of Power placed in room 3"), and then wiped before the first frame — shrines could not appear in a real game at all, and the log line was true when it printed and false a moment later. A confirming log line is not evidence the object survived. If a spawned thing is mysteriously absent, check for a pool reset downstream of the spawn before you go looking at the renderer.
Minimap markers must wind COUNTER-clockwise. GL_CULL_FACE is enabled globally and Minimap::draw never disables it, so a marker wound the intuitive way (clockwise from the top) is entirely back-facing and culled to nothing — no error, no warning, just an invisible icon. Match the existing quads: right → top → left → bottom.
A legendary skill means DIFFERENT things in different slots — and its tooltip is a separate, silently-rotting table. ItemDef.legendarySkill (items.json) is dispatched per slot: weapon → on-hit proc (m_weaponProc), armor → m_armorAura, ring → m_ringPassive, gloves → m_glovesPassive, offhand → the perfect-block callback, boots/helmet → active skills. The SAME SkillId therefore needs a slot-appropriate implementation and slot-appropriate text. All tooltip text now resolves through ONE entry point — HUD::resolveSkillName / HUD::resolveSkillDescription (hud_inventory.cpp), used by BOTH the item tooltip and the inventory screen's skill-bar tooltip, so a skill can't describe itself two ways in two places. It layers three sources, in order: (1) a slot-specific override — for a skill that genuinely differs per slot (Blood Nova is a free on-hit proc on a weapon but a health-sacrificing retaliation on armor/offhand; Divine Judgment is a pillar nuke when cast but a below-25%-HP auto-rescue as a ring). (2) SkillDef.description from skills.json — the source of truth for every skill that has a def (all 54: every class skill + every castable legendary). (3) a small C++ fallback table — the ONLY source for the ~10 legendary PASSIVES that have no SkillDef at all (Thorns, Berserker, Second Wind, Life Steal, Soul Harvest, Gravity Pull, Phase Strike, Void Kill, Arc Fire, Throwaway). So: a new skill WITH a def gets its text in skills.json; a def-less passive gets it in the C++ table; a skill that reads differently per slot ALSO needs a tier-1 override — otherwise tier 2 silently overwrites the correct per-slot text with the generic one. Never add a tier-3 case for a skill that has a def: tier 2 always wins, so the line is unreachable, and unreachable text that looks authoritative is exactly how a tooltip rots. Nothing fails to compile and no test catches any of this — it is how divine_judgment (Phoenix Band) and shadow_ricochet (Shadow Scepter, Phantom Knives) shipped with dead [<slot>] Unknown tooltips. Equally: if you give a slot a new dispatch, make sure the slot actually reads the skill — the perfect-block handler ignored legendarySkillId entirely, so every legendary shield ran the same freeze-bash regardless of what its tooltip promised.
Many SkillIds are UNREACHABLE legacy content — check before you "fix" one. A class's kit is exactly ClassDef.skills[4] (engine_init.cpp kClassDefs); a skill not in some class's four AND not any item's legendarySkill cannot be cast by anyone. item.h flags these // legacy — kept for save compat: POISON_ARROW, STUN_GRENADE, RAPID_FIRE, MULTI_SHOT, SHADOW_SHOT, COMBAT_DRONE, CONSECRATION, DIVINE_SHIELD, … They still have skills.json defs and tryActivate cases, so they LOOK live — and their bugs look real (Poison Arrow applied no poison; Stun Grenade didn't stun; Rapid Fire just aliases Overcharged Magazine). Verify reachability first, or you will spend the day fixing something no player can reach. The enum values must never be deleted — SkillId is serialized by ordinal, so removing one shifts every later skill and corrupts saves.
A skill's floor "upgrade" mutates the shared SkillDef. beginThunderclapUpgrade/endThunderclapUpgrade (engine_update_skills.cpp) scale the def's duration around the cast and restore it after, because fireThunderclap reads its stun straight off the def. If you add an upgrade like this: (a) scale, never assign — the old code assigned a hardcoded 0.5f written when the base was 0.2s, so once the JSON said 0.8s the "upgrade" silently shortened the stun; (b) gate on effectiveFloor (floor + difficulty*50), which is what the HUD's gold "upgraded" border uses — gating on the raw floor makes the bar disagree with the code on Nightmare/Hell; (c) call it from the server's remote-cast path too (processRemoteActivation), not just the local one, or a GUEST never gets the upgrade in co-op.
A GameAction ordinal is an on-disk format — never insert or remove one. Input::saveBindings writes controls.json as one row per action keyed by its enum ordinal, so inserting or deleting a member silently re-maps every existing player's bindings onto the wrong actions. Rename in place; append before COUNT. (DODGE, CHARACTER_SCREEN, QUICKBAR_SLOT_3/4 sit out of thematic order at the tail purely for this.) Two more traps: the rebind UI lists Input::REBIND_ROWS actions = the contiguous 0..INVENTORY range PLUS an explicit tail (kRebindTail, currently just DODGE) — a late-appended action sits above INVENTORY (ordinals can't reorder) but a combat-critical one like DODGE still needs to be rebindable, so add it to the tail rather than leaving it stranded (all three rebind sites — the render + the two capture handlers + the two reset helpers — key off REBIND_ROWS/rebindActionAt, and actionName needs a case). A truly fixed chord (e.g. CHARACTER_SCREEN, whose K alias lives in the non-serialized InputBinding.key2) stays OUT of the tail. Rebind conflict policy is "clear the other": setKeyBinding/setButtonBinding unbind the key/button (button = same button AND same modifier) from any other rebindable row before assigning, so no listed action answers to a key another one fires on. And changing an existing action's DEFAULT binding needs a migration: loadBindings overwrites defaults row-by-row, so a previously-saved file's stale row beats the new default and the change never reaches anyone who ever opened the options menu. Bump BINDINGS_REV (persisted as the CFG_BINDINGS_REV sentinel row) and repair just the affected actions — and only their controller or keyboard half — at the tail of loadBindings.
Per-lane state MUTATED during the RENDER pass must index the per-lane array directly, NOT go through the swap macro. LOCAL_PLAYER_SWAP_FIELDS works only because gameUpdate calls swapInPlayer(sp) then swapOutPlayer(sp) around each lane — the write-back persists the alias. But the per-viewport RENDER loop (engine_render.cpp) calls swapInPlayer(sp) and never swaps out, so a render-time write to a swap-macro alias is silently discarded (overwritten by the next viewport's swap-in) and the array field never advances. The D2 enemy target bar (m_targetEnts[]/m_targetLingers[], renderTargetBar) tracks its target + fade during render, so it binds m_targetEnts[m_localPlayerIndex] by reference rather than using the swap macro — a single shared member had P2's bar showing P1's target and drained the linger twice per frame (once per viewport). Rule of thumb: swap macro = update-path per-lane state; direct array index by m_localPlayerIndex = render-path per-lane state.
Arena opponents are HIDDEN on the minimap (PvP map-awareness policy). The other-player minimap dots (otherActive[] in engine_hud.cpp) are drawn for co-op ALLIES but suppressed when m_level.inArena — a live radar of every enemy removes the positioning read that PvP is about, and it also makes online arena consistent with Local Versus (which never added them). Co-op dungeon runs keep the ally dots. Any new "show other players on the map" feature must gate the same way.
On PC couch co-op a split-screen LANE is not the same as a physical controller INDEX. The reads translate a lane through s_padForPlayer[] (input.cpp) via padForLane(): default identity (lane N = pad N, so two-controller couch and Switch's JoyCon-per-lane are unchanged), but with exactly ONE controller Input::assignCouchPads() sets {-1, 0} — Player 1 is the keyboard (lane 0 → no pad) and the controller is Player 2 (lane 1 → pad 0). Without this, lane 1 read a nonexistent pad 1 while pad 0 doubled onto P1 ("one controller, both players on P1"). EVERY per-lane controller read must route through padForLane — getAxis, isButtonDown/Pressed, isGamepadConnected, the gyro cache, and rumble all do; the button-edge snapshot (s_currentPadButtons[c]) is indexed by PHYSICAL controller, so remapping current AND previous stays consistent. Call assignCouchPads() right after setSplitScreen(true) at every couch start (startCouchGame, beginCouchJoin, the client SV_JOIN_ACCEPT finalize); setSplitScreen(false) resets the map to identity. The couch LOBBY (subState 4) still runs with split OFF, so its isButtonPressed(1, …) merges all pads — any controller's A joins P2, which is why the join always worked even though in-game P2 was dead. Count-based assignment (1 pad ⇒ keyboard P1) covers the common case; a per-device "claim your slot at character select" system would be the richer version.
An input read inside gameUpdate must be player-gated. gameUpdate runs once per split-screen lane, but the mouse/wheel are single global devices — so an ungated read applies P1's input to BOTH lanes (this is how the quickbar wheel moved P2's selected slot). Gate on Input::getActivePlayer() == 0 for mouse/keyboard, exactly as player.cpp does for the look delta; controllers route per-slot automatically via setActivePlayer.
Per-frame input edges must be consumed in consumePressedState, never reset in Input::update. Window::pollEvents accumulates events BEFORE Input::update runs, and the fixed-timestep ticks that read them run AFTER — so zeroing an edge in update() destroys it between the write and the read. That is exactly what made getMouseWheelDelta() always return 0, so the quickbar's mouse wheel never worked at all. Clearing in consumePressedState (called after the first fixed tick) also means a frame that runs zero ticks — common above 60 FPS — carries the input to the next tick instead of dropping it.
The inventory screen is navigable by mouse AND cursor (WASD/E or D-pad) at the same time — never gate it on isGamepadConnected. The old code did, so a keyboard player got no discrete nav and a connected pad hijacked the mouse (the physical pointer was overwritten by the synthetic cursor for the click hit-test). Now one predicate, Engine::inventoryUsesCursor(), decides who drives the highlight + tooltip: a gamepad-only split lane (player > 0) is always cursor; the keyboard+mouse lane (player 0) follows the last input used — m_invCursorActive flips true on any WASD/E/D-pad nav and false when the mouse moves or clicks. Both updateInventoryInteraction and renderInventoryHUD read that ONE predicate, so the interaction and the render can't disagree about which pointer is live. The cursor still reuses the mouse hover path via inventoryCursorToMouse (a synthetic pointer at the selected slot → the same drawItemTooltip), so there is exactly one tooltip code path; WASD is GameAction::MOVE_* (bound to plain W/S/A/D, no stick binding) and equip is GameAction::PICKUP (E), both edge-read while gameplay input is frozen. Keyboard reaches the two item panels via a left/right edge-jump (equipment sits left of the backpack) since it has no shoulder buttons to cycle panels. The inventory mouse hit-test MUST be remapped into the player's viewport in split-screen. The inventory is DRAWN inside P1's viewport at vpW/vpH (half the window — renderHUD→renderInventoryHUD gets hudW=vpW), but updateInventoryInteraction read the full-window mouse and hit-tested against Window::getWidth()/getHeight(). Different coordinate spaces → every couch P1 click missed the drawn slots, so mouse equip / drag / double-click silently did nothing (most visible in Local Versus / the Arena, hence "double-click to equip doesn't work for P1 in the arena"). Fix: when m_splitPlayerCount > 1, shrink sw/sh to the viewport and shift the pointer into P1's viewport-local space, mirroring the render loop's sp==0 viewport (top half on a horizontal split, left half on a vertical one). P1 is always the first viewport; P2 is controller-only and never reaches this mouse path. Any input-side inventory hit-test (stash, character screen) has the same trap — use the drawn viewport's dims, never the raw window. Two smaller cursor-mode bugs live in the same area: m_invCursorActive is now PER-LANE (in LOCAL_PLAYER_SWAP_FIELDS beside m_invCursorPanel/m_dragState) — as a shared bool, P2's D-pad nav flipped P1 into cursor mode and skipped P1's mouse path (incl. the drag-release frame, which strands m_dragState); and the inventory-open seed reads Input::laneDeviceIsGamepad(m_localPlayerIndex) (this lane) not the global activeDeviceIsGamepad() (which flips to Gamepad on any P2 pad touch), plus a mouse release now also forces mouse mode.
Split-screen glyphs are PER-LANE — never read the global Input::activeDeviceIsGamepad() for a per-viewport prompt. s_activeDevice is a single global (last-device-wins), so in couch co-op P2 nudging a pad flips P1's on-screen button prompts to controller glyphs (and vice-versa). The device is tracked per lane (s_laneDevice[] in input.cpp, re-derived every frame): a lane with no assigned pad is keyboard/mouse; lane ≥1 is controller-only (keyboard is gated to lane 0 in checkActionRaw); lane 0 with a pad is last-device-wins. Two ways to consume it: (1) Input::laneDeviceIsGamepad(lane) where you hold a concrete lane index; (2) the render loop calls Input::setGlyphLane(sp) per viewport so the activeDevice() calls already baked into drawKeySymbol and the skill/quick bars resolve to that player with no signature changes — it clears to -1 after the loop, and -1/non-split falls back to the global, so menus and single-player are unchanged. Adding a new per-viewport glyph needs nothing; adding a glyph OUTSIDE the render loop (a shared overlay) correctly gets the global.
A melee swing must be LOS-gated or it hits through walls, floors, and ceilings. CombatQuery::queryConeSorted is a pure angle+distance cone and — for melee — a horizontal (XZ) one, so without a wall test it happily damages an enemy behind a wall, or directly above/below on a platform. It takes an opt-in const LevelGrid* losGrid (default null): the MELEE paths pass it (Combat::fireMelee and Combat::pvpCone now take const LevelGrid& grid; the client-side melee-predict cone passes &m_level.grid; fireCleave threads it through), the AoE novas/explosions leave it null because they are radial and deliberately wrap cover. The gate casts the full 3-D ray origin→entity-centre (Raycast::cast, slab-aware) and skips a hit blocked by geometry closer than the target. A new melee-cone caller that forgets losGrid silently reaches through walls again.
UI geometry must be single-sourced, or the clickable rects drift off the drawn thing. HUD::drawQuickbar and InventoryUI::hitTest each derived their own quickbar layout; the hit-test kept a stale slot count and skipped the uiScale + FLASK_CLUSTER_SHIFT the renderer applied, so the click rects did not overlap the drawn bar at ANY resolution and drag-assign / reorder / remove were silent no-ops for the life of the feature. Draw and hit-test now both call InventoryUI::quickbarLayout (as the skill bars call skillBarLayout). Don't hand a layout an offset parameter the hit-test can't see — that's the drift vector. Pin it with a "centre of drawn slot i hit-tests to i" test across several resolutions; that one assertion would have caught this on day one.
Every equip path must call sendInventorySync(). The server fires a client's weapon from its own copy of that client's inventory (handleWeaponFireForPlayer), so an equip that doesn't push leaves a guest dealing the OLD weapon's damage while their screen shows the new one. The quickbar's use-path was the one route that omitted it. (CL_EQUIP_ITEM is a dead enum value in net.h — never sent, never handled. CL_INVENTORY_SYNC is the live path; no protocol bump needed.)
A run-wide m_gameState change on the host is INVISIBLE to clients — broadcast it or they hang. m_gameState is per-machine; when the host flips out of IN_GAME, serverUpdate stops, snapshots stop, and every guest stares at a frozen world with a live connection (no disconnect, no timeout — a pure hang). This shipped twice: the Dungeon Engine kill and the Hell-complete ending both snapped the host's state to VICTORY locally. The pattern that fixes it: a reliable SV_EVENT that makes every machine run the SAME local transition (beginCreditsSequence → SV_EVENT::CREDITS → startCredits), with per-state guards so a stray packet in a menu is a no-op. Per-PLAYER states (GAME_OVER death screen) are exempt — the world keeps running for everyone else.
A player buff that isn't on NetPlayer does NOTHING in co-op — and worse, it rubber-bands. The server integrates remote movement in PlayerController::updateNetPlayerFromInput, so a speed buff living only in the client's local Player is predicted but never simulated: the server keeps moving that NetPlayer at base speed and the snapshot drags them back every tick. A working buff needs the WHOLE chain: a NetPlayer field; mirroring in both seedRemoteView and writeBackRemoteView (seedRemoteView starts from v = Player{}, so anything unmirrored is zeroed every frame); application in updateNetPlayerFromInput; expiry in serverNetPost for remote lanes only (the host expires its own locally — ticking both burns it down at double speed); and a SnapPlayer field if the client must adopt it (it must, for anything it predicts). Copy shadowDanceTimer or overdriveTimer, both done right (overdriveTimer — Mech Overdrive / War Cry — was the missing-field cautionary tale until 2026-07-16; its fix is the cleanest minimal example of the full chain: field in net_player.h, both mirrors in engine.cpp, apply in player.cpp updateNetPlayerFromInput, remote-lane tick in serverNetPost, zero on join). Player::shrineBuff is the worked example WITH wire adoption (game/shrine.h). When the adoption needs spare wire bits, check BOTH SnapPlayer flag bytes before claiming any: statusFlags bits 5–6 hold the shrine-buff type (only bit 7 is free there), while the pose byte flags uses only 0/1/3/4 (active/onGround/reloading/blocking) — Static Charge stacks took its bits 5–7. Claiming an occupied bit corrupts a live feature silently; nothing compiles wrong. The Wanderer kit (Deflect absorb/burst, Death's Dance, Adrenaline) is the worked example of porting a whole MECHANIC, not just a timer: the burst was extracted into one shared Engine::fireDeflectBurst (local tick + server remote-lane expiry call the SAME code); the absorb pool round-trips through NetPlayer every frame because it accumulates on the throwaway view; the dodge-through callback carries Player& victim + Player::netSlot identity (it used to hardcode m_localPlayer, so a guest's dodge-through swung the HOST's weapon and fed the HOST's stacks); and the view mirrors roll state READ-ONLY (np.rollTimer is owned by the input replay). Floor-derived gates (adrenalineUpgraded) are recomputed server-side per frame — player.cpp can't see the floor. Direct-constructed projectiles must set ownerSlot or kills credit slot 0.
Anything that changes maxHealth must also heal by the same amount. SnapPlayer sends health as a ratio of maxHealth, so a bare max-HP bump leaves absolute HP unchanged while the denominator grows — every HP bar (theirs, and in co-op everyone else's view of them) visibly lurches downward at the exact moment the player gains a health buff. Grant the max and heal the delta; the ratio holds and the bar grows.
A field that drives a render tint MUST be on the wire, or the tell is invisible to every guest. Entity.hasAuraBuff is the standing counter-example: it shifts the enemy tint in engine_render_entities.cpp and is not replicated, so aura-buffed enemies look completely normal to a co-op client. The champion tell deliberately does the opposite — champAffixes is replicated and Champion::tintFor is a pure function of it, so host and guest derive the same colour from the same byte and cannot disagree. Copy the boss shield/minionShield tint, which is explicitly wire-driven.
SnapEntity is padding-free and sizeof == SNAP_ENTITY_WIRE is asserted; SnapPlayer is NOT. The assert on SnapEntity is the canary that catches a field added to the struct but forgotten in one of its four (de)serializers (two writers, two readers — writeSnapEntity/readSnapEntity plus duplicated inline loops in serialize/deserialize), which would silently corrupt the stream. It aligns to 2, so an odd byte count needs an explicit reserved0 to keep the invariant true. Do not add the same assert to SnapPlayer: its tail is a block of u32s, which forces interior padding, so it has always been larger in memory than on the wire. The memcmp delta still works because WorldSnapshot's ctor zero-initialises every slot.
EntitySystem::spawn does NOT zero a recycled pool slot. Every new Entity field must be explicitly reset there (see the existing block clearing boss/status/champion fields) or a reused slot inherits the dead entity's state — a phantom champion still tinted, scaled, and running Molten on a plain enemy.
Entity handles vs raw indices. Always use EntityHandle + handleValid/handleGet for cross-frame references. Indices alone go stale when slots get reused.
Item visual resolution timing. ItemDef.meshId/materialId are zero until ItemLoader::resolveVisuals runs after MaterialSystem::init and the mesh registry is filled. Don't render items earlier in init.
Necromancer raises are capped PER CORPSE, not per raiser. Entity::resurrectCount counts raises performed (a stat on the necromancer, uncapped, and reused as a scratch counter elsewhere — goblin bleed pockets, boss wave index); the cap lives on Entity::timesRevived, which counts raises suffered, and RESURRECT_MAX (10, entity.h) is the limit. Without a per-corpse limit a necromancer standing over one body raises it every 3 s forever: unkillable while the raiser lives, and dripping XP/loot each cycle. Both raise sites — the SUMMONER role and the HEALER role's no-one-to-heal fallback — share one predicate, corpseRaisable() in entity.h, which also holds the not-dead / friendly / deathTimer<=0 / boss guards; add new conditions THERE, not in the two pool scans. timesRevived is reset in EntitySystem::spawn (a recycled slot inheriting a spent tally would spawn an enemy that can never be raised) and is host-side only, so it never touches SnapEntity or PROTOCOL_VERSION.
A regular enemy's role may be a STRING or an ARRAY. enemy_loader.cpp accepts both, so an enemy can carry several roles at once the way bosses do ("role": ["shield_bearer", "charger"] — the Cave Troll, which tanks AND sprints). A single string still works and is the common case. Don't add a second field for this; the array form is already the mechanism.
Ranged enemies flip a coin between LEADING their shot and firing at your current position. All three enemy fire sites (CHASE, retreat re-engage, strafe-fire in enemy_ai_states.cpp) go through LeadAssist::enemyAimPoint(targetPos, targetVel, timeToHit, lead) with lead = (std::rand() & 1). A perfect intercept solve on every shot reads as a hitscan sniper — a constant-velocity player is hit every time and the only counter is changing direction on the enemy's exact fire cadence. Half-and-half means strafing beats some shots and standing still beats others. The maths is split from the coin flip so it stays pure/testable, and all three sites share ONE rule rather than three copies of a lead formula that can drift.
EnemyRole is a bitmask, not an enum. Use e.enemyRole & EnemyRole::SUMMONER, not ==. Bosses can combine multiple roles.
Autoplay on a stacked floor: identify the STOREY by the slab underfoot, never by raw feet-Y. Autoplay::botStoryY (autoplay_nav.h) asks effectiveFloorHeight with PLATFORM_STEP_TOLERANCE subtracted back off, which cancels that function's step-up window and returns the highest slab at or BELOW the feet. Matching on pos.y directly looks correct and is not: the bot jumps constantly, a jump clears 2.4 m against a 3 m storey pitch, and a 0.4 m match window then rejects every drop hole on the bot's own storey for the whole flight — measured at 21-27% of all ticks, 100% of them airborne, with the router silently falling back to a heading three floors below. effectiveFloorHeight unmodified has the mirror bug: near the apex it reports the storey being jumped TOWARD.
A goal several corridors away needs a FIELD, not a bearing, and A* will not save you. Pathfinder::findPath stops at MAX_ASTAR_SEARCH (256) closed cells — on 3-wide maze corridors that is barely a dozen cells of real travel, so a cross-floor goal returns 0 and every caller's "fall back to the straight line" branch aims the bot at a wall. The Descent's answer is Autoplay::DescentField (game/autoplay_descent.{h,cpp}), a BFS flow field seeded from the storey's drop holes; copy its two inherited details if you build another — expand 4-connected (diagonals clip corners a body cannot) and steer at the next cell's CENTRE (this is what pulls a body off the corridor wall instead of letting it track along it).
The Autoplay fall veto must be gated on BotIntent::engaging, and applied ONLY to VHALL upper-exit floors — never FOUR_STORY. Autoplay::wouldFall (autoplay_nav.h) vetoes a FIGHT movement step that drops off a ledge, so a kiting bot can't back off a balcony rim it just climbed to. But (a) it must be gated on in.engaging (set by decideCombat), because the FOUR_STORY descent is a fall the bot WANTS and comes from the TRAVEL branch; and (b) it is scoped to VERTICAL_HALL && floorDoorPos.y > 1.5f (an upper exit) — FOUR_STORY descends by falling and must stay untouched, and a ground-exit VHALL wants the bot to drop off its balcony to descend, so a fall veto there would strand it. A new movement producer that should respect the fall veto sets engaging; one that is an intended drop must NOT.
The Autoplay sidearm owns the WEAPON slot; autoEquipBackpack must stay suppressed while it does. A melee build that meets an enemy it can only reach by falling (VHALL upper-exit) equips the best ranged weapon in its bag (BuildScore::bestRangedBackpackIdx) and switches back when the trigger clears. autoEquipBackpack runs on every pickup + a housekeeping pass and re-gears to the active build cell, which would instantly undo the swap — the guard (if (m_autoplaySidearmActive && lane == 0) return; at the top of autoEquipBackpack) is load-bearing. The stashed melee weapon is found again by ItemInstance::uid (its backpack slot can move as loot comes and goes), not by a remembered index. While worn, buildBotView overrides the doctrine cell to the Ranged column (Autoplay::rangedCellFor) so the brain holds ground; the persisted buildCell is untouched. The switch is opportunistic — no ranged weapon in the bag means it never triggers (the fall veto alone keeps the bot safe).