@its-not-rocket-science/ananke 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -10,6 +10,33 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [0.1.3] — 2026-03-20
+
+### Changed
+
+- `src/index.ts` (CE-4) now exports only the Tier 1 stable surface defined in `STABLE_API.md`.
+  Tier 2 (experimental) and Tier 3 (internal) exports have been removed from the root barrel
+  and are accessible via direct module paths (e.g. `dist/src/sim/aging.js`).
+- `createWorld`, `loadScenario`, `validateScenario`, `ARCHETYPE_MAP`, `ITEM_MAP` promoted to
+  Tier 1 (were incorrectly placed under Tier 3 in 0.1.2).
+- `describeCharacter`, `formatCharacterSheet`, `formatOneLine` added to root barrel (were
+  listed as Tier 1 in `STABLE_API.md` but missing from the 0.1.2 export).
+
+---
+
+## [0.1.2] — 2026-03-19
+
+### Added
+
+- `createWorld(seed, entities)` — Tier-1 convenience factory; builds a `WorldState` from
+  `EntitySpec[]` (archetype, weapon, armour string IDs) without manual entity construction
+- `loadScenario(json)` / `validateScenario(json)` — JSON-driven world creation for
+  non-TypeScript consumers (Godot GDScript, Unity C#, scenario files)
+- `ARCHETYPE_MAP` — `ReadonlyMap` of all 21 built-in archetypes (7 base + 14 species)
+- `ITEM_MAP` — `ReadonlyMap` of all historical and starter weapons/armour
+
+---
+
 ## [0.1.1] — 2026-03-19
 
 ### Documentation

package/dist/src/index.d.ts

@@ -3,6 +3,7 @@ export * from "./types.js";
 export * from "./archetypes.js";
 export * from "./generate.js";
 export * from "./equipment.js";
+export * from "./describe.js";
 export * from "./sim/vec3.js";
 export * from "./sim/condition.js";
 export * from "./sim/injury.js";
@@ -14,29 +15,5 @@ export * from "./sim/world.js";
 export * from "./model3d.js";
 export * from "./replay.js";
 export * from "./bridge/index.js";
-export * from "./channels.js";
-export * from "./traits.js";
-export * from "./derive.js";
-export * from "./sim/intent.js";
-export * from "./sim/action.js";
-export * from "./sim/combat.js";
-export * from "./quest.js";
-export * from "./quest-generators.js";
-export * from "./relationships.js";
-export * from "./relationships-effects.js";
-export * from "./inventory.js";
-export * from "./item-durability.js";
-export * from "./settlement.js";
-export * from "./settlement-services.js";
-export * from "./chronicle.js";
-export * from "./story-arcs.js";
-export * from "./narrative-render.js";
-export * from "./world-generation.js";
-export * from "./sim/trace.js";
-export * from "./rng.js";
-export * from "./dist.js";
-export * from "./lod.js";
-export * from "./sim/impairment.js";
-export * from "./sim/indexing.js";
-export * from "./sim/tuning.js";
-export * from "./sim/testing.js";
+export * from "./world-factory.js";
+export * from "./scenario.js";

package/dist/src/index.js

@@ -1,54 +1,28 @@
 // ── Tier 1 — Stable host API ─────────────────────────────────────────────────
-// These exports form the public integration surface.  Breaking changes require
-// a major semver bump (x.0.0) and a migration guide in CHANGELOG.md.
-// Safe to import directly in host applications and typed as stable in STABLE_API.md.
-export * from "./units.js"; // q(), SCALE, qMul, mulDiv — fixed-point arithmetic
+// This is the only import path companion projects and hosts should use:
+//   import { stepWorld, createWorld, q, SCALE } from "@its-not-rocket-science/ananke"
+//
+// Breaking changes to any export here require a major semver bump (x.0.0) and
+// a migration guide in CHANGELOG.md.  See STABLE_API.md for the full contract.
+//
+// Tier 2 (experimental) and Tier 3 (internal) exports are accessible via direct
+// module imports, e.g. import { stepAging } from ".../dist/src/sim/aging.js"
+export * from "./units.js"; // q(), SCALE, qMul, qDiv, clampQ, mulDiv, to, from, sqrtQ
 export * from "./types.js"; // IndividualAttributes, core scalar types
 export * from "./archetypes.js"; // Archetype, BodyPlan, built-in species presets
 export * from "./generate.js"; // generateIndividual()
 export * from "./equipment.js"; // WEAPONS database, EquipmentCatalogue
-export * from "./sim/vec3.js"; // Vec3, lerpVec3, addVec3 — 3-D vector helpers
+export * from "./describe.js"; // describeCharacter(), formatCharacterSheet(), formatOneLine()
+export * from "./sim/vec3.js"; // Vec3, lerpVec3, addVec3
 export * from "./sim/condition.js"; // ConditionSnapshot, condition constants
 export * from "./sim/injury.js"; // InjuryRegion, BodyRegion, injury constants
 export * from "./sim/entity.js"; // Entity (stable fields: id, pos, mass_kg, attributes…)
 export * from "./sim/commands.js"; // CommandMap, EntityCommand, action verbs
 export * from "./sim/kernel.js"; // stepWorld(), applyImpactToInjury(), applyExplosion()
 export * from "./sim/body.js"; // BodyPlan, BodySegment, humanoid / quadruped plans
-export * from "./sim/world.js"; // WorldState, KernelContext, createWorld()
-export * from "./model3d.js"; // extractRigSnapshots(), deriveAnimationHints(), RigSnapshot, AnimationHints, GrapplePoseConstraint
+export * from "./sim/world.js"; // WorldState, KernelContext
+export * from "./model3d.js"; // extractRigSnapshots(), deriveAnimationHints(), RigSnapshot, AnimationHints
 export * from "./replay.js"; // ReplayRecorder, replayTo(), serializeReplay(), deserializeReplay()
-export * from "./bridge/index.js"; // BridgeEngine, InterpolatedState, BridgeConfig — 3D renderer bridge
-// ── Tier 2 — Advanced / experimental API ─────────────────────────────────────
-// Tested and usable subsystems under active development.  May change between
-// minor versions (0.x.0); CHANGELOG.md will document any breaking change.
-// Reference STABLE_API.md §Tier 2 for the full export list per module.
-export * from "./channels.js"; // damage channel constants (BLUNT, SLASH, …)
-export * from "./traits.js"; // trait descriptors
-export * from "./derive.js"; // derived attribute helpers
-export * from "./sim/intent.js"; // IntentMap, buildIntent()
-export * from "./sim/action.js"; // ActionResult, resolveAction()
-export * from "./sim/combat.js"; // resolveHit(), resolveParry(), applyCombat()
-export * from "./quest.js"; // Quest, QuestObjective, questStep()
-export * from "./quest-generators.js"; // generateQuest(), generateQuestChain()
-export * from "./relationships.js"; // RelationshipMap, updateRelationship()
-export * from "./relationships-effects.js"; // applyRelationshipEffect()
-export * from "./inventory.js"; // Inventory, equipItem(), addItemToInventory()
-export * from "./item-durability.js"; // durability helpers, resolveRepair()
-export * from "./settlement.js"; // Settlement, stepSettlement()
-export * from "./settlement-services.js"; // service resolution helpers
-export * from "./chronicle.js"; // ChronicleEntry, addChronicleEntry()
-export * from "./story-arcs.js"; // StoryArc, detectArcs()
-export * from "./narrative-render.js"; // renderEntry(), renderChronicle(), generateNarrative()
-export * from "./world-generation.js"; // WorldTemplate, generateWorld()
-export * from "./sim/trace.js"; // SimTrace, traceStep() — debugging / profiling
-// ── Tier 3 — Internal / kernel API ───────────────────────────────────────────
-// Exported for power users and diagnostic tooling.  Not stability-guaranteed;
-// may change at any time without a changelog entry.  Prefer Tier 1/2 surfaces
-// in production host code.  See STABLE_API.md §Tier 3 for rationale.
-export * from "./rng.js"; // makeRng(), eventSeed() — RNG internals
-export * from "./dist.js"; // distribution primitives
-export * from "./lod.js"; // level-of-detail helpers
-export * from "./sim/impairment.js"; // low-level impairment accumulators
-export * from "./sim/indexing.js"; // SpatialIndex internals
-export * from "./sim/tuning.js"; // kernel tuning constants (may be adjusted)
-export * from "./sim/testing.js"; // mkHumanoidEntity() and other test helpers
+export * from "./bridge/index.js"; // BridgeEngine, InterpolatedState, BridgeConfig
+export * from "./world-factory.js"; // createWorld(), EntitySpec, ARCHETYPE_MAP, ITEM_MAP
+export * from "./scenario.js"; // loadScenario(), validateScenario(), AnankeScenario

package/dist/src/scenario.d.ts

@@ -0,0 +1,37 @@
+/**
+ * CE-3: JSON scenario loader.
+ *
+ * Provides typed AnankeScenario interface, structural validation, and
+ * a loadScenario() function that converts validated JSON into a WorldState.
+ */
+import type { WorldState } from "./sim/world.js";
+export interface AnankeScenarioEntity {
+    id: number;
+    teamId: number;
+    archetype: string;
+    weapon: string;
+    armour?: string;
+    x_m?: number;
+    y_m?: number;
+}
+export interface AnankeScenario {
+    $schema?: string;
+    id: string;
+    seed: number;
+    maxTicks: number;
+    tractionCoeff?: number;
+    entities: AnankeScenarioEntity[];
+}
+/**
+ * Validate structural correctness of a JSON scenario object.
+ * Returns an array of error strings — empty array means valid.
+ * Does NOT perform simulation-level lookups (e.g. archetype/weapon existence).
+ */
+export declare function validateScenario(json: unknown): string[];
+/**
+ * Parse and load a scenario from JSON, returning a WorldState ready for stepWorld().
+ *
+ * Calls validateScenario first — throws an Error with all validation messages if invalid.
+ * Maps AnankeScenarioEntity.id as the entity seed.
+ */
+export declare function loadScenario(json: unknown): WorldState;

package/dist/src/scenario.js

@@ -0,0 +1,109 @@
+/**
+ * CE-3: JSON scenario loader.
+ *
+ * Provides typed AnankeScenario interface, structural validation, and
+ * a loadScenario() function that converts validated JSON into a WorldState.
+ */
+import { createWorld } from "./world-factory.js";
+// ── Validation ────────────────────────────────────────────────────────────────
+/**
+ * Validate structural correctness of a JSON scenario object.
+ * Returns an array of error strings — empty array means valid.
+ * Does NOT perform simulation-level lookups (e.g. archetype/weapon existence).
+ */
+export function validateScenario(json) {
+    const errors = [];
+    // Must be a plain object
+    if (json === null || typeof json !== "object" || Array.isArray(json)) {
+        errors.push("scenario must be a plain object");
+        return errors; // can't continue checking fields
+    }
+    const obj = json;
+    // id — non-empty string
+    if (typeof obj["id"] !== "string" || obj["id"].length === 0) {
+        errors.push("scenario.id must be a non-empty string");
+    }
+    // seed — positive integer
+    if (typeof obj["seed"] !== "number" ||
+        !Number.isInteger(obj["seed"]) ||
+        obj["seed"] <= 0) {
+        errors.push("scenario.seed must be a positive integer");
+    }
+    // maxTicks — positive integer
+    if (typeof obj["maxTicks"] !== "number" ||
+        !Number.isInteger(obj["maxTicks"]) ||
+        obj["maxTicks"] <= 0) {
+        errors.push("scenario.maxTicks must be a positive integer");
+    }
+    // entities — non-empty array
+    if (!Array.isArray(obj["entities"])) {
+        errors.push("scenario.entities must be an array");
+        return errors; // can't check entity elements
+    }
+    const rawEntities = obj["entities"];
+    if (rawEntities.length === 0) {
+        errors.push("scenario.entities must not be empty");
+        return errors;
+    }
+    // Validate each entity element
+    const seenIds = new Set();
+    for (let i = 0; i < rawEntities.length; i++) {
+        const ent = rawEntities[i];
+        if (ent === null || typeof ent !== "object" || Array.isArray(ent)) {
+            errors.push(`scenario.entities[${i}] must be a plain object`);
+            continue;
+        }
+        const e = ent;
+        if (typeof e["id"] !== "number") {
+            errors.push(`scenario.entities[${i}].id must be a number`);
+        }
+        else {
+            const eid = e["id"];
+            if (seenIds.has(eid)) {
+                errors.push(`scenario.entities[${i}].id ${eid} is a duplicate`);
+            }
+            seenIds.add(eid);
+        }
+        if (typeof e["teamId"] !== "number") {
+            errors.push(`scenario.entities[${i}].teamId must be a number`);
+        }
+        if (typeof e["archetype"] !== "string") {
+            errors.push(`scenario.entities[${i}].archetype must be a string`);
+        }
+        if (typeof e["weapon"] !== "string") {
+            errors.push(`scenario.entities[${i}].weapon must be a string`);
+        }
+    }
+    return errors;
+}
+// ── Loader ────────────────────────────────────────────────────────────────────
+/**
+ * Parse and load a scenario from JSON, returning a WorldState ready for stepWorld().
+ *
+ * Calls validateScenario first — throws an Error with all validation messages if invalid.
+ * Maps AnankeScenarioEntity.id as the entity seed.
+ */
+export function loadScenario(json) {
+    const errors = validateScenario(json);
+    if (errors.length > 0) {
+        throw new Error(`loadScenario: invalid scenario:\n  ${errors.join("\n  ")}`);
+    }
+    const scenario = json;
+    const specs = scenario.entities.map(ent => {
+        const spec = {
+            id: ent.id,
+            teamId: ent.teamId,
+            seed: ent.id, // use entity id as deterministic seed
+            archetype: ent.archetype,
+            weaponId: ent.weapon,
+        };
+        if (ent.armour !== undefined)
+            spec.armourId = ent.armour;
+        if (ent.x_m !== undefined)
+            spec.x_m = ent.x_m;
+        if (ent.y_m !== undefined)
+            spec.y_m = ent.y_m;
+        return spec;
+    });
+    return createWorld(scenario.seed, specs);
+}

package/dist/src/world-factory.d.ts

@@ -0,0 +1,33 @@
+/**
+ * CE-2: createWorld convenience factory.
+ *
+ * Builds a deterministic WorldState from a simple declarative entity spec.
+ * No Math.random() — all randomness flows through generateIndividual(spec.seed, archetype).
+ * All position coordinates are fixed-point (SCALE.m multiplier + Math.round).
+ */
+import type { Archetype } from "./archetypes.js";
+import type { Item } from "./equipment.js";
+import type { WorldState } from "./sim/world.js";
+/** Map of string keys to Archetype objects for use with createWorld(). */
+export declare const ARCHETYPE_MAP: ReadonlyMap<string, Archetype>;
+/** Map of item id → Item for weapons and armour usable with createWorld(). */
+export declare const ITEM_MAP: ReadonlyMap<string, Item>;
+export interface EntitySpec {
+    id: number;
+    teamId: number;
+    seed: number;
+    archetype: string;
+    weaponId: string;
+    armourId?: string;
+    x_m?: number;
+    y_m?: number;
+}
+/**
+ * Build a deterministic WorldState from a declarative entity spec list.
+ *
+ * - Uses spec.seed for generateIndividual() — no Math.random().
+ * - Position coordinates are fixed-point: Math.round(metres * SCALE.m).
+ * - Throws on unknown archetype, weaponId, or armourId.
+ * - Throws on duplicate entity ids.
+ */
+export declare function createWorld(seed: number, entities: EntitySpec[]): WorldState;

package/dist/src/world-factory.js

@@ -0,0 +1,132 @@
+/**
+ * CE-2: createWorld convenience factory.
+ *
+ * Builds a deterministic WorldState from a simple declarative entity spec.
+ * No Math.random() — all randomness flows through generateIndividual(spec.seed, archetype).
+ * All position coordinates are fixed-point (SCALE.m multiplier + Math.round).
+ */
+import { q, SCALE } from "./units.js";
+import { generateIndividual } from "./generate.js";
+import { HUMAN_BASE, AMATEUR_BOXER, PRO_BOXER, GRECO_WRESTLER, KNIGHT_INFANTRY, LARGE_PACIFIC_OCTOPUS, SERVICE_ROBOT, } from "./archetypes.js";
+import { ELF_SPECIES, DWARF_SPECIES, HALFLING_SPECIES, ORC_SPECIES, OGRE_SPECIES, GOBLIN_SPECIES, TROLL_SPECIES, VULCAN_SPECIES, KLINGON_SPECIES, ROMULAN_SPECIES, DRAGON_SPECIES, CENTAUR_SPECIES, SATYR_SPECIES, HEECHEE_SPECIES, } from "./species.js";
+import { ALL_HISTORICAL_MELEE, ALL_HISTORICAL_RANGED } from "./weapons.js";
+import { STARTER_WEAPONS, STARTER_ARMOUR, STARTER_ARMOUR_11C } from "./equipment.js";
+import { v3 } from "./sim/vec3.js";
+import { defaultIntent } from "./sim/intent.js";
+import { defaultAction } from "./sim/action.js";
+import { defaultCondition } from "./sim/condition.js";
+import { defaultInjury } from "./sim/injury.js";
+// ── Static archetype map ──────────────────────────────────────────────────────
+/** Map of string keys to Archetype objects for use with createWorld(). */
+export const ARCHETYPE_MAP = new Map([
+    // Direct archetypes from archetypes.ts
+    ["HUMAN_BASE", HUMAN_BASE],
+    ["AMATEUR_BOXER", AMATEUR_BOXER],
+    ["PRO_BOXER", PRO_BOXER],
+    ["GRECO_WRESTLER", GRECO_WRESTLER],
+    ["KNIGHT_INFANTRY", KNIGHT_INFANTRY],
+    ["LARGE_PACIFIC_OCTOPUS", LARGE_PACIFIC_OCTOPUS],
+    ["SERVICE_ROBOT", SERVICE_ROBOT],
+    // Species archetypes from species.ts
+    ["ELF", ELF_SPECIES.archetype],
+    ["DWARF", DWARF_SPECIES.archetype],
+    ["HALFLING", HALFLING_SPECIES.archetype],
+    ["ORC", ORC_SPECIES.archetype],
+    ["OGRE", OGRE_SPECIES.archetype],
+    ["GOBLIN", GOBLIN_SPECIES.archetype],
+    ["TROLL", TROLL_SPECIES.archetype],
+    ["VULCAN", VULCAN_SPECIES.archetype],
+    ["KLINGON", KLINGON_SPECIES.archetype],
+    ["ROMULAN", ROMULAN_SPECIES.archetype],
+    ["DRAGON", DRAGON_SPECIES.archetype],
+    ["CENTAUR", CENTAUR_SPECIES.archetype],
+    ["SATYR", SATYR_SPECIES.archetype],
+    ["HEECHEE", HEECHEE_SPECIES.archetype],
+]);
+// ── Static item map ───────────────────────────────────────────────────────────
+function buildItemMap() {
+    const map = new Map();
+    const allItems = [
+        ...ALL_HISTORICAL_MELEE,
+        ...ALL_HISTORICAL_RANGED,
+        ...STARTER_WEAPONS,
+        ...STARTER_ARMOUR,
+        ...STARTER_ARMOUR_11C,
+    ];
+    for (const item of allItems) {
+        map.set(item.id, item);
+    }
+    return map;
+}
+/** Map of item id → Item for weapons and armour usable with createWorld(). */
+export const ITEM_MAP = buildItemMap();
+// ── createWorld ───────────────────────────────────────────────────────────────
+/**
+ * Build a deterministic WorldState from a declarative entity spec list.
+ *
+ * - Uses spec.seed for generateIndividual() — no Math.random().
+ * - Position coordinates are fixed-point: Math.round(metres * SCALE.m).
+ * - Throws on unknown archetype, weaponId, or armourId.
+ * - Throws on duplicate entity ids.
+ */
+export function createWorld(seed, entities) {
+    const built = [];
+    for (const spec of entities) {
+        // ── Archetype lookup ──────────────────────────────────────────────────────
+        const archetype = ARCHETYPE_MAP.get(spec.archetype);
+        if (archetype === undefined) {
+            throw new Error(`createWorld: unknown archetype "${spec.archetype}". ` +
+                `Valid keys: ${[...ARCHETYPE_MAP.keys()].join(", ")}`);
+        }
+        // ── Weapon lookup ─────────────────────────────────────────────────────────
+        const weapon = ITEM_MAP.get(spec.weaponId);
+        if (weapon === undefined) {
+            throw new Error(`createWorld: unknown weaponId "${spec.weaponId}"`);
+        }
+        // ── Optional armour lookup ────────────────────────────────────────────────
+        let armour;
+        if (spec.armourId !== undefined) {
+            armour = ITEM_MAP.get(spec.armourId);
+            if (armour === undefined) {
+                throw new Error(`createWorld: unknown armourId "${spec.armourId}"`);
+            }
+        }
+        // ── Generate individual attributes ────────────────────────────────────────
+        const attrs = generateIndividual(spec.seed, archetype);
+        // ── Default position ──────────────────────────────────────────────────────
+        // Team 1 defaults to x=0; all others default to x=0.6m.
+        const defaultX = spec.teamId === 1 ? 0 : 0.6;
+        const x_fixed = Math.round((spec.x_m ?? defaultX) * SCALE.m);
+        const y_fixed = Math.round((spec.y_m ?? 0) * SCALE.m);
+        // ── Build loadout ─────────────────────────────────────────────────────────
+        const items = [weapon];
+        if (armour !== undefined)
+            items.push(armour);
+        // ── Assemble entity ───────────────────────────────────────────────────────
+        const entity = {
+            id: spec.id,
+            teamId: spec.teamId,
+            attributes: attrs,
+            energy: { reserveEnergy_J: attrs.performance.reserveEnergy_J, fatigue: q(0) },
+            loadout: { items },
+            traits: [],
+            position_m: v3(x_fixed, y_fixed, 0),
+            velocity_mps: v3(0, 0, 0),
+            intent: defaultIntent(),
+            action: defaultAction(),
+            condition: defaultCondition(),
+            injury: defaultInjury(),
+            grapple: { holdingTargetId: 0, heldByIds: [], gripQ: q(0), position: "standing" },
+        };
+        built.push(entity);
+    }
+    // ── Sort by id ────────────────────────────────────────────────────────────
+    built.sort((a, b) => a.id - b.id);
+    // ── Duplicate id check ────────────────────────────────────────────────────
+    const ids = built.map(e => e.id);
+    const dupes = ids.filter((id, i) => ids.indexOf(id) !== i);
+    if (dupes.length > 0) {
+        throw new Error(`createWorld: duplicate entity IDs detected: ${[...new Set(dupes)].join(", ")}`);
+    }
+    return { tick: 0, seed, entities: built };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@its-not-rocket-science/ananke",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Deterministic lockstep-friendly SI-units RPG/physics core (fixed-point TS)",
   "license": "MIT",