wownerogue/docs/RENDER_PACKS.md

Render kit: modes, packs and FX

The client render kit (html/js/render/, namespace RK) draws the same Scene in several techniques and art styles, so the tavern and the dungeon are interchangeable environments and new art can be shipped as a product without touching gameplay code.

Modes vs. packs

• Render modes are techniques (how a scene is drawn): Tiled, ASCII, Iso, 3D (renderModes.js). Each declares a projection of topdown, iso, or 3d.
• Packs are the sets and styles within a projection, chosen from the pack picker and registered in packRegistry.js / assetPacks.js.
• A premium mode is usable once the account has any unlocked pack for that mode's projection (RK.canUseMode).
• The scene model is kind-based (floor, wall, table, torch, monster, and so on), so one pack renders both the tavern (sceneFromTavern) and the dungeon (sceneFromGameState). That is what makes packs interchangeable across town and dungeon.

Registered packs (assetPacks.js):

Pack id	Projection	Label
original	topdown	Original Tiles
roguelike-interior	topdown	Roguelike Interior
roguelike-dungeon	topdown	Roguelike Dungeon
iso-dungeon	iso	Isometric Dungeon
iso-medieval	iso	Medieval Town
kenney-3d-characters	3d	Animated 3D

The active pack is stored per projection (rk_pack_<projection> in localStorage, an in-memory map under Node). A stored pack that is unregistered or locked is ignored in favour of the first unlocked pack for that projection.

Entitlement is per pack, not per purchase: each pack maps to a row in the operator-owned cosmetic_catalog table and resolves through src/multiplayer/entitlements.js as free, grant-only, lifetime-credits threshold, or subscription tier. entitlements.js also carries a built-in default catalog used when the table is unavailable. See MONETIZATION.md.

For browser QA, ?unlock=1 sets a sticky local bypass for render-mode and pack display gates and ?unlock=0 clears it. It 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 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 the gameplay area without scrolling (RK.SPGame.focusGameplay).

Local 3D runtime

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

/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 the first time 3D is selected (RK.ensureThree), so ASCII and Tiled users never download them. 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, and widens the CSP to trust third-party script. All checked-in environment profiles keep it off, so Three.js stays same-origin.

Library delivery is separate from model delivery. Runtime GLBs under html/assets/generated/3d/ are gitignored and must be provisioned independently; the renderer keeps a low-poly placeholder while 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 and with no WebGL, shared by the tiled and iso renderers so a scene lights up the same way in either projection:

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

A tile carries fx: 'fire' or hazard: '<kind>' in the scene legend (sceneModel.js). The renderer draws only the tile's base in the static pass and lets RK.fx paint the animated layer in the live loop. The tavern places wall braziers and a hearth. Dungeon hazards are keyed off the map characters L, P, and ^ in dungeonTileKind, so a generator that emits them renders hazards with no renderer change.

Torches are wall-mounted: the generator places them only on wall cells adjacent to floor, so DUNGEON_LEGEND.torch uses over: 'wall' and the fire branch draws the wall base plus the procedural flame.

Lighting model (iso and 3D)

Both premium projections light the dungeon rather than tinting it, and both derive lighting from the same scene.lightGrid the 2D modes use, so switching projection changes the technique and never what a player is allowed to see.

Iso composites in one pass per frame:

• tiles are shaded opaque (_shadedImage, quantized to six cached levels) rather than alpha-faded. Multiplying a sprite's own pixels toward a cold near-black keeps distant stone solid and unlit; alpha-fading would make remembered walls translucent and let the tiles behind them show through.
• light pools (_lightPool) are additive, squashed to the ground plane, and emitted by torches (flickering), the player's lantern, and objective beacons on the stairs and treasure.
• crevice AO (_wallAO) darkens floor cells by how many walls they touch.
• embers rise off each flame, seeded per cell so they do not reshuffle every frame.
• a cold blue wash (_memoryWash) separates remembered rooms from torchlit ones by colour temperature. The wash colour must stay darker than the tiles it covers: a mid-tone blue lifts memory brighter than the lit centre and inverts the depth hierarchy.

3D (threeRenderer.js) draws the level as three InstancedMeshes (walls, ground, props), so a 70x35 dungeon costs three draw calls and a fog-of-war update is a few thousand matrix writes instead of thousands of mesh allocations. Wall and floor materials are generated on a canvas at startup (coursed stone, irregular flagstones, both doubling as bump maps), so there is nothing extra to download and nothing for the CSP to block. On top of that: a low warm key light with a player-tracking shadow frustum, a pool of six point lights reassigned each frame to the nearest braziers, a hand-held lantern, drifting dust motes, and a wall cutaway that squashes the walls between the isometric camera and the player.

Two constraints that are easy to get wrong:

• Fog is measured from the camera, which sits about 17 world units back along the isometric offset, not from the player. A fog band tuned as if it started at the player puts the player a quarter of the way into fog and crushes the scene to near-black.
• lightGrid must not be applied to albedo at full strength in 3D. The point lights already provide falloff, so multiplying by the grid as well double-darkens every surface. 3D compresses it to 0.38 + 0.62 * lb and lets the lamps shape the scene.

Features (entrance, exit, treasure, items) are set dressing, not avatars, in both projections: stairs with a beacon shaft, a gold chest, a spinning pickup. Rendering them through the entity path would draw each one as a humanoid, which makes the entrance look like a second player standing at the map origin.

Module reference

File	Role
sceneModel.js	Renderer-agnostic Scene plus the tavern and game-state adapters, the dungeon legend, and tile-character mapping. Handles both array grids and the client's sparse {y:{x:v}} maps.
renderModes.js	Mode registry, entitlement checks, renderer factory, and lazy Three.js loading.
tileRenderer.js	Top-down atlas renderer. over compositing (object tiles drawn on a base tile), torch-lit vignette, ember and flicker loop, animated fire and hazard emitters.
asciiRenderer.js	Glyph renderer for the free ASCII mode.
isoRenderer.js	Canvas isometric projection. Orientation-aware walls (_S for x-runs, _W for y-runs, corner tile), floor variety, contact shadows, vignette. Kenney iso dungeon set (html/assets/kenney/iso-dungeon/).
threeRenderer.js	Same-origin Three.js scene. Instanced level geometry, procedural stone and flagstone materials, torch light pool and shadows, dedicated feature and monster meshes, dust motes, wall cutaway, fog-aware entity retention, animated GLB cloning, camera follow, and full renderer and resource cleanup.
packRegistry.js	Multi-pack-per-projection registry: active-pack selection persisted per projection, entitlement-gated, graceful fallback. Node-testable.
assetPacks.js	Pack definitions and asset payloads; registers the shipped packs.
zoomControl.js	RK.attachZoom(host) and RK.attachCamera(host): wheel and pinch zoom (0.4 to 4.0), double-click reset, pixelated scaling.
fxLayer.js	Shared canvas FX primitives, fire, and hazard overlays.
catSprites.js	Animated tavern cat (Pet Cats Pack idle strips, 10 frames of 50x50).
chainAmbience.js	RK.mountChainAmbience(host): drifting top-block-hash fragments, a block-height readout, and a ripple when a block lands. Consumes the public blockheight broadcast, is decoration only, and pauses and prunes itself while the tab is hidden.
spGameRenderer.js	Single-player render bridge (RK.SPGame): player-centred camera, local 3D lazy-load, gameplay-focus restoration, and fallback to the legacy render engine when the kit is unavailable.

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