@jgengine/core 0.10.0 → 0.12.0

package/dist/render/lookPreset.d.ts

@@ -0,0 +1,41 @@
+import type { BackdropConfig, LightingConfig } from "../game/playableGame.js";
+import type { SkyEnvironmentConfig } from "../world/features.js";
+import type { PostProcessingConfig } from "./postProcessing.js";
+/**
+ * Named default-look preset composing the existing lighting/sky/fog/post knobs into one field.
+ * `"cinematic"` (the default when unset) draws a scene lit like a shipped game — a real day sky
+ * with a view-following shadow-casting sun + hemisphere fill, a network-free image-based-lighting
+ * environment so PBR surfaces catch soft reflections, and a tuned tone-map/bloom/AO/vignette post
+ * stack. `"flat"` opts out of the sky/IBL/post rig to the bare ambient+directional default (pre-#773).
+ * The upgraded default primitive materials — tuned roughness/metalness plus subtle procedural surface
+ * detail so un-modeled boxes/capsules stop reading as flat plastic — apply under both presets.
+ * @capability default-look one field that lights a scene like a shipped game (opt out with "flat")
+ */
+export type LookPreset = "cinematic" | "flat";
+/** Explicit graphics knobs a game may set; the preset only fills the ones left undefined. */
+export interface GameLookInput {
+    look?: LookPreset;
+    lighting?: LightingConfig;
+    backdrop?: BackdropConfig;
+    postProcessing?: PostProcessingConfig;
+    /** True when the world already declares its own sky — the preset then leaves the sky to the world. */
+    hasWorldSky?: boolean;
+}
+/** Concrete lighting/backdrop/post the shell renders after the preset has filled unset knobs. */
+export interface ResolvedGameLook {
+    lighting?: LightingConfig;
+    backdrop?: BackdropConfig;
+    postProcessing?: PostProcessingConfig;
+}
+/** A static day sky: a real dome plus the shell's view-following shadow-casting sun and hemisphere fill. */
+export declare const CINEMATIC_SKY: SkyEnvironmentConfig;
+/** Tuned tone-map + bloom + gentle SSAO + vignette/grade stack — the shipped-game post look. */
+export declare const CINEMATIC_POST_PROCESSING: PostProcessingConfig;
+/**
+ * Expand a game's `look` into concrete lighting/backdrop/post. The default is `"cinematic"`, so a
+ * scene reads lit-like-a-game out of the box; `"flat"` passes the explicit knobs through untouched.
+ * Anything the game authored wins — the preset only fills unset knobs, and it never adds a sky when
+ * the world already owns one (so the sky's tuned sun/hemisphere serve as the lighting rig).
+ * @capability resolve-game-look expand a look preset into concrete lighting/backdrop/post knobs
+ */
+export declare function resolveGameLook(input: GameLookInput): ResolvedGameLook;

package/dist/render/lookPreset.js

@@ -0,0 +1,29 @@
+/** A static day sky: a real dome plus the shell's view-following shadow-casting sun and hemisphere fill. */
+export const CINEMATIC_SKY = { preset: "day" };
+/** Tuned tone-map + bloom + gentle SSAO + vignette/grade stack — the shipped-game post look. */
+export const CINEMATIC_POST_PROCESSING = {
+    toneMapping: "aces",
+    bloom: {},
+    ao: { intensity: 1.4 },
+    grade: {},
+};
+/**
+ * Expand a game's `look` into concrete lighting/backdrop/post. The default is `"cinematic"`, so a
+ * scene reads lit-like-a-game out of the box; `"flat"` passes the explicit knobs through untouched.
+ * Anything the game authored wins — the preset only fills unset knobs, and it never adds a sky when
+ * the world already owns one (so the sky's tuned sun/hemisphere serve as the lighting rig).
+ * @capability resolve-game-look expand a look preset into concrete lighting/backdrop/post knobs
+ */
+export function resolveGameLook(input) {
+    const look = input.look ?? "cinematic";
+    if (look === "flat") {
+        return { lighting: input.lighting, backdrop: input.backdrop, postProcessing: input.postProcessing };
+    }
+    const sky = input.backdrop?.sky ?? (input.hasWorldSky === true ? undefined : CINEMATIC_SKY);
+    const backdrop = sky === input.backdrop?.sky ? input.backdrop : { ...input.backdrop, sky };
+    return {
+        lighting: input.lighting,
+        backdrop,
+        postProcessing: input.postProcessing ?? CINEMATIC_POST_PROCESSING,
+    };
+}

