@jgengine/core 0.26.0 → 0.28.0

package/dist/anim/skeletonStandard.js

@@ -0,0 +1,326 @@
+/**
+ * The engine's one humanoid skeleton standard, and the path any other CC0 rig takes onto it.
+ *
+ * The standard is the **KayKit character rig**: one armature shared by every rigged character in
+ * `kaykit-adventurers` (Barbarian, Knight, Mage, Rogue, Rogue_Hooded) and `kaykit-skeletons`
+ * (Skeleton_Mage/Minion/Rogue/Warrior). Because they share it, all nine characters play the same
+ * clip set and one authored graph, foot-IK rig, attachment slot or ragdoll layout serves all of
+ * them. There is no second standard to keep in sync.
+ *
+ * A rig on a different scheme (Quaternius aliens, Mixamo exports) is not rewritten: its bones are
+ * *mapped* slot by slot onto the standard's names, and what it does not have is reported rather
+ * than guessed. A rig missing every leg slot can still be driven on its spine and head; a rig
+ * missing a slot never silently borrows a neighbour's bone.
+ */
+/** Every standard slot, in parent-before-child order. */
+export const SKELETON_SLOTS = [
+    "root",
+    "hips",
+    "spine",
+    "chest",
+    "head",
+    "upperArm.l",
+    "upperArm.r",
+    "lowerArm.l",
+    "lowerArm.r",
+    "hand.l",
+    "hand.r",
+    "handSlot.l",
+    "handSlot.r",
+    "upperLeg.l",
+    "upperLeg.r",
+    "lowerLeg.l",
+    "lowerLeg.r",
+    "foot.l",
+    "foot.r",
+    "toes.l",
+    "toes.r",
+];
+/** The parent slot of each slot that has one; `root` has none. */
+export const SKELETON_PARENT = {
+    hips: "root",
+    spine: "hips",
+    chest: "spine",
+    head: "chest",
+    "upperArm.l": "chest",
+    "upperArm.r": "chest",
+    "lowerArm.l": "upperArm.l",
+    "lowerArm.r": "upperArm.r",
+    "hand.l": "lowerArm.l",
+    "hand.r": "lowerArm.r",
+    "handSlot.l": "hand.l",
+    "handSlot.r": "hand.r",
+    "upperLeg.l": "hips",
+    "upperLeg.r": "hips",
+    "lowerLeg.l": "upperLeg.l",
+    "lowerLeg.r": "upperLeg.r",
+    "foot.l": "lowerLeg.l",
+    "foot.r": "lowerLeg.r",
+    "toes.l": "foot.l",
+    "toes.r": "foot.r",
+};
+/**
+ * The one humanoid skeleton standard. Bone names are the authored KayKit names; the loaded
+ * hierarchy spells them without `.` and `resolveRigNode` accepts either.
+ *
+ * @capability skeleton-standard the shared humanoid bone standard every rigged character maps onto
+ */
+export const SKELETON_STANDARD = {
+    id: "kaykit-humanoid",
+    label: "KayKit character rig (adventurers + skeletons)",
+    slots: {
+        root: "root",
+        hips: "hips",
+        spine: "spine",
+        chest: "chest",
+        head: "head",
+        "upperArm.l": "upperarm.l",
+        "upperArm.r": "upperarm.r",
+        "lowerArm.l": "lowerarm.l",
+        "lowerArm.r": "lowerarm.r",
+        "hand.l": "hand.l",
+        "hand.r": "hand.r",
+        "handSlot.l": "handslot.l",
+        "handSlot.r": "handslot.r",
+        "upperLeg.l": "upperleg.l",
+        "upperLeg.r": "upperleg.r",
+        "lowerLeg.l": "lowerleg.l",
+        "lowerLeg.r": "lowerleg.r",
+        "foot.l": "foot.l",
+        "foot.r": "foot.r",
+        "toes.l": "toes.l",
+        "toes.r": "toes.r",
+    },
+};
+/** Prefixes stripped from a bone name before matching: exporter scopes, not rig vocabulary. */
+const NAME_PREFIXES = ["mixamorig", "armature"];
+/**
+ * The standard itself, as a scheme: a KayKit rig already is the standard, so its own names are the
+ * candidates. Both authored (`upperleg.l`) and runtime (`upperlegl`) spellings are accepted.
+ *
+ * @capability skeleton-standard map a rig on the standard scheme onto the standard's slots
+ */
+export const KAYKIT_SCHEME = {
+    id: "kaykit-humanoid",
+    label: "KayKit character rig",
+    source: "KayKit Adventurers / Skeletons (CC0)",
+    slots: Object.fromEntries(SKELETON_SLOTS.filter((slot) => SKELETON_STANDARD.slots[slot] !== undefined).map((slot) => {
+        const authored = SKELETON_STANDARD.slots[slot];
+        return [slot, [authored, runtimeBoneName(authored)]];
+    })),
+};
+/**
+ * Mixamo exports (`mixamorig*` names, or the same names without the prefix). Mixamo has a neck and
+ * a shoulder per side, which the standard folds into `chest` and `upperArm`; its toe is
+ * `ToeBase`, which is the standard's `toes`. Mixamo's topmost bone is `Hips`, so `root` and `hips`
+ * both resolve to it — a rig on this scheme has no bone above the pelvis.
+ */
+export const MIXAMO_SCHEME = {
+    id: "mixamo",
+    label: "Mixamo humanoid",
+    source: "Mixamo auto-rig exports (per-asset licence)",
+    slots: {
+        root: ["Hips"],
+        hips: ["Hips"],
+        spine: ["Spine"],
+        chest: ["Spine2", "Spine1"],
+        head: ["Head"],
+        "upperArm.l": ["LeftArm"],
+        "upperArm.r": ["RightArm"],
+        "lowerArm.l": ["LeftForeArm"],
+        "lowerArm.r": ["RightForeArm"],
+        "hand.l": ["LeftHand"],
+        "hand.r": ["RightHand"],
+        "upperLeg.l": ["LeftUpLeg"],
+        "upperLeg.r": ["RightUpLeg"],
+        "lowerLeg.l": ["LeftLeg"],
+        "lowerLeg.r": ["RightLeg"],
+        "foot.l": ["LeftFoot"],
+        "foot.r": ["RightFoot"],
+        "toes.l": ["LeftToeBase"],
+        "toes.r": ["RightToeBase"],
+    },
+};
+/**
+ * Quaternius sci-fi aliens: a `Root` plus a `Spine_1..Spine_6` chain, a `Neck` and a `Head`. The
+ * pack ships no arms and no legs, so those slots stay empty and the alien can only be driven on
+ * its spine and head. That is the honest mapping: the pack's own clip set is `Alien_Idle` alone.
+ */
+export const QUATERNIUS_ALIEN_SCHEME = {
+    id: "quaternius-alien",
+    label: "Quaternius sci-fi alien",
+    source: "Quaternius Modular Sci-Fi (CC0)",
+    slots: {
+        root: ["Root"],
+        hips: ["Spine_1"],
+        spine: ["Spine_3", "Spine_2"],
+        chest: ["Spine_5", "Spine_4"],
+        head: ["Head"],
+    },
+};
+/** Every scheme the engine ships a mapping for, keyed by {@link RigScheme.id}. */
+export const RIG_SCHEMES = {
+    [KAYKIT_SCHEME.id]: KAYKIT_SCHEME,
+    [MIXAMO_SCHEME.id]: MIXAMO_SCHEME,
+    [QUATERNIUS_ALIEN_SCHEME.id]: QUATERNIUS_ALIEN_SCHEME,
+};
+/**
+ * The runtime name GLTFLoader gives an authored bone name: three's `PropertyBinding.sanitizeNodeName`
+ * strips `[ ] . : /`, so the authored `upperleg.l` loads as `upperlegl`.
+ *
+ * @capability skeleton-standard convert an authored bone name to its loaded runtime name
+ */
+export function runtimeBoneName(authored) {
+    return authored.replace(/[[\].:/]/g, "");
+}
+/** Lowercase alphanumerics of a bone name, with exporter scope prefixes removed. */
+function matchKey(name) {
+    let key = name.toLowerCase().replace(/[^a-z0-9]/g, "");
+    for (const prefix of NAME_PREFIXES) {
+        if (key.startsWith(prefix) && key.length > prefix.length)
+            key = key.slice(prefix.length);
+    }
+    return key;
+}
+/**
+ * Maps a rig's bone names onto {@link SKELETON_STANDARD} through one {@link RigScheme}. Each slot
+ * takes the first candidate that resolves; a candidate list is tried in order, so a scheme can name
+ * a preferred bone and fall back. Bones that fill no slot come back in `unmapped`, and slots the rig
+ * cannot fill in `missing` — the caller decides whether a partial map is usable.
+ *
+ * @capability skeleton-standard map any CC0 rig's bones onto the shared humanoid slots
+ */
+export function mapRigToStandard(bones, scheme = KAYKIT_SCHEME) {
+    const resolved = typeof scheme === "string" ? RIG_SCHEMES[scheme] : scheme;
+    if (resolved === undefined)
+        throw new Error(`unknown rig scheme "${String(scheme)}"; known: ${Object.keys(RIG_SCHEMES).join(", ")}`);
+    const byKey = new Map();
+    for (const bone of bones) {
+        const key = matchKey(bone);
+        if (key.length > 0 && !byKey.has(key))
+            byKey.set(key, bone);
+    }
+    const slots = {};
+    const missing = [];
+    const used = new Set();
+    for (const slot of SKELETON_SLOTS) {
+        const candidates = resolved.slots[slot];
+        if (candidates === undefined) {
+            missing.push(slot);
+            continue;
+        }
+        let found;
+        for (const candidate of candidates) {
+            const bone = byKey.get(matchKey(candidate));
+            if (bone !== undefined) {
+                found = bone;
+                break;
+            }
+        }
+        if (found === undefined)
+            missing.push(slot);
+        else {
+            slots[slot] = found;
+            used.add(found);
+        }
+    }
+    return { scheme: resolved.id, slots, missing, unmapped: bones.filter((bone) => !used.has(bone)) };
+}
+/**
+ * Per-slot length ratios that stretch a source rig's bone chain onto the standard's proportions, so
+ * a retargeted clip moves both rigs the same distance rather than the same angle. Slots with no
+ * counterpart on either side are omitted; a source length of zero is skipped instead of dividing.
+ *
+ * @capability skeleton-standard scale a retargeted clip to the target rig's bone proportions
+ */
+export function retargetBoneScales(source, target) {
+    const targetBySlot = new Map(target.map((entry) => [entry.slot, entry.length]));
+    const scales = {};
+    for (const entry of source) {
+        const to = targetBySlot.get(entry.slot);
+        if (to === undefined || entry.length <= 0 || to <= 0)
+            continue;
+        scales[entry.slot] = to / entry.length;
+    }
+    return scales;
+}
+/** Track-name property suffixes three writes on an `AnimationClip`. */
+const TRACK_PROPERTIES = ["quaternion", "position", "scale", "morphTargetInfluences"];
+/**
+ * Bone-name prefixes for a set of standard slots, for an {@link AnimLayer.mask}. A slot on one side
+ * contributes its side-less prefix (`upperLeg.l` → `upperleg`), which matches both sides' tracks; an
+ * unsided slot contributes its own runtime name. Masking by slot means a rig mapped onto the
+ * standard is masked without hand-typing its bone names.
+ *
+ * @capability skeleton-standard build a layer mask from the standard's own slots
+ */
+export function standardBoneMask(slots) {
+    const out = new Set();
+    for (const slot of slots) {
+        const bone = SKELETON_STANDARD.slots[slot];
+        if (bone === undefined)
+            continue;
+        const sided = slot.endsWith(".l") || slot.endsWith(".r");
+        out.add(sided ? slot.slice(0, -2).toLowerCase() : runtimeBoneName(bone));
+    }
+    return [...out];
+}
+/** Standard slots an upper-body action layer drives: spine, chest, head and both arms. */
+export const UPPER_BODY_SLOTS = [
+    "spine",
+    "chest",
+    "head",
+    "upperArm.l",
+    "upperArm.r",
+    "lowerArm.l",
+    "lowerArm.r",
+    "hand.l",
+    "hand.r",
+    "handSlot.l",
+    "handSlot.r",
+];
+/** Standard slots a lower-body layer drives: hips, both legs and both feet. */
+export const LOWER_BODY_SLOTS = [
+    "hips",
+    "upperLeg.l",
+    "upperLeg.r",
+    "lowerLeg.l",
+    "lowerLeg.r",
+    "foot.l",
+    "foot.r",
+    "toes.l",
+    "toes.r",
+];
+/** Layer mask for an upper-body action layer (aim, reload, hit reaction) on a standard rig. */
+export const UPPER_BODY_MASK = standardBoneMask(UPPER_BODY_SLOTS);
+/** Layer mask for a lower-body layer on a standard rig. */
+export const LOWER_BODY_MASK = standardBoneMask(LOWER_BODY_SLOTS);
+/**
+ * Renames a clip's tracks from a rig's own bone names onto the standard's, so one authored clip
+ * plays on a mapped rig. The emitted node is the **runtime** bone name (see {@link runtimeBoneName}),
+ * which is what both the loaded scene graph and the loaded clips spell. A track whose node fills no
+ * slot is dropped (`null` in the result) rather than left pointing at a bone the rig does not have;
+ * a track whose property is not one of the four three writes is dropped too, since renaming it
+ * would not make it resolvable.
+ *
+ * @capability skeleton-standard rename an animation clip's tracks onto a mapped rig
+ */
+export function retargetTracks(tracks, map) {
+    const bySlot = new Map();
+    for (const slot of SKELETON_SLOTS) {
+        const bone = map.slots[slot];
+        if (bone !== undefined)
+            bySlot.set(matchKey(bone), slot);
+    }
+    return tracks.map((track) => {
+        const split = track.lastIndexOf(".");
+        if (split <= 0)
+            return null;
+        const slot = bySlot.get(matchKey(track.slice(0, split)));
+        const property = track.slice(split + 1);
+        if (slot === undefined || !TRACK_PROPERTIES.includes(property))
+            return null;
+        const target = SKELETON_STANDARD.slots[slot];
+        return target === undefined ? null : `${runtimeBoneName(target)}.${property}`;
+    });
+}

