@jgengine/core 0.27.0 → 0.29.0

package/dist/economy/transactionLedger.js

@@ -0,0 +1,301 @@
+import { devtools } from "../devtools/devtools.js";
+const EPSILON = 1e-9;
+function isMinorUnits(value) {
+    return Number.isSafeInteger(value);
+}
+function withinOverdraft(nextBalance, overdraft) {
+    if (nextBalance >= 0)
+        return true;
+    if (overdraft === undefined || overdraft === false)
+        return false;
+    if (overdraft === true)
+        return true;
+    return nextBalance >= -overdraft.max;
+}
+function validCharge(charge) {
+    return (charge.id.trim() !== "" &&
+        charge.account.trim() !== "" &&
+        charge.currency.trim() !== "" &&
+        charge.reason.trim() !== "" &&
+        isMinorUnits(charge.amountPerPeriod) && charge.amountPerPeriod > 0 &&
+        Number.isFinite(charge.everySeconds) && charge.everySeconds > 0 &&
+        (charge.startSeconds === undefined || (Number.isFinite(charge.startSeconds) && charge.startSeconds >= 0)) &&
+        (charge.maxCatchUp === undefined || (Number.isInteger(charge.maxCatchUp) && charge.maxCatchUp > 0)));
+}
+/**
+ * The books a business 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.
+ * {@link TransactionLedger.post} is the one money path — sales, purchases, upkeep and loan
+ * payments all go through it, so nothing moves without a reason on the record.
+ * {@link TransactionLedger.chargeDue} settles recurring charges (upkeep, rent) on their own
+ * cadence, bounded per advance; a cycle with no funds is counted as missed instead of overdrawing.
+ * Journal memory is bounded by `maxEntries`, with `totals()` keeping the per-reason summary beyond it.
+ *
+ * @capability transaction-ledger record every money movement with its reason over per-account integer minor-unit balances
+ */
+export function createTransactionLedger(options = {}) {
+    const maxEntries = Math.max(1, Math.floor(options.maxEntries ?? 1024));
+    const maxCyclesPerAdvance = Math.max(1, Math.floor(options.maxCyclesPerAdvance ?? 256));
+    let nowSeconds = 0;
+    let accounts = {};
+    let entries = [];
+    let totals = {};
+    let charges = {};
+    let cursors = {};
+    let seq = 0;
+    const probe = options.devtoolsName === undefined
+        ? null
+        : devtools.probes.register(options.devtoolsName, () => ({ ...readStats(), totals: readTotals() }));
+    function readStats() {
+        return { accounts: Object.keys(accounts).length, entries: entries.length, charges: Object.keys(charges).length, seq };
+    }
+    function readTotals() {
+        const out = {};
+        for (const [reason, entry] of Object.entries(totals))
+            out[reason] = { ...entry };
+        return out;
+    }
+    function readAccounts() {
+        const out = {};
+        for (const [account, wallet] of Object.entries(accounts))
+            out[account] = { ...wallet };
+        return out;
+    }
+    function apply(at, account, currency, amount, reason, ref, overdraft) {
+        const wallet = accounts[account];
+        if (wallet === undefined)
+            return { ok: false, reason: "unknown-account" };
+        if (!isMinorUnits(amount) || amount === 0)
+            return { ok: false, reason: "invalid-amount" };
+        if (reason.trim() === "")
+            return { ok: false, reason: "invalid-reason" };
+        const next = (wallet[currency] ?? 0) + amount;
+        if (!isMinorUnits(next) || !withinOverdraft(next, overdraft))
+            return { ok: false, reason: "insufficient-funds" };
+        wallet[currency] = next;
+        seq += 1;
+        const entry = ref === undefined
+            ? { seq, at, account, currency, amount, balanceAfter: next, reason }
+            : { seq, at, account, currency, amount, balanceAfter: next, reason, ref };
+        entries.push(entry);
+        if (entries.length > maxEntries)
+            entries.splice(0, entries.length - maxEntries);
+        const total = totals[reason] ?? { count: 0, net: 0 };
+        totals[reason] = { count: total.count + 1, net: total.net + amount };
+        return { ok: true, entry: { ...entry } };
+    }
+    return {
+        openAccount(account, currency, initial = 0) {
+            if (account.trim() === "" || currency.trim() === "")
+                return;
+            if (!isMinorUnits(initial))
+                return;
+            const wallet = accounts[account] ?? (accounts[account] = {});
+            if (wallet[currency] === undefined)
+                wallet[currency] = initial;
+        },
+        balanceOf(account, currency) {
+            return accounts[account]?.[currency] ?? 0;
+        },
+        post(input) {
+            return apply(input.at, input.account, input.currency, input.amount, input.reason, input.ref, input.overdraft);
+        },
+        addCharge(charge) {
+            if (!validCharge(charge) || charges[charge.id] !== undefined)
+                return false;
+            charges[charge.id] = { ...charge };
+            cursors[charge.id] = {
+                nextDueSeconds: charge.startSeconds ?? nowSeconds,
+                fired: 0,
+                missed: 0,
+                done: false,
+            };
+            return true;
+        },
+        removeCharge(id) {
+            if (charges[id] === undefined)
+                return false;
+            const nextCharges = { ...charges };
+            const nextCursors = { ...cursors };
+            delete nextCharges[id];
+            delete nextCursors[id];
+            charges = nextCharges;
+            cursors = nextCursors;
+            return true;
+        },
+        chargeDue(toSeconds) {
+            if (toSeconds < nowSeconds) {
+                throw new RangeError(`chargeDue cannot rewind: ${toSeconds} < ${nowSeconds}`);
+            }
+            const charged = [];
+            const missed = [];
+            for (const id of Object.keys(charges).sort()) {
+                const charge = charges[id];
+                const cursor = { ...cursors[id] };
+                if (cursor.done || cursor.nextDueSeconds > toSeconds) {
+                    cursors[id] = cursor;
+                    continue;
+                }
+                const dueCount = Math.floor((toSeconds - cursor.nextDueSeconds) / charge.everySeconds + EPSILON) + 1;
+                const policy = charge.catchUp ?? "each";
+                const perChargeLimit = charge.maxCatchUp ?? Number.POSITIVE_INFINITY;
+                const kept = policy === "skip" ? 1 : Math.min(dueCount, perChargeLimit, maxCyclesPerAdvance);
+                const firstDue = cursor.nextDueSeconds;
+                if (policy === "skip") {
+                    const at = firstDue + (dueCount - 1) * charge.everySeconds;
+                    const result = apply(at, charge.account, charge.currency, -charge.amountPerPeriod, charge.reason, charge.ref ?? id, undefined);
+                    if (result.ok) {
+                        charged.push(result.entry);
+                        cursor.fired += 1;
+                    }
+                    else {
+                        cursor.missed += 1;
+                        missed.push({ id, cycles: 1 });
+                    }
+                }
+                else if (policy === "sum") {
+                    const at = firstDue + (kept - 1) * charge.everySeconds;
+                    const result = apply(at, charge.account, charge.currency, -charge.amountPerPeriod * kept, charge.reason, charge.ref ?? id, undefined);
+                    if (result.ok) {
+                        charged.push(result.entry);
+                        cursor.fired += kept;
+                    }
+                    else {
+                        cursor.missed += kept;
+                        missed.push({ id, cycles: kept });
+                    }
+                }
+                else {
+                    let failed = 0;
+                    for (let i = 0; i < kept; i += 1) {
+                        const at = firstDue + i * charge.everySeconds;
+                        const result = apply(at, charge.account, charge.currency, -charge.amountPerPeriod, charge.reason, charge.ref ?? id, undefined);
+                        if (result.ok) {
+                            charged.push(result.entry);
+                            cursor.fired += 1;
+                        }
+                        else {
+                            failed += 1;
+                        }
+                    }
+                    cursor.missed += failed;
+                    if (failed > 0)
+                        missed.push({ id, cycles: failed });
+                }
+                cursor.nextDueSeconds = firstDue + dueCount * charge.everySeconds;
+                cursors[id] = cursor;
+            }
+            nowSeconds = toSeconds;
+            return { charged, missed };
+        },
+        entries(filter = {}) {
+            const limit = filter.limit === undefined ? Number.POSITIVE_INFINITY : Math.max(0, Math.floor(filter.limit));
+            const out = [];
+            for (const entry of entries) {
+                if (filter.account !== undefined && entry.account !== filter.account)
+                    continue;
+                if (filter.reason !== undefined && entry.reason !== filter.reason)
+                    continue;
+                if (filter.since !== undefined && entry.at < filter.since)
+                    continue;
+                out.push({ ...entry });
+            }
+            return Number.isFinite(limit) && out.length > limit ? out.slice(out.length - limit) : out;
+        },
+        totals: readTotals,
+        accounts: readAccounts,
+        snapshot() {
+            return {
+                nowSeconds,
+                accounts: readAccounts(),
+                entries: entries.map((entry) => ({ ...entry })),
+                totals: readTotals(),
+                charges: Object.fromEntries(Object.entries(charges).map(([id, charge]) => [id, { ...charge }])),
+                cursors: Object.fromEntries(Object.entries(cursors).map(([id, cursor]) => [id, { ...cursor }])),
+                seq,
+            };
+        },
+        restore(next) {
+            if (!Number.isFinite(next.nowSeconds) || next.nowSeconds < 0)
+                return false;
+            if (!Number.isInteger(next.seq) || next.seq < 0)
+                return false;
+            if (next.accounts === undefined || next.entries === undefined || next.totals === undefined)
+                return false;
+            if (next.charges === undefined || next.cursors === undefined)
+                return false;
+            const nextAccounts = {};
+            for (const [account, wallet] of Object.entries(next.accounts)) {
+                const copy = {};
+                for (const [currency, amount] of Object.entries(wallet)) {
+                    if (!isMinorUnits(amount))
+                        return false;
+                    copy[currency] = amount;
+                }
+                nextAccounts[account] = copy;
+            }
+            const nextEntries = [];
+            for (const entry of next.entries) {
+                if (!Number.isInteger(entry.seq) || entry.seq < 1)
+                    return false;
+                if (!Number.isFinite(entry.at) || entry.at < 0)
+                    return false;
+                if (typeof entry.account !== "string" || entry.account.trim() === "")
+                    return false;
+                if (typeof entry.currency !== "string" || entry.currency.trim() === "")
+                    return false;
+                if (!isMinorUnits(entry.amount) || !isMinorUnits(entry.balanceAfter))
+                    return false;
+                if (typeof entry.reason !== "string" || entry.reason.trim() === "")
+                    return false;
+                nextEntries.push({ ...entry });
+            }
+            const nextTotals = {};
+            for (const [reason, total] of Object.entries(next.totals)) {
+                if (!Number.isInteger(total.count) || total.count < 0 || !isMinorUnits(total.net))
+                    return false;
+                nextTotals[reason] = { count: total.count, net: total.net };
+            }
+            const nextCharges = {};
+            const nextCursors = {};
+            for (const [id, charge] of Object.entries(next.charges)) {
+                if (!validCharge(charge) || charge.id !== id)
+                    return false;
+                const cursor = next.cursors[id];
+                if (cursor === undefined)
+                    return false;
+                if (!Number.isFinite(cursor.nextDueSeconds) || cursor.nextDueSeconds < 0)
+                    return false;
+                if (!Number.isInteger(cursor.fired) || cursor.fired < 0)
+                    return false;
+                if (!Number.isInteger(cursor.missed) || cursor.missed < 0)
+                    return false;
+                if (typeof cursor.done !== "boolean")
+                    return false;
+                nextCharges[id] = { ...charge };
+                nextCursors[id] = { ...cursor };
+            }
+            nowSeconds = next.nowSeconds;
+            accounts = nextAccounts;
+            entries = nextEntries.length > maxEntries ? nextEntries.slice(nextEntries.length - maxEntries) : nextEntries;
+            totals = nextTotals;
+            charges = nextCharges;
+            cursors = nextCursors;
+            seq = next.seq;
+            return true;
+        },
+        stats: readStats,
+        reset() {
+            nowSeconds = 0;
+            accounts = {};
+            entries = [];
+            totals = {};
+            charges = {};
+            cursors = {};
+            seq = 0;
+        },
+        dispose() {
+            probe?.();
+        },
+    };
+}