package/dist/render/postProcessing.d.ts

@@ -34,6 +34,17 @@ export interface GradeConfig {
     vignette?: number;
     /** Animated film-grain amplitude. Default 0.012. */
     grain?: number;
+    /** Chromatic-aberration RGB split, in fractions of the frame (~0..0.01), scaled toward the edges. Default 0 (off). */
+    chromaticAberration?: number;
+}
+/** Depth-of-field (bokeh) stage — throws the fore/background out of focus around a focus distance. */
+export interface DofConfig {
+    /** Focus distance from the camera in world units. Default 18. */
+    focus?: number;
+    /** Aperture — larger blurs a shallower slice more aggressively. Default 0.00025. */
+    aperture?: number;
+    /** Maximum blur radius, 0..1. Default 0.01. */
+    maxBlur?: number;
 }
 /**
  * Declarative post-processing chain (RenderPass → AO → Bloom → tone-map output →
@@ -52,5 +63,14 @@ export interface PostProcessingConfig {
     bloom?: BloomConfig | false;
     /** Ambient occlusion. Heavier than the other stages — omit or `false` on low-end targets. Default off (omitted). */
     ao?: AoConfig | false;
+    /** Depth-of-field / bokeh. Heavier stage — omit or `false` to skip. Default off (omitted). */
+    dof?: DofConfig | false;
     grade?: GradeConfig | false;
 }
+/**
+ * A cinematic "product shot" post preset — the full chain on (contact-AO, soft bloom, a warm film
+ * grade with vignette + a touch of grain + chromatic aberration). Meant for a `StudioStage` where a
+ * single parametric asset is framed on a backdrop, so every studio reads shipped, not intern-tier. DoF
+ * is left off by default (it needs a per-scene focus distance); set `dof` to enable it.
+ */
+export declare const STUDIO_STAGE_POST: PostProcessingConfig;

package/dist/render/postProcessing.js

@@ -1 +1,21 @@
-export {};
+/**
+ * A cinematic "product shot" post preset — the full chain on (contact-AO, soft bloom, a warm film
+ * grade with vignette + a touch of grain + chromatic aberration). Meant for a `StudioStage` where a
+ * single parametric asset is framed on a backdrop, so every studio reads shipped, not intern-tier. DoF
+ * is left off by default (it needs a per-scene focus distance); set `dof` to enable it.
+ */
+export const STUDIO_STAGE_POST = {
+    toneMapping: "aces",
+    exposure: 1.05,
+    bloom: { strength: 0.28, radius: 0.6, threshold: 0.8 },
+    ao: { radius: 1.4, intensity: 2.2, distanceFalloff: 3, blend: 1 },
+    grade: {
+        lift: [0.008, 0.008, 0.014],
+        gain: [1.05, 1.02, 0.98],
+        gamma: 0.96,
+        saturation: 1.12,
+        vignette: 0,
+        grain: 0.006,
+        chromaticAberration: 0.001,
+    },
+};

