@jgengine/assets 0.27.0 → 0.28.0

package/CHANGELOG.md

@@ -26,6 +26,136 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.28.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.28.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.25.0`; `@jgengine/github` is `0.15.0`.
+- `groupStaticObjects` (`@jgengine/shell/world/staticObjectBatches`) takes an explicit `cell` argument (default `STATIC_BATCH_CELL`), and `STATIC_BATCH_CHUNK` is now `STATIC_BATCH_CELL`. `STATIC_BATCH_MIN` is 2. A caller that passed a chunk size to pick the grouping keeps working by passing it as the third argument.
+- `createNearAgents` (`@jgengine/core/gameplay`) `snapshot()`/`restore()` now carry the crowd as well as the agents: `{ agents, crowd }` where `crowd` is a `NavCrowdSnapshot`. A restored near agent resumes the route it was walking instead of re-planning a fresh one, which is what makes an off-screen world round-trip tick-exactly.
+- `OffScreenSnapshot.residents[].staleAt` is `number | null`; `null` is the "never goes stale" sentinel that was `Infinity`. `Infinity` does not survive JSON, so a saved off-screen world decayed a far, routine-less resident on every load.
+- `TrafficSnapshot.counters` and `PoliceResponseState.counters` no longer carry `slowestTickMs`. A wall-clock timing sample is not state; it stays on `stats()` only, so a save document is byte-deterministic.
+- `MaterialMaps.displacement` (`@jgengine/assets`) and `TerrainMaterialMaps.displacement` (`@jgengine/core/world/features`) are optional now. A caller that used to invent a displacement URL can drop it; nothing reads it.
+
+### Added
+
+- `setModelSubMeshMerge` (`@jgengine/shell/render/modelMeshMerge`) turns load-time sub-mesh merging off for a game that must keep one node per source mesh.
+- `render/staticBatches` devtools system probe reports the grouped batches, the instances behind them, the draws submitted and the distinct instances drawn after culling, so batching and per-instance culling are visible in `debug_snapshot().systems`. `countStaticBatchDraws` (`@jgengine/shell/world/staticObjectBatches`) reads those counts from a live scene.
+- `freezeStaticTransforms` / `thawStaticTransforms` (`@jgengine/shell/render/staticTransforms`) keep authored scenery out of the per-frame matrix update.
+- `ModelLodConfig` (`@jgengine/core/game/playableGame`) sets a character model's full-rate, half-rate and crowd distances plus the crowd hysteresis.
+- `characterLodTier` / `characterLodPolicy` (`@jgengine/shell/render/characterLod`) resolve a distance to a tier, and the `render/characters` devtools system probe reports rigs by tier, skinned parts, bone pose writes per frame and crowd instances in `debug_snapshot().systems`.
+- Load-time shader warmup for 3D presentations. `createShaderWarmup` (`@jgengine/shell/render/shaderWarmup`) compiles the mounted scene through `WebGLRenderer.compileAsync` in rounds, one per burst of streamed models, and reports a phase, round and program count a loading screen can render. It is bounded: a round is raced against its budget, so a driver that never reports a finished program cannot hold the first frame.
+- `SceneWarmupCover` (`@jgengine/shell/render/SceneWarmupGate`) is the opaque cover the shell puts over the canvas until that warmup finishes. It carries `data-shell-code-loading`, so capture and drive already wait for it, and it clears itself on a failed compile. Game UI and menus mount above it and stay usable.
+- `createPoliceResponse` (`@jgengine/core/world`) is the wanted level over the shared `ai/heatSystem` curve: a crime raises heat only while `sensor/perception` memory holds the suspect in view (the sighting's own `sourceId`/`sourceTick` kept as its owner), decay starts once every witness has been out of sight for `escapeSeconds`, and a caller-supplied tier table decides what police do — patrol, investigate, pursue, roadblock — with pursuer budgets, a last-sighting search area that grows while the trail is cold, and roadblock sites off the authored road data. `state()`/`restore()` round-trip mid-chase and the injected generator is the only source of variety.
+- `policeRoadsFromLaneGraph` (`@jgengine/core/world`) reads cordon sites and an indexed nearby-lane query out of an authored lane graph: `traffic_roadblock` markers projected onto the lane they block, or the graph's intersections when none are authored.
+- `DEFAULT_POLICE_TIERS` and `DEFAULT_POLICE_TUNING` are the starting tier table and curve a game overrides.
+- `createRideSystem` (`@jgengine/core/gameplay`) runs a park's rides: each one cycles load → ride → unload at its own capacity, boards from its own line, wears against its own breakdown curve (chance per completed cycle, repair seconds and money) and reports boards, alights, breakdowns and repairs through a sink, so the game keeps the bodies, the visuals and the wallet. `snapshot()`/`restore()` round-trip a park mid-cycle, `retune(id, patch)` changes a ride's ratings, capacity, timings or breakdown curve in play, and `service(id)` pays the maintenance cost and clears wear.
+- `createWaitQueue` (`@jgengine/core/gameplay`) is a real line: guests join the back, leave from anywhere, and the wait a new arrival faces comes from the queue's own measured boarding throughput rather than a configured constant. `DEFAULT_QUEUE_SEED_SERVICE_SECONDS` only bootstraps the estimate until two boardings have been observed.
+- `createRideChooser`, `rideChoiceOptions`, `rideChoiceCandidates`, `rideQueueCostWeight` and `rideAppeal` (`@jgengine/core/gameplay`) turn a guest's `RideTaste` (intensity comfort, nausea comfort, queue tolerance) plus the park's ride data into `createUtilityBrain` options, each ride costed by the seconds its own line reports — ride choice is one more scored option, not a fixed order.
+- `DEFAULT_RIDE_BREAKDOWN`, `DEFAULT_RIDE_RATING_RANGE` and `DEFAULT_RIDE_FUN_CURVE` are the starting curve and scales a park overrides.
+- `createMissionRuntime` (`@jgengine/core/gameplay`) runs missions as data: a mission is a graph of objectives the machine walks, with named fail states, per-objective timers, conditional branches, per-objective and completion rewards, a `rollout` fact rolled from the injected RNG, and a `next` mission that chains a follow-up. `tick(dt, world)` advances the active mission against caller-supplied actors, counters, facts and survivors; `signal`/`fail` let an authored trigger complete or fail it. `snapshot()`/`restore()` round-trip a run, `stats()` and an optional `devtoolsName` probe expose it, and cost per tick is the active objective's own fail list plus one goal test.
+- Objective kinds are the shared primitives `reach`, `interact`, `survive`, `pursue`, `kill` and `collect`; a fail condition can be `actor-died`, `timer` or `fact`.
+- `escortMission`, `chaseMission` and `defendMission` (`@jgengine/core/gameplay`) are compositions of those kinds, not archetypes: an escort is a `reach` with an `actor-died` guard, a defend is a `survive` with a survivor floor that banks what is left standing as the score, and a chase is a `pursue` with an escape guard.
+- `validateMissionCatalog` (`@jgengine/core/gameplay`) is the mission content gate: duplicate ids, unknown branch/next/timeout targets, unknown fail states and markers, per-kind required fields, unreachable objectives, and the counter-only rule — a mission with a completion path made entirely of `kill`/`collect` objectives is an error. `createMissionRuntime` runs it at construction, so a counter-only mission throws instead of shipping.
+- `registerMissionTriggerActions`, `MISSION_TRIGGER_ACTIONS`, `createMissionTriggerBridge` and `missionMarkers` (`@jgengine/core/gameplay`) start, advance and fail a mission from authored scene markers using the shared `on`/`action` trigger vocabulary; positional objectives read marker positions off the authored document.
+- `applyMissionRewards` (`@jgengine/core/gameplay`) pays a mission through the same appliers quests use (XP, currency, items, unlocks) and rolls named loot tables through the game's loot registry.
+- `createMarket` (`@jgengine/core/gameplay`) prices goods from supply and demand over finite stock on a stated curve: `price = clamp(basePrice × (coverPeriods × demand / max(stock, 1))^elasticity)` between `basePrice × minFactor` and `basePrice × maxFactor`. `sell` decrements the finite stock and refuses a sale it cannot cover with the shortfall named, `restock` lowers the price, `quote`/`priceAfter` read the move without mutating, `recordDemand(unitsSold, unitsUnmet)` folds a period of observed buying into demand, and `priceCurve` replaces the curve. `retune` changes a good's policy in play; `snapshot()`/`restore()` round-trip stock and demand; money is integer minor units.
+- `createTransactionLedger` (`@jgengine/core/gameplay`) keeps per-account, per-currency balances in integer minor units with a journal that records every movement, the balance it produced and the reason it happened. `post` is the one money path — sales, purchases, upkeep and loan payments all carry a caller-owned reason and an optional `ref` — and `totals()` keeps a per-reason count and net beyond the `maxEntries` journal cap. `addCharge` registers a recurring charge (upkeep, rent) settled on its cadence by `chargeDue`, bounded per charge and per advance; a cycle with no funds is counted as missed instead of overdrawing.
+- `buildLoanSchedule` and `createLoanBook` (`@jgengine/core/gameplay`) draw a loan, post the principal, and settle interest (`"loan-interest"`) and principal (`"loan-principal"`) as separate reason-tagged entries. A schedule is built up front in integer minor units — `"amortized"` levels the payment on the outstanding balance, `"flat"` charges interest on the original principal — and the final payment absorbs the rounding, so the principal parts sum to the principal exactly. A payment that comes due with no funds stays in arrears and counts once per advance; after `maxMissed` the loan is defaulted and stops being advanced. `repay` pays principal early, and state is terms plus progress, so the schedule is rebuilt on restore.
+- `createGameSave` (`@jgengine/core/gameplay`) is the one game save document: a `version`, the game/time/playtime metadata a save menu shows, the world's shared RNG seed and cursor, and one section per registered system. Register each stateful system once (`name` + `snapshot()`/`restore()`, optional `reset()`); `capture()` builds the document, `save()`/`touch()` persist it through the same injected `SaveBackend` `createSaveStore` uses, `load()`/`switchSlot()` restore every section and the RNG cursor, and `migrate` upgrades an older payload. Autosave cadence is caller policy, and `digest()`/`digests()` hash the whole state (or one section) for a save/reload determinism test.
+- `gameSaveDigest` (`@jgengine/core/gameplay`) hashes a `GameSaveDocument`'s state — every section, the clock and the RNG cursor — excluding the wall-clock `savedAt`.
+- `GameSaveConfig.devtoolsName` registers a devtools probe reporting the active slot, the save status, the change revision and the system count.
+- `createVisitorPopulation` (`@jgengine/core/sim/population`) counts a crowd by its members: a visitor exists only once the game's `VisitorWorld.admit` has made its body and `VisitorWorld.has` confirms it, so `onSite()` is the member count and `arrivalsToday()` is the sum of the admissions the world accepted. `arrivalRate`, `capacity`, `shouldLeave` and `inside` are caller policy; `adopt` takes over a body a save or a seed made; `rollDay()` closes the day without emptying the park.
+- `createDamageRuntime` (`@jgengine/core/combat/damageRuntime`) announces every damage application as `combat.damage` on the game's own event bus: `target`, `source`, `type`, `amount`, `absorbed`, `remaining`, `lethal`, plus `status` for a status tick. Pass `events: ctx.game.events` and `healthOf` (the target's live health, read before you apply it) so a HUD can name the blow and tell whether the target died; without `healthOf` the event reports `remaining: null` and `lethal: false`. `recentDamage(limit)` and the devtools probe line carry the same stream.
+- `StatusDamageTick.source` (`@jgengine/core/combat/statusRuntime`) names who applied the status that is ticking, so a burn names its arsonist.
+- `clearCameraBoom` (`@jgengine/shell/camera`) answers where a camera can sit without entering world collision: the desired position is rejected when the boom hits a surface, and the camera is placed one `clearance` before it. Pulling in is immediate, easing back out follows `releaseRate`, so a boom reads as a spring arm rather than a hard stop. `sceneCameraQuery(ctx.scene.raycast)` feeds it the existing world solids, object colliders and walls — no new collision layer — and any other hit query can be passed instead.
+- `FirstPersonCameraConfig.collision` (`{ clearance?, armBack? } | false`) keeps the `first` rig's eye out of the trunk or wall the body can reach. On by default; `false` restores the unchecked camera.
+- `createEffectSystem` (`@jgengine/core/combat/effects`) takes `onDamage?(application)`: one `EffectDamageApplication` per target a draining effect lands on, before `onLethal` despawns it. It carries `target`, `source` (the effect's `from`), `effect`, `incoming`, `dealt`, `remaining` (the last pool's current) and `lethal`; restorative applications stay silent.
+- `installCaptureCamera`/`readCaptureCamera`/`clearCaptureCamera` and `CaptureCameraOverride` (`@jgengine/core/world/captureCamera`) are the harness counterpart of `?look=`, and the same install-style seam as `world/spawnOverride`: the runner installs a rig, the shell reads it. `resolveCaptureCameraConfig` (`@jgengine/shell/camera/rigResolve`) reads it above a game's static `camera` block, its runtime `ctx.camera.setRig` selection and its director cinematics, so a game that drives its own camera can no longer photograph that camera instead of a requested `--look` framing. With nothing installed the resolution is exactly `resolveRuntimeCameraConfig`, so every game renders as before.
+- `EFFECT_LIBRARY` and `resolveEffect` (`@jgengine/core/vfx/effectLibrary`) name 24 GPU particle effects — fire, smoke, sparks, dust, splashes, muzzle flash, explosions, magic and weather — each authored as rate, lifetime, size, colour and a procedural sprite texture, so `ctx.particles.play("explosion/core", { position })` renders one by name and the editor authors the same name.
+- `ctx.particles.play(name)` and `ctx.particles.attachEffect(id, name)` (`@jgengine/core/vfx/particleDirector`) play a library effect by name; `effectNames()` lists them.
+- `planParticleBudget` (`@jgengine/core/vfx/particleBudget`) caps the live particle count to a graphics tier and drops whole effects lowest-priority-first when the request does not fit.
+- `GraphicsProfile.particleBudget` is the tier's scene-wide live particle cap (low 1024, medium 2048, high 4096, ultra 8192); `particleCap` stays the per-effect pool clamp.
+- `AuthoredEmitter.effect` (`@jgengine/core/editor/simulation`) authors a named library effect in `editor.scene.json` instead of a full config; `config` is now optional and exactly one of the two is required. `SimulationInspector` gains an effect picker.
+- `foliage/grass-macro` and `ground/dirt-macro` in the shared material library: the same ambientCG scans at a 24 m / 20 m tile, so they carry structure at the scale an RTS camera 50 m out resolves instead of texel noise.
+- `libraryTerrainMaterial(name)` (`@jgengine/assets/catalogs/materialLibrary`) returns the terrain detail material config for a library name, tiling from the entry's authored metres and blending from its terrain policy; a map the archive does not ship is omitted.
+- `libraryBuildingSurface(name, options)` and `librarySurfaceParameters(name)` bridge a library name to `BuildingSurfaceMaterial` and `MaterialSurfaceParameters`, so a facade names its material instead of hand-wiring maps, colour and repeat.
+- The library reports a `displacement` role (`libraryMaterialRoles`) without loading it, and `MaterialMaps.displacement` / `TerrainMaterialMaps.displacement` are optional; ambientCG archives without one (Fingerprints001) no longer publish a phantom displacement URL. `libraryTerrainMaterial` passes it through for callers that do displace.
+- `terrain-macro` dev demo captures one field from 52 m in `?mode=flat|dense|macro` to compare ground materials at RTS scale.
+- `SKELETON_STANDARD`, `mapRigToStandard`, `retargetTracks`, `retargetBoneScales` and the `RIG_SCHEMES` table (`@jgengine/core/anim/skeletonStandard`) are the engine's one humanoid skeleton standard: the CC0 KayKit character rig that `kaykit-adventurers` and `kaykit-skeletons` already share, named slot by slot (`root`, `hips`, `spine`, `chest`, `head`, `upperarm.l`…`toes.r`, `handslot.l/r`). A rig on another naming scheme maps onto those slots through a scheme table — Mixamo (`mixamorig*`) and the Quaternius sci-fi aliens ship as `MIXAMO_SCHEME` and `QUATERNIUS_ALIEN_SCHEME` — and every slot the rig cannot fill comes back in `missing` instead of borrowing a neighbour's bone. `retargetTracks` renames a clip's tracks onto a mapped rig, `retargetBoneScales` gives the per-slot length ratios that match bone proportions, and `runtimeBoneName` is the `.`-stripped spelling the loaded hierarchy and clips both use.
+- `locomotionGraph` (`@jgengine/core/anim/locomotionGraph`) now builds the whole directional locomotion set: `strafeLeft`/`strafeRight` add a `strafe` blend on the new `direction` parameter, `backward` adds a `backward` blend behind the new `facing` parameter, and every graph gets a `turn` blend on the new `turnRate` parameter (pivoting on `walk` when no turn clip is authored). Each state joins the idle/walk/run blend through a crossfaded transition, so a direction change blends instead of popping; supplying none of them leaves the speed-only tree unchanged. `LOCOMOTION_DIRECTION_PARAM`, `LOCOMOTION_FACING_PARAM`, `LOCOMOTION_TURN_RATE_PARAM`, `LOCOMOTION_STRAFE_STATE`, `LOCOMOTION_BACKWARD_STATE` and `LOCOMOTION_TURN_STATE` are exported, and a custom mover feeds the three parameters through the entity blackboard key `ANIM_PARAMS_KEY`.
+- `ModelAnimationStates` gains `strafeLeft`, `strafeRight`, `backward` and `turn`.
+- `classifyClip`/`rolesFromClips` know the `strafe` and `backward` clip roles, so `defaultAnimationForClips` derives the KayKit directional states automatically (`Running_Strafe_Left`, `Running_Strafe_Right`, `Walking_Backwards`) for any rig resolved with `animation: "auto"`.
+- `ragdollConfigFromPoses`, `ragdollBoneOrientations`, `RagdollPose`, `RagdollBodyShape` and `HUMANOID_RAGDOLL_BODIES` (`@jgengine/core/anim/ragdollRig`) turn a rig mapped onto the skeleton standard into a physics ragdoll at the moment of death: one box body per standard slot that has a shape, sized to the character, and one distance link per body to its nearest shaped ancestor, holding the bones' own separation. The bodies start where the character was, so the collapse continues the death pose. `handSlot.l/r` carry no body (prop sockets, not body parts); a slot the rig lacks is skipped and its children link to the nearest present ancestor. Because the engine's `PhysicsWorld` bodies carry translation only, `ragdollBoneOrientations` gives the skeleton its orientation by rotating each bone's death-pose direction-to-child onto the current one.
+- `useRagdoll` (`@jgengine/shell/render/useRagdoll`) arms a ragdoll on a rigged character when `active` goes true and drives every mapped bone's world position and aim from its body each frame. It steps the injected `PhysicsWorld`; deactivating removes the bodies and leaves the rig where the ragdoll put it. Stop the character's `ModelConfig.ik` while it is active, or the two write the same joints.
+- `multiplyQuaternions` and `quaternionFromUnitVectors` (`@jgengine/core/anim/ikSolver`) are the two pure rotation helpers the ragdoll's aim needs.
+- `locomotionGraph({ rootMotion: true })` (and `ModelAnimationStates.rootMotion`) marks the whole locomotion set — idle/walk/run, strafe, backward and turn — as root-motion states, so one authored locomotion graph carries its own travel as `AnimGraphOutput.rootDelta` for the movement owner to consume.
+- `actionLayer` and `withActionLayers` (`@jgengine/core/anim/actionLayer`) build a masked overlay layer from plain data: a resting clip plus a one-shot state per entry in `actions`, each joined by a consumed-trigger transition and returning on `exitTime`. Aim, reload, wave and hit reactions are one builder instead of a hand-written state machine per game. `additive: true` makes it a recoil/breathing overlay — the shell's `makeClipAdditive` makes the rest clip's first frame the zero reference, so the rest state is held at `speed: 0` and contributes no pose while the base keeps animating. `mask` is required and nonempty, because an overlay that names no bones would drive the whole rig; `withActionLayers` rejects a duplicate layer id instead of shadowing the base.
+- `standardBoneMask`, `UPPER_BODY_SLOTS`/`LOWER_BODY_SLOTS` and `UPPER_BODY_MASK`/`LOWER_BODY_MASK` (`@jgengine/core/anim/skeletonStandard`) derive a layer mask from the skeleton standard's own slots, so a rig mapped onto the standard is masked without hand-typing its bone names.
+- `ModelLookAtConfig` (`@jgengine/core/game/playableGame`, `ModelConfig.ik.lookAt`) can aim at more than the camera: `target` takes `"camera"` (default), `{ entity }` offset by `entityEyeHeight` (default 1.5), or `{ point }`. `maxYaw`/`maxPitch` bound the turn in radians and `weight` (default 1) scales how much of the solved turn reaches the bone. An entity target that is not spawned keeps its last known direction instead of snapping the head back to the camera. `applyFootIk`'s sixth argument is now `lookAtTarget` and applies the limits and weight; `FootIkRig` carries `lookAtLimits` and `lookAtWeight`.
+- The shell derives the directional locomotion parameters from the entity's own movement, so a rig with the `strafe`/`backward` states uses them with no game-side code: `direction` (the motion's share along the character's right axis), `facing` (its share along the facing axis) and `turnRate` (its yaw change per second) come from the entity's `position` and `rotationY` each visual sample and override conflicting authored extras. `readModelAnimationParams` gains an optional `ModelMotionStep` argument (`dx`, `dz`, `dyaw`, `seconds`); omitting it leaves direction to the authored extras, which is the previous behaviour. A step past the live `snapDistance` reports no direction and zero speed rather than inventing a lateral.
+- `createMenuTransition` (`@jgengine/core/ui/menuTransition`): closed → enter → open → exit → closed timing over an injected clock, with reduced-motion collapse to zero and `snapshot`/`restore`.
+- `@jgengine/core/ui/menuNav`: `menuNavMove` focus movement over a vertical list, horizontal row or grid with disabled-item skipping, `menuIntentForKey`, `menuIntentForPadButton`, `menuIntentForPadAxis` and `shouldRepeatMenuNav` for held d-pad/stick repeat.
+- `MenuScreen` (`@jgengine/react/menuScreen`): animated enter/exit screen with a translucent scrim, a `backdrop` slot for a live 3D scene, reduced-motion collapse and exit unmount. Animates transform/opacity only.
+- `TitleMenu` (`@jgengine/react/titleMenu`): title-screen block — wordmark, eyebrow, tagline, navigable verb list, footer, control hint and backdrop slot. Games own the wording, verbs and art.
+- `useMenuNav` (`@jgengine/react/menuNav`): keyboard and standard-gamepad focus navigation for any menu — roving `tabIndex`, arrow/WASD/Home/End moves, Enter/Space/A confirm, Escape/Backspace/B/Start back, held-stick repeat, disabled-item skipping, no focus trap (Tab stays native, typing is never intercepted) and keys that work when focus starts outside the menu.
+- `PauseMenu` now navigates with the same keyboard/gamepad rules; Resume is the first item and Escape resumes.
+- Engine demo `menu-framework` (`bun run shoot menu-framework --mode play`) renders a live 3D scene behind the title and pause screens.
+- `credits-panel` — `CreditsPanel` (`@jgengine/react/creditsPanel`): a scrollable, HudTheme-skinned credits screen over the scene with one back affordance reachable by keyboard, gamepad and pointer.
+- Loading screen with tips — `LoadingScreen` (`@jgengine/react/loadingScreen`): progress bar (real 0–1 value or indeterminate), rotating tips, a ready gate any key / A / click accepts, reduced-motion aware, and a scene backdrop.
+- `createTipRotation` (`@jgengine/core/ui/loadingTips`): deterministic, seeded tip order that cycles every tip once, with `snapshot`/`restore`.
+- Save slots wired to the save document — `refreshSaveSlots`, `saveSlotMeta`, `formatSavePlaytime` and `gameSaveSlotSource` (`@jgengine/core/game/saveSlotIndex`) read the slots a `createGameSave` actually wrote and fill a `createSaveSlots` index with the name, saved time and playtime chip a save-select menu shows.
+- `SaveStore.peek(slot)` and `GameSave.peek(slot)`: read a slot's stored document without touching the live session, applying sections or changing status.
+- `SaveSlotWrite.savedAt`: a save payload that knows when it was written can stamp that time instead of the index's clock.
+- `@jgengine/core/settings/accessibilitySettings`: the persisted accessibility ids (`accessibility.textScale`, `accessibility.colorblind`, `accessibility.reducedMotion`, `accessibility.highContrast`, `accessibility.captions`, `controls.holdVsToggle`), `accessibilitySettingRows(store)` for a settings surface, `readAccessibilitySettings(store)`, and `holdToggleActive(previous, { pressed, held }, mode)` for hold-or-toggle actions.
+- The shell's settings menu has an `accessibility` category (text size, colourblind palette, reduce motion, high contrast, captions, hold-or-toggle) unless a game hides it. Text size scales every `--jg-type-*` token through `--jg-text-scale`; reduce motion zeroes the engine's motion scale; high contrast, colourblind and captions are exposed as `data-*` hooks on the HUD root.
+- `SettingsSection`, `SettingsRowControl`, `SettingsSlider`, `SettingsToggle`, `SettingsSelect`, `SettingsKeybindControl` and `SettingsTabs` (`@jgengine/react/settingsBlocks`): the settings rows and click-to-capture controls as composable, HudTheme-tokenized blocks, so a game lays out its own settings screen instead of taking the stock dialog. Rebinding writes into the game's existing rebind/holdings store.
+- `useAccessibilitySettings`, `useHoldVsToggle` and `useAccessibilityRows` (`@jgengine/react/accessibilitySettings`) read the live preferences for any custom layout.
+- `HudThemeRoot` takes `accessibility` and applies text scale and the preference data attributes at the HUD root; the shell passes the player's stored preferences there for both the 3D and HUD-only presentation paths.
+- `MissionTickInput.events` (`@jgengine/core/gameplay`) carries the world events that happened this tick - `kill`, `collect`, `deliver` with a target, the actor, free-form `tags` and a count. An objective's `match` filter (`target`, `by`, `tags`, `withoutTags`) credits a constrained counter only from matching events, so a decoy, a wrong weapon or another killer's kill does not advance it.
+- `failOn` accepts `event` (a matching reported event ends the run) and `left-area` (the watched actor is farther than `radius` from an authored marker), completing the reachable fail states: cargo lost, time out, escort died, left the area. `validateMissionCatalog` rejects a `left-area` fail with no actor or unknown marker and a `match` on a non-counter objective instead of ignoring it.
+- `MissionView` now carries `counted`, `count`, `step`, `steps`, `outcome` and `reason`, so a HUD renders "step 2 of 3", a timer and the fail state from `view()` alone. A counter objective's progress mirrors the caller's counters into `state.progress`, so `view()` and a save both see it.
+- `TerrainDetailMaterialConfig.missing` (`@jgengine/core/world/features`): a terrain detail material built from pulled scans no longer takes the whole view down when those maps are not on disk. `"procedural"` (the default) keeps the authored procedural ground and logs one warning naming the missing map, so a game whose asset packs are pulled rather than committed boots anywhere; `"fail"` keeps the presentation retry screen for a view that genuinely cannot render without the scan, which is what the recovery demo asks for.
+
+### Changed
+
+- `bun run land` (`scripts/land.ts`) lands a task branch in one command: it refuses `main` or a dirty tree, pushes, opens or reuses the PR into `beta`, runs `--verify`, watches checks, merges and prints `landed <url>`. Exit codes: 0 landed, 1 verify failed, 2 checks failed, 3 could not merge.
+- The CI `test` job is split by path into four matrix shards (`scripts/test-shard.ts`), about 90 s each instead of 5m37s in one job; `ci` still aggregates every shard and no test file is dropped.
+- A loaded model whose meshes share a material now merges to one mesh per material at load, baking each source mesh's transform into the merged vertices. Every instance cloned from that model draws once per material instead of once per sub-mesh, and the instanced scatter/static-batch path harvests the same merged meshes. Skinned meshes, instanced meshes, meshes with morph targets or rigged ancestors, meshes with children, hidden meshes, mirrored meshes, and every model carrying an animation clip are left untouched. A material-assignment `selector.mesh` still resolves a sub-mesh name the merge absorbed.
+- Static authored/`scenery` props batch per model per 128 m cell with a minimum of 2, instead of per model per 64 m cell with a minimum of 3. Props spread thinner than the old minimum in their cell used to fall back to a full individual model draw — Harbor Heat drew 425 of its 488 props that way — and now join one instanced draw per material. Cell size stays configurable because one `InstancedMesh` has one bounding sphere, which three also frustum-tests in the shadow pass: a batch spanning the whole city submits every camera-visible instance to every shadow cascade (Harbor Heat +14% triangles), while 128 m keeps that rejection working (+1.1%).
+- Culling stays per instance: the visibility predicate compacts each batch's drawn range every frame and the batch's bounding sphere is rebuilt from what it draws, so a batch with nothing in view contributes a draw of zero.
+- Static subtrees stop paying three's per-frame matrix pass. `freezeStaticTransforms` (`@jgengine/shell/render/staticTransforms`) bakes a subtree's world matrices once and clears `matrixAutoUpdate`/`matrixWorldAutoUpdate`; `thawStaticTransforms` puts it back for a seam that moves on an event. Batched static props and object/entity marker groups use it.
+- Actor and object marker groups now own their matrix: the per-frame pose write recomposes only when the pose actually changed, so a parked prop or an idle actor leaves its subtree out of that frame's world-matrix pass. Moving actors are unchanged.
+- A postfx prepass no longer re-walks the scene graph. `renderWithCurrentMatrices` (`@jgengine/shell/postfx/shadowPrepass`) draws the stylize normal prepass and the GTAO/DOF prepasses with the matrices the beauty pass built moments earlier in the same frame.
+
+Harbor Heat: `updateMatrixWorld` 2.99 ms → 1.66 ms per frame.
+- A rigged model's skinned parts merge into one skinned mesh per skeleton and material at load (`mergeSkinnedModelParts`, `@jgengine/shell/render/modelMeshMerge`). Vertices move into bind space and skin indices are remapped onto the union of the parts' bones, so the posed result is unchanged. A KayKit character's six body parts become one draw and one bone-matrix upload per character.
+- Characters now carry distance tiers. Under 15 m the rig poses every frame, under 40 m every other frame with the accumulated time, and past 25 m a crowd-eligible rig is drawn by the GPU crowd path and stops updating bones. The thresholds live in `ModelConfig.lod` per model; `lod: false` keeps a model at full rate (a player avatar or a cutscene character), and the local player is always full rate. Any animated model with no `ik`, `attachments` or `parts` is crowd-eligible, so a game with no configuration still loses its distant characters' skeletons.
+- `CharacterCrowd` (`@jgengine/shell/render/CharacterCrowd`) draws those far characters: one baked rig per kind, one instanced draw per material, each member's clip, gait phase and speed sampled on the GPU. Entity markers decide the tier, so a character only leaves its rig once the batch for its kind is baked.
+
+Harbor Heat at the spawn view: 426 skinned meshes  71, bone pose writes per frame 2,894  41, draws 2,537  1,387, `updateMatrixWorld` 1.47  1.36 ms, frame 25.1  16.7 ms.
+- Shadow casters under a 0.5 m world radius clear `castShadow` as they stream in (`cullSmallShadowCasters`, `@jgengine/shell/render/shadowCasters`). A prop that small is a couple of shadow-map texels wide, so the depth pass spent a draw on a smudge; the authored flag comes back when the mesh leaves the scene. Only clears, so a mesh the game keeps out of the pass stays out. The `render/shadows` devtools system probe reports casters and how many were skipped.
+- Cascaded shadow maps refresh the far cascades on a cadence instead of every frame (`scheduleCascadeRefresh`): with three cascades the nearest redraws every frame, the middle every 2nd and the far every 4th; with four, the two nearest every frame and the rest every 2nd/4th. A skipped cascade keeps the matrix and map from its last refresh, so the pair stays consistent and the shadows do not slide.
+- Cascaded shadow reach now comes from the graphics tier when a game does not author `shadowMaxFar`: the tier's shadow-map resolution sets the reach (512 → 100 m, 1024 → 150 m, 2048/4096 → 200 m), clamped by that tier's draw distance. An authored `shadowMaxFar` still wins, so existing games keep the distance they chose.
+
+Harbor Heat's shadow pass self time at `--quality full`: 2.88 → 1.37 ms per frame, `WebGLShadowMap.render` 11.0% → 5.3% of the sampled window; the material patch hook every draw pays dropped out of the top self-time entries (0.83 ms → under 0.3 ms per frame). Frame time is unchanged within the capture noise floor at that view, where the post-processing chain dominates.
+- `EntityDiedEvent.source` and `DeathReason` name what killed the entity: a `player_kill`'s `source` is the killer's instance id, and an environment death carries `attacker` for a non-player entity. `deathReasonFromEffect` fills both from the effect's `from`. Reading an existing environment reason keeps working; a rule that matched `kind` still matches.
+- `ctx.scene.entity.effect` (including telegraph-bound and projectile effects) now raises exactly one `combat.damage` per target on `ctx.game.events`, with the same shape `createDamageRuntime` emits: `type` is the effect id, `remaining`/`lethal` come from the last pool in the catalog's `receive` order. `createDamageRuntime` keeps its own emission, so a game using both paths gets one event per blow, not two.
+- `.claude/skills/jgengine-combat` says which damage path to use: the runtime for typed/zoned/armored damage, the effect path for catalog `receive` pools.
+- The dev runner installs the resolved `?look=`/`--cam=` rig as the capture camera, and the shell's camera rig and presentation both resolve through `resolveCaptureCameraConfig`.
+- `metricsPathFor` (`scripts/shot-metrics`) is the `--inspect` metrics path for a shot. `--out` without an image extension used to swap nothing, so the metrics JSON was written straight over the screenshot; the metrics path now always differs from the shot path.
+- `WorldParticles` allocates the tier's `particleBudget` across the standing emitters and queued bursts with `planParticleBudget`, and reports `cap`/`budgetParticles`/`droppedIds` on its `particles` diagnostics probe.
+
+### Fixed
+
+- `settingsBoundary.test.ts` builds its fixture under `.scratch/` inside the checkout instead of `%TEMP%`, so `@jgengine/*` resolves through the workspace and the browser test passes in a fresh worktree with no `dist`; CI was hiding this because it builds first.
+- The skill installer treats an unreadable `.jgengine-version.json` as missing and says which file it ignored, so a half-written or hand-edited marker is rewritten on the next install instead of blocking it; refusal messages now name the metadata file.
+- Skill and doctor fixtures write a realistic next-minor version instead of `99.0.0`, so the CI log no longer reports impossible install versions.
+- `SettingsMenu` keeps Escape closing the dialog while a keybind capture is ending. The capture already consumes Escape at the window, so the extra "wait for capture state" guard only dropped a close request that arrived before the next render, which failed `touchHudReachability` on every `beta` run since #2100.
+- `RoutineTimeline.nextChangeAfter` (`@jgengine/core/sim/routine`) no longer answers with the time it was given when a stop time is fractional. `time` arrives as a whole number of cycles plus a stop time, so its low bits are already rounded; a boundary that rounding put a hair behind `time` read as a change still to come, and the answer repeated, so anything that stepped by it looped forever. Boundaries are compared in absolute time within a few ulps of `time`, so every answer is strictly later. `phaseAt` uses the same tolerance, so a phase that starts exactly on a rounded boundary reports the new phase instead of the walk that led to it.
+- `createOffScreenWorld.refreshCheap` stops catching up instead of spinning if a schedule ever again fails to name a later change: it decays needs to `now`, holds the phase and retries one cycle later.
+- A type token now honors the player's text scale: `--jg-type-*` are `calc(max(floor, size) * var(--jg-text-scale, 1))`, so raising text size resizes every engine block rather than only a menu's own labels.
+
 ## 0.27.0
 
 ### Migrate

package/dist/catalogs/materialLibrary.d.ts

@@ -1,4 +1,6 @@
 import { type MaterialAsset, type MaterialSurfaceParameters, type MaterialTextureMetadata, type MaterialTextureRole } from "@jgengine/core/material/materialAsset";
+import type { BuildingSurfaceMaterial } from "@jgengine/core/world/buildings";
+import type { TerrainDetailMaterialConfig } from "@jgengine/core/world/features";
 /** How a library surface renders: an ordinary PBR surface, cut-out foliage, glass or water. */
 export type LibrarySurface = "opaque" | "foliage" | "glass" | "water";
 /** Browse groups the library browser and `assets list` share. */
