@its-not-rocket-science/ananke 0.1.0

package/dist/src/narrative.js

@@ -0,0 +1,257 @@
+// src/narrative.ts — Phase 18: Combat Narrative Layer
+//
+// Pure translation module — no sim/kernel dependencies.
+// Converts TraceEvent streams and injury snapshots into human-readable text.
+import { SCALE, q } from "./units.js";
+import { TraceKinds } from "./sim/kinds.js";
+// ── Internal helpers ──────────────────────────────────────────────────────────
+function nameOf(id, cfg) {
+    return cfg.nameMap?.get(id) ?? `combatant ${id}`;
+}
+function isYouSubject(id, cfg) {
+    return cfg.nameMap?.get(id) === "you";
+}
+// Verb stems and third-person conjugations
+const THIRD_PERSON = {
+    strike: "strikes",
+    slash: "slashes",
+    stab: "stabs",
+    bludgeon: "bludgeons",
+    shoot: "shoots",
+    snipe: "snipes",
+    blast: "blasts",
+    grapple: "grapples",
+};
+function conjugate(stem, youSubject) {
+    if (youSubject)
+        return stem;
+    return THIRD_PERSON[stem] ?? stem + "s";
+}
+function meleeStem(profile) {
+    if (!profile)
+        return "strike";
+    if (profile.penetrationBias >= q(0.65))
+        return "stab";
+    if (profile.structuralFrac >= q(0.50))
+        return "bludgeon";
+    if (profile.surfaceFrac >= q(0.50))
+        return "slash";
+    return "strike";
+}
+function rangedStem(profile) {
+    if (!profile)
+        return "shoot";
+    if (profile.penetrationBias >= q(0.80))
+        return "snipe";
+    if (profile.surfaceFrac >= q(0.55))
+        return "blast";
+    return "shoot";
+}
+function regionPhrase(region) {
+    switch (region) {
+        case "head": return "in the head";
+        case "torso": return "in the torso";
+        case "arm": return "in the arm";
+        case "leg": return "in the leg";
+        default: return `on the ${region}`;
+    }
+}
+function energyQualifier(energy_J) {
+    if (energy_J >= 500)
+        return "devastatingly";
+    if (energy_J >= 200)
+        return "powerfully";
+    return "";
+}
+function narrateAttack(ev, cfg) {
+    const att = nameOf(ev.attackerId, cfg);
+    const tgt = nameOf(ev.targetId, cfg);
+    if (ev.blocked) {
+        if (cfg.verbosity === "terse")
+            return null;
+        return `${att} attacks ${tgt} — blocked`;
+    }
+    if (ev.parried) {
+        if (cfg.verbosity === "terse")
+            return null;
+        return `${att} attacks ${tgt} — parried`;
+    }
+    if (ev.shieldBlocked) {
+        if (cfg.verbosity === "terse")
+            return null;
+        return `${att} attacks ${tgt} — hits shield`;
+    }
+    // Landed hit
+    if (ev.energy_J < 10) {
+        const armourNote = ev.armoured ? " (armoured)" : "";
+        return `${att} barely grazes ${tgt} ${regionPhrase(ev.region)}${armourNote}`;
+    }
+    const profile = ev.weaponId ? cfg.weaponProfiles?.get(ev.weaponId) : undefined;
+    const isYou = isYouSubject(ev.attackerId, cfg);
+    const stem = meleeStem(profile);
+    const verb = conjugate(stem, isYou);
+    const qual = energyQualifier(ev.energy_J);
+    const region = regionPhrase(ev.region);
+    const armour = ev.armoured ? " (armoured)" : "";
+    return qual
+        ? `${att} ${qual} ${verb} ${tgt} ${region}${armour}`
+        : `${att} ${verb} ${tgt} ${region}${armour}`;
+}
+function narrateProjectileHit(ev, cfg) {
+    const shooter = nameOf(ev.shooterId, cfg);
+    const target = nameOf(ev.targetId, cfg);
+    const distM = (ev.distance_m / SCALE.m).toFixed(0);
+    if (!ev.hit) {
+        if (cfg.verbosity === "terse")
+            return null;
+        if (ev.suppressed)
+            return `${shooter} fires at ${target} (suppressive, ${distM}m)`;
+        return `${shooter} misses ${target} at ${distM}m`;
+    }
+    const profile = ev.weaponId ? cfg.weaponProfiles?.get(ev.weaponId) : undefined;
+    const isYou = isYouSubject(ev.shooterId, cfg);
+    const stem = rangedStem(profile);
+    const verb = conjugate(stem, isYou);
+    const region = ev.region ? ` in the ${ev.region}` : "";
+    return `${shooter} ${verb} ${target}${region} at ${distM}m`;
+}
+function narrateGrapple(ev, cfg) {
+    const att = nameOf(ev.attackerId, cfg);
+    const tgt = nameOf(ev.targetId, cfg);
+    switch (ev.phase) {
+        case "start":
+            if (cfg.verbosity === "terse")
+                return null;
+            return `${att} grapples ${tgt}`;
+        case "tick":
+            if (cfg.verbosity !== "verbose")
+                return null;
+            return `${att} maintains grapple on ${tgt}`;
+        case "break":
+            if (cfg.verbosity === "terse")
+                return null;
+            return `${tgt} breaks free from ${att}`;
+    }
+}
+// ── Public API ────────────────────────────────────────────────────────────────
+/**
+ * Narrate a single trace event.
+ * Returns null for events that should be omitted at the current verbosity level.
+ */
+export function narrateEvent(ev, cfg) {
+    switch (ev.kind) {
+        case TraceKinds.Attack:
+            return narrateAttack(ev, cfg);
+        case TraceKinds.ProjectileHit:
+            return narrateProjectileHit(ev, cfg);
+        case TraceKinds.KO:
+            return `${nameOf(ev.entityId, cfg)} is knocked unconscious`;
+        case TraceKinds.Death:
+            return `${nameOf(ev.entityId, cfg)} dies`;
+        case TraceKinds.MoraleRoute:
+            return `${nameOf(ev.entityId, cfg)} breaks and flees`;
+        case TraceKinds.MoraleRally:
+            return `${nameOf(ev.entityId, cfg)} rallies`;
+        case TraceKinds.Grapple:
+            return narrateGrapple(ev, cfg);
+        case TraceKinds.WeaponBind:
+            if (cfg.verbosity === "terse")
+                return null;
+            return `${nameOf(ev.attackerId, cfg)} and ${nameOf(ev.targetId, cfg)} blades lock (${ev.durationTicks} ticks)`;
+        case TraceKinds.WeaponBindBreak:
+            if (cfg.verbosity === "terse")
+                return null;
+            return `${nameOf(ev.entityId, cfg)} breaks the bind (${ev.reason})`;
+        case TraceKinds.Fracture:
+            return `${nameOf(ev.entityId, cfg)}'s ${ev.region} is fractured`;
+        case TraceKinds.BlastHit:
+            return `${nameOf(ev.entityId, cfg)} caught in explosion (${ev.blastEnergy_J}J, ${ev.fragHits} fragments)`;
+        case TraceKinds.TreatmentApplied:
+            if (cfg.verbosity !== "verbose")
+                return null;
+            return `${nameOf(ev.treaterId, cfg)} treats ${nameOf(ev.targetId, cfg)} (${ev.action}${ev.regionId ? ` — ${ev.regionId}` : ""})`;
+        case TraceKinds.CapabilityActivated:
+            if (cfg.verbosity !== "verbose")
+                return null;
+            return `${nameOf(ev.entityId, cfg)} activates ${ev.effectId}`;
+        case TraceKinds.CapabilitySuppressed:
+            if (cfg.verbosity !== "verbose")
+                return null;
+            return `${nameOf(ev.entityId, cfg)}'s ${ev.effectId} is suppressed`;
+        case TraceKinds.CastInterrupted:
+            if (cfg.verbosity !== "verbose")
+                return null;
+            return `${nameOf(ev.entityId, cfg)}'s concentration breaks`;
+        default:
+            return null;
+    }
+}
+/**
+ * Convert a sequence of trace events into a list of narrative lines.
+ * Events that return null from narrateEvent are omitted.
+ */
+export function buildCombatLog(events, cfg) {
+    const lines = [];
+    for (const ev of events) {
+        const line = narrateEvent(ev, cfg);
+        if (line !== null)
+            lines.push(line);
+    }
+    return lines;
+}
+/**
+ * Summarise an entity's injury state as a short descriptive phrase.
+ */
+export function describeInjuries(injury) {
+    if (injury.dead)
+        return "Fatal";
+    const lines = [];
+    if (injury.consciousness < q(0.20))
+        lines.push("Unconscious");
+    else if (injury.consciousness < q(0.50))
+        lines.push("Semi-conscious");
+    if (injury.fluidLoss > q(0.60))
+        lines.push("Severe hemorrhage");
+    else if (injury.fluidLoss > q(0.30))
+        lines.push("Significant blood loss");
+    else if (injury.fluidLoss > q(0.10))
+        lines.push("Minor bleeding");
+    if (injury.shock > q(0.60))
+        lines.push("Deep shock");
+    else if (injury.shock > q(0.30))
+        lines.push("Shock");
+    for (const [region, ri] of Object.entries(injury.byRegion)) {
+        if (ri.fractured)
+            lines.push(`${region} fractured`);
+    }
+    if (lines.length === 0)
+        return "No significant injuries";
+    return lines.join("; ");
+}
+/**
+ * Produce a one-line outcome summary for a completed engagement.
+ */
+export function describeCombatOutcome(combatants, tickCount) {
+    const teams = new Map();
+    for (const c of combatants) {
+        if (!teams.has(c.teamId))
+            teams.set(c.teamId, { alive: 0, total: 0 });
+        const t = teams.get(c.teamId);
+        t.total++;
+        if (!c.injury.dead && c.injury.consciousness > q(0.20))
+            t.alive++;
+    }
+    const surviving = [...teams.entries()].filter(([, t]) => t.alive > 0);
+    const defeated = [...teams.entries()].filter(([, t]) => t.alive === 0);
+    const suffix = tickCount !== undefined ? ` (${tickCount} ticks)` : "";
+    if (surviving.length === 0)
+        return "All combatants down" + suffix;
+    if (defeated.length === 0) {
+        const parts = [...teams.entries()]
+            .map(([id, t]) => `Team ${id}: ${t.alive}/${t.total} standing`);
+        return parts.join("; ") + suffix;
+    }
+    const winners = surviving.map(([id]) => `Team ${id}`).join(", ");
+    const losers = defeated.map(([id]) => `Team ${id}`).join(", ");
+    return `${winners} wins — ${losers} defeated${suffix}`;
+}

