wownerogue/docs/RENDER_PACKS.md

Render kit: modes, packs & FX

The client render kit (html/js/render/, namespace RK) draws the same Scene in multiple techniques and art styles, so the tavern and dungeon are rich, interchangeable environments and new art can be added as products.

Modes vs. packs

• Render modes = techniques (how a scene is drawn): Tiled, ASCII, Iso, 3D (renderModes.js). Each declares a projection (topdown / iso / 3d).
• Packs = sets/styles within a projection (chosen via the pack picker): e.g. topdown Roguelike Interior ↔ Roguelike Dungeon, iso Dungeon ↔ Medieval. Registered in packRegistry.js / assetPacks.js. "Fancy" is not a mode — it's a pack (tiles + FX).
• A premium mode unlocks once the user has any unlocked pack for its projection.
• The scene model is kind-based (floor/wall/table/torch/monster/…), so one pack renders both the tavern (sceneFromTavern) and the dungeon (sceneFromGameState) — that's what makes packs interchangeable across both.

Entitlement: packs are gated by the operator-owned cosmetic catalog (cosmetic_catalog table, src/multiplayer/entitlements.js) — free / grant / lifetime-spend / subscription-tier. See MONETIZATION.md.

For browser QA, ?unlock=1 sets a sticky local bypass for render-mode and pack display gates; ?unlock=0 clears it. This affects only that browser's localStorage, grants no server entitlement, and is not an operator access-control mechanism.

Gameplay focus contract

Single-player keyboard movement is deliberately accepted only while #game-display owns browser focus, so typing in chat or another form cannot move the player. Choosing Tiled, ASCII, Iso, 3D, a pack, or a camera control immediately returns focus to that gameplay area without scrolling.

Local 3D runtime

Three.js 0.160.0 is an exact production dependency. The server advertises the local version in /runtime-config.js and exposes only the browser build and required addons beneath:

/vendor/three/0.160.0/three.module.min.js
/vendor/three/0.160.0/addons/loaders/GLTFLoader.js
/vendor/three/0.160.0/addons/utils/SkeletonUtils.js

The modules are imported lazily when 3D is selected. Local delivery is always enabled in the application runtime and takes precedence over external sources. RENDERER_CDN_ENABLED=true makes the jsDelivr renderer source path eligible only in a runtime where local delivery is disabled. All checked-in environment profiles keep external renderer execution off, including production, so Three.js remains same-origin under CSP.

Three.js library delivery is separate from generated model delivery. Runtime GLBs under html/assets/generated/3d/ are gitignored and must be provisioned independently; the renderer keeps a low-poly fallback when a model cannot load and removes it once the animated GLB is attached.

The FX layer (fxLayer.js, RK.fx)

Pure-canvas animated FX (CSP-safe, no WebGL), shared by the tiled and iso renderers so a scene lights up the same way in either projection:

• RK.fx.fire — dancing two-layer flame + warm glow (torches, hearths).
• RK.fx.hazard — pulsing overlay for hazard tiles (lava / poison / spikes) with a footprint-clip callback so it fits square cells and iso diamonds alike.
• RK.fx.flicker / pulse / glow — the primitives.

A tile carries fx: 'fire' or hazard: '<kind>' in the scene legend (sceneModel.js); the renderer draws only the tile's floor base in the static pass and lets RK.fx paint the animated layer in the live loop. The tavern has wall braziers + a hearth; the dungeon hazard kinds are wired and render the moment the generator emits their chars (L/P/^) — pending the generator + gameplay stakes.

Other pieces

File	Role
isoRenderer.js	Canvas isometric projection. Orientation-aware walls (_S for x-runs, _W for y-runs, corner tile), floor variety, contact shadows + vignette juice. Kenney iso dungeon set (assets/kenney/iso-dungeon/).
tileRenderer.js	Top-down atlas renderer. over compositing (object tiles drawn on a base tile), torch-lit vignette, ember/flicker loop, animated fire/hazard emitters.
zoomControl.js	RK.attachZoom(host) — wheel/pinch zoom (0.4–4.0), dblclick reset, pixelated scaling.
catSprites.js	Animated tavern cat (Pet Cats Pack idle strips).
packRegistry.js	Multi-pack-per-projection registry: active-pack selection persisted per projection, entitlement-gated, graceful fallback. Node-testable.
threeRenderer.js	Same-origin Three.js scene, fog-aware entity retention, animated GLB cloning, fitted model scale, camera follow, and complete renderer/resource cleanup.
spGameRenderer.js	Single-player render bridge, player-centred camera, local 3D lazy-load, and explicit gameplay-focus restoration.

Tests: test/renderPackResolver.test.js, test/packRegistry_ultra.test.js, test/rendererCdnPolicy.test.js, and test/pvpUiPolish.test.js.