package/dist/rules/predicate.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A declarative, serializable predicate AST evaluated against a plain fact bag. Predicates carry no
+ * closures, so they survive save/load and stay deterministic — the reusable condition seam that
+ * event-conditioned rules, quests, perks, and reactive AI gate on instead of hand-rolled callbacks.
+ */
+/** A leaf value a predicate can compare against — JSON-safe so predicates serialize cleanly. */
+export type PredicateValue = string | number | boolean | null;
+/** Dot path into a fact bag, e.g. `"hit.crit"` or `"attacker.team"`. */
+export type PredicatePath = string;
+/**
+ * One node of the predicate tree. Combinators (`all`/`any`/`not`) nest; leaf comparators read a
+ * dot path from the facts and compare it. `has` passes when the path resolves to a non-nullish value.
+ */
+export type Predicate = {
+    readonly all: readonly Predicate[];
+} | {
+    readonly any: readonly Predicate[];
+} | {
+    readonly not: Predicate;
+} | {
+    readonly eq: readonly [PredicatePath, PredicateValue];
+} | {
+    readonly ne: readonly [PredicatePath, PredicateValue];
+} | {
+    readonly gt: readonly [PredicatePath, number];
+} | {
+    readonly gte: readonly [PredicatePath, number];
+} | {
+    readonly lt: readonly [PredicatePath, number];
+} | {
+    readonly lte: readonly [PredicatePath, number];
+} | {
+    readonly in: readonly [PredicatePath, readonly PredicateValue[]];
+} | {
+    readonly has: PredicatePath;
+};
+/** Plain, serializable bag of facts a predicate reads by dot path. */
+export type PredicateFacts = Record<string, unknown>;
+/**
+ * Read a dot path out of a fact bag, descending only through plain objects. Returns `undefined` when
+ * any segment is missing or non-traversable. Bounded by the path's segment count.
+ *
+ * @capability declarative-predicate serializable data-driven conditions with no callbacks in saved content
+ */
+export declare function readPath(facts: PredicateFacts, path: PredicatePath): unknown;
+/**
+ * Evaluate a predicate against a fact bag. An omitted predicate matches unconditionally, so callers
+ * can treat "no condition" and "always" identically. Pure and deterministic — no allocation beyond
+ * path splits and no reliance on evaluation order between sibling clauses.
+ *
+ * @capability declarative-predicate serializable data-driven conditions with no callbacks in saved content
+ */
+export declare function evaluatePredicate(predicate: Predicate | undefined, facts: PredicateFacts): boolean;

package/dist/rules/predicate.js

