@jgengine/core 0.8.0 → 0.10.0

package/dist/ui/hudLayout.js

@@ -0,0 +1,207 @@
+export function isPanelDraggable(state, id) {
+    return state.panels[id] !== undefined && (state.editing || !state.locked);
+}
+export const HUD_ANCHOR_FRACTIONS = {
+    "top-left": { fx: 0, fy: 0 },
+    top: { fx: 0.5, fy: 0 },
+    "top-right": { fx: 1, fy: 0 },
+    left: { fx: 0, fy: 0.5 },
+    center: { fx: 0.5, fy: 0.5 },
+    right: { fx: 1, fy: 0.5 },
+    "bottom-left": { fx: 0, fy: 1 },
+    bottom: { fx: 0.5, fy: 1 },
+    "bottom-right": { fx: 1, fy: 1 },
+};
+const HUD_ANCHORS = Object.keys(HUD_ANCHOR_FRACTIONS);
+export function isHudAnchor(value) {
+    return typeof value === "string" && value in HUD_ANCHOR_FRACTIONS;
+}
+export function anchoredPlacement(anchor, inset) {
+    const { fx, fy } = HUD_ANCHOR_FRACTIONS[anchor];
+    return {
+        anchor,
+        dx: fx === 1 ? -inset.x : inset.x,
+        dy: fy === 1 ? -inset.y : inset.y,
+    };
+}
+export function nearestAnchor(rect, viewport) {
+    const cx = viewport.width > 0 ? (rect.x + rect.width / 2) / viewport.width : 0.5;
+    const cy = viewport.height > 0 ? (rect.y + rect.height / 2) / viewport.height : 0.5;
+    let best = "center";
+    let bestDist = Infinity;
+    for (const anchor of HUD_ANCHORS) {
+        const { fx, fy } = HUD_ANCHOR_FRACTIONS[anchor];
+        const dist = (cx - fx) * (cx - fx) + (cy - fy) * (cy - fy);
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = anchor;
+        }
+    }
+    return best;
+}
+export function clampRect(rect, viewport) {
+    return {
+        x: Math.max(0, Math.min(rect.x, viewport.width - rect.width)),
+        y: Math.max(0, Math.min(rect.y, viewport.height - rect.height)),
+        width: rect.width,
+        height: rect.height,
+    };
+}
+export function placementFromRect(rect, viewport, snap = 1) {
+    const clamped = clampRect(rect, viewport);
+    const anchor = nearestAnchor(clamped, viewport);
+    const { fx, fy } = HUD_ANCHOR_FRACTIONS[anchor];
+    const step = snap > 0 ? snap : 1;
+    const dx = clamped.x + fx * clamped.width - fx * viewport.width;
+    const dy = clamped.y + fy * clamped.height - fy * viewport.height;
+    return {
+        anchor,
+        dx: Math.round(dx / step) * step,
+        dy: Math.round(dy / step) * step,
+    };
+}
+export function rectFromPlacement(placement, size, viewport) {
+    const { fx, fy } = HUD_ANCHOR_FRACTIONS[placement.anchor];
+    return {
+        x: fx * viewport.width + placement.dx - fx * size.width,
+        y: fy * viewport.height + placement.dy - fy * size.height,
+        width: size.width,
+        height: size.height,
+    };
+}
+function parseSerialized(raw) {
+    const out = new Map();
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return out;
+    }
+    if (typeof data !== "object" || data === null)
+        return out;
+    const panels = data.panels;
+    if (typeof panels !== "object" || panels === null)
+        return out;
+    for (const [id, value] of Object.entries(panels)) {
+        if (typeof value !== "object" || value === null)
+            continue;
+        const { anchor, dx, dy } = value;
+        if (!isHudAnchor(anchor))
+            continue;
+        if (typeof dx !== "number" || !Number.isFinite(dx))
+            continue;
+        if (typeof dy !== "number" || !Number.isFinite(dy))
+            continue;
+        out.set(id, { anchor, dx, dy });
+    }
+    return out;
+}
+export function createHudLayout(options) {
+    const snap = options?.snap ?? 1;
+    const defaults = new Map();
+    const pending = new Map();
+    let topZ = 0;
+    let state = { panels: {}, locked: options?.locked ?? true, editing: false };
+    const listeners = new Set();
+    const emit = () => {
+        for (const listener of [...listeners])
+            listener(state);
+    };
+    const setPanel = (panel) => {
+        state = { ...state, panels: { ...state.panels, [panel.id]: panel } };
+    };
+    return {
+        getState: () => state,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        register(id, placement) {
+            defaults.set(id, placement);
+            if (state.panels[id] !== undefined)
+                return;
+            const override = pending.get(id);
+            setPanel({
+                id,
+                placement: override ?? placement,
+                z: ++topZ,
+                moved: override !== undefined,
+            });
+        },
+        move(id, rect, viewport) {
+            const panel = state.panels[id];
+            if (panel === undefined)
+                return;
+            const placement = placementFromRect(rect, viewport, snap);
+            setPanel({ ...panel, placement, moved: true });
+            emit();
+        },
+        bringToFront(id) {
+            const panel = state.panels[id];
+            if (panel === undefined || panel.z === topZ)
+                return;
+            setPanel({ ...panel, z: ++topZ });
+            emit();
+        },
+        setLocked(locked) {
+            if (state.locked === locked)
+                return;
+            state = { ...state, locked };
+            emit();
+        },
+        setEditing(editing) {
+            if (state.editing === editing)
+                return;
+            state = { ...state, editing };
+            emit();
+        },
+        reset(id) {
+            const ids = id === undefined ? Object.keys(state.panels) : [id];
+            let changed = false;
+            for (const panelId of ids) {
+                pending.delete(panelId);
+                const panel = state.panels[panelId];
+                const fallback = defaults.get(panelId);
+                if (panel === undefined || fallback === undefined || !panel.moved)
+                    continue;
+                setPanel({ ...panel, placement: fallback, moved: false });
+                changed = true;
+            }
+            if (changed)
+                emit();
+        },
+        serialize() {
+            const panels = {};
+            for (const panel of Object.values(state.panels)) {
+                if (panel.moved)
+                    panels[panel.id] = panel.placement;
+            }
+            for (const [id, placement] of pending) {
+                if (state.panels[id] === undefined)
+                    panels[id] = placement;
+            }
+            const data = { v: 1, panels };
+            return JSON.stringify(data);
+        },
+        hydrate(raw) {
+            if (raw === null || raw === undefined || raw === "")
+                return;
+            const parsed = parseSerialized(raw);
+            if (parsed.size === 0)
+                return;
+            let changed = false;
+            for (const [id, placement] of parsed) {
+                const panel = state.panels[id];
+                if (panel === undefined) {
+                    pending.set(id, placement);
+                    continue;
+                }
+                setPanel({ ...panel, placement, moved: true });
+                changed = true;
+            }
+            if (changed)
+                emit();
+        },
+    };
+}

