@its-not-rocket-science/ananke 0.1.0

package/dist/src/inheritance.js

@@ -0,0 +1,136 @@
+// src/inheritance.ts — Phase 49: Legacy & Inheritance
+//
+// Character death does not end the campaign.  An heir:
+//   • inherits all equipped items from the deceased's loadout
+//   • receives a partial transfer of the deceased's relationship graph
+//   • takes possession of the deceased's campaign inventory
+//   • is registered in the campaign; the deceased is removed
+//
+// No simulation physics — pure bookkeeping that composes with campaign.ts.
+import { SCALE, q, clampQ, mulDiv } from "./units.js";
+import { establishRelationship } from "./relationships.js";
+// ── Equipment transfer ────────────────────────────────────────────────────────
+/**
+ * Move all loadout items from deceased to heir.
+ * Heir's existing items are preserved (deceased's items are appended).
+ * Deceased's loadout is cleared.
+ *
+ * @returns Number of items transferred.
+ */
+export function transferEquipment(deceased, heir) {
+    const items = deceased.loadout.items;
+    const count = items.length;
+    heir.loadout.items = [...heir.loadout.items, ...items];
+    deceased.loadout.items = [];
+    return count;
+}
+// ── Relationship transfer ─────────────────────────────────────────────────────
+/**
+ * Partially copy the deceased's relationships to the heir.
+ *
+ * For each relationship R(deceased, X):
+ *   heir's trust_Q    = R.trust_Q    × transferRate_Q
+ *   heir's affinity_Q = |R.affinity_Q| × transferRate_Q  (sign preserved)
+ *
+ * Existing heir–X relationships are not overwritten.
+ * The deceased's relationships are left in the graph unmodified.
+ *
+ * @returns Number of new heir relationships created.
+ */
+export function transferRelationships(graph, deceasedId, heirId, transferRate_Q) {
+    const keys = graph.entityIndex.get(deceasedId);
+    if (!keys || keys.size === 0)
+        return 0;
+    let created = 0;
+    for (const key of keys) {
+        const rel = graph.relationships.get(key);
+        if (!rel)
+            continue;
+        const otherId = rel.entityA === deceasedId ? rel.entityB : rel.entityA;
+        if (otherId === heirId)
+            continue;
+        // Skip if heir already has a relationship with this entity
+        const existingKey = heirId < otherId ? `${heirId}:${otherId}` : `${otherId}:${heirId}`;
+        if (graph.relationships.has(existingKey))
+            continue;
+        const newTrust = clampQ(mulDiv(rel.trust_Q, transferRate_Q, SCALE.Q), q(0), SCALE.Q);
+        // Affinity can be negative: scale magnitude, preserve sign
+        const rawMag = mulDiv(rel.affinity_Q < 0 ? -rel.affinity_Q : rel.affinity_Q, transferRate_Q, SCALE.Q);
+        const newAffinity = clampQ((rel.affinity_Q < 0 ? -rawMag : rawMag), (-SCALE.Q), SCALE.Q);
+        establishRelationship(graph, heirId, otherId, 0, newAffinity, newTrust);
+        created++;
+    }
+    return created;
+}
+// ── Inventory transfer ────────────────────────────────────────────────────────
+/**
+ * Transfer all campaign inventory items from deceased to heir.
+ * Stacks merge: heir's existing counts are summed with deceased's amounts.
+ * The deceased's campaign inventory entry is deleted after transfer.
+ *
+ * @returns Map of transferred items (itemId → count transferred).
+ */
+export function transferInventory(campaign, deceasedId, heirId) {
+    const deceasedInv = campaign.entityInventories.get(deceasedId);
+    if (!deceasedInv || deceasedInv.size === 0)
+        return new Map();
+    const transferred = new Map(deceasedInv);
+    const heirInv = campaign.entityInventories.get(heirId) ?? new Map();
+    for (const [itemId, count] of deceasedInv) {
+        heirInv.set(itemId, (heirInv.get(itemId) ?? 0) + count);
+    }
+    campaign.entityInventories.set(heirId, heirInv);
+    campaign.entityInventories.delete(deceasedId);
+    return transferred;
+}
+// ── Full inheritance orchestration ────────────────────────────────────────────
+/**
+ * Apply the full inheritance process when a character dies and an heir takes over.
+ *
+ * Steps performed:
+ *  1. Transfers loadout equipment from deceased to heir entity.
+ *  2. Transfers campaign inventory (deceased → heir, with stack merging).
+ *  3. Partially transfers relationships (if `graph` is provided).
+ *  4. Moves the deceased's campaign location to the heir.
+ *  5. Registers the heir in the campaign; removes the deceased.
+ *  6. Logs the event to `campaign.log`.
+ *
+ * Both deceased (via `campaign.entities`) and heir (provided directly) must be
+ * supplied.  The deceased entity is updated in-place before being removed so
+ * that equipment is properly cleared.
+ *
+ * @returns InheritanceReport with counts of transferred items and relationships.
+ */
+export function applyInheritance(campaign, graph, spec, heir) {
+    const { deceasedId, heirId } = spec;
+    const transferRate_Q = spec.relationshipTransferRate_Q ?? q(0.50);
+    // 1. Equipment
+    const deceased = campaign.entities.get(deceasedId);
+    let itemsTransferred = 0;
+    if (deceased) {
+        itemsTransferred = transferEquipment(deceased, heir);
+    }
+    // 2. Inventory
+    const inventoryTransferred = transferInventory(campaign, deceasedId, heirId);
+    // 3. Relationships
+    let relationshipsTransferred = 0;
+    if (graph) {
+        relationshipsTransferred = transferRelationships(graph, deceasedId, heirId, transferRate_Q);
+    }
+    // 4. Location
+    const loc = campaign.entityLocations.get(deceasedId);
+    if (loc !== undefined) {
+        campaign.entityLocations.set(heirId, loc);
+        campaign.entityLocations.delete(deceasedId);
+    }
+    // 5. Registry update
+    campaign.entities.set(heirId, heir);
+    if (deceased)
+        campaign.entities.delete(deceasedId);
+    // 6. Log
+    campaign.log.push({
+        worldTime_s: campaign.worldTime_s,
+        text: `Entity ${heirId} inherits from deceased entity ${deceasedId} (${itemsTransferred} items, ${relationshipsTransferred} relationships).`,
+    });
+    return { itemsTransferred, relationshipsTransferred, inventoryTransferred };
+}