package/dist/editor/creatorStorage.js

@@ -1,3 +1,4 @@
+import { findEffect } from "../vfx/effectLibrary.js";
 import { cloneEditorDocument, decodeEditorDocument, editorDocumentSize } from "./document.js";
 import { isScatterPath } from "../world/scatterRegion.js";
 function byteSize(value) {
@@ -59,7 +60,8 @@ export function validateCreatorDocument(value, policy) {
             const child = emitter.options?.collisionEffect;
             if (child !== undefined)
                 maxChildParticles = Math.max(maxChildParticles, Math.min(child.count, child.config.max ?? child.count));
-            return total + (emitter.config.max ?? 512);
+            const authored = emitter.config ?? (emitter.effect === undefined ? undefined : findEffect(emitter.effect)?.config);
+            return total + (authored?.max ?? 512);
         }, 0);
         // The renderer retains up to 32 concurrent child bursts, shared by all standing emitters.
         if (weatherParticles + emitterParticles + 32 * maxChildParticles > (policy.maxSimulationParticles ?? 0))

package/dist/editor/simulation.d.ts

@@ -5,13 +5,16 @@ import { type ParticleAttachOptions } from "../vfx/particleDirector.js";
 import type { FireGridConfig } from "../world/weather.js";
 import type { FlockConfig } from "../ai/flock.js";
 import type { EditorDocument, EditorVec3 } from "./types.js";