package/dist/ui/hudScale.d.ts

@@ -0,0 +1,44 @@
+import type { HudRect, HudSize } from "./hudLayout.js";
+/** Where a game is meant to be played. `"web"` alone keeps today's desktop-first HUD; adding `"mobile"` turns on design-resolution fit scaling on compact displays. */
+export type HudPlatform = "web" | "mobile";
+/**
+ * Design-resolution fit for the HUD surface. The game authors its UI against
+ * `designSize`; on smaller viewports the whole HUD scales down by the limiting
+ * axis ratio, clamped to `[minScale, maxScale]`, so panels keep their layout
+ * and simply shrink instead of overflowing.
+ */
+export interface HudFitConfig {
+    designSize?: HudSize;
+    /** Floor for the computed scale — below this, shrinking further makes text unreadable. Default 0.4. */
+    minScale?: number;
+    /** Ceiling for the computed scale. Default 1 (never upscale past authored size). */
+    maxScale?: number;
+}
+/** Per-game HUD viewport declaration carried on `PlayableGame.hudFit`; `mobile` overrides the fit on compact displays so the owner can tune the phone layout separately. */
+export interface HudViewportConfig extends HudFitConfig {
+    mobile?: HudFitConfig;
+}
+export declare const DEFAULT_HUD_DESIGN_SIZE: HudSize;
+export declare const DEFAULT_HUD_MIN_SCALE = 0.4;
+export declare const DEFAULT_HUD_MAX_SCALE = 1;
+export declare function resolveHudFit(config: HudViewportConfig | undefined, mobile: boolean): Required<HudFitConfig>;
+/**
+ * The one scaling rule for every display: the ratio of the live viewport to
+ * the authored design size along the limiting axis, clamped. 1 on a viewport
+ * at or above design size; smoothly below 1 down to `minScale` on phones.
+ */
+export declare function hudScaleForViewport(fit: Required<HudFitConfig>, viewport: HudSize): number;
+export interface HudOverflow {
+    id: string;
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/** Non-null when any edge of `rect` falls outside `viewport` by more than `tolerance` px; each field is the overflow distance past that edge (0 when inside). */
+export declare function rectOverflow(rect: HudRect, viewport: HudSize, tolerance?: number): Omit<HudOverflow, "id"> | null;
+/** Every panel rect that escapes the viewport — the data behind the HUD overflow gate. */
+export declare function overflowingPanels(panels: readonly {
+    id: string;
+    rect: HudRect;
+}[], viewport: HudSize, tolerance?: number): HudOverflow[];

package/dist/ui/hudScale.js

@@ -0,0 +1,55 @@
+export const DEFAULT_HUD_DESIGN_SIZE = { width: 1600, height: 900 };
+export const DEFAULT_HUD_MIN_SCALE = 0.4;
+export const DEFAULT_HUD_MAX_SCALE = 1;
+export function resolveHudFit(config, mobile) {
+    const base = {
+        designSize: config?.designSize ?? DEFAULT_HUD_DESIGN_SIZE,
+        minScale: config?.minScale ?? DEFAULT_HUD_MIN_SCALE,
+        maxScale: config?.maxScale ?? DEFAULT_HUD_MAX_SCALE,
+    };
+    if (!mobile || config?.mobile === undefined)
+        return base;
+    return {
+        designSize: config.mobile.designSize ?? base.designSize,
+        minScale: config.mobile.minScale ?? base.minScale,
+        maxScale: config.mobile.maxScale ?? base.maxScale,
+    };
+}
+/**
+ * The one scaling rule for every display: the ratio of the live viewport to
+ * the authored design size along the limiting axis, clamped. 1 on a viewport
+ * at or above design size; smoothly below 1 down to `minScale` on phones.
+ */
+export function hudScaleForViewport(fit, viewport) {
+    if (!Number.isFinite(viewport.width) ||
+        !Number.isFinite(viewport.height) ||
+        viewport.width <= 0 ||
+        viewport.height <= 0 ||
+        fit.designSize.width <= 0 ||
+        fit.designSize.height <= 0) {
+        return 1;
+    }
+    const ratio = Math.min(viewport.width / fit.designSize.width, viewport.height / fit.designSize.height);
+    return Math.min(fit.maxScale, Math.max(fit.minScale, ratio));
+}
+/** Non-null when any edge of `rect` falls outside `viewport` by more than `tolerance` px; each field is the overflow distance past that edge (0 when inside). */
+export function rectOverflow(rect, viewport, tolerance = 1.5) {
+    const left = Math.max(0, -rect.x);
+    const top = Math.max(0, -rect.y);
+    const right = Math.max(0, rect.x + rect.width - viewport.width);
+    const bottom = Math.max(0, rect.y + rect.height - viewport.height);
+    if (left <= tolerance && top <= tolerance && right <= tolerance && bottom <= tolerance)
+        return null;
+    const round = (n) => Math.round(n * 10) / 10;
+    return { left: round(left), top: round(top), right: round(right), bottom: round(bottom) };
+}
+/** Every panel rect that escapes the viewport — the data behind the HUD overflow gate. */
+export function overflowingPanels(panels, viewport, tolerance = 1.5) {
+    const out = [];
+    for (const panel of panels) {
+        const overflow = rectOverflow(panel.rect, viewport, tolerance);
+        if (overflow !== null)
+            out.push({ id: panel.id, ...overflow });
+    }
+    return out;
+}

package/dist/ui/orientation.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The game-level orientation contract. A game declares how it supports phone
+ * orientations; the shell resolves that against the live orientation to decide
+ * whether to show a dismissible rotate hint (advisory) or a full-screen gate
+ * that blocks gameplay until the device is turned (required).
+ */
+/** How a game supports a phone orientation on coarse-pointer displays. */
+export type MobileOrientationRule = "any" | "portrait" | "landscape" | "portrait-required" | "landscape-required" | "unsupported";
+/** Object form of the `orientation` field: the strict per-platform contract. */
+export interface GameOrientationConfig {
+    /** Orientation contract on coarse-pointer / phone displays. Default `"any"`. */
+    mobile?: MobileOrientationRule;
+}
+/**
+ * The `orientation` field of a game definition. Legacy shorthand `"landscape"`
+ * / `"portrait"` stays advisory (a dismissible rotate hint, never a gate). The
+ * object form `{ mobile: "landscape-required" }` is the strict contract that
+ * blocks gameplay behind the rotate screen until the device is turned.
+ */
+export type GameOrientation = "landscape" | "portrait" | GameOrientationConfig;
+/** A concrete device orientation. */
+export type LayoutOrientation = "portrait" | "landscape";
+/** The resolved orientation contract for a platform: whether it's supported, gated, or merely preferred. */
+export interface OrientationRequirement {
+    /** False only for `"unsupported"` — the game declares it isn't built for phones. */
+    supported: boolean;
+    /** Orientation gameplay is hard-gated to; `null` when there is no gate. */
+    required: LayoutOrientation | null;
+    /** Orientation the game reads best in; drives an advisory hint when not required. */
+    preferred: LayoutOrientation | null;
+}
+/** Normalize the `orientation` field (legacy string or object) to a single mobile rule. */
+export declare function resolveMobileOrientationRule(orientation: GameOrientation | undefined): MobileOrientationRule;
+/** Resolve the game's orientation declaration into a concrete requirement for a platform. Desktop is always unconstrained. */
+export declare function resolveOrientationRequirement(orientation: GameOrientation | undefined, platform: "mobile" | "desktop"): OrientationRequirement;
+/** The rotate gate blocks gameplay: a hard requirement (or `unsupported`) the live orientation doesn't satisfy. */
+export declare function orientationGateActive(requirement: OrientationRequirement, liveOrientation: LayoutOrientation): boolean;
+/** An advisory rotate hint applies: a preference (not a hard gate) the live orientation doesn't satisfy. */
+export declare function orientationHintActive(requirement: OrientationRequirement, liveOrientation: LayoutOrientation): boolean;

package/dist/ui/orientation.js

@@ -0,0 +1,49 @@
+/**
+ * The game-level orientation contract. A game declares how it supports phone
+ * orientations; the shell resolves that against the live orientation to decide
+ * whether to show a dismissible rotate hint (advisory) or a full-screen gate
+ * that blocks gameplay until the device is turned (required).
+ */
+/** Normalize the `orientation` field (legacy string or object) to a single mobile rule. */
+export function resolveMobileOrientationRule(orientation) {
+    if (orientation === undefined)
+        return "any";
+    if (orientation === "landscape")
+        return "landscape";
+    if (orientation === "portrait")
+        return "portrait";
+    return orientation.mobile ?? "any";
+}
+/** Resolve the game's orientation declaration into a concrete requirement for a platform. Desktop is always unconstrained. */
+export function resolveOrientationRequirement(orientation, platform) {
+    if (platform === "desktop")
+        return { supported: true, required: null, preferred: null };
+    const rule = resolveMobileOrientationRule(orientation);
+    switch (rule) {
+        case "unsupported":
+            return { supported: false, required: null, preferred: null };
+        case "landscape-required":
+            return { supported: true, required: "landscape", preferred: "landscape" };
+        case "portrait-required":
+            return { supported: true, required: "portrait", preferred: "portrait" };
+        case "landscape":
+            return { supported: true, required: null, preferred: "landscape" };
+        case "portrait":
+            return { supported: true, required: null, preferred: "portrait" };
+        case "any":
+            return { supported: true, required: null, preferred: null };
+    }
+}
+/** The rotate gate blocks gameplay: a hard requirement (or `unsupported`) the live orientation doesn't satisfy. */
+export function orientationGateActive(requirement, liveOrientation) {
+    if (!requirement.supported)
+        return true;
+    return requirement.required !== null && requirement.required !== liveOrientation;
+}
+/** An advisory rotate hint applies: a preference (not a hard gate) the live orientation doesn't satisfy. */
+export function orientationHintActive(requirement, liveOrientation) {
+    return (requirement.supported &&
+        requirement.required === null &&
+        requirement.preferred !== null &&
+        requirement.preferred !== liveOrientation);
+}

package/dist/ui/swingTimer.d.ts

@@ -0,0 +1,42 @@
+/** The local player's auto-attack state for one frame. `swingTimer` counts DOWN in seconds to 0 (= a swing lands). */
+export interface SwingPlayerInput {
+    autoAttack: boolean;
+    swingTimer: number;
+    weapon: {
+        speed: number;
+    };
+}
+/** The current target, or the fields the bar needs from it. */
+export interface SwingTargetInput {
+    dead: boolean;
+    /** Entity kind; an `"object"` target (a node/chest) never shows a swing bar. */
+    kind: string;
+}
+/** Whether the bar shows a "ready" label or the seconds-remaining countdown. */
+export type SwingLabelKind = "ready" | "seconds";
+/** One frame of swing-bar state plus the cursor (`nextPeriod`/`nextTimer`) the caller carries back into the next call. */
+export interface SwingTimerState {
+    /** Whether the bar should render at all. */
+    visible: boolean;
+    /** Fill 0..1, growing toward 1 as the next swing nears. */
+    frac: number;
+    /** True the moment the swing is ready to land. */
+    ready: boolean;
+    labelKind: SwingLabelKind;
+    /** Seconds remaining until the next swing (0 when ready). */
+    seconds: number;
+    /** Recovered swing period this frame — pass back as `prevPeriod` next call. */
+    nextPeriod: number;
+    /** This frame's timer — pass back as `prevTimer` next call to detect the reset edge. */
+    nextTimer: number;
+}
+/** Threshold above which a timer jump is treated as a fresh swing (period reset). */
+export declare const SWING_EDGE_EPSILON = 0.0001;
+/**
+ * Pure swing-timer bar state — no hidden state, no clock, no DOM. The caller
+ * threads `prevPeriod`/`prevTimer` back each frame. The period is recovered on
+ * the reset edge (when `swingTimer` jumps up = a new swing began) as
+ * `max(swingTimer, weapon.speed)`, so the fill is correct even without knowing
+ * the weapon's exact cadence. Hidden unless auto-attacking a live, non-object target.
+ */
+export declare function swingTimerState(player: SwingPlayerInput, target: SwingTargetInput | null, prevPeriod: number, prevTimer: number): SwingTimerState;

package/dist/ui/swingTimer.js

@@ -0,0 +1,38 @@
+/** Threshold above which a timer jump is treated as a fresh swing (period reset). */
+export const SWING_EDGE_EPSILON = 1e-4;
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+const HIDDEN = {
+    visible: false,
+    frac: 0,
+    ready: false,
+    labelKind: "seconds",
+    seconds: 0,
+};
+/**
+ * Pure swing-timer bar state — no hidden state, no clock, no DOM. The caller
+ * threads `prevPeriod`/`prevTimer` back each frame. The period is recovered on
+ * the reset edge (when `swingTimer` jumps up = a new swing began) as
+ * `max(swingTimer, weapon.speed)`, so the fill is correct even without knowing
+ * the weapon's exact cadence. Hidden unless auto-attacking a live, non-object target.
+ */
+export function swingTimerState(player, target, prevPeriod, prevTimer) {
+    const swingTimer = player.swingTimer;
+    if (!player.autoAttack || target === null || target.dead || target.kind === "object") {
+        return { ...HIDDEN, nextPeriod: prevPeriod, nextTimer: swingTimer };
+    }
+    const isResetEdge = swingTimer > prevTimer + SWING_EDGE_EPSILON || prevPeriod <= 0;
+    const period = isResetEdge ? Math.max(swingTimer, player.weapon.speed) : prevPeriod;
+    const frac = period <= 0 ? 1 : clamp01(1 - swingTimer / period);
+    const ready = swingTimer <= 0;
+    return {
+        visible: true,
+        frac,
+        ready,
+        labelKind: ready ? "ready" : "seconds",
+        seconds: Math.max(0, swingTimer),
+        nextPeriod: period,
+        nextTimer: swingTimer,
+    };
+}

package/dist/visibility/assetStreaming.d.ts

@@ -0,0 +1,66 @@
+import type { StreamingSettings } from "./settings.js";
+import type { VisibilityStats } from "./diagnostics.js";
+export type AssetLoadState = "queued" | "loading" | "loaded" | "unloaded" | "error";
+export interface AssetLoadResult {
+    /** Approximate resident size, used for the memory budget and small-asset resident policy. */
+    readonly bytes?: number;
+    /** Opaque handle to the loaded resource (texture, mesh, buffer). */
+    readonly value?: unknown;
+}
+export interface CancelSignal {
+    readonly cancelled: boolean;
+}
+export interface AssetStreamingOptions {
+    /** Async loader. Must honor `signal.cancelled` and avoid committing work when it flips true. */
+    readonly load: (assetId: string, signal: CancelSignal) => Promise<AssetLoadResult>;
+    /** Release GPU/CPU resources for an asset. */
+    readonly unload?: (assetId: string) => void;
+    readonly settings?: Partial<StreamingSettings>;
+    readonly now?: () => number;
+}
+export interface AssetRecord {
+    readonly id: string;
+    state: AssetLoadState;
+    bytes: number;
+    priority: number;
+    refCount: number;
+    pinned: boolean;
+    lastActiveMs: number;
+    value: unknown;
+}
+export interface StreamingStats {
+    queued: number;
+    loading: number;
+    loaded: number;
+    unloaded: number;
+    errored: number;
+    inFlight: number;
+    cancelled: number;
+    bytes: number;
+}
+export interface AssetStreamingSystem {
+    /** Demand an asset (near/in view). Deduplicated — an already loaded/loading/queued asset is never re-fetched concurrently. */
+    request(assetId: string, priority?: number): void;
+    /** Shared ownership by an active object. A retained asset (refCount > 0) is never auto-unloaded. */
+    retain(assetId: string): void;
+    release(assetId: string): void;
+    /** Pin resident regardless of distance/refcount/scene. */
+    pin(assetId: string): void;
+    unpin(assetId: string): void;
+    /** Refresh the "last needed" timestamp used by the grace-period unload. */
+    markActive(assetId: string): void;
+    /** Advance one frame: start up to the load budget, evict past-grace assets up to the unload budget. */
+    tick(dt: number): void;
+    /** Cancel an in-flight or queued request that is no longer needed. */
+    cancel(assetId: string): void;
+    stateOf(assetId: string): AssetLoadState | undefined;
+    isLoaded(assetId: string): boolean;
+    record(assetId: string): AssetRecord | undefined;
+    stats(): StreamingStats;
+    /** Merge asset counters into a per-frame VisibilityStats. */
+    applyTo(stats: VisibilityStats): void;
+    /** Resolve once every in-flight load settles — for deterministic tests. */
+    settle(): Promise<void>;
+    clear(): void;
+}
+export declare function createAssetStreamingSystem(options: AssetStreamingOptions): AssetStreamingSystem;