@jgengine/core 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -11,7 +11,27 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
-## Unreleased
+## 0.10.0
+
+### Migrate
+
+- **Nothing to change for existing games** — the shared mobile-composition system (viewport allocation, region collision, `--jg-*` viewport vars) is wired automatically by the shell for every game; `HudPanel`s inside a `HudCanvas` register themselves. Legacy `orientation: "landscape" | "portrait"` keeps its advisory dismissible-hint behavior unchanged.
+- **Opt a driving/landscape game into the strict gate**: replace the advisory `orientation` with the contract form — `orientation: { mobile: "landscape-required" }` (rules: `any` · `portrait`/`landscape` advisory · `portrait-required`/`landscape-required` · `unsupported`). In portrait the engine now shows a polished `RotateDeviceScreen`, suppresses input, freezes the sim, and unmounts the HUD/controls until the device is landscape.
+- **Declare HUD intent** where useful: `HudPanel` gains `priority` (`critical`/`secondary`/`tertiary`), `mobileBehavior` (`hidden` unmounts on phones, `transient` softens collision, …), `allowOverlapWith`, and `collisionGroup`. Optional — omitting them keeps prior behavior.
+- **Mobile validation now also fails on overlap**: `bun run shoot <game> --device mobile|mobile-landscape|both` exits non-zero on forbidden inter-element collisions (not just viewport overflow), naming both regions.
+
+### Added
+
+- Shared mobile layout composition — `@jgengine/core/ui/gameLayout` (pure geometry: `resolveLayoutMode`, `intersects`, `overlapArea`, `detectLayoutCollisions`, `computeGameplayRect`, `LayoutRegion`, `GameViewportLayout`) and `@jgengine/core/ui/orientation` (`resolveOrientationRequirement`, `orientationGateActive`, `MobileOrientationRule`). `@jgengine/react` adds `GameViewportProvider` (mounted by the shell), hooks (`useGameViewportLayout`, `useGameLayoutMode`, `useGameOrientation`, `useReservedControlZones`, `useLayoutCollisions`, `useRegisterLayoutRegion`), and a headless `RotateDeviceScreen`. The provider tracks `window.visualViewport`, publishes `--jg-viewport-*` / `--jg-visual-viewport-*` / `--jg-safe-*` CSS vars, resolves the explicit layout mode, and detects forbidden region overlaps (dev `data-jg-layout-collision` + console diagnostic).
+- Mandatory orientation contract — `PlayableGame.orientation` accepts `{ mobile: <rule> }`; `landscape-required`/`portrait-required` render an engine-owned rotate gate that blocks gameplay (input suppressed, simulation frozen, HUD/controls unmounted), self-correcting when the device is turned. Reduced-motion and safe-area respected; `visualViewport`-sized for mobile Safari/PWA.
+- Reserved touch-control zones — the touch dock registers its joystick / action-cluster / utility rectangles (runtime-measured) as `control` regions, so HUD placement and collision validation know exactly where controls sit.
+- HUD placement metadata — `HudPanel` gains `priority`, `mobileBehavior`, `allowOverlapWith`, `collisionGroup`, and registers as a collision-tracked layout region.
+- Mobile-landscape shoot device — `bun run shoot --device mobile-landscape` (844×390) plus collision-gate reads that fail mobile validation on forbidden overlaps.
+- Canyon Chase migrated as the reference landscape-required game — declares `orientation: { mobile: "landscape-required" }`, composes its HUD through coordinated `HudPanel` regions (pursuit distance critical, border secondary, survey map hidden on mobile, radio transient) instead of independent fixed corners.
+
+### Changed
+
+- First-person projectile tracers now originate from the weapon muzzle instead of the camera/eye centerline. Hit detection is unchanged (still crosshair-accurate) — only the drawn tracer's start point moved to the viewmodel muzzle, which tracks full aim yaw and pitch. Non-viewmodel games and enemy tracers are unaffected.
 
 ## 0.9.0
 

package/dist/ai/spawnDirector.d.ts

@@ -47,6 +47,16 @@ export interface SpawnRequest {
     point?: NavPoint;
     laneId?: number;
 }