-/** A named emitter authored in metres, with game-owned appearance and attachment ids. */
+/** A named emitter authored in metres: either a library effect name or a full config. */
 export interface AuthoredEmitter {
     id: string;
     /** Spawn only while this authored fire area burns; live particles finish their lifetime. */
     fireAreaId?: string;
     position: EditorVec3;
-    config: EmitterConfig;
+    /** Named effect from the shared library (`fire/flame`, `explosion/core`, …). */
+    effect?: string;
+    /** Full emitter config; used when `effect` is absent. */
+    config?: EmitterConfig;
     options?: ParticleAttachOptions;
 }
 /** A bounded fire grid; fuel and damage policy remain game content. */

package/dist/editor/simulation.js

@@ -1,6 +1,7 @@
 import { validateForceField } from "../physics/forceVolume.js";
 import { validateAuthoredWeather } from "../world/authoredWeather.js";
 import { validateEmitterConfig } from "../vfx/particles.js";
+import { effectNames } from "../vfx/effectLibrary.js";
 import { validateParticleAttachOptions } from "../vfx/particleDirector.js";
 function object(value, path) {
     if (value === null || typeof value !== "object" || Array.isArray(value))
@@ -91,35 +92,44 @@ export function decodeEditorSimulation(value, document) {
         });
     }
     rows(source.emitters, "$.simulation.emitters", 128, (row, path) => {
-        known(row, ["id", "position", "config", "options", "fireAreaId"], path);
+        known(row, ["id", "position", "effect", "config", "options", "fireAreaId"], path);
         if (row.fireAreaId !== undefined) {
             text(row.fireAreaId, `${path}.fireAreaId`);
             if (!Array.isArray(source.fires) || !source.fires.some((area) => area !== null && typeof area === "object" && area.id === row.fireAreaId))
                 throw new Error(`${path}.fireAreaId: missing fire area ${row.fireAreaId}`);
         }
-        const diagnostics = validateEmitterConfig(row.config);
-        if (diagnostics.length)
-            throw new Error(`${path}.config: ${diagnostics.join("; ")}`);
+        if ((row.effect === undefined) === (row.config === undefined))
+            throw new Error(`${path}: expected exactly one of effect or config`);
+        if (row.effect !== undefined) {
+            text(row.effect, `${path}.effect`);
+            if (!effectNames().includes(row.effect))
+                throw new Error(`${path}.effect: unknown effect ${row.effect}`);
+        }
+        else {
+            const diagnostics = validateEmitterConfig(row.config);
+            if (diagnostics.length)
+                throw new Error(`${path}.config: ${diagnostics.join("; ")}`);
+            const config = object(row.config, `${path}.config`);
+            for (const key of ["max", "rate", "spread", "drag"])
+                if (config[key] !== undefined)
+                    finite(config[key], `${path}.config.${key}`, 0, key === "max" ? 100_000 : key === "drag" ? 1 : Infinity);
+            if (config.max !== undefined && !Number.isInteger(config.max))
+                throw new Error(`${path}.config.max: expected an integer`);
+            for (const key of ["position", "spawnJitter", "direction", "gravity"])
+                if (config[key] !== undefined)
+                    tuple(config[key], `${path}.config.${key}`);
+            for (const key of ["lifetime", "speed"])
+                if (config[key] !== undefined) {
+                    const range = object(config[key], `${path}.config.${key}`);
+                    finite(range.min, `${path}.config.${key}.min`, 0);
+                    finite(range.max, `${path}.config.${key}.max`, range.min);
+                }
+        }
         if (row.options !== undefined) {
             const errors = validateParticleAttachOptions(row.options);
             if (errors.length)
                 throw new Error(`${path}.options: ${errors.join("; ")}`);
         }
-        const config = object(row.config, `${path}.config`);
-        for (const key of ["max", "rate", "spread", "drag"])
-            if (config[key] !== undefined)
-                finite(config[key], `${path}.config.${key}`, 0, key === "max" ? 100_000 : key === "drag" ? 1 : Infinity);
-        if (config.max !== undefined && !Number.isInteger(config.max))
-            throw new Error(`${path}.config.max: expected an integer`);
-        for (const key of ["position", "spawnJitter", "direction", "gravity"])
-            if (config[key] !== undefined)
-                tuple(config[key], `${path}.config.${key}`);
-        for (const key of ["lifetime", "speed"])
-            if (config[key] !== undefined) {
-                const range = object(config[key], `${path}.config.${key}`);
-                finite(range.min, `${path}.config.${key}.min`, 0);
-                finite(range.max, `${path}.config.${key}.max`, range.min);
-            }
         if (row.options !== undefined) {
             const options = object(row.options, `${path}.options`);
             if (options.space !== undefined && options.space !== "local" && options.space !== "world")

package/dist/game/cameraConfig.d.ts

@@ -30,6 +30,20 @@ export interface FirstPersonCameraConfig {
     reticle?: boolean;
     /** Render a viewmodel in view: the built-in three-mesh gun, or `PlayableGame.viewmodel` when set (#542). `false` renders no viewmodel regardless of `PlayableGame.viewmodel`. Default true. */
     viewmodel?: boolean;
+    /**
+     * Keep the eye out of world collision. The boom anchors `armBack` behind the eye and
+     * pulls the camera toward it so the near plane stays clear of a trunk or wall the body
+     * can reach; pulling in is immediate, easing back out is not. `false` restores the
+     * unchecked camera. Default on, with `clearance` = near plane + 0.15.
+     */
+    collision?: false | FirstPersonCollisionConfig;
+}
+/** Clearance tuning for the first-person camera's collision pull-in. */
+export interface FirstPersonCollisionConfig {
+    /** Gap kept between the camera and the surface it would enter, world units. Defaults to the near plane plus 0.15. */
+    clearance?: number;
+    /** How far behind the eye the boom anchors, giving the pull somewhere to travel. Default 1.5. */
+    armBack?: number;
 }
 /**
  * Which camera rig the shell mounts. Every rig accepts `followEntityId: null`

package/dist/game/clipRoles.d.ts

@@ -4,7 +4,7 @@ import type { ModelAnimationConfig } from "./playableGame.js";
  * differently (`Idle` / `Walking_A` / `Armature|Run`); roles are the pack-agnostic vocabulary
  * the engine defaults from.
  */
-export type ClipRole = "idle" | "walk" | "run" | "attack" | "hit" | "death" | "jump" | "spawn" | "interact" | "cheer";
+export type ClipRole = "idle" | "walk" | "run" | "strafe" | "backward" | "attack" | "hit" | "death" | "jump" | "spawn" | "interact" | "cheer";
 /**
  * Keyword table driving {@link classifyClip}: lowercase keywords matched against a clip name's
  * tokens (exact token match beats prefix match). Extend or replace per game/pack — the table is
@@ -34,9 +34,10 @@ export declare function classifyClip(name: string, table?: ClipRoleTable): ClipR
 export declare function rolesFromClips(clips: readonly string[], table?: ClipRoleTable): Partial<Record<ClipRole, string[]>>;
 /**
  * Build the default `ModelConfig.animation` for a rigged asset from its catalog clip names:
- * speed-driven idle/walk/run states plus hit/death/attack one-shots where identifiable. Returns
- * `undefined` when no idle clip is identifiable — an ambiguous rig renders its bind pose rather
- * than guessing. Walk falls back to idle when the pack has no walk clip.
+ * speed-driven idle/walk/run states plus hit/death/attack one-shots where identifiable, and the
+ * lateral/backward states when the pack names them (KayKit's `Running_Strafe_Left`,
+ * `Walking_Backwards`). Returns `undefined` when no idle clip is identifiable - an ambiguous rig
+ * renders its bind pose rather than guessing. Walk falls back to idle when the pack has no walk clip.
  *
  * @capability clip-roles derive a complete default animation config from a rigged asset's clip names
  */

package/dist/game/clipRoles.js

@@ -7,6 +7,8 @@ const ROLE_PRIORITY = [
     "spawn",
     "interact",
     "cheer",
+    "strafe",
+    "backward",
     "run",
     "walk",
     "idle",
@@ -17,6 +19,8 @@ export const DEFAULT_CLIP_ROLE_TABLE = {
         idle: ["idle"],
         walk: ["walk"],
         run: ["run", "sprint", "jog"],
+        strafe: ["strafe"],
+        backward: ["backward", "backpedal"],
         attack: ["attack", "punch", "slash", "shoot", "chop", "stab", "cast", "swing", "strike", "kick", "throw"],
         hit: ["hit", "receive", "impact", "hurt", "damage"],
         death: ["death", "die", "dead", "dying"],
@@ -94,11 +98,21 @@ function oneShotSpec(variants) {
         return undefined;
     return variants.length === 1 ? variants[0] : variants;
 }
+/** Which side a strafe clip covers, read from its own name; `undefined` when the name names no side. */
+function strafeSide(name) {
+    const lower = name.toLowerCase();
+    if (lower.includes("left"))
+        return "left";
+    if (lower.includes("right"))
+        return "right";
+    return undefined;
+}
 /**
  * Build the default `ModelConfig.animation` for a rigged asset from its catalog clip names:
- * speed-driven idle/walk/run states plus hit/death/attack one-shots where identifiable. Returns
- * `undefined` when no idle clip is identifiable — an ambiguous rig renders its bind pose rather
- * than guessing. Walk falls back to idle when the pack has no walk clip.
+ * speed-driven idle/walk/run states plus hit/death/attack one-shots where identifiable, and the
+ * lateral/backward states when the pack names them (KayKit's `Running_Strafe_Left`,
+ * `Walking_Backwards`). Returns `undefined` when no idle clip is identifiable - an ambiguous rig
+ * renders its bind pose rather than guessing. Walk falls back to idle when the pack has no walk clip.
  *
  * @capability clip-roles derive a complete default animation config from a rigged asset's clip names
  */
@@ -119,8 +133,24 @@ export function defaultAnimationForClips(clips, table = DEFAULT_CLIP_ROLE_TABLE)
         oneShots.death = death;
     if (attack !== undefined)
         oneShots.attack = attack;
+    let strafeLeft;
+    let strafeRight;
+    for (const clip of roles.strafe ?? []) {
+        const side = strafeSide(clip);
+        if (side === "left")
+            strafeLeft ??= clip;
+        else if (side === "right")
+            strafeRight ??= clip;
+    }
     return {
-        states: { idle, walk, ...(run === undefined ? {} : { run }) },
+        states: {
+            idle,
+            walk,
+            ...(run === undefined ? {} : { run }),
+            ...(strafeLeft === undefined ? {} : { strafeLeft }),
+            ...(strafeRight === undefined ? {} : { strafeRight }),
+            ...(roles.backward?.[0] === undefined ? {} : { backward: roles.backward[0] }),
+        },
         ...(Object.keys(oneShots).length === 0 ? {} : { oneShots }),
     };
 }

package/dist/game/events.d.ts

@@ -9,10 +9,36 @@ export interface EntityDiedEvent {
     catalogId: string;
     userId?: string;
     displayName?: string;
+    /** The cause (`reason.kind`) and, through `source`, what dealt it. */
     reason: DeathReason;
+    /** Instance id of the killer, hazard or effect that caused it, when the caller knew one. */
+    source?: string;
     position: [number, number, number];
     serverId?: string;
 }
+/**
+ * One application of damage to one target: what hit it, for how much, and where its health stands.
+ * `target` is always the thing that took the blow, so a hero and a keep hit in the same frame raise
+ * two separate events and a HUD reads only the one whose `target` it owns.
+ */
+export interface DamageAppliedEvent {
+    /** The registered target that took the damage. */
+    target: string;
+    /** Who or what dealt it: an attacker instance id, a hazard, or the status that ticked. */
+    source?: string;
+    /** Damage type resolved through the target's table (`"kinetic"`, `"fire"`). On the effect path (`ctx.scene.entity.effect`) there is no table, so it is the effect id that landed. */
+    type: string;
+    /** Damage dealt after the zone, type and armor steps. */
+    amount: number;
+    /** How much of the zone-adjusted incoming amount resistance and armor stopped. */
+    absorbed: number;
+    /** Health left after this application, or `null` when the runtime was given no health reader. */
+    remaining: number | null;
+    /** True only when a health reader reported the pool reaching zero or below. */
+    lethal: boolean;
+    /** The status that ticked, when the damage came from a carried status rather than a direct hit. */
+    status?: string;
+}
 /** Request that an entity's rig play a one-shot animation clip bound to `event` in its `animation.oneShots` (e.g. an "attack" swing); the shell resolves the clip and plays it once over the locomotion state. With an `animation.graph`, `event` arms the trigger of that name. */
 export interface EntityAnimationEvent {
     instanceId: string;
@@ -265,6 +291,7 @@ export interface AudioLoopStopEvent {
 }
 export interface GameEventMap {
     "entity.died": EntityDiedEvent;
+    "combat.damage": DamageAppliedEvent;
     "entity.floatText": EntityFloatTextEvent;
     "combat.telegraph": CombatTelegraphEvent;
     "combat.vfx": CombatVfxEvent;