package/dist/src/inventory.d.ts

@@ -0,0 +1,194 @@
+import type { Q } from "./units.js";
+import type { IndividualAttributes } from "./types.js";
+/** An instance of an item in the inventory. */
+export interface ItemInstance {
+    /** Unique identifier for this specific item instance. */
+    instanceId: string;
+    /** References the equipment catalogue template. */
+    templateId: string;
+    /** Stack quantity (for stackable items). */
+    quantity: number;
+    /** Durability: 1.0 = pristine, 0.0 = broken. Undefined = no durability. */
+    durability_Q?: Q | undefined;
+    /** Modifications applied to this item. */
+    modifications?: ItemMod[] | undefined;
+    /** Path to containing container(s), empty if top-level. */
+    containerPath: string[];
+}
+/** A container (bag, pouch, backpack) that holds items. */
+export interface Container {
+    /** Unique identifier within the inventory. */
+    containerId: string;
+    /** Display name. */
+    name: string;
+    /** Maximum weight capacity in kg (scaled by SCALE.kg). */
+    capacity_Kg: number;
+    /** Optional volume capacity in litres. */
+    volume_L?: number | undefined;
+    /** Items stored directly in this container. */
+    items: ItemInstance[];
+    /** Whether this container is currently equipped/accessible. */
+    isEquipped: boolean;
+    /** Base mass of the empty container itself. */
+    emptyMass_kg: number;
+}
+/** A record of equipped items by slot. */
+export interface EquippedItems {
+    /** Weapon in main hand. */
+    mainHand?: ItemInstance;
+    /** Weapon/shield in off hand. */
+    offHand?: ItemInstance;
+    /** Body armour. */
+    body?: ItemInstance;
+    /** Head protection. */
+    head?: ItemInstance;
+    /** Container slots (back, belt, etc.). */
+    containers: Map<string, ItemInstance>;
+}
+/** Complete inventory for an entity. */
+export interface Inventory {
+    /** Owner entity ID. */
+    ownerId: number;
+    /** All containers owned (equipped or not). */
+    containers: Container[];
+    /** Currently equipped items. */
+    equipped: EquippedItems;
+    /** Total encumbrance in kg (scaled). */
+    encumbrance_Kg: number;
+    /** Maximum encumbrance based on strength. */
+    maxEncumbrance_Kg: number;
+    /** Currency/money (if applicable). */
+    currency?: number;
+}
+/** Item modification types. */
+export interface ItemMod {
+    type: "sharpened" | "reinforced" | "enchanted" | "damaged" | "masterwork";
+    /** Display name of the modification. */
+    name: string;
+    /** Effects on item stats (applied as multipliers). */
+    statMultipliers?: {
+        damageMul?: Q;
+        durabilityMul?: Q;
+        weightMul?: Q;
+        valueMul?: Q;
+    };
+}
+export type EncumbranceCategory = "unencumbered" | "light" | "medium" | "heavy" | "overloaded";
+export interface EncumbranceCategoryDef {
+    category: EncumbranceCategory;
+    maxRatio: number;
+    penalties: InventoryEncumbrancePenalties;
+}
+export interface InventoryEncumbrancePenalties {
+    /** Fine control penalty (affects combat precision). */
+    fineControlPenalty_Q: Q;
+    /** Dodge/parry latency increase as multiplier. */
+    dodgeParryLatencyMul: Q;
+    /** Movement speed multiplier. */
+    speedMul: Q;
+    /** Cannot sprint if true. */
+    noSprint: boolean;
+    /** Cannot move if true. */
+    noMove: boolean;
+}
+export declare const ENCUMBRANCE_CATEGORIES: EncumbranceCategoryDef[];
+/** Create an empty inventory for an entity. */
+export declare function createInventory(ownerId: number): Inventory;
+/** Create a new container. */
+export declare function createContainer(containerId: string, name: string, capacity_Kg: number, emptyMass_kg: number, volume_L?: number): Container;
+/**
+ * Calculate maximum encumbrance based on physical strength.
+ * Stronger characters can carry more absolute weight.
+ */
+export declare function calculateMaxEncumbrance_Kg(attributes: IndividualAttributes, capacityFactor?: Q): number;
+/** Calculate total weight of items in a container (including container itself). */
+export declare function calculateContainerWeight(container: Container): number;
+/** Get mass of a single item instance (including modifications). */
+export declare function getItemInstanceMass(item: ItemInstance): number;
+/** Calculate total encumbrance for an inventory. */
+export declare function calculateTotalEncumbrance(inventory: Inventory): number;
+/** Recalculate encumbrance and update inventory. */
+export declare function recalculateEncumbrance(inventory: Inventory, attributes: IndividualAttributes): void;
+/** Get the encumbrance category and penalties for current load. */
+export declare function getEncumbranceCategory(inventory: Inventory): EncumbranceCategoryDef;
+/** Get effective encumbrance penalties (combines with any existing penalties). */
+export declare function getEffectiveEncumbrancePenalties(inventory: Inventory, baseFineControl: Q): {
+    category: EncumbranceCategory;
+    penalties: InventoryEncumbrancePenalties;
+    effectiveFineControl: Q;
+};
+/** Add a container to inventory. */
+export declare function addContainer(inventory: Inventory, container: Container): void;
+/** Remove a container from inventory. */
+export declare function removeContainer(inventory: Inventory, containerId: string): boolean;
+/** Equip/unequip a container. */
+export declare function setContainerEquipped(inventory: Inventory, containerId: string, equipped: boolean): boolean;
+/** Find a container by ID. */
+export declare function findContainer(inventory: Inventory, containerId: string): Container | undefined;
+/** Add an item to a specific container. */
+export declare function addItemToContainer(container: Container, item: ItemInstance): {
+    success: boolean;
+    reason?: string;
+};
+/** Remove an item from a container by instance ID. */
+export declare function removeItemFromContainer(container: Container, instanceId: string): ItemInstance | undefined;
+/** Find an item anywhere in the inventory. */
+export declare function findItem(inventory: Inventory, instanceId: string): {
+    item: ItemInstance;
+    container: Container | null;
+} | undefined;
+/** Move an item between containers. */
+export declare function moveItem(inventory: Inventory, itemId: string, fromContainerId: string | null, // null = equipped
+toContainerId: string): {
+    success: boolean;
+    reason?: string;
+};
+/** Equip an item from a container to an equipment slot. */
+export declare function equipItem(inventory: Inventory, itemId: string, slot: "mainHand" | "offHand" | "body" | "head"): {
+    success: boolean;
+    reason?: string | undefined;
+    previousItem?: ItemInstance | undefined;
+};
+/** Unequip an item and return it to a container. */
+export declare function unequipItem(inventory: Inventory, slot: "mainHand" | "offHand" | "body" | "head", targetContainerId?: string): {
+    success: boolean;
+    reason?: string | undefined;
+    item?: ItemInstance | undefined;
+};
+/**
+ * Count items in inventory by template ID.
+ * Searches all containers and equipped items.
+ */
+export declare function getItemCountByTemplateId(inventory: Inventory, templateId: string): number;
+/**
+ * Find all material items of a specific material type.
+ * Returns an array of Material items (requires kind "material" and materialTypeId).
+ * Note: This assumes ItemInstance can be cast to Material if kind === "material".
+ * The caller must ensure the item is a material.
+ */
+export declare function findMaterialsByType(inventory: Inventory, materialTypeId: string): ItemInstance[];
+/**
+ * Consume items by template ID, removing them from inventory.
+ * Returns true if enough items were found and consumed.
+ */
+export declare function consumeItemsByTemplateId(inventory: Inventory, templateId: string, quantity: number): boolean;
+/**
+ * Add an item to inventory, attempting to place it in a suitable container.
+ * Prefers equipped containers with sufficient capacity.
+ * Returns success and the container it was added to (or null if equipped).
+ */
+export declare function addItemToInventory(inventory: Inventory, item: ItemInstance): {
+    success: boolean;
+    container: Container | null;
+    reason?: string;
+};
+/** Apply a modification to an item. */
+export declare function applyItemMod(item: ItemInstance, mod: ItemMod): void;
+/** Remove a modification from an item. */
+export declare function removeItemMod(item: ItemInstance, modType: ItemMod["type"]): boolean;
+/** Get effective stat multiplier from all modifications. */
+export declare function getItemStatMultiplier(item: ItemInstance, stat: keyof NonNullable<ItemMod["statMultipliers"]>): Q;
+/** Serialize inventory to JSON-friendly format. */
+export declare function serializeInventory(inventory: Inventory): unknown;
+/** Deserialize inventory. */
+export declare function deserializeInventory(data: unknown): Inventory;