package/dist/src/party.d.ts

@@ -0,0 +1,70 @@
+import type { Q } from "./units.js";
+import type { Entity } from "./sim/entity.js";
+import type { Inventory } from "./inventory.js";
+/** A named adventuring party with a leader and members. */
+export interface Party {
+    id: string;
+    name: string;
+    leaderId: number;
+    memberIds: Set<number>;
+    sharedInventory?: Inventory | undefined;
+}
+/** Party-to-party standing (similar to faction standing). */
+export type PartyStanding = Q;
+/** Registry of all parties and their relationships. */
+export interface PartyRegistry {
+    parties: Map<string, Party>;
+    /** partyId → (partyId → standing) */
+    relationships: Map<string, Map<string, PartyStanding>>;
+}
+export declare const PARTY_STANDING_HOSTILE: Q;
+export declare const PARTY_STANDING_RIVAL: Q;
+export declare const PARTY_STANDING_NEUTRAL: Q;
+export declare const PARTY_STANDING_ALLY: Q;
+export declare const PARTY_STANDING_ALLIED: Q;
+/** Standing below this → parties treat each other as hostile. */
+export declare const PARTY_HOSTILE_THRESHOLD: Q;
+/** Standing above this → parties will not initiate combat. */
+export declare const PARTY_FRIENDLY_THRESHOLD: Q;
+/** Create an empty party registry. */
+export declare function createPartyRegistry(): PartyRegistry;
+/** Create a new party and add it to the registry. */
+export declare function createParty(registry: PartyRegistry, partyId: string, name: string, leaderId: number): Party;
+/** Add an entity to a party (also sets entity.party if entity is mutable). */
+export declare function addPartyMember(registry: PartyRegistry, partyId: string, entityId: number, entity?: Entity): void;
+/** Remove an entity from a party. */
+export declare function removePartyMember(registry: PartyRegistry, partyId: string, entityId: number, entity?: Entity): void;
+/** Change party leader. */
+export declare function setPartyLeader(registry: PartyRegistry, partyId: string, newLeaderId: number): void;
+/** Get party for an entity, if any. */
+export declare function getPartyForEntity(registry: PartyRegistry, entityId: number): Party | undefined;
+/** Get party ID for an entity, if any. */
+export declare function getPartyIdForEntity(registry: PartyRegistry, entityId: number): string | undefined;
+/** Get standing between two parties (default NEUTRAL). */
+export declare function getPartyStanding(registry: PartyRegistry, partyAId: string, partyBId: string): PartyStanding;
+/** Set standing between two parties (clamped). */
+export declare function setPartyStanding(registry: PartyRegistry, partyAId: string, partyBId: string, standing: PartyStanding): void;
+/** Set mutual standing between two parties (same both ways). */
+export declare function setMutualPartyStanding(registry: PartyRegistry, partyAId: string, partyBId: string, standing: PartyStanding): void;
+/** Determine if two parties are hostile based on standing threshold. */
+export declare function arePartiesHostile(registry: PartyRegistry, partyAId: string, partyBId: string): boolean;
+/** Determine if two parties are friendly (won't attack). */
+export declare function arePartiesFriendly(registry: PartyRegistry, partyAId: string, partyBId: string): boolean;
+/** Get standing between two entities based on party membership. */
+export declare function getPartyStandingBetweenEntities(registry: PartyRegistry, a: Entity, b: Entity): PartyStanding | undefined;
+/** Check if two entities are hostile based on party standing. */
+export declare function areEntitiesHostileByParty(registry: PartyRegistry, a: Entity, b: Entity): boolean;
+/** Check if two entities are friendly based on party standing. */
+export declare function areEntitiesFriendlyByParty(registry: PartyRegistry, a: Entity, b: Entity): boolean;
+/**
+ * Compute loyalty of a companion (entity) towards its party leader.
+ * Loyalty is derived from relationship affinity and trust (if relationship exists).
+ * Returns Q in [0, SCALE.Q] where 0 =背叛 (betrayal imminent), SCALE.Q = absolute loyalty.
+ */
+export declare function computeCompanionLoyalty(companion: Entity, leaderId: number, relationshipGraph?: import("./relationships.js").RelationshipGraph): Q;
+export declare function getPartySharedInventory(registry: PartyRegistry, partyId: string): Inventory | undefined;
+export declare function ensurePartySharedInventory(registry: PartyRegistry, partyId: string): Inventory;
+/** Serialize party registry to JSON string. */
+export declare function serializePartyRegistry(registry: PartyRegistry): string;
+/** Deserialize party registry from JSON string. */
+export declare function deserializePartyRegistry(json: string): PartyRegistry;