package/dist/combat/damageRuntime.d.ts

@@ -1,3 +1,4 @@
+import type { DamageAppliedEvent, GameEvents } from "../game/events.js";
 import type { StatusApplicationOutcome, StatusInstance } from "./statusApplication.js";
 import { readDamageTable, type DamageTableDef, type DamageTableRow } from "./damageTable.js";
 import { type HitZoneResolution, type HitZoneTable } from "./hitZones.js";
@@ -78,6 +79,14 @@ export interface DamageRuntimeConfig {
     armorStat?: string;
     /** Injected `[0,1)` stream for crit rolls. Omitting it warns once and is not replayable. */
     rng?: () => number;
+    /** Bus every applied damage is announced on as `combat.damage`. Omitted, events reach only the probe. */
+    events?: GameEvents;
+    /**
+     * A target's live health, read once per application before the caller applies it. The event's
+     * `remaining` is that value minus the damage dealt, and `lethal` is `remaining <= 0`; omit the
+     * reader and every event reports `remaining: null` and `lethal: false`.
+     */
+    healthOf?: (targetId: string) => number | null;
     /** Register a one-line devtools probe under this name. */
     devtoolsName?: string;
 }
@@ -123,6 +132,8 @@ export interface DamageRuntime {
     restore(next: DamageRuntimeState): void;
     /** Carried statuses, for a HUD or a test. */
     statusesOf(targetId: string): readonly StatusInstance[];
+    /** The last `limit` damage applications this model announced, oldest first. Default all it keeps. */
+    recentDamage(limit?: number): readonly DamageAppliedEvent[];
     stats(): {
         targets: number;
         hits: number;
@@ -143,7 +154,9 @@ export declare class UnknownTargetProfileError extends Error {
 /**
  * Build a damage model from data. The number a hit lands is
  * `base × zone multiplier × type multiplier × (1 − armor mitigation)`; statuses tick through the
- * same table and armor, so a burn on an armored target is mitigated like a bullet.
+ * same table and armor, so a burn on an armored target is mitigated like a bullet. Every application
+ * — a hit or a status tick — is announced as `combat.damage` carrying the target, source, type,
+ * amount, absorbed, remaining health and a lethal flag, so a HUD names the blow instead of guessing.
  *
  * @capability damage-runtime resolve hits through a damage table, hit zones, and armor, and tick data-defined statuses with declared stacking
  */

package/dist/combat/damageRuntime.js

@@ -3,6 +3,10 @@ import { resolveRng } from "../random/resolveRng.js";
 import { assertDamageTable, readDamageTable, resolveTableDamage, } from "./damageTable.js";
 import { assertHitZoneTable, hitZoneMultiplier, resolveHitZone, } from "./hitZones.js";
 import { createStatusRuntime, } from "./statusRuntime.js";
+/** How many recent damage applications the runtime keeps for `recentDamage` and its probe line. */
+const RECENT_DAMAGE_LIMIT = 8;
+/** Most applications the probe line spells out; the ring keeps more than it prints. */
+const RECENT_DAMAGE_PROBE_LINES = 3;
 /** Raised when a hit names a target that was never registered — a wiring error, not a 0-damage hit.
  * @capability damage-target-unknown reject a hit on a target with no registered resistance or armor profile
  */
@@ -17,7 +21,9 @@ export class UnknownTargetProfileError extends Error {
 /**
  * Build a damage model from data. The number a hit lands is
  * `base × zone multiplier × type multiplier × (1 − armor mitigation)`; statuses tick through the
- * same table and armor, so a burn on an armored target is mitigated like a bullet.
+ * same table and armor, so a burn on an armored target is mitigated like a bullet. Every application
+ * — a hit or a status tick — is announced as `combat.damage` carrying the target, source, type,
+ * amount, absorbed, remaining health and a lethal flag, so a HUD names the blow instead of guessing.
  *
  * @capability damage-runtime resolve hits through a damage table, hit zones, and armor, and tick data-defined statuses with declared stacking
  */
@@ -25,6 +31,8 @@ export function createDamageRuntime(config) {
     assertDamageTable(config.table);
     assertHitZoneTable(config.zones);
     const rng = resolveRng(config.rng, "createDamageRuntime");
+    const bus = config.events;
+    const healthOf = config.healthOf;
     let table = config.table;
     let zones = config.zones;
     let armorStat = config.armorStat ?? "armor";
@@ -34,6 +42,7 @@ export function createDamageRuntime(config) {
     let dealt = 0;
     let statusTicks = 0;
     let last = null;
+    const recent = [];
     let statusRuntime;
     statusRuntime = createStatusRuntime({
         statuses: config.statuses ?? [],
@@ -60,14 +69,50 @@ export function createDamageRuntime(config) {
     function resolveStatusDamage(tick) {
         if (!targets.has(tick.target))
             return tick.amount;
-        return scaleAt(tick.target, tick.channel, tick.amount).damage ?? 0;
+        const dealt = scaleAt(tick.target, tick.channel, tick.amount).damage ?? 0;
+        announce({
+            target: tick.target,
+            type: tick.channel,
+            incoming: tick.amount,
+            dealt,
+            ...(tick.source !== undefined ? { source: tick.source } : {}),
+            status: tick.status,
+        });
+        return dealt;
+    }
+    function announce(input) {
+        const health = healthOf?.(input.target) ?? null;
+        const remaining = health === null ? null : Math.max(0, health - input.dealt);
+        const event = {
+            target: input.target,
+            ...(input.source !== undefined ? { source: input.source } : {}),
+            type: input.type,
+            amount: input.dealt,
+            absorbed: Math.max(0, input.incoming - input.dealt),
+            remaining,
+            lethal: remaining !== null && remaining <= 0,
+            ...(input.status !== undefined ? { status: input.status } : {}),
+        };
+        recent.push(event);
+        if (recent.length > RECENT_DAMAGE_LIMIT)
+            recent.shift();
+        bus?.emit("combat.damage", event);
+    }
+    function describe(event) {
+        const source = event.source === undefined ? "" : ` from ${event.source}`;
+        const status = event.status === undefined ? "" : ` ${event.status}`;
+        const left = event.remaining === null ? "" : ` → ${event.remaining.toFixed(0)}`;
+        return `${event.target} -${event.amount.toFixed(0)}${source}${status}${left}${event.lethal ? " LETHAL" : ""}`;
     }
     function probeLine() {
         const l = last;
         const tail = l === null
             ? "no hits"
             : `last ${l.type} ${l.base.toFixed(1)}→${l.damage.toFixed(1)} ${l.zone}${l.crit ? " crit" : ""}`;
-        return `${targets.size} targets · ${hits} hits ${crits} crits · ${statusTicks} status ticks · ${dealt.toFixed(0)} dealt · ${tail}`;
+        const events = recent.length === 0
+            ? ""
+            : ` · events ${recent.slice(-RECENT_DAMAGE_PROBE_LINES).map(describe).join(" | ")}`;
+        return `${targets.size} targets · ${hits} hits ${crits} crits · ${statusTicks} status ticks · ${dealt.toFixed(0)} dealt · ${tail}${events}`;
     }
     const unregister = config.devtoolsName === undefined
         ? null
@@ -86,7 +131,8 @@ export function createDamageRuntime(config) {
         },
         hit(input) {
             const zone = resolveHitZone(zones, input.zone, rng);
-            const row = scaleAt(input.target, input.type, input.base * zone.multiplier);
+            const incoming = input.base * zone.multiplier;
+            const row = scaleAt(input.target, input.type, incoming);
             const applied = [];
             for (const request of input.statuses ?? []) {
                 const statusId = typeof request === "string" ? request : request.id;
@@ -108,6 +154,13 @@ export function createDamageRuntime(config) {
                 crits += 1;
             dealt += damage;
             last = { type: input.type, base: input.base, damage, zone: zone.zone, crit: zone.crit };
+            announce({
+                target: input.target,
+                type: input.type,
+                incoming,
+                dealt: damage,
+                ...(input.source !== undefined ? { source: input.source } : {}),
+            });
             return {
                 target: input.target,
                 type: input.type,
@@ -197,8 +250,13 @@ export function createDamageRuntime(config) {
             crits = next.crits;
             dealt = next.dealt;
             last = next.last === null ? null : { ...next.last };
+            recent.length = 0;
         },
         statusesOf: (targetId) => statusRuntime.statusesOf(targetId),
+        recentDamage(limit) {
+            const count = limit === undefined ? recent.length : Math.max(0, Math.min(recent.length, Math.floor(limit)));
+            return recent.slice(recent.length - count);
+        },
         stats: () => ({ targets: targets.size, hits, crits, statusTicks, dealt }),
         dispose() {
             statusRuntime.dispose();

package/dist/combat/death.js

@@ -36,6 +36,8 @@ export function createDeathSystem(deps) {
                 event.userId = identity.userId;
             if (identity.displayName !== undefined)
                 event.displayName = identity.displayName;
+            const source = reason.kind === "environment" ? reason.attacker ?? reason.source : reason.source;
+            event.source = source;
             deps.events.emit("entity.died", event);
             const onDeath = normalizeOnDeath(deps.resolveOnDeath(instanceId, reason));
             const drops = [];
@@ -62,8 +64,10 @@ export function deathReasonFromEffect(ctx) {
     const killerUserId = ctx.userIdOf?.(ctx.from);
     if (killerUserId !== undefined) {
         return ctx.via?.item !== undefined
-            ? { kind: "player_kill", killerUserId, via: { item: ctx.via.item } }
-            : { kind: "player_kill", killerUserId };
+            ? { kind: "player_kill", killerUserId, source: ctx.from, via: { item: ctx.via.item } }
+            : { kind: "player_kill", killerUserId, source: ctx.from };
     }
-    return { kind: "environment", source: ctx.via?.item ?? "effect" };
+    return ctx.via?.item !== undefined
+        ? { kind: "environment", source: ctx.via.item, attacker: ctx.from }
+        : { kind: "environment", source: "effect", attacker: ctx.from };
 }

package/dist/combat/deathReason.d.ts

@@ -1,13 +1,19 @@
-/** Why an entity died — who or what gets credit, for drop/command rules and the `entity.died` event. */
+/**
+ * Why an entity died — who or what gets credit, for drop/command rules and the `entity.died` event.
+ * `source` names what dealt it: a player kill's killer instance id, or the hazard/item of an
+ * environment death; `attacker` carries the non-player entity's instance id when one dealt it.
+ */
 export type DeathReason = {
     kind: "player_kill";
     killerUserId: string;
+    source?: string;
     via?: {
         item?: string;
     };
 } | {
     kind: "environment";
     source: string;
+    attacker?: string;
 } | {
     kind: "self";
     source: string;

package/dist/combat/effects.d.ts

@@ -74,6 +74,26 @@ export interface AreaTarget {
     scale: number;
 }
 export declare function resolveAreaTargets(spatial: CombatSpatialDeps, input: AreaTargetInput, accept?: (instanceId: string) => boolean): AreaTarget[];
+/**
+ * One effect application that drained a target's pools, as an announcer needs it. The effect path
+ * has no damage table, so the caller names the channel (`effect`) and reads health its own way.
+ */
+export interface EffectDamageApplication {
+    /** The entity that took the drain. */
+    target: string;
+    /** Who dealt it: the effect's `from` instance id (attacker, hazard, projectile owner). */
+    source: string;
+    /** The effect id that landed (`"damage"`, `"bullet"`, `"fire"`). */
+    effect: string;
+    /** Magnitude before receive modifiers and area falloff. */
+    incoming: number;
+    /** Magnitude drained after modifiers, falloff and available pool headroom. */
+    dealt: number;
+    /** The last pool's current after the drain — the pool whose exhaustion is `lethal`. */
+    remaining: number | null;
+    /** True when the last pool reached its minimum. */
+    lethal: boolean;
+}
 export interface EffectSystemDeps {
     resolveReceive(instanceId: string): ReceiveMap | null | undefined;
     /** Preferred portable bridge to caller-owned resource state. */
@@ -93,6 +113,11 @@ export interface EffectSystemDeps {
      */
     resolveSlainIdentity?(instanceId: string): SlainIdentity | null | undefined;
     onLethal?(instanceId: string, ctx: LethalContext): void;
+    /**
+     * Called once per target a draining effect lands on, after its pools changed and before
+     * {@link onLethal} despawns it. Restorative applications (`via.amount` below zero) stay silent.
+     */
+    onDamage?(application: EffectDamageApplication): void;
 }
 export interface EffectSystem {
     canReceive(instanceId: string, effect: string, magnitude?: number): string | null;

package/dist/combat/effects.js

@@ -103,6 +103,22 @@ export function createEffectSystem(deps) {
         if (canReceive(instanceId, effect, drainMagnitude) !== null)
             return null;
         const result = drainPools(instanceId, effect, rule, drainMagnitude);
+        if (drainMagnitude > 0 && deps.onDamage !== undefined) {
+            let dealt = 0;
+            for (const delta of result.applied)
+                if (delta.delta < 0)
+                    dealt -= delta.delta;
+            const lastStatId = rule.order[rule.order.length - 1];
+            deps.onDamage({
+                target: instanceId,
+                source: from,
+                effect,
+                incoming: drainMagnitude,
+                dealt,
+                remaining: statPools.get(instanceId, lastStatId)?.current ?? null,
+                lethal: result.lethal,
+            });
+        }
         if (result.lethal) {
             // Capture identity before onLethal, which runs the death system and despawns the target.
             const slain = deps.resolveSlainIdentity?.(instanceId);

package/dist/combat/statusRuntime.d.ts

@@ -44,6 +44,8 @@ export interface StatusDamageTick {
     amount: number;
     /** What the caller's pipeline reported as dealt; equals `amount` when no pipeline was supplied. */
     dealt: number;
+    /** Who applied the status that is ticking, when known — a burn names its arsonist. */
+    source?: string;
 }
 /** A stat tick: a per-stack delta the caller reads while the status lives. */
 export interface StatusStatTick {

package/dist/combat/statusRuntime.js

@@ -87,6 +87,7 @@ export function createStatusRuntime(options) {
             channel: effect.channel,
             amount,
             dealt: amount,
+            ...(instance.source !== undefined ? { source: instance.source } : {}),
         };
         if (options.applyDamage !== undefined)
             tick.dealt = options.applyDamage(tick);