+/** Preference for picking a spawn point relative to `avoid` positions: closer, farther, or unweighted. */
+export type SpawnPointDistanceBias = "near" | "far" | "none";
+/** Semantic options for selecting a spawn point without exposing weighting internals. */
+export interface SpawnPointSelectionOptions {
+    candidates: readonly NavPoint[];
+    avoid?: readonly NavPoint[];
+    random: () => number;
+    distanceBias?: SpawnPointDistanceBias;
+    biasStrength?: number;
+}
 export interface DirectorStep {
     state: SpawnDirectorState;
     spawns: SpawnRequest[];
@@ -55,6 +65,9 @@ export declare function createSpawnDirectorState(config: SpawnDirectorConfig): S
 export declare function raiseAlert(state: SpawnDirectorState, amount: number): SpawnDirectorState;
 export declare function advanceWave(config: SpawnDirectorConfig, state: SpawnDirectorState): SpawnDirectorState;
 export declare function advanceSpawnDirector(config: SpawnDirectorConfig, state: SpawnDirectorState, dt: number, ctx: DirectorContext): DirectorStep;
+/** Selects a candidate spawn point using a semantic distance preference and caller-supplied randomness. */
+export declare function pickSpawnPoint(options: SpawnPointSelectionOptions): NavPoint | null;
+/** @deprecated Pass one SpawnPointSelectionOptions object instead. */
 export declare function pickSpawnPoint(points: readonly NavPoint[], players: readonly NavPoint[], options: {
     roll: number;
     bias?: number;

package/dist/ai/spawnDirector.js

@@ -118,7 +118,14 @@ export function advanceSpawnDirector(config, state, dt, ctx) {
         if (spawnPoints !== undefined && spawnPoints.length > 0) {
             const [roll, nextRng] = nextRandom(rng);
             rng = nextRng;
-            const point = pickSpawnPoint(spawnPoints, playerPositions, { roll, bias: config.spawnPointBias });
+            const bias = config.spawnPointBias ?? 1;
+            const point = pickSpawnPoint({
+                candidates: spawnPoints,
+                avoid: playerPositions,
+                random: () => roll,
+                distanceBias: bias < 0 ? "far" : bias > 0 ? "near" : "none",
+                biasStrength: Math.abs(bias),
+            });
             if (point !== null) {
                 spawn.point = point;
                 spawn.laneId = spawnPoints.indexOf(point);
@@ -134,29 +141,46 @@ export function advanceSpawnDirector(config, state, dt, ctx) {
         spawns,
     };
 }
-export function pickSpawnPoint(points, players, options) {
-    if (points.length === 0)
+export function pickSpawnPoint(optionsOrPoints, legacyPlayers = [], legacyOptions = { roll: 0 }) {
+    let options;
+    if (Array.isArray(optionsOrPoints)) {
+        const legacyBias = legacyOptions.bias ?? 1;
+        options = {
+            candidates: optionsOrPoints,
+            avoid: legacyPlayers,
+            random: () => legacyOptions.roll,
+            distanceBias: legacyBias < 0 ? "far" : legacyBias > 0 ? "near" : "none",
+            biasStrength: Math.abs(legacyBias),
+        };
+    }
+    else {
+        options = optionsOrPoints;
+    }
+    const { candidates, avoid = [], random, distanceBias = "near", biasStrength = 1 } = options;
+    if (candidates.length === 0)
         return null;
-    const bias = options.bias ?? 1;
+    if (distanceBias === "none" || avoid.length === 0 || biasStrength === 0) {
+        return candidates[Math.min(candidates.length - 1, Math.floor(clamp01(random()) * candidates.length))];
+    }
+    const exponent = distanceBias === "far" ? biasStrength : -biasStrength;
     const weights = [];
     let total = 0;
-    for (const point of points) {
+    for (const point of candidates) {
         let nearest = Number.POSITIVE_INFINITY;
-        for (const player of players) {
-            const d = Math.hypot(point[0] - player[0], point[1] - player[1]);
-            if (d < nearest)
-                nearest = d;
+        for (const avoidedPoint of avoid) {
+            const distance = Math.hypot(point[0] - avoidedPoint[0], point[1] - avoidedPoint[1]);
+            if (distance < nearest)
+                nearest = distance;
         }
-        const distance = nearest === Number.POSITIVE_INFINITY ? 0 : nearest;
-        const weight = Math.max(1e-6, (1 + distance) ** -bias);
+        const weight = Math.max(1e-6, (1 + nearest) ** exponent);
         weights.push(weight);
         total += weight;
     }
-    let cursor = clamp01(options.roll) * total;
-    for (let i = 0; i < points.length; i += 1) {
-        cursor -= weights[i];
+    let cursor = clamp01(random()) * total;
+    for (let index = 0; index < candidates.length; index += 1) {
+        cursor -= weights[index];
         if (cursor <= 0)
-            return points[i];
+            return candidates[index];
     }
-    return points[points.length - 1];
+    return candidates[candidates.length - 1];
 }

package/dist/ai/spawnPoint.d.ts

@@ -0,0 +1,5 @@
+import type { NavPoint } from "../nav/navGrid.js";
+import { type SpawnPointDistanceBias, type SpawnPointSelectionOptions } from "./spawnDirector.js";
+export type { SpawnPointDistanceBias, SpawnPointSelectionOptions };
+/** Selects a spawn point by game intent while keeping weighting mechanics internal. */
+export declare function selectSpawnPoint(options: SpawnPointSelectionOptions): NavPoint | null;

package/dist/ai/spawnPoint.js

@@ -0,0 +1,5 @@
+import { pickSpawnPoint, } from "./spawnDirector.js";
+/** Selects a spawn point by game intent while keeping weighting mechanics internal. */
+export function selectSpawnPoint(options) {
+    return pickSpawnPoint(options);
+}

package/dist/audio/audioFalloff.d.ts

@@ -1,3 +1,4 @@
+import type { SynthPatch } from "./synth.js";
 export type AudioBusId = string;
 export type FalloffCurve = "linear" | "inverse" | "none";
 export interface AudioFalloffConfig {
@@ -15,8 +16,10 @@ export interface AudioBusDef {
 }
 export interface SoundDef {
     id: string;
-    /** Playable source — a URL/data URI the shell's Web Audio glue fetches and decodes. */
-    url: string;
+    /** Sample source — a URL/data URI the shell's Web Audio glue fetches and decodes. Provide exactly one of `url` or `synth`. */
+    url?: string;
+    /** Procedural source — a pure synth patch the shell realises on Web Audio, no file fetch. Provide exactly one of `url` or `synth`. */
+    synth?: SynthPatch;
     bus: AudioBusId;
     /** Base gain before bus/falloff multipliers. Default 1. */
     gain?: number;

package/dist/audio/music.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Named synthesised instrument. Each maps to a voice in the shell's instrument
+ * library (`@jgengine/shell/audio/musicVoices`); an unknown name falls back to a
+ * plain sine voice so a theme is never silent.
+ */
+export type MusicInstrument = "strings" | "flute" | "harp" | "horn" | "choir" | "bell" | "timpani" | "bass" | "stacc" | "pad" | "lute" | "dulcimer" | "frameDrum" | "warDrum" | "reed" | "pipe" | "squareLead" | "woodBlock" | "tinyBell" | "piano" | "shaker" | "brassStab" | "cymSwell" | "oboe";
+/** One scheduled note in a theme, positioned on the loop's quarter-note grid. */
+export interface NoteEvent {
+    /** Quarter-note position within the loop (0-based). */
+    beat: number;
+    /** MIDI note number (60 = middle C). */
+    midi: number;
+    /** Sounding length in quarter-note beats. */
+    dur: number;
+    /** Velocity 0..1. */
+    vel: number;
+    /** Which instrument voice plays it. */
+    inst: MusicInstrument;
+}
+/**
+ * A through-composed, looping music track. `events` need not be sorted; the
+ * director schedules them ahead against a fixed anchor so loops are seamless.
+ */
+export interface MusicTheme {
+    id: string;
+    /** Tempo in beats (quarter notes) per minute. */
+    bpm: number;
+    /** Loop length in 4/4 bars; the loop is `bars * 4` beats long. */
+    bars: number;
+    events: readonly NoteEvent[];
+    /**
+     * Per-theme loudness normalisation multiplied into the crossfade target, so
+     * dense and sparse themes sit at the same perceived level. Default 1.
+     */
+    trim?: number;
+}
+/** A resolved note occurrence: the source note plus its absolute onset in seconds. */
+export interface ScheduledNote {
+    event: NoteEvent;
+    /** Absolute onset in seconds, on the timeline of the `anchorSec`/window args. */
+    when: number;
+}
+/** Standard equal-temperament MIDI-to-frequency (A4 = 440 Hz at MIDI 69). */
+export declare function mtof(midi: number): number;
+/** Loop length of a theme in seconds. */
+export declare function themeLoopSeconds(theme: MusicTheme): number;
+/**
+ * Pure lookahead scheduler: every note occurrence of `theme` whose onset falls
+ * in the half-open window `(fromSec, toSec]`, given the theme's loop-zero at
+ * `anchorSec`. Handles any number of loop wraps, so a director calls it once per
+ * tick with a non-overlapping window and never double-schedules a note.
+ */
+export declare function notesInWindow(theme: MusicTheme, anchorSec: number, fromSec: number, toSec: number): ScheduledNote[];

package/dist/audio/music.js

@@ -0,0 +1,34 @@
+/** Standard equal-temperament MIDI-to-frequency (A4 = 440 Hz at MIDI 69). */
+export function mtof(midi) {
+    return 440 * 2 ** ((midi - 69) / 12);
+}
+/** Loop length of a theme in seconds. */
+export function themeLoopSeconds(theme) {
+    return (theme.bars * 4 * 60) / theme.bpm;
+}
+/**
+ * Pure lookahead scheduler: every note occurrence of `theme` whose onset falls
+ * in the half-open window `(fromSec, toSec]`, given the theme's loop-zero at
+ * `anchorSec`. Handles any number of loop wraps, so a director calls it once per
+ * tick with a non-overlapping window and never double-schedules a note.
+ */
+export function notesInWindow(theme, anchorSec, fromSec, toSec) {
+    const loop = themeLoopSeconds(theme);
+    if (loop <= 0 || toSec <= fromSec)
+        return [];
+    const spb = 60 / theme.bpm;
+    const out = [];
+    for (const event of theme.events) {
+        const onset = event.beat * spb;
+        let k = Math.max(0, Math.floor((fromSec - anchorSec - onset) / loop));
+        for (;;) {
+            const when = anchorSec + onset + k * loop;
+            if (when > toSec)
+                break;
+            if (when > fromSec)
+                out.push({ event, when });
+            k += 1;
+        }
+    }
+    return out;
+}

package/dist/audio/synth.d.ts

@@ -0,0 +1,60 @@
+/** Oscillator waveform available to a pitched synth voice. */
+export type SynthWave = "sine" | "square" | "sawtooth" | "triangle";
+/** Biquad filter shape a noise voice is coloured through. */
+export type SynthFilter = "lowpass" | "highpass" | "bandpass";
+/**
+ * A pitched oscillator voice: a 12ms linear attack to `gain`, then an
+ * exponential decay to silence across `duration`, with an optional
+ * exponential pitch slide from `freq` to `slideTo`.
+ */
+export interface ToneVoice {
+    kind: "tone";
+    /** Start frequency in Hz. */
+    freq: number;
+    /** Total voice length in seconds (the decay spans this). */
+    duration: number;
+    /** Peak gain before patch/bus scaling. Default 1. */
+    gain?: number;
+    /** Oscillator waveform. Default "sine". */
+    wave?: SynthWave;
+    /** Start offset in seconds from the cue trigger. Default 0. */
+    delay?: number;
+    /** When set, pitch ramps exponentially from `freq` to this Hz across `duration`. */
+    slideTo?: number;
+    /** Attack ramp in seconds. Default 0.012. */
+    attack?: number;
+}
+/**
+ * A filtered white-noise burst — impacts, whooshes, breath, crackle. Realised
+ * from a shared 1s noise buffer at a randomised playback rate and start offset,
+ * decaying exponentially to silence at `duration * decay`.
+ */
+export interface NoiseVoice {
+    kind: "noise";
+    /** Total voice length in seconds. */
+    duration: number;
+    /** Biquad cutoff/centre in Hz. */
+    filterFreq: number;
+    /** Peak gain before patch/bus scaling. Default 1. */
+    gain?: number;
+    /** Filter shape. Default "lowpass". */
+    filterType?: SynthFilter;
+    /** Fraction of `duration` over which the burst decays to silence. Default 0.9. */
+    decay?: number;
+    /** Start offset in seconds from the cue trigger. Default 0. */
+    delay?: number;
+}
+/** One layered voice of a synth cue. */
+export type SynthVoice = ToneVoice | NoiseVoice;
+/**
+ * A procedural sound cue: a set of voices triggered together, each with its own
+ * `delay`, summed into one one-shot. Pure serialisable data — the shell realises
+ * it on Web Audio, so the same catalog runs headless in tests with no `AudioContext`.
+ */
+export interface SynthPatch {
+    voices: readonly SynthVoice[];
+    /** Overall cue gain multiplier applied to every voice. Default 1. */
+    gain?: number;
+}
+/** Total wall-clock length of a patch in seconds — the latest voice end across all voices. */
+export declare function patchDuration(patch: SynthPatch): number;

package/dist/audio/synth.js

@@ -0,0 +1,8 @@
+/** Total wall-clock length of a patch in seconds — the latest voice end across all voices. */
+export function patchDuration(patch) {
+    let end = 0;
+    for (const voice of patch.voices) {
+        end = Math.max(end, (voice.delay ?? 0) + voice.duration);
+    }
+    return end;
+}

package/dist/authoring.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Task-first JGEngine authoring surface.
+ *
+ * Game code should begin here. Domain and runtime deep imports remain available for
+ * advanced composition, but this module intentionally exposes common authored
+ * concepts without requiring callers to understand the repository layout.
+ */
+export { defineGame, type GameDefinition, type GameDefinitionConfig, type GameLoop, type InventoryDeclaration, type PhysicsConfig, type GameServerConfig, } from "./game/defineGame.js";
+export { lootTable, type LootTableDef, type LootEntry, type Drop, } from "./game/lootTable.js";
+export { biomes, voxel, plots, tilemap, flat, environment, terrain, rain, snow, grass, ocean, building, road, type WorldFeature, } from "./world/features.js";
+export { seededRng, seededStreams } from "./random/rng.js";
+export { selectSpawnPoint, type SpawnPointSelectionOptions, type SpawnPointDistanceBias, } from "./ai/spawnPoint.js";
+export { contextVerb } from "./interaction/contextMenu.js";
+export { type ActionCodesMap } from "./input/actionBindings.js";

package/dist/authoring.js

@@ -0,0 +1,14 @@
+/**
+ * Task-first JGEngine authoring surface.
+ *
+ * Game code should begin here. Domain and runtime deep imports remain available for
+ * advanced composition, but this module intentionally exposes common authored
+ * concepts without requiring callers to understand the repository layout.
+ */
+export { defineGame, } from "./game/defineGame.js";
+export { lootTable, } from "./game/lootTable.js";
+export { biomes, voxel, plots, tilemap, flat, environment, terrain, rain, snow, grass, ocean, building, road, } from "./world/features.js";
+export { seededRng, seededStreams } from "./random/rng.js";
+export { selectSpawnPoint, } from "./ai/spawnPoint.js";
+export { contextVerb } from "./interaction/contextMenu.js";
+export {} from "./input/actionBindings.js";

package/dist/cartridge/runtime.js

@@ -409,7 +409,7 @@ export function createCartridge(spec) {
         const run = getRun(ctx);
         syncPhase(ctx, run);
         if (spec.rules.killLeaderboardStat !== undefined) {
-            ctx.game.leaderboard.track({ stat: spec.rules.killLeaderboardStat, scope: "profile" });
+            ctx.game.leaderboard?.track({ stat: spec.rules.killLeaderboardStat, scope: "profile" });
         }
         run.disposeEvents?.();
         run.disposeEvents = ctx.game.events.on("entity.died", (event) => {
@@ -428,7 +428,7 @@ export function createCartridge(spec) {
                 return;
             run.kills += 1;
             if (spec.rules.killLeaderboardStat !== undefined) {
-                ctx.game.leaderboard.increment(ctx.player.userId, spec.rules.killLeaderboardStat, { scope: "profile" });
+                ctx.game.leaderboard?.increment(ctx.player.userId, spec.rules.killLeaderboardStat, { scope: "profile" });
             }
             ctx.scene.worldItem.spawn({
                 itemId: XP_GEM_BASE_TYPE,

package/dist/combat/dotField.d.ts

@@ -0,0 +1,43 @@
+import type { BuildupProc } from "./breakMeters.js";
+/** A single damage-over-time instance: how hard, how often, and for how long. */
+export interface DotSpec {
+    /** Damage dealt at each interval. */
+    damagePerTick: number;
+    /** Milliseconds between damage ticks; clamped to a positive minimum. */
+    intervalMs: number;
+    /** Total lifetime in milliseconds; the DoT expires once its age reaches this. */
+    durationMs: number;
+    /** Label echoed on each emitted tick (bleed, poison, burn); defaults to the apply key. */
+    status?: string;
+}
+/** One damage event (or expiry marker) emitted by `DotField.tick` for the game to route through its effects. */
+export interface DotTick {
+    /** The key the DoT was applied under. */
+    id: string;
+    /** The DoT's `status` label, or its key when none was given. */
+    status: string;
+    /** Damage to route through the game's effect pipeline this frame; 0 on a bare expiry marker. */
+    damage: number;
+    /** True on the entry that ends the DoT — remove any HUD icon on it. */
+    expired: boolean;
+}
+/**
+ * A pool of timed damage-over-time instances keyed by string (`bleed`, `poison`, `burn`) — the
+ * recurring-damage counterpart to `breakMeters`' one-shot buildup procs (#536.4). `tick` advances
+ * every active DoT and returns the damage due this frame, one entry per interval crossed, so the game
+ * routes each through its own effect pipeline; a pure scheduler that never applies damage itself.
+ */
+export interface DotField {
+    /** Start or refresh a DoT under `id`; reapplying the same key restarts its age and lifetime. */
+    apply(id: string, spec: DotSpec): void;
+    /** Bridge a `breakMeters` buildup proc into recurring damage under `id`. */
+    applyProc(id: string, proc: BuildupProc, damagePerTick: number, intervalMs: number): void;
+    active(id: string): boolean;
+    cancel(id: string): void;
+    clear(): void;
+    count(): number;
+    /** Advance every active DoT; returns the damage due this frame plus an `expired` marker per finished DoT. */
+    tick(dtSeconds: number): DotTick[];
+}
+/** Builds an empty {@link DotField}; `apply` DoTs onto it and drain damage each frame with `tick`. */
+export declare function createDotField(): DotField;

package/dist/combat/dotField.js

@@ -0,0 +1,48 @@
+/** Builds an empty {@link DotField}; `apply` DoTs onto it and drain damage each frame with `tick`. */
+export function createDotField() {
+    const dots = new Map();
+    return {
+        apply(id, spec) {
+            dots.set(id, {
+                status: spec.status ?? id,
+                damagePerTick: spec.damagePerTick,
+                intervalMs: Math.max(1, spec.intervalMs),
+                durationMs: Math.max(0, spec.durationMs),
+                ageMs: 0,
+                ticksEmitted: 0,
+            });
+        },
+        applyProc(id, proc, damagePerTick, intervalMs) {
+            this.apply(id, { damagePerTick, intervalMs, durationMs: proc.durationMs, status: proc.status });
+        },
+        active: (id) => dots.has(id),
+        cancel: (id) => void dots.delete(id),
+        clear: () => dots.clear(),
+        count: () => dots.size,
+        tick(dtSeconds) {
+            if (dtSeconds <= 0)
+                return [];
+            const dtMs = dtSeconds * 1000;
+            const emitted = [];
+            for (const [id, dot] of dots) {
+                dot.ageMs += dtMs;
+                const activeMs = Math.min(dot.ageMs, dot.durationMs);
+                const dueTicks = Math.floor(activeMs / dot.intervalMs);
+                let last = null;
+                while (dot.ticksEmitted < dueTicks) {
+                    dot.ticksEmitted += 1;
+                    last = { id, status: dot.status, damage: dot.damagePerTick, expired: false };
+                    emitted.push(last);
+                }
+                if (dot.ageMs >= dot.durationMs) {
+                    dots.delete(id);
+                    if (last !== null)
+                        last.expired = true;
+                    else
+                        emitted.push({ id, status: dot.status, damage: 0, expired: true });
+                }
+            }
+            return emitted;
+        },
+    };
+}

package/dist/combat/projectiles.d.ts

@@ -1,6 +1,6 @@
 import type { BallisticSweep } from "../physics/ballisticSweep.js";
 import type { EntityPosition } from "../scene/entityStore.js";
-import type { EntityColliderSet } from "../scene/colliders.js";
+import { type EntityColliderSet } from "../scene/colliders.js";
 import { type SceneRaycastApi } from "../scene/sceneRaycast.js";
 import type { Aim } from "../scene/spatial.js";
 import type { CombatSpatialDeps, EffectResult, EffectSystem, EffectVia } from "./effects.js";
@@ -10,7 +10,7 @@ export interface ProjectileShotInput {
     via: EffectVia;
     aim: Aim;
     effect: string;
-    /** Defaults to `{ kind: "legacy" }` — aim.origin or shooter position. */
+    /** Defaults to `{ kind: "eye" }` — aim.origin when given, else shooter position at eye height. */
     originPolicy?: ShotOriginPolicy;
 }
 export interface EntityRaycastHit {

package/dist/combat/projectiles.js

@@ -1,3 +1,4 @@
+import { defaultEntityColliders, resolveColliders } from "../scene/colliders.js";
 import { createSceneRaycast, firstImpact, hitsUntilBlocked, } from "../scene/sceneRaycast.js";
 import { aimDirection, aimSpreadDeg, resolveShot, } from "./shotOrigin.js";
 const DEFAULT_RANGE = 100;
@@ -70,7 +71,7 @@ export function createProjectileSystem(deps) {
     const shots = new Map();
     let shotCounter = 0;
     const now = deps.now ?? (() => Date.now());
-    const defaultPolicy = deps.defaultOriginPolicy ?? { kind: "legacy" };
+    const defaultPolicy = deps.defaultOriginPolicy ?? { kind: "eye" };
     function itemStat(via, stat) {
         return via.item === undefined ? null : deps.getStat(via.item, stat);
     }
@@ -84,6 +85,7 @@ export function createProjectileSystem(deps) {
         return resolveShot({
             positionOf: deps.spatial.positionOf,
             rotationYOf: deps.rotationYOf,
+            collidersOf: deps.entityCollidersOf,
         }, from, aim, policy ?? defaultPolicy);
     }
     const internalSceneRaycast = deps.sceneRaycast ??
@@ -149,15 +151,26 @@ export function createProjectileSystem(deps) {
                 if (hit.targetKind === "entity" && spreadRad > 0) {
                     const position = deps.spatial.positionOf(hit.instanceId);
                     if (position !== undefined) {
-                        const dx = position[0] - origin[0];
-                        const dy = position[1] - origin[1];
-                        const dz = position[2] - origin[2];
+                        const colliders = resolveColliders(deps.entityCollidersOf?.(hit.instanceId) ?? defaultEntityColliders());
+                        const collider = colliders.find((candidate) => candidate.name === hit.colliderName) ?? colliders[0];
+                        const localOffset = collider?.shape.offset ?? [0, 0, 0];
+                        const slack = collider === undefined
+                            ? BASE_HIT_RADIUS
+                            : collider.shape.kind === "sphere"
+                                ? collider.shape.radius
+                                : Math.hypot(...collider.shape.halfExtents);
+                        const rotationY = deps.rotationYOf?.(hit.instanceId) ?? 0;
+                        const cos = Math.cos(rotationY);
+                        const sin = Math.sin(rotationY);
+                        const dx = position[0] + localOffset[0] * cos + localOffset[2] * sin - origin[0];
+                        const dy = position[1] + localOffset[1] - origin[1];
+                        const dz = position[2] - localOffset[0] * sin + localOffset[2] * cos - origin[2];
                         const along = dx * direction[0] + dy * direction[1] + dz * direction[2];
                         const px = dx - direction[0] * along;
                         const py = dy - direction[1] * along;
                         const pz = dz - direction[2] * along;
                         const perpendicular = Math.sqrt(px * px + py * py + pz * pz);
-                        if (perpendicular > 0.5 + Math.tan(spreadRad) * along)
+                        if (perpendicular > slack + Math.tan(spreadRad) * along)
                             continue;
                     }
                 }

package/dist/combat/regenShield.d.ts

@@ -0,0 +1,35 @@
+/** Tuning for `createRegenShield`: pool size, refill rate, and the post-damage grace period. */
+export interface RegenShieldConfig {
+    max: number;
+    /** Points restored per second once the post-damage grace period has elapsed. */
+    regenPerSecond: number;
+    /** Grace period after the last damage before regen resumes. */
+    regenDelayMs: number;
+    /** Starting value; defaults to `max` (full). */
+    current?: number;
+}
+/**
+ * A shield pool that stops regenerating for `regenDelayMs` after every hit, then refills at
+ * `regenPerSecond` — the delayed-regen primitive that replaces snapshot-comparing stat values per
+ * tick to detect "damage taken" (#536.3). `damage` resets the grace timer; `tick` counts it down and
+ * regenerates once it elapses.
+ */
+export interface RegenShield {
+    current(): number;
+    max(): number;
+    setMax(value: number): void;
+    fraction(): number;
+    isFull(): boolean;
+    isBroken(): boolean;
+    /** True while the post-damage grace period is suppressing regen. */
+    suppressed(): boolean;
+    /** Absorb `amount` and reset the regen grace timer; returns damage that got through (0 while the shield holds). */
+    damage(amount: number): number;
+    /** Add `amount` without touching the regen timer (a pickup or scripted refill). */
+    restore(amount: number): void;
+    set(value: number): void;
+    /** Advance time: count down the grace period, then regenerate once it has elapsed. */
+    tick(dtSeconds: number): void;
+}
+/** Builds a {@link RegenShield} that suppresses regen for `regenDelayMs` after each hit. */
+export declare function createRegenShield(config: RegenShieldConfig): RegenShield;

package/dist/combat/regenShield.js

@@ -0,0 +1,45 @@
+/** Builds a {@link RegenShield} that suppresses regen for `regenDelayMs` after each hit. */
+export function createRegenShield(config) {
+    let max = Math.max(0, config.max);
+    const regenPerSecond = Math.max(0, config.regenPerSecond);
+    const regenDelayMs = Math.max(0, config.regenDelayMs);
+    function clamp(value, ceiling) {
+        return Math.max(0, Math.min(ceiling, value));
+    }
+    let current = clamp(config.current ?? max, max);
+    let sinceDamageMs = regenDelayMs;
+    return {
+        current: () => current,
+        max: () => max,
+        setMax(value) {
+            max = Math.max(0, value);
+            current = clamp(current, max);
+        },
+        fraction: () => (max <= 0 ? 0 : current / max),
+        isFull: () => current >= max,
+        isBroken: () => current <= 0,
+        suppressed: () => sinceDamageMs < regenDelayMs,
+        damage(amount) {
+            if (amount <= 0)
+                return 0;
+            sinceDamageMs = 0;
+            const overflow = Math.max(0, amount - current);
+            current = clamp(current - amount, max);
+            return overflow;
+        },
+        restore(amount) {
+            if (amount > 0)
+                current = clamp(current + amount, max);
+        },
+        set(value) {
+            current = clamp(value, max);
+        },
+        tick(dtSeconds) {
+            if (dtSeconds <= 0)
+                return;
+            sinceDamageMs += dtSeconds * 1000;
+            if (sinceDamageMs >= regenDelayMs)
+                current = clamp(current + regenPerSecond * dtSeconds, max);
+        },
+    };
+}