@@ -21,6 +23,19 @@ export interface LibraryMaterial {
     tileMetres: number;
     /** Sparse physical response merged over the imported or authored slot. */
     response: MaterialSurfaceParameters;
+    /**
+     * How this scan blends onto terrain when the defaults are wrong for its scale. A macro ground
+     * scan tiles over tens of metres, so its own albedo is a broad wash rather than the authored
+     * ground colour; it wants to arrive as grain (`tint` low) instead of replacing the biome tint.
+     */
+    terrain?: LibraryTerrainDetail;
+}
+/** Blend policy for putting a library scan on terrain; only entries whose scale needs it declare one. */
+export interface LibraryTerrainDetail {
+    /** Blend strength over the procedural/vertex-colour ground, 0..1. Default 1. */
+    strength?: number;
+    /** How much of the scan's own colour replaces the authored ground colour, 0..1. Default 1. */
+    tint?: number;
 }
 /**
  * The shared library: 40+ ambientCG PBR materials plus the glass and water surfaces that need a
@@ -28,8 +43,8 @@ export interface LibraryMaterial {
  * response is a type error instead of a silently grey surface.
  */
 export declare const MATERIAL_LIBRARY: readonly LibraryMaterial[];
-/** Map roles a library scan can carry: the PBR set plus cut-out coverage. */
-export type LibraryMapRole = "color" | "normal" | "roughness" | "ao" | "opacity";
+/** Map roles a library scan can carry: the PBR set plus cut-out coverage and a height map. */
+export type LibraryMapRole = "color" | "normal" | "roughness" | "ao" | "opacity" | "displacement";
 /** Resolve a library name; unknown names return `null` so a caller can report them by name. */
 export declare function findLibraryMaterial(name: string): LibraryMaterial | null;
 /** Every library name, in authored order. */