@@ -0,0 +1,64 @@
+/**
+ * A declarative, serializable predicate AST evaluated against a plain fact bag. Predicates carry no
+ * closures, so they survive save/load and stay deterministic — the reusable condition seam that
+ * event-conditioned rules, quests, perks, and reactive AI gate on instead of hand-rolled callbacks.
+ */
+/**
+ * Read a dot path out of a fact bag, descending only through plain objects. Returns `undefined` when
+ * any segment is missing or non-traversable. Bounded by the path's segment count.
+ *
+ * @capability declarative-predicate serializable data-driven conditions with no callbacks in saved content
+ */
+export function readPath(facts, path) {
+    let current = facts;
+    for (const segment of path.split(".")) {
+        if (typeof current !== "object" || current === null)
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+function asNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Evaluate a predicate against a fact bag. An omitted predicate matches unconditionally, so callers
+ * can treat "no condition" and "always" identically. Pure and deterministic — no allocation beyond
+ * path splits and no reliance on evaluation order between sibling clauses.
+ *
+ * @capability declarative-predicate serializable data-driven conditions with no callbacks in saved content
+ */
+export function evaluatePredicate(predicate, facts) {
+    if (predicate === undefined)
+        return true;
+    if ("all" in predicate)
+        return predicate.all.every((child) => evaluatePredicate(child, facts));
+    if ("any" in predicate)
+        return predicate.any.some((child) => evaluatePredicate(child, facts));
+    if ("not" in predicate)
+        return !evaluatePredicate(predicate.not, facts);
+    if ("has" in predicate) {
+        const value = readPath(facts, predicate.has);
+        return value !== undefined && value !== null;
+    }
+    if ("eq" in predicate)
+        return readPath(facts, predicate.eq[0]) === predicate.eq[1];
+    if ("ne" in predicate)
+        return readPath(facts, predicate.ne[0]) !== predicate.ne[1];
+    if ("in" in predicate)
+        return predicate.in[1].includes(readPath(facts, predicate.in[0]));
+    if ("gt" in predicate) {
+        const value = asNumber(readPath(facts, predicate.gt[0]));
+        return value !== undefined && value > predicate.gt[1];
+    }
+    if ("gte" in predicate) {
+        const value = asNumber(readPath(facts, predicate.gte[0]));
+        return value !== undefined && value >= predicate.gte[1];
+    }
+    if ("lt" in predicate) {
+        const value = asNumber(readPath(facts, predicate.lt[0]));
+        return value !== undefined && value < predicate.lt[1];
+    }
+    const value = asNumber(readPath(facts, predicate.lte[0]));
+    return value !== undefined && value <= predicate.lte[1];
+}

package/dist/rules/ruleEffects.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A registration seam for the effect ids that triggered rules reference. Saved content names an
+ * effect by id; the game declares what that id means here (label for inspectors, optional param
+ * schema note) so authored rules validate against a known vocabulary instead of stringly-invented,
+ * un-inspectable callbacks. Mirrors the authored-trigger action registry for editor parity.
+ */
+import type { PredicateValue } from "./predicate.js";
+/** A declared effect a triggered rule may reference. Behavior lives in the game; this is metadata. */
+export interface RuleEffectDefinition {
+    /** Effect id used in {@link TriggeredRule.effect} references. */
+    id: string;
+    /** Human label for debug/inspector surfaces. */
+    label?: string;
+    /** Default params merged under a rule's own params, for authoring convenience. */
+    defaults?: Readonly<Record<string, PredicateValue>>;
+}
+/**
+ * Declare a rule effect id. Idempotent per id (last registration wins); call at module load next to
+ * catalogs so authored content and inspectors share one vocabulary.
+ *
+ * @capability triggered-rules event-conditioned effects with declarative predicates, lifetimes, and stacking
+ */
+export declare function registerRuleEffect(definition: RuleEffectDefinition): void;
+/**
+ * Look up a declared rule effect, or `undefined` when the id was never registered — lets callers
+ * reject unknown effect references in authored content.
+ *
+ * @capability triggered-rules event-conditioned effects with declarative predicates, lifetimes, and stacking
+ */
+export declare function getRuleEffect(id: string): RuleEffectDefinition | undefined;
+/**
+ * Every declared rule effect, for populating inspector dropdowns and validating a content set.
+ *
+ * @capability triggered-rules event-conditioned effects with declarative predicates, lifetimes, and stacking
+ */
+export declare function listRuleEffects(): RuleEffectDefinition[];
+/** Clear the rule-effect registry — tests only. @internal */
+export declare function clearRuleEffects(): void;

package/dist/rules/ruleEffects.js

@@ -0,0 +1,37 @@
+/**
+ * A registration seam for the effect ids that triggered rules reference. Saved content names an
+ * effect by id; the game declares what that id means here (label for inspectors, optional param
+ * schema note) so authored rules validate against a known vocabulary instead of stringly-invented,
+ * un-inspectable callbacks. Mirrors the authored-trigger action registry for editor parity.
+ */
+const registry = new Map();
+/**
+ * Declare a rule effect id. Idempotent per id (last registration wins); call at module load next to
+ * catalogs so authored content and inspectors share one vocabulary.
+ *
+ * @capability triggered-rules event-conditioned effects with declarative predicates, lifetimes, and stacking
+ */
+export function registerRuleEffect(definition) {
+    registry.set(definition.id, definition);
+}
+/**
+ * Look up a declared rule effect, or `undefined` when the id was never registered — lets callers
+ * reject unknown effect references in authored content.
+ *
+ * @capability triggered-rules event-conditioned effects with declarative predicates, lifetimes, and stacking
+ */
+export function getRuleEffect(id) {
+    return registry.get(id);
+}
+/**
+ * Every declared rule effect, for populating inspector dropdowns and validating a content set.
+ *
+ * @capability triggered-rules event-conditioned effects with declarative predicates, lifetimes, and stacking
+ */
+export function listRuleEffects() {
+    return [...registry.values()];
+}
+/** Clear the rule-effect registry — tests only. @internal */
+export function clearRuleEffects() {
+    registry.clear();
+}

package/dist/rules/triggeredRules.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The reusable bridge from typed runtime events to effects. A triggered rule is pure data — which
+ * event it listens to, a declarative predicate over the event facts, how the affected target is
+ * resolved, an effect *reference* (never a callback), and how the resulting effect is gated, lived,
+ * and stacked. Affixes, talents, perks, quests, achievements, environment rules, and reactive AI all
+ * subscribe through this one seam instead of owning parallel trigger runtimes.
+ *
+ * Core stays decoupled from any specific effect system: `dispatch` returns provenance-rich firings
+ * and the game applies them to whatever effect/stat system it owns. Gate state (cooldowns, rate
+ * windows, remaining charges) and active timed effects serialize cleanly so future triggers survive
+ * save/load.
+ */
+import { type Predicate, type PredicateFacts, type PredicateValue } from "./predicate.js";
+/** Role slots an event exposes; a target selector resolves one of these to a concrete id. */
+export type TargetRole = "subject" | "object" | "source" | "owner";
+/**
+ * How a rule picks the id its effect lands on: a fixed event role, a dot path into the event facts,
+ * or a literal id. Data-only so it saves with the rule.
+ */
+export type TargetSelector = {
+    readonly role: TargetRole;
+} | {
+    readonly path: string;
+} | {
+    readonly literal: string;
+};
+/** A reference to an effect the game knows how to apply — id plus JSON-safe params, no closures. */
+export interface EffectRef {
+    readonly id: string;
+    readonly params?: Readonly<Record<string, PredicateValue>>;
+}
+/**
+ * How a repeated application of the same rule's effect on the same target combines with a live one:
+ * `refresh` re-arms the timer at one stack, `stack` adds a stack up to `maxStacks` and re-arms,
+ * `independent` keeps each application as its own instance with its own expiry, `ignore` drops the
+ * new application while one is already active.
+ */
+export type StackPolicy = "refresh" | "stack" | "independent" | "ignore";
+/** Bounded firing budget over a sliding time window. */
+export interface RateLimit {
+    readonly count: number;
+    readonly windowMs: number;
+}
+/**
+ * A declarative subscription from an event to an effect. Everything here is serializable content —
+ * the runtime reads it, it never embeds behavior. `effect` names an effect the game resolves; core
+ * only routes and gates.
+ */
+export interface TriggeredRule {
+    /** Stable id, unique within an engine. */
+    readonly id: string;
+    /** Event type this rule subscribes to. */
+    readonly event: string;
+    /** Owner/source identity (item instance, talent node, quest id) for provenance and bulk cleanup. */
+    readonly owner?: string;
+    /** Declarative gate over the event facts; omitted fires unconditionally. */
+    readonly when?: Predicate;
+    /** How the affected target id is resolved; defaults to the `subject` role. */
+    readonly target?: TargetSelector;
+    /** The effect to apply when the rule fires. */
+    readonly effect: EffectRef;
+    /** Minimum ms between fires of this rule against the same resolved target. */
+    readonly cooldownMs?: number;
+    /** Sliding-window firing cap across all targets. */
+    readonly rateLimit?: RateLimit;
+    /** Total fires before the rule is spent; omitted is unlimited. */
+    readonly charges?: number;
+    /** Lifetime of the applied effect in ms; omitted is instantaneous (no active instance kept). */
+    readonly durationMs?: number;
+    /** Stacking policy for repeat applications while an instance is live; defaults to `refresh`. */
+    readonly stacking?: StackPolicy;
+    /** Cap for the `stack` policy; defaults to 1 (i.e. behaves like `refresh` until raised). */
+    readonly maxStacks?: number;
+}
+/** A typed event handed to the engine; roles feed target resolution, facts feed the predicate. */
+export interface RuleEvent {
+    readonly type: string;
+    readonly subject?: string;
+    readonly object?: string;
+    readonly source?: string;
+    /** Fact bag the predicate and `{ path }` target selectors read. */
+    readonly facts?: PredicateFacts;
+}
+/** A live timed effect an engine is tracking until it expires or is cleaned up. */
+export interface ActiveEffect {
+    readonly instanceId: string;
+    readonly ruleId: string;
+    readonly effectId: string;
+    readonly owner: string | undefined;
+    readonly target: string;
+    readonly params: Readonly<Record<string, PredicateValue>> | undefined;
+    readonly appliedAt: number;
+    readonly expiresAt: number;
+    readonly stacks: number;
+}
+/** Reason a firing did not produce an effect — surfaced for debug inspection, never thrown. */
+export type FiringBlock = "predicate" | "no-target" | "cooldown" | "rate-limit" | "no-charges" | "stack-ignored";
+/**
+ * The outcome of matching one rule against one event. `applied` is the effect the caller should now
+ * run through its own effect system; a blocked firing reports why. Provenance (rule, owner, event,
+ * timestamp) rides along for auditability.
+ */
+export interface RuleFiring {
+    readonly ruleId: string;
+    readonly event: string;
+    readonly owner: string | undefined;
+    readonly target: string;
+    readonly effect: EffectRef;
+    readonly at: number;
+    /** Set when the firing produced/updated a timed instance. */
+    readonly instanceId?: string;
+    /** Stack count on the target after this firing (>= 1 for timed effects). */
+    readonly stacks?: number;
+    /** Absent when the effect was applied; set when the firing was gated out. */
+    readonly blocked?: FiringBlock;
+}
+/** Serializable runtime state — everything that changes future triggers. Rules travel with it. */
+export interface TriggeredRuleState {
+    seq: number;
+    rules: TriggeredRule[];
+    charges: Record<string, number>;
+    cooldowns: Record<string, number>;
+    windows: Record<string, number[]>;
+    active: ActiveEffect[];
+}
+/** A running set of triggered rules with gating, timed lifetimes, stacking, cleanup, and save/load. */
+export interface TriggeredRuleEngine {
+    /** Register or replace a rule by id. */
+    add(rule: TriggeredRule): void;
+    /** Drop a rule and any active effects it produced. */
+    remove(ruleId: string): void;
+    /** Drop every rule and active effect belonging to an owner (unequip, respec, entity removal). */
+    removeByOwner(owner: string): void;
+    /** Snapshot of registered rules in insertion order. */
+    rules(): readonly TriggeredRule[];
+    /** Match an event against all rules, gate, spawn/refresh timed effects, and return firings. */
+    dispatch(event: RuleEvent, now: number): readonly RuleFiring[];
+    /** Advance time and return the active effects that expired (and were removed) this tick. */
+    tick(now: number): readonly ActiveEffect[];
+    /** All live timed effects. */
+    active(): readonly ActiveEffect[];
+    /** Live timed effects landed on a given target. */
+    activeFor(target: string): readonly ActiveEffect[];
+    /** Drop all active timed effects but keep rules and gate state. */
+    clearActive(): void;
+    /** Reset gate state and active effects (respec/encounter reset) while keeping rules. */
+    reset(): void;
+    /** Serialize all future-affecting state. */
+    snapshot(): TriggeredRuleState;
+    /** Replace all state from a snapshot. */
+    hydrate(state: TriggeredRuleState): void;
+}
+/**
+ * Create an empty triggered-rule engine. Rules are added as data; dispatching an event returns the
+ * firings the caller applies to its own effect system. Time is caller-supplied (`now` in ms), so the
+ * engine is deterministic and drives equally from a fixed-step loop or a save-restored timeline.
+ *
+ * @capability triggered-rules event-conditioned effects with declarative predicates, lifetimes, and stacking
+ */
+export declare function createTriggeredRuleEngine(rules?: readonly TriggeredRule[]): TriggeredRuleEngine;