package/dist/src/party.js

@@ -0,0 +1,226 @@
+// src/party.ts — Phase 48: Multi-Party Dynamics
+//
+// Party system for adventuring groups, companion loyalty, and inter-party conflict.
+// Parties are sub-groups within factions (or cross-faction) that share goals,
+// inventory, and have relationships with other parties.
+import { SCALE, q, clampQ } from "./units.js";
+import { createInventory, addContainer, createContainer } from "./inventory.js";
+// ── Standing constants ────────────────────────────────────────────────────────
+export const PARTY_STANDING_HOSTILE = q(0.0);
+export const PARTY_STANDING_RIVAL = q(0.20);
+export const PARTY_STANDING_NEUTRAL = q(0.50);
+export const PARTY_STANDING_ALLY = q(0.70);
+export const PARTY_STANDING_ALLIED = q(1.0);
+/** Standing below this → parties treat each other as hostile. */
+export const PARTY_HOSTILE_THRESHOLD = q(0.30);
+/** Standing above this → parties will not initiate combat. */
+export const PARTY_FRIENDLY_THRESHOLD = q(0.70);
+// ── Factory ───────────────────────────────────────────────────────────────────
+/** Create an empty party registry. */
+export function createPartyRegistry() {
+    return {
+        parties: new Map(),
+        relationships: new Map(),
+    };
+}
+/** Create a new party and add it to the registry. */
+export function createParty(registry, partyId, name, leaderId) {
+    if (registry.parties.has(partyId)) {
+        throw new Error(`Party ${partyId} already exists`);
+    }
+    const memberIds = new Set([leaderId]);
+    const party = { id: partyId, name, leaderId, memberIds, sharedInventory: undefined };
+    registry.parties.set(partyId, party);
+    // Initialize self-standing as allied
+    const selfRow = new Map();
+    selfRow.set(partyId, PARTY_STANDING_ALLIED);
+    registry.relationships.set(partyId, selfRow);
+    return party;
+}
+/** Add an entity to a party (also sets entity.party if entity is mutable). */
+export function addPartyMember(registry, partyId, entityId, entity) {
+    const party = registry.parties.get(partyId);
+    if (!party) {
+        throw new Error(`Party ${partyId} not found`);
+    }
+    party.memberIds.add(entityId);
+    if (entity) {
+        entity.party = partyId;
+    }
+}
+/** Remove an entity from a party. */
+export function removePartyMember(registry, partyId, entityId, entity) {
+    const party = registry.parties.get(partyId);
+    if (!party)
+        return;
+    party.memberIds.delete(entityId);
+    if (entity && entity.party === partyId) {
+        entity.party = undefined;
+    }
+    // If party becomes empty, remove it? Keep for now.
+}
+/** Change party leader. */
+export function setPartyLeader(registry, partyId, newLeaderId) {
+    const party = registry.parties.get(partyId);
+    if (!party) {
+        throw new Error(`Party ${partyId} not found`);
+    }
+    if (!party.memberIds.has(newLeaderId)) {
+        throw new Error(`New leader ${newLeaderId} is not a member of party ${partyId}`);
+    }
+    party.leaderId = newLeaderId;
+}
+/** Get party for an entity, if any. */
+export function getPartyForEntity(registry, entityId) {
+    for (const party of registry.parties.values()) {
+        if (party.memberIds.has(entityId)) {
+            return party;
+        }
+    }
+    return undefined;
+}
+/** Get party ID for an entity, if any. */
+export function getPartyIdForEntity(registry, entityId) {
+    for (const [partyId, party] of registry.parties.entries()) {
+        if (party.memberIds.has(entityId)) {
+            return partyId;
+        }
+    }
+    return undefined;
+}
+// ── Relationship Management ───────────────────────────────────────────────────
+/** Get standing between two parties (default NEUTRAL). */
+export function getPartyStanding(registry, partyAId, partyBId) {
+    if (partyAId === partyBId)
+        return PARTY_STANDING_ALLIED;
+    const row = registry.relationships.get(partyAId);
+    if (!row)
+        return PARTY_STANDING_NEUTRAL;
+    const standing = row.get(partyBId);
+    return standing ?? PARTY_STANDING_NEUTRAL;
+}
+/** Set standing between two parties (clamped). */
+export function setPartyStanding(registry, partyAId, partyBId, standing) {
+    if (partyAId === partyBId)
+        return;
+    let row = registry.relationships.get(partyAId);
+    if (!row) {
+        row = new Map();
+        registry.relationships.set(partyAId, row);
+    }
+    row.set(partyBId, clampQ(standing, 0, SCALE.Q));
+    // Ensure symmetric row exists for partyB (but may have different standing? we keep asymmetric)
+    let rowB = registry.relationships.get(partyBId);
+    if (!rowB) {
+        rowB = new Map();
+        registry.relationships.set(partyBId, rowB);
+    }
+}
+/** Set mutual standing between two parties (same both ways). */
+export function setMutualPartyStanding(registry, partyAId, partyBId, standing) {
+    setPartyStanding(registry, partyAId, partyBId, standing);
+    setPartyStanding(registry, partyBId, partyAId, standing);
+}
+/** Determine if two parties are hostile based on standing threshold. */
+export function arePartiesHostile(registry, partyAId, partyBId) {
+    const standing = getPartyStanding(registry, partyAId, partyBId);
+    return standing < PARTY_HOSTILE_THRESHOLD;
+}
+/** Determine if two parties are friendly (won't attack). */
+export function arePartiesFriendly(registry, partyAId, partyBId) {
+    const standing = getPartyStanding(registry, partyAId, partyBId);
+    return standing >= PARTY_FRIENDLY_THRESHOLD;
+}
+// ── Entity‑Level Queries ──────────────────────────────────────────────────────
+/** Get standing between two entities based on party membership. */
+export function getPartyStandingBetweenEntities(registry, a, b) {
+    const partyAId = a.party;
+    const partyBId = b.party;
+    if (!partyAId || !partyBId)
+        return undefined;
+    return getPartyStanding(registry, partyAId, partyBId);
+}
+/** Check if two entities are hostile based on party standing. */
+export function areEntitiesHostileByParty(registry, a, b) {
+    const partyAId = a.party;
+    const partyBId = b.party;
+    if (!partyAId || !partyBId)
+        return false; // no party relationship
+    return arePartiesHostile(registry, partyAId, partyBId);
+}
+/** Check if two entities are friendly based on party standing. */
+export function areEntitiesFriendlyByParty(registry, a, b) {
+    const partyAId = a.party;
+    const partyBId = b.party;
+    if (!partyAId || !partyBId)
+        return false;
+    return arePartiesFriendly(registry, partyAId, partyBId);
+}
+// ── Companion Loyalty ─────────────────────────────────────────────────────────
+/**
+ * Compute loyalty of a companion (entity) towards its party leader.
+ * Loyalty is derived from relationship affinity and trust (if relationship exists).
+ * Returns Q in [0, SCALE.Q] where 0 =背叛 (betrayal imminent), SCALE.Q = absolute loyalty.
+ */
+export function computeCompanionLoyalty(companion, leaderId, relationshipGraph) {
+    // If no relationship graph, assume neutral loyalty (0.5)
+    if (!relationshipGraph)
+        return PARTY_STANDING_NEUTRAL;
+    const rel = relationshipGraph.relationships.get(`${Math.min(companion.id, leaderId)}:${Math.max(companion.id, leaderId)}`);
+    if (!rel)
+        return PARTY_STANDING_NEUTRAL;
+    // Loyalty = weighted combination of affinity (shifted to 0..1) and trust
+    const affinityNormalized = (rel.affinity_Q + SCALE.Q) / (2 * SCALE.Q); // -1..1 → 0..1
+    const loyalty = (affinityNormalized * 0.6 + rel.trust_Q / SCALE.Q * 0.4) * SCALE.Q;
+    return clampQ(Math.round(loyalty), 0, SCALE.Q);
+}
+// ── Shared Inventory ──────────────────────────────────────────────────────
+export function getPartySharedInventory(registry, partyId) {
+    const party = registry.parties.get(partyId);
+    return party?.sharedInventory;
+}
+export function ensurePartySharedInventory(registry, partyId) {
+    const party = registry.parties.get(partyId);
+    if (!party)
+        throw new Error(`Party ${partyId} not found`);
+    if (!party.sharedInventory) {
+        party.sharedInventory = createInventory(-1);
+        // Add a default container
+        const container = createContainer(`shared-${partyId}`, "Shared Storage", 100 * SCALE.kg, // 100 kg capacity
+        0);
+        addContainer(party.sharedInventory, container);
+    }
+    return party.sharedInventory;
+}
+// ── Serialization ─────────────────────────────────────────────────────────────
+const MAP_MARKER = "__ananke_map__";
+const SET_MARKER = "__ananke_set__";
+function replacer(_key, value) {
+    if (value instanceof Map) {
+        return { [MAP_MARKER]: true, entries: [...value.entries()] };
+    }
+    if (value instanceof Set) {
+        return { [SET_MARKER]: true, values: [...value.values()] };
+    }
+    return value;
+}
+function reviver(_key, value) {
+    if (value !== null && typeof value === "object") {
+        const v = value;
+        if (v[MAP_MARKER] === true) {
+            return new Map(v.entries);
+        }
+        if (v[SET_MARKER] === true) {
+            return new Set(v.values);
+        }
+    }
+    return value;
+}
+/** Serialize party registry to JSON string. */
+export function serializePartyRegistry(registry) {
+    return JSON.stringify(registry, replacer);
+}
+/** Deserialize party registry from JSON string. */
+export function deserializePartyRegistry(json) {
+    return JSON.parse(json, reviver);
+}