@@ -46,6 +61,9 @@ export interface LibraryMaterialOptions {
 /**
  * Serialized runtime map URLs for a library material, matching what `assets pull <source>` writes
  * into `<basePath>/<source-id>/`. Roles the archive does not ship are omitted, never invented.
+ * `displacement` is not loaded here: no standard-path renderer samples a height map, and a decoded
+ * 1K map per material would cost real GPU memory. Terrain callers get the URL through
+ * {@link libraryTerrainMaterial} instead.
  */
 export declare function libraryMaterialMaps(entry: LibraryMaterial, options?: LibraryMaterialOptions): Partial<Record<MaterialTextureRole, MaterialTextureMetadata>>;
 /**
@@ -59,3 +77,46 @@ export declare function libraryMaterialAsset(name: string, options?: LibraryMate
  * Empty query returns everything, so a browser can render the full library first.
  */
 export declare function filterLibraryMaterials(query: string, group?: LibraryGroup): readonly LibraryMaterial[];
+/** Options for {@link libraryTerrainMaterial}. */
+export interface LibraryTerrainOptions {
+    /** URL prefix `assets pull` writes under; defaults to `/materials`. */
+    basePath?: string;
+    /** World units per texture tile; defaults to the entry's authored `tileMetres`. */
+    repeat?: number;
+    /** Blend strength over the procedural ground, 0..1; the entry's terrain policy, else 1. */
+    strength?: number;
+    /** How much of the map's own colour replaces the authored ground colour, 0..1; the entry's terrain policy, else 1. */
+    tint?: number;
+}
+/**
+ * A library name as terrain detail material config: `terrain({ detail: { material: libraryTerrainMaterial("foliage/grass-macro") } })`.
+ * Tiling comes from the entry's authored metres and blend from its terrain policy, so a game selects
+ * a ground by name instead of assembling map URLs. A map the archive does not ship is omitted, so
+ * `displacement` is never a URL the caller had to invent.
+ * @capability library-terrain-material put a named library material on terrain without faking optional maps
+ */
+export declare function libraryTerrainMaterial(name: string, options?: LibraryTerrainOptions): TerrainDetailMaterialConfig;
+/** Options for {@link libraryBuildingSurface}. */
+export interface LibraryBuildingSurfaceOptions {
+    /** URL prefix `assets pull` writes under; defaults to `/materials`. */
+    basePath?: string;
+    /** Metres one building part slot covers, `[width, height]`; tiles per slot follow from the entry's `tileMetres`. */
+    slotMetres?: readonly [number, number];
+    /** Tiles per slot, along [x, y]; wins over `slotMetres`. */
+    repeat?: number | readonly [number, number];
+    /** Albedo multiplier over the map; defaults to the entry's authored response colour. */
+    color?: string;
+}
+/**
+ * A library name as a building surface: `building({ palette: { wall: libraryBuildingSurface("brick/red", { slotMetres: [12, 3] }) } })`.
+ * The maps tile at the entry's authored metres, and the response's colour/roughness/metalness come
+ * with them, so a facade picks a material by name instead of hand-wiring a surface per part kind.
+ * @capability library-building-surface paint a building part from a named library material
+ */
+export declare function libraryBuildingSurface(name: string, options?: LibraryBuildingSurfaceOptions): BuildingSurfaceMaterial;
+/**
+ * A library name as the sparse surface parameters a `MaterialAsset` or a render-time override takes,
+ * so a material picked by name keeps its authored roughness, metalness and cut-out policy.
+ * @capability library-surface-parameters carry a named library material's response into authored overrides
+ */
+export declare function librarySurfaceParameters(name: string): MaterialSurfaceParameters;

package/dist/catalogs/materialLibrary.js

@@ -51,11 +51,13 @@ export const MATERIAL_LIBRARY = [
     { name: "foliage/leaf", title: "Leaf card", group: "foliage", source: "ambientcg-leaf001", surface: "foliage", tileMetres: 0.8, response: { metalness: 0, roughness: 0.55, alphaMode: "mask", alphaCutoff: 0.45, doubleSided: true, sheen: 0.6, sheenColor: "#c8d18a", sheenRoughness: 0.7 } },
     { name: "foliage/leaf-dense", title: "Dense leaf card", group: "foliage", source: "ambientcg-leaf003", surface: "foliage", tileMetres: 1, response: { metalness: 0, roughness: 0.6, alphaMode: "mask", alphaCutoff: 0.45, doubleSided: true, sheen: 0.55, sheenColor: "#b9cc7d", sheenRoughness: 0.75 } },
     { name: "foliage/grass", title: "Grass ground", group: "foliage", source: "ambientcg-grass001", surface: "opaque", tileMetres: 2, response: { metalness: 0, roughness: 0.9 } },
+    { name: "foliage/grass-macro", title: "Grass ground (macro)", group: "foliage", source: "ambientcg-grass001", surface: "opaque", tileMetres: 24, response: { metalness: 0, roughness: 0.9 }, terrain: { strength: 0.6, tint: 0.3 } },
     { name: "foliage/grass-dry", title: "Dry grass", group: "foliage", source: "ambientcg-grass004", surface: "opaque", tileMetres: 2, response: { metalness: 0, roughness: 0.92 } },
     { name: "foliage/moss", title: "Moss", group: "foliage", source: "ambientcg-moss001", surface: "opaque", tileMetres: 1.2, response: { metalness: 0, roughness: 0.95 } },
     { name: "foliage/leaf-litter", title: "Leaf litter", group: "foliage", source: "ambientcg-scatteredleaves008", surface: "opaque", tileMetres: 2.4, response: { metalness: 0, roughness: 0.88 } },
     // Ground and nature.
     { name: "ground/dirt", title: "Forest floor", group: "ground", source: "ambientcg-ground037", surface: "opaque", tileMetres: 2.4, response: { metalness: 0, roughness: 0.9 } },
+    { name: "ground/dirt-macro", title: "Forest floor (macro)", group: "ground", source: "ambientcg-ground037", surface: "opaque", tileMetres: 20, response: { metalness: 0, roughness: 0.9 }, terrain: { strength: 0.6, tint: 0.3 } },
     { name: "ground/sand", title: "Beach sand", group: "ground", source: "ambientcg-ground055s", surface: "opaque", tileMetres: 2, response: { metalness: 0, roughness: 0.88 } },
     { name: "ground/sand-dark", title: "Dark sand", group: "ground", source: "ambientcg-ground080", surface: "opaque", tileMetres: 2, response: { metalness: 0, roughness: 0.86 } },
     { name: "ground/mud", title: "Wet mud", group: "ground", source: "ambientcg-ground095b", surface: "opaque", tileMetres: 2, response: { metalness: 0, roughness: 0.52 } },
@@ -81,7 +83,11 @@ export const MATERIAL_LIBRARY = [
 ];
 const byName = new Map(MATERIAL_LIBRARY.map((entry) => [entry.name, entry]));
 /** Every readable map role a library material can carry, in load order. */
-const LIBRARY_ROLES = ["color", "normal", "roughness", "ao", "opacity"];
+const LIBRARY_ROLES = ["color", "normal", "roughness", "ao", "opacity", "displacement"];
+/** Authoring role a library map feeds: `opacity` is an alpha map, `displacement` is a height map. */
+function textureRoleFor(role) {
+    return role === "opacity" ? "alpha" : role === "displacement" ? "height" : role;
+}
 /** Resolve a library name; unknown names return `null` so a caller can report them by name. */
 export function findLibraryMaterial(name) {
     return byName.get(name) ?? null;
@@ -102,13 +108,18 @@ export function libraryMaterialRoles(entry) {
 /**
  * Serialized runtime map URLs for a library material, matching what `assets pull <source>` writes
  * into `<basePath>/<source-id>/`. Roles the archive does not ship are omitted, never invented.
+ * `displacement` is not loaded here: no standard-path renderer samples a height map, and a decoded
+ * 1K map per material would cost real GPU memory. Terrain callers get the URL through
+ * {@link libraryTerrainMaterial} instead.
  */
 export function libraryMaterialMaps(entry, options = {}) {
     const base = `${(options.basePath ?? "/materials").replace(/\/+$/, "")}/${entry.source ?? ""}`;
     const source = entry.source === undefined ? undefined : sourceById.get(entry.source);
     const textures = {};
     for (const role of libraryMaterialRoles(entry)) {
-        const target = role === "opacity" ? "alpha" : role;
+        if (role === "displacement")
+            continue;
+        const target = textureRoleFor(role);
         textures[target] = {
             url: `${base}/${MATERIAL_MAP_FILES[role]}`,
             colorSpace: MATERIAL_TEXTURE_SEMANTICS[target].colorSpace,
@@ -171,3 +182,90 @@ export function filterLibraryMaterials(query, group) {
         return `${entry.name} ${entry.title} ${entry.group} ${entry.source ?? ""}`.toLowerCase().includes(needle);
     });
 }
+function requireLibraryMaterial(name) {
+    const entry = findLibraryMaterial(name);
+    if (entry === null)
+        throw new TypeError(`Unknown library material "${name}"`);
+    return entry;
+}
+/** Pulled URL for one map role, or `undefined` when this entry's archive never ships it. */
+function mapUrl(entry, role, basePath) {
+    if (entry.source === undefined || !libraryMaterialRoles(entry).includes(role))
+        return undefined;
+    return `${basePath.replace(/\/+$/, "")}/${entry.source}/${MATERIAL_MAP_FILES[role]}`;
+}
+/**
+ * A library name as terrain detail material config: `terrain({ detail: { material: libraryTerrainMaterial("foliage/grass-macro") } })`.
+ * Tiling comes from the entry's authored metres and blend from its terrain policy, so a game selects
+ * a ground by name instead of assembling map URLs. A map the archive does not ship is omitted, so
+ * `displacement` is never a URL the caller had to invent.
+ * @capability library-terrain-material put a named library material on terrain without faking optional maps
+ */
+export function libraryTerrainMaterial(name, options = {}) {
+    const entry = requireLibraryMaterial(name);
+    const basePath = options.basePath ?? "/materials";
+    const color = mapUrl(entry, "color", basePath);
+    const normal = mapUrl(entry, "normal", basePath);
+    if (color === undefined || normal === undefined) {
+        throw new TypeError(`Library material "${name}" carries no pulled color/normal maps; terrain needs a scanned surface.`);
+    }
+    const roughness = mapUrl(entry, "roughness", basePath);
+    const ao = mapUrl(entry, "ao", basePath);
+    const displacement = mapUrl(entry, "displacement", basePath);
+    const maps = {
+        color,
+        normal,
+        ...(roughness === undefined ? {} : { roughness }),
+        ...(ao === undefined ? {} : { ao }),
+        ...(displacement === undefined ? {} : { displacement }),
+    };
+    return {
+        maps,
+        repeat: options.repeat ?? entry.tileMetres,
+        strength: options.strength ?? entry.terrain?.strength ?? 1,
+        tint: options.tint ?? entry.terrain?.tint ?? 1,
+    };
+}
+/**
+ * A library name as a building surface: `building({ palette: { wall: libraryBuildingSurface("brick/red", { slotMetres: [12, 3] }) } })`.
+ * The maps tile at the entry's authored metres, and the response's colour/roughness/metalness come
+ * with them, so a facade picks a material by name instead of hand-wiring a surface per part kind.
+ * @capability library-building-surface paint a building part from a named library material
+ */
+export function libraryBuildingSurface(name, options = {}) {
+    const entry = requireLibraryMaterial(name);
+    const basePath = options.basePath ?? "/materials";
+    const color = mapUrl(entry, "color", basePath);
+    const normal = mapUrl(entry, "normal", basePath);
+    if (color === undefined || normal === undefined) {
+        throw new TypeError(`Library material "${name}" carries no pulled color/normal maps; a shader surface has nothing to tile onto a building.`);
+    }
+    const roughness = mapUrl(entry, "roughness", basePath);
+    const ao = mapUrl(entry, "ao", basePath);
+    const maps = {
+        color,
+        normal,
+        ...(roughness === undefined ? {} : { roughness }),
+        ...(ao === undefined ? {} : { ao }),
+    };
+    const repeat = options.repeat
+        ?? (options.slotMetres === undefined
+            ? undefined
+            : [options.slotMetres[0] / entry.tileMetres, options.slotMetres[1] / entry.tileMetres]);
+    const surfaceColor = options.color ?? entry.response.color;
+    return {
+        maps,
+        ...(surfaceColor === undefined ? {} : { color: surfaceColor }),
+        ...(repeat === undefined ? {} : { repeat }),
+        ...(entry.response.roughness === undefined ? {} : { roughness: entry.response.roughness }),
+        ...(entry.response.metalness === undefined ? {} : { metalness: entry.response.metalness }),
+    };
+}
+/**
+ * A library name as the sparse surface parameters a `MaterialAsset` or a render-time override takes,
+ * so a material picked by name keeps its authored roughness, metalness and cut-out policy.
+ * @capability library-surface-parameters carry a named library material's response into authored overrides
+ */
+export function librarySurfaceParameters(name) {
+    return { ...requireLibraryMaterial(name).response };
+}

package/dist/materials.d.ts

@@ -14,7 +14,7 @@ export interface ExtractedMaterialMap {
  * URLs never depend on the provider's naming or the pulled resolution.
  */
 export declare function extractMaterialMaps(archive: Uint8Array): ExtractedMaterialMap[];
-/** URLs of one material's PBR maps; `ao`/`roughness`/`opacity`/`ktx2` appear only when declared by its source. */
+/** URLs of one material's PBR maps; `ao`/`roughness`/`opacity`/`ktx2`/`displacement` appear only when declared by its source. */
 export interface MaterialMaps {
     color: string;
     normal: string;
@@ -22,7 +22,8 @@ export interface MaterialMaps {
     ao?: string;
     /** Cut-out coverage map, present on foliage and decal-style scans. */
     opacity?: string;
-    displacement: string;
+    /** Height map for callers that displace geometry; absent on archives published without one. */
+    displacement?: string;
     ktx2?: string;
 }
 /** A resolved material: identity, attribution, and its normalized map URLs. */

package/dist/materials.js

@@ -62,7 +62,7 @@ function refFor(source, basePath) {
             ...(source.materialMaps?.includes("roughness") ? { roughness: `${base}/${MATERIAL_MAP_FILES.roughness}` } : {}),
             ...(source.materialMaps?.includes("ao") ? { ao: `${base}/${MATERIAL_MAP_FILES.ao}` } : {}),
             ...(source.materialMaps?.includes("opacity") ? { opacity: `${base}/${MATERIAL_MAP_FILES.opacity}` } : {}),
-            displacement: `${base}/${MATERIAL_MAP_FILES.displacement}`,
+            ...(source.materialMaps?.includes("displacement") ? { displacement: `${base}/${MATERIAL_MAP_FILES.displacement}` } : {}),
             ...(source.materialMaps?.includes("ktx2") ? { ktx2: `${base}/${MATERIAL_MAP_FILES.ktx2}` } : {}),
         },
     };

package/dist/snippet.js

@@ -30,7 +30,7 @@ export function materialWiringSnippet(id, basePath = "/materials") {
         `export const materials = buildMaterialCatalog({ basePath: ${JSON.stringify(basePath)} });`,
         ``,
         `const material = materials.resolve(${JSON.stringify(id)})!;`,
-        `// material.maps => { color, normal, displacement, roughness?, ao?, ktx2? } URLs under ${basePath}/${id}/`,
+        `// material.maps => { color, normal, displacement?, roughness?, ao?, ktx2? } URLs under ${basePath}/${id}/`,
         ``,
         `// onto the ground (terrain() in defineGame({ world: environment({ terrain: ... }) })):`,
         `terrain({ detail: { material: { maps: material.maps, repeat: 4 } } })`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/assets",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Self-generating, license-verified index of thousands of CC0 3D models for JGengine. Sources fetch from providers' own CDNs at pull time; the npm tarball ships only the typed index and CLI (no GLB bytes).",
   "license": "Apache-2.0",
   "type": "module",
@@ -38,7 +38,7 @@
     "@gltf-transform/core": "4.2.1",
     "@gltf-transform/extensions": "4.2.1",
     "@gltf-transform/functions": "4.2.1",
-    "@jgengine/core": "^0.27.0",
+    "@jgengine/core": "^0.28.0",
     "fflate": "^0.8.2"
   },
   "devDependencies": {

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.27.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.28.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.27.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.28.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-assets/SKILL.md

@@ -58,9 +58,13 @@ Material sources declare the map roles in their pinned archive through `AssetSou
 
 ## Material library
 
-`@jgengine/assets/catalogs/materialLibrary` is the shared palette: `MATERIAL_LIBRARY` names 56 surfaces (`asphalt/wet`, `metal/painted`, `stucco/painted`, `brick/red`, `wood/oak`, `foliage/leaf`, `glass/clear`, `water/ocean`, `ground/sand`, `concrete/smooth`, …), each with its ambientCG source, world tile size in metres and physical response. Select by name — never by source id or filename.
+`@jgengine/assets/catalogs/materialLibrary` is the shared palette: `MATERIAL_LIBRARY` names 58 surfaces (`asphalt/wet`, `metal/painted`, `stucco/painted`, `brick/red`, `wood/oak`, `foliage/leaf`, `glass/clear`, `water/ocean`, `ground/sand`, `concrete/smooth`, …), each with its ambientCG source, world tile size in metres and physical response. Select by name — never by source id or filename.
 
-- `assets pull library --dir <public>` pulls every pinned map set (about 360 MB of 1K-JPG archives; each pulled material is then 5–7 MB beside its name). Pull into a game's `public/materials` and build assets with `libraryMaterialAsset(name)`; the returned `MaterialAsset` is the same editable value the editor writes into `editor.scene.json`.
+- `assets pull library --dir <public>` pulls every pinned map set (about 360 MB of 1K-JPG archives; each pulled material is then 5-7 MB beside its name). Pull into a game's `public/materials` and build assets with `libraryMaterialAsset(name)`; the returned `MaterialAsset` is the same editable value the editor writes into `editor.scene.json`.
+- Three bridges turn a name into the seam each consumer takes, so a game never hand-wires URLs: `libraryTerrainMaterial(name)` is a `TerrainDetailMaterialConfig` (`terrain({ detail: { material: … } })`), `libraryBuildingSurface(name, { slotMetres })` is a `BuildingSurfaceMaterial` (a `building()` palette entry), and `librarySurfaceParameters(name)` is the sparse `MaterialSurfaceParameters` a `MaterialAsset` or an override carries.
+- Tiling comes from the entry's authored metres: `libraryTerrainMaterial` uses `tileMetres` for `repeat`, and `libraryBuildingSurface` derives tiles-per-slot from `slotMetres`. Both throw on a shader surface (glass, water) rather than tiling a scan that does not exist.
+- A **macro** entry is the same scan at a much larger tile (`foliage/grass-macro` 24 m, `ground/dirt-macro` 20 m) for cameras 50 m and further out. At that distance a 2 m tile resolves to sub-pixel noise that averages back to one flat colour; a 24 m tile still shows structure. Its `terrain` policy keeps the authored ground colour (`tint` low) and takes only the scan's grain. `?mode=flat|dense|macro` on the `terrain-macro` dev demo compares the three at 52 m.
+- Library map roles are `color`, `normal`, `roughness`, `ao`, `opacity` and `displacement`; `displacement` is reported by `libraryMaterialRoles` and passed through `libraryTerrainMaterial`, but `libraryMaterialAsset` does not load it, because no standard-path renderer samples a height map. Never construct that URL by hand to satisfy a type.
 - Clear and frosted glass, ocean and puddle carry no scan: ambientCG publishes no glass or water material, so those four are response parameters. `glass/smudged` adds ambientCG's fingerprint normal.
 - Geometry without a `uv` attribute renders through `@jgengine/shell/render/triplanarMaterial` (`TriplanarAssetMaterial`, `useTriplanarAssetMaterial`, or `applyTriplanarProjection` on an owned material). It projects colour, normal, roughness and AO from world position at the asset's tile size, and instanced meshes project in instanced space. Use it for generated or imported world geometry; keep UV-mapped models on the ordinary path.
 - Metals need an environment to reflect. A metal entry under a bare clear colour reads as coloured chrome — pair `metal/*` with `EnvironmentLighting` or an authored sky.

package/skills/jgengine-assets/api.md

@@ -36,7 +36,7 @@
 - `MATERIAL_MAP_FILES` (const): const MATERIAL_MAP_FILES: { readonly color: "color.jpg"; readonly normal: "normal.jpg"; readonly roughness: "roughness.jpg"; readonly ao: "ao.jpg"; readonly opacity: "opacity.jpg"; readonly displacement: "displacement.jpg"; readonly ktx2: "material.ktx2"; } — Normalized filenames a pulled material directory contains, keyed by map role. Kept in its own module so catalogs and editors can name a pulled file without loading the archive reader.
 - `MaterialCatalog` (interface): interface MaterialCatalog — Resolves material ids and `material/…` aliases to `MaterialRef`s.
 - `MaterialMapRole` (type): type MaterialMapRole = keyof typeof MATERIAL_MAP_FILES — One PBR map's role within a material, including an optional compressed KTX2 asset.
-- `MaterialMaps` (interface): interface MaterialMaps — URLs of one material's PBR maps; `ao`/`roughness`/`opacity`/`ktx2` appear only when declared by its source.
+- `MaterialMaps` (interface): interface MaterialMaps — URLs of one material's PBR maps; `ao`/`roughness`/`opacity`/`ktx2`/`displacement` appear only when declared by its source.
 - `MaterialRef` (interface): interface MaterialRef — A resolved material: identity, attribution, and its normalized map URLs.
 - `ModelDims` (interface): interface ModelDims — Measured horizontal footprint, footprint center, and lowest Y of a model in model space.
 - `ModelSnippetOptions` (interface): interface ModelSnippetOptions { basePath?: string; seam?: "objectModels" | "entityModels" } — ⚠ undocumented · used by `modelWiringSnippet`: Copy-paste wiring for a pulled GLB id: resolve through the catalog, drop into a model seam.
@@ -84,7 +84,7 @@
 - `kaykitSources` (const): const kaykitSources: readonly AssetSource[] — ⚠ undocumented
 - `keyFromSpriteFile` (function): function keyFromSpriteFile(file: string): string — Strips the `.svg`/`.png` extension off a pulled sprite/icon filename to get its id suffix.
 - `libraryMaterialAsset` (function): function libraryMaterialAsset(name: string, options: LibraryMaterialOptions = {}): MaterialAsset — Build the editable, serializable material asset for a library name: maps, response and CC0 attribution in one value the editor can save into `editor.scene.json` and the shell renders. `projection` records whether those maps should sample authored UVs or world-space triplanar.
-- `libraryMaterialMaps` (function): function libraryMaterialMaps(entry: LibraryMaterial, options: LibraryMaterialOptions = {}): Partial<Record<MaterialTextureRole, MaterialTextureMetadata>> — Serialized runtime map URLs for a library material, matching what `assets pull <source>` writes into `<basePath>/<source-id>/`. Roles the archive does not ship are omitted, never invented.
+- `libraryMaterialMaps` (function): function libraryMaterialMaps(entry: LibraryMaterial, options: LibraryMaterialOptions = {}): Partial<Record<MaterialTextureRole, MaterialTextureMetadata>> — Serialized runtime map URLs for a library material, matching what `assets pull <source>` writes into `<basePath>/<source-id>/`. Roles the archive does not ship are omitted, never invented. `displacement` is not loaded here: no standard-path renderer samples a height map, and a decoded 1K map per material would cost real GPU memory. Terrain callers get the URL through {@link libraryTerrainMaterial} instead.
 - `libraryMaterialNames` (function): function libraryMaterialNames(): readonly string[] — Every library name, in authored order.
 - `libraryMaterialRoles` (function): function libraryMaterialRoles(entry: LibraryMaterial): readonly LibraryMapRole[] — Map roles the pinned archive of `entry` actually ships, from its catalog source declaration.
 - `materialAliases` (const): const materialAliases: readonly AssetAlias[] — Semantic keys onto the ambientCG catalog, mirroring the model alias layer.
@@ -135,18 +135,24 @@
 
 ## @jgengine/assets/catalogs/materialLibrary
 
+- `LibraryBuildingSurfaceOptions` (interface): interface LibraryBuildingSurfaceOptions — Options for {@link libraryBuildingSurface}.
 - `LibraryGroup` (type): type LibraryGroup = | "asphalt" | "concrete" | "stucco" | "brick" | "tile" | "metal" | "wood" | "foliage" | "ground" | "fabric" | "stone" | "glass" | "water" — Browse groups the library browser and `assets list` share.
-- `LibraryMapRole` (type): type LibraryMapRole = "color" | "normal" | "roughness" | "ao" | "opacity" — Map roles a library scan can carry: the PBR set plus cut-out coverage.
+- `LibraryMapRole` (type): type LibraryMapRole = "color" | "normal" | "roughness" | "ao" | "opacity" | "displacement" — Map roles a library scan can carry: the PBR set plus cut-out coverage and a height map.
 - `LibraryMaterial` (interface): interface LibraryMaterial — One named material a game or the editor selects by name. `source` names the ambientCG catalog entry whose pulled maps it uses; glass and water carry response parameters only, because ambientCG publishes no scanned glass or water material and both are shader surfaces.
 - `LibraryMaterialOptions` (interface): interface LibraryMaterialOptions — Options for {@link libraryMaterialMaps} and {@link libraryMaterialAsset}.
 - `LibrarySurface` (type): type LibrarySurface = "opaque" | "foliage" | "glass" | "water" — How a library surface renders: an ordinary PBR surface, cut-out foliage, glass or water.
+- `LibraryTerrainDetail` (interface): interface LibraryTerrainDetail — Blend policy for putting a library scan on terrain; only entries whose scale needs it declare one.
+- `LibraryTerrainOptions` (interface): interface LibraryTerrainOptions — Options for {@link libraryTerrainMaterial}.
 - `MATERIAL_LIBRARY` (const): const MATERIAL_LIBRARY: readonly LibraryMaterial[] — The shared library: 40+ ambientCG PBR materials plus the glass and water surfaces that need a shader rather than a scan. `satisfies` keeps every entry complete, so a missing tile size or response is a type error instead of a silently grey surface.
 - `filterLibraryMaterials` (function): function filterLibraryMaterials(query: string, group?: LibraryGroup): readonly LibraryMaterial[] — Filter the library for a picker: case-insensitive match on name, title, group or source. Empty query returns everything, so a browser can render the full library first.
 - `findLibraryMaterial` (function): function findLibraryMaterial(name: string): LibraryMaterial | null — Resolve a library name; unknown names return `null` so a caller can report them by name.
+- `libraryBuildingSurface` (function): function libraryBuildingSurface(name: string, options: LibraryBuildingSurfaceOptions = {}): BuildingSurfaceMaterial — A library name as a building surface: `building({ palette: { wall: libraryBuildingSurface("brick/red", { slotMetres: [12, 3] }) } })`. The maps tile at the entry's authored metres, and the response's colour/roughness/metalness come with them, so a facade picks a material by name instead of hand-wiring a surface per part kind.
 - `libraryMaterialAsset` (function): function libraryMaterialAsset(name: string, options: LibraryMaterialOptions = {}): MaterialAsset — Build the editable, serializable material asset for a library name: maps, response and CC0 attribution in one value the editor can save into `editor.scene.json` and the shell renders. `projection` records whether those maps should sample authored UVs or world-space triplanar.
-- `libraryMaterialMaps` (function): function libraryMaterialMaps(entry: LibraryMaterial, options: LibraryMaterialOptions = {}): Partial<Record<MaterialTextureRole, MaterialTextureMetadata>> — Serialized runtime map URLs for a library material, matching what `assets pull <source>` writes into `<basePath>/<source-id>/`. Roles the archive does not ship are omitted, never invented.
+- `libraryMaterialMaps` (function): function libraryMaterialMaps(entry: LibraryMaterial, options: LibraryMaterialOptions = {}): Partial<Record<MaterialTextureRole, MaterialTextureMetadata>> — Serialized runtime map URLs for a library material, matching what `assets pull <source>` writes into `<basePath>/<source-id>/`. Roles the archive does not ship are omitted, never invented. `displacement` is not loaded here: no standard-path renderer samples a height map, and a decoded 1K map per material would cost real GPU memory. Terrain callers get the URL through {@link libraryTerrainMaterial} instead.
 - `libraryMaterialNames` (function): function libraryMaterialNames(): readonly string[] — Every library name, in authored order.
 - `libraryMaterialRoles` (function): function libraryMaterialRoles(entry: LibraryMaterial): readonly LibraryMapRole[] — Map roles the pinned archive of `entry` actually ships, from its catalog source declaration.
+- `librarySurfaceParameters` (function): function librarySurfaceParameters(name: string): MaterialSurfaceParameters — A library name as the sparse surface parameters a `MaterialAsset` or a render-time override takes, so a material picked by name keeps its authored roughness, metalness and cut-out policy.
+- `libraryTerrainMaterial` (function): function libraryTerrainMaterial(name: string, options: LibraryTerrainOptions = {}): TerrainDetailMaterialConfig — A library name as terrain detail material config: `terrain({ detail: { material: libraryTerrainMaterial("foliage/grass-macro") } })`. Tiling comes from the entry's authored metres and blend from its terrain policy, so a game selects a ground by name instead of assembling map URLs. A map the archive does not ship is omitted, so `displacement` is never a URL the caller had to invent.
 
 ## @jgengine/assets/catalogs/starter
 
@@ -274,7 +280,7 @@
 - `MATERIAL_MAP_FILES` (const): const MATERIAL_MAP_FILES: { readonly color: "color.jpg"; readonly normal: "normal.jpg"; readonly roughness: "roughness.jpg"; readonly ao: "ao.jpg"; readonly opacity: "opacity.jpg"; readonly displacement: "displacement.jpg"; readonly ktx2: "material.ktx2"; } — Normalized filenames a pulled material directory contains, keyed by map role. Kept in its own module so catalogs and editors can name a pulled file without loading the archive reader.
 - `MaterialCatalog` (interface): interface MaterialCatalog — Resolves material ids and `material/…` aliases to `MaterialRef`s.
 - `MaterialMapRole` (type): type MaterialMapRole = keyof typeof MATERIAL_MAP_FILES — One PBR map's role within a material, including an optional compressed KTX2 asset.
-- `MaterialMaps` (interface): interface MaterialMaps — URLs of one material's PBR maps; `ao`/`roughness`/`opacity`/`ktx2` appear only when declared by its source.
+- `MaterialMaps` (interface): interface MaterialMaps — URLs of one material's PBR maps; `ao`/`roughness`/`opacity`/`ktx2`/`displacement` appear only when declared by its source.
 - `MaterialRef` (interface): interface MaterialRef — A resolved material: identity, attribution, and its normalized map URLs.
 - `buildMaterialCatalog` (function): function buildMaterialCatalog(options: BuildMaterialCatalogOptions = {}): MaterialCatalog — A resolvable catalog over every `kind: "material"` source. Ids are source ids (`ambientcg-grass001`) plus the `material/…` aliases; every resolve returns the normalized map URLs under `basePath`, matching what `assets pull` writes into `<dir>/materials/<id>/`.
 - `extractMaterialMaps` (function): function extractMaterialMaps(archive: Uint8Array): ExtractedMaterialMap[] — Pulls the recognized PBR maps out of a material archive (ambientCG's flat `<Asset>_<Res>_<Map>.jpg` layout) and normalizes their names so resolved URLs never depend on the provider's naming or the pulled resolution.

package/skills/jgengine-assets/capabilities.md

@@ -48,6 +48,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `validateHairCardAuthoring` (function) · `import { validateHairCardAuthoring } from "@jgengine/core/material/hairCards"`
 
+## library-building-surface — paint a building part from a named library material
+
+- `libraryBuildingSurface` (function) · `import { libraryBuildingSurface } from "@jgengine/assets/catalogs/materialLibrary"`
+
+## library-surface-parameters — carry a named library material's response into authored overrides
+
+- `librarySurfaceParameters` (function) · `import { librarySurfaceParameters } from "@jgengine/assets/catalogs/materialLibrary"`
+
+## library-terrain-material — put a named library material on terrain without faking optional maps
+
+- `libraryTerrainMaterial` (function) · `import { libraryTerrainMaterial } from "@jgengine/assets/catalogs/materialLibrary"`
+
 ## material-feature-requirements — Declare material shader requirements when authors add maps or appearance adapters.
 
 - `materialCapabilitiesForAsset` (function) · `import { materialCapabilitiesForAsset } from "@jgengine/core/material/materialAsset"`