@onimaxxing/worldgen-node 0.31.3 → 0.33.0

package/README.md

@@ -325,6 +325,7 @@ interface WorldgenFailure {
   stage: string;                      // pipeline stage that reported the error
   world_index: number;                // -1 for cluster-level failures
   message: string;
+  origin?: TemplateRuleOrigin;        // failing rule, when a guaranteed template rule failed
 }
 
 interface WorldgenEvent {
@@ -352,11 +353,47 @@ interface WorldMapData {
   subworld_table: string[];           // distinct subworld type paths (same vocab as biome_cells[].type)
   biome_cells: BiomeCell[];
   geysers: GeyserSpawn[];
+  template_placements: TemplatePlacement[];
+  template_rule_outcomes: TemplateRuleOutcome[];
   buildings: EntitySpawn[];
   pickupables: EntitySpawn[];
   other_entities: EntitySpawn[];
 }
 
+interface TemplatePlacement {
+  template: string;                   // e.g. "poi/frozen/heatsink_a"
+  x: number; y: number;               // anchor cell
+  rule: string | null;                // ruleId, "storytrait:<path>", "starting_base", or null
+  origin: TemplateRuleOrigin;         // exact rule that placed it
+}
+
+// (file, index) joins against the yaml as read: index is the position in
+// the authored rule array, before trait removals and the priority sort.
+interface TemplateRuleOrigin {
+  kind: 'world' | 'subworld' | 'worldTrait' | 'clusterMixing'
+      | 'subworldMixing' | 'storyTrait' | 'startingBase';
+  file: string;                       // snapshot files-map key
+  index: number | null;               // null for startingBase
+  ruleId: string | null;
+  world?: string;                     // world whose pass ran it (all kinds but world/startingBase)
+  placement?: number;                 // clusterMixing: worldPlacements index in file
+}
+
+// One per rule evaluated, in evaluation order (rule pass, then story
+// traits), including rules that placed nothing.
+interface TemplateRuleOutcome {
+  origin: TemplateRuleOrigin;
+  listRule: string;                   // yaml listRule, e.g. "GuaranteeSomeTryMore"
+  someCount: number;
+  moreCount: number;
+  times: number;
+  template_count: number;             // names.length
+  guaranteed: number;                 // placements the game requires, over all iterations
+  placed: number;
+  failed: boolean;                    // ApplyTemplateRule returned false
+  rolled_back: boolean;               // story trait failed here; its placements were removed
+}
+
 interface BiomeCell {
   id: number;
   type: string;                       // subworld type path

package/index.d.ts

@@ -204,6 +204,13 @@ export interface WorldgenFailure {
   world_index: number;
   /** Human-readable description. */
   message: string;
+  /**
+   * Present when a guaranteed template rule failed (`stage:
+   * "TemplateSpawning"`): the rule's origin, with `world` always set to
+   * the world whose pass ran it. That world can differ from
+   * `world_index`, which follows the game's error-reporting world.
+   */
+  origin?: TemplateRuleOrigin;
 }
 
 export interface WorldgenEvent {
@@ -303,6 +310,7 @@ export interface WorldMapData {
   biome_cells: BiomeCell[];
   geysers: GeyserSpawn[];
   template_placements: TemplatePlacement[];
+  template_rule_outcomes: TemplateRuleOutcome[];
   buildings: EntitySpawn[];
   pickupables: EntitySpawn[];
   other_entities: EntitySpawn[];
@@ -316,6 +324,100 @@ export interface TemplatePlacement {
   y: number;
   /** `ruleId`, `"storytrait:<path>"`, `"starting_base"`, or `null`. */
   rule: string | null;
+  /** The rule (or starting base) that placed this template. */
+  origin: TemplateRuleOrigin;
+}
+
+/**
+ * Where a template rule is authored:
+ * - `world`: world yaml `worldTemplateRules[index]`.
+ * - `subworld`: subworld yaml `subworldTemplateRules[index]`, for every
+ *   subworld in the world's `subworldFiles`, including subworlds that
+ *   subworld mixing or `worldMixing.additionalSubworldFiles` added.
+ * - `worldTrait`: world trait yaml `additionalWorldTemplateRules[index]`.
+ * - `clusterMixing`: cluster yaml
+ *   `worldPlacements[placement].worldMixing.additionalWorldTemplateRules[index]`.
+ *   Applied to a placement whose world was substituted by world mixing.
+ * - `subworldMixing`: subworld-mixing settings yaml
+ *   `additionalWorldTemplateRules[index]`.
+ * - `storyTrait`: story trait yaml `additionalWorldTemplateRules[index]`.
+ * - `startingBase`: the world yaml's `startingBaseTemplate`. Not a rule
+ *   array, so `index` is `null`.
+ *
+ * `index` is the position in the authored array, before a trait's
+ * `removeWorldTemplateRulesById` and before the priority sort, so
+ * `(file, index)` joins against the yaml as read, independent of seed.
+ * A world that lists the same subworld twice, or a subworld-mixing file
+ * chosen for two slots, evaluates that rule twice under the same key.
+ */
+export interface TemplateRuleOrigin {
+  kind:
+    | 'world'
+    | 'subworld'
+    | 'worldTrait'
+    | 'clusterMixing'
+    | 'subworldMixing'
+    | 'storyTrait'
+    | 'startingBase';
+  /** Snapshot files-map key, e.g. `"expansion1::worldgen/worlds/TerraMoonlet.yaml"`. */
+  file: string;
+  index: number | null;
+  ruleId: string | null;
+  /**
+   * Files-map key of the world whose pass ran the rule. Set for every
+   * kind except `world` and `startingBase`, whose `file` is that world.
+   */
+  world?: string;
+  /** `worldPlacements` index in `file`; `clusterMixing` only. */
+  placement?: number;
+}
+
+/**
+ * One template rule evaluated in a world's template pass, in evaluation
+ * order: the rule pass (priority-sorted world, trait, mixing and
+ * subworld rules), then the story-trait pass. Rules that placed nothing
+ * are included. Yaml-sourced fields keep their yaml names.
+ */
+export interface TemplateRuleOutcome {
+  origin: TemplateRuleOrigin;
+  listRule:
+    | 'GuaranteeOne'
+    | 'GuaranteeSome'
+    | 'GuaranteeSomeTryMore'
+    | 'GuaranteeAll'
+    | 'GuaranteeRange'
+    | 'TryOne'
+    | 'TrySome'
+    | 'TryRange'
+    | 'TryAll';
+  someCount: number;
+  moreCount: number;
+  times: number;
+  /** Length of the rule's `names` list. */
+  template_count: number;
+  /**
+   * Placements the game requires, summed over `times` iterations: the
+   * per-iteration guarantee from `listRule` (`someCount`, 1, the
+   * candidate count for `GuaranteeAll`, the rolled range value). An
+   * iteration with no usable candidates (all used, missing, or none
+   * left without `allowDuplicates`) is skipped and adds nothing.
+   */
+  guaranteed: number;
+  /** Templates this rule placed. `GuaranteeSomeTryMore` can exceed `guaranteed`. */
+  placed: number;
+  /**
+   * The game's `ApplyTemplateRule` returned false: a guarantee went
+   * unmet, or `overridePlacement` hit a cell that already has a
+   * template. Outside the story-trait pass this aborts worldgen in game
+   * (see `failure`).
+   */
+  failed: boolean;
+  /**
+   * Story-trait rule whose trait failed on this world: every placement
+   * of that trait here was removed, and the trait moved on to another
+   * world. `placed` still counts what this rule placed before removal.
+   */
+  rolled_back: boolean;
 }
 
 export interface BiomeCell {
@@ -497,6 +599,8 @@ export interface PartialWorld {
   world_traits: string[];
   geysers: GeyserSpawn[];
   template_placements: TemplatePlacement[];
+  /** Story-trait rules are absent (`story_traits_skipped`). */
+  template_rule_outcomes: TemplateRuleOutcome[];
   element_idx: Uint16Array;
   mass: Float32Array;
   temperature: Float32Array;
@@ -540,7 +644,7 @@ export interface PartialsResult {
   worlds: PartialWorld[];
   /** Requested selectors that matched no slot this seed. */
   absent: string[];
-  failure?: { stage: string; world_index: number; message: string } | null;
+  failure?: WorldgenFailure | null;
 }
 
 // -----------------------------------------------------------------------

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@onimaxxing/worldgen-node",
   "description": "WASM entry point for ONI worldgen",
-  "version": "0.31.3",
+  "version": "0.33.0",
   "license": "MIT",
   "repository": {
     "type": "git",