@onimaxxing/worldgen-node 0.21.2 → 0.22.0

package/README.md

@@ -10,6 +10,7 @@ same cluster the game would generate for a given coordinate.
 - Geyser, building, pickupable, and other entity spawn positions.
 - Per-cell mass, temperature, and disease (raw after `worldgen.generate`; settled after `worldgen.advance`).
 - Both basegame and Spaced Out clusters, including story traits, mixing codes, and DLC toggles.
+- Partial generation of selected worlds (`worldgen.partials`).
 
 Output is verified cell-by-cell against snapshots captured from the
 running game, with a slight modification to force determinism during
@@ -133,6 +134,28 @@ Generate a cluster from a game coordinate and return the decoded
 map (see [`MapData` shape](#mapdata-shape)). Caches the cluster
 internally, replacing anything previously cached.
 
+```ts
+worldgen.partials(coord: string, opts: PartialsOptions): PartialsResult
+```
+
+Generate only the selected worlds of a cluster. Stateless; does not
+touch the cluster cache.
+
+`opts.worlds` selects by placement index or world path (full path or
+last segment, matched after mixing). Selectors that match nothing come
+back in `absent` rather than erroring. Cell grids are pre-settle; for
+settled state use `worldgen.generate` + `worldgen.advance`.
+
+```ts
+const r = worldgen.partials('V-SNDST-C-42-0-4A-MUWF1', {
+  worlds: ['VanillaSandstoneDefault'],
+});
+for (const g of r.worlds[0]?.geysers ?? []) console.log(g.type, g.x, g.y);
+```
+
+Geyser output matches a full generate exactly. Story-trait templates
+and starmap locations are not generated in partial mode.
+
 ```ts
 worldgen.entities(): EntitySpawners
 ```

package/index.cjs

@@ -87,6 +87,10 @@ const worldgen = {
   entities() {
     return JSON.parse(_wasm.get_entity_spawners());
   },
+  // Partial worldgen; see index.js for the full contract notes.
+  partials(coord, opts) {
+    return JSON.parse(_wasm.partials_from_coordinate(coord, JSON.stringify(opts ?? {})));
+  },
   clear() {
     _wasm.clear_cluster_cache();
   },

package/index.d.ts

@@ -451,6 +451,99 @@ export interface EntitySpawnerWorld {
   other_entities: EntitySpawn[];
 }
 
+// -----------------------------------------------------------------------
+// Partial worldgen
+// -----------------------------------------------------------------------
+
+export interface PartialsOptions {
+  /**
+   * Placement indices and/or world-path strings. A string matches the
+   * POST-mixing world path for this seed, in full
+   * (`"expansion1::worlds/SandstoneDefault"`) or by its last segment,
+   * case-insensitive, not the localized display name ("Terra").
+   * Selectors that match nothing land in the result's `absent` list
+   * instead of erroring.
+   */
+  worlds: Array<number | string>;
+  /** `"templates"` (default) or `"notemplates"` (skip template placement). */
+  mode?: 'templates' | 'notemplates';
+}
+
+/**
+ * One generated world from `worldgen.partials`. Grid fields arrive as
+ * plain JSON arrays (not the typed arrays `generate` uses) and hold
+ * pre-settle state.
+ */
+export interface PartialWorld {
+  /** Placement index in the cluster layout (stable slot identity). */
+  index: number;
+  /** Post-mixing world path; see `WorldMapData.name`. */
+  name: string;
+  remixed_from: string | null;
+  remixed_source: string | null;
+  width: number;
+  height: number;
+  is_starting: boolean;
+  world_traits: string[];
+  geysers: GeyserSpawn[];
+  /**
+   * Digest-format per-world geyser hashes (FNV-1a-64, uppercase hex,
+   * empty when count is 0): the exact values the committed parity
+   * digests store. The counts hash a fixed tag allowlist that excludes
+   * some DLC5 spawners (e.g. SmallReefGeyser), so `geyser_spawns_count`
+   * can be less than `geysers.length`; the `geysers` array is the
+   * complete list.
+   */
+  geyser_spawns_sha: string;
+  geyser_spawns_count: number;
+  geyser_stats_sha: string;
+  geyser_stats_count: number;
+  element_idx: number[];
+  mass: number[];
+  temperature: number[];
+  disease_idx: number[];
+  disease_count: number[];
+  backwall_element_idx: number[];
+  backwall_mass: number[];
+  backwall_temperature: number[];
+  zone_idx: number[];
+  zone_table: string[];
+  subworld_idx: number[];
+  subworld_table: string[];
+  biome_cells: BiomeCell[];
+  buildings: EntitySpawn[];
+  pickupables: EntitySpawn[];
+  other_entities: EntitySpawn[];
+}
+
+export interface PartialsMixingApplied {
+  /** Placement index whose vanilla world was substituted. */
+  slot: number;
+  from: string;
+  to: string;
+  source: string;
+}
+
+export interface PartialsResult {
+  coordinate: string;
+  seed: number;
+  cluster: string;
+  /**
+   * Markers: story-trait templates were skipped, so cell grids on
+   * worlds that would have received one differ from a full `generate`.
+   * Geysers are unaffected.
+   */
+  partial: true;
+  story_traits_skipped: true;
+  /** World-mixing substitutions applied for this seed (all slots). */
+  mixing_applied: PartialsMixingApplied[];
+  /** Generated worlds, one per selected slot present this seed. */
+  worlds: PartialWorld[];
+  /** Requested selectors that matched no slot this seed. */
+  absent: string[];
+  failure?: { stage: string; world_index: number; message: string } | null;
+}
+
 // -----------------------------------------------------------------------
 // init + worldgen singleton
 // -----------------------------------------------------------------------
@@ -536,6 +629,17 @@ export const worldgen: {
    */
   entities(): EntitySpawners | { error: string };
 
+  /**
+   * Partial worldgen: generate only the selected worlds of a cluster.
+   * Geyser output is bit-identical to a full generate. Partial mode
+   * never places story-trait templates or assigns starmap locations.
+   * Stateless: does not populate the cluster cache used by
+   * `advance()` / `entities()`.
+   *
+   * Returns `{ error }` (not a throw) on parse/config failures.
+   */
+  partials(coordinate: string, opts: PartialsOptions): PartialsResult | { error: string };
+
   /**
    * Drop the cached generated cluster. Editor settings (if mutated)
    * are preserved.

package/oni_wasm.d.ts

@@ -92,6 +92,25 @@ export function get_entity_spawners(): string;
  */
 export function noise_node_kinds(): string;
 
+/**
+ * Partial worldgen: generate only the selected worlds of a cluster.
+ * Cluster-level pre-passes (mixing, trait selection) run over every
+ * placement; per-world phases run only for the selected slots.
+ * Stateless; does not touch `CLUSTER_CACHE`.
+ *
+ * Geyser output matches a full generate exactly, and each world
+ * carries the digest-format geyser hashes. Verified element-wise by
+ * `tests/partial_parity.rs` and against the digest corpus by
+ * `scripts/partials_geyser_verify.mjs`.
+ *
+ * Story-trait templates and starmap locations are never produced;
+ * both depend on cross-world state a partial run lacks. Stock story
+ * traits carry no geysers, so geyser output is unaffected. Cell
+ * grids are pre-settle, as with `generate`; there is no partial
+ * settle (use `generate` + `advance` for settled state).
+ */
+export function partials_from_coordinate(coordinate: string, options_json: string): string;
+
 /**
  * Toggle template placement. WASM-side counterpart of the native
  * `SKIP_TEMPLATES` env var.

package/oni_wasm.js

@@ -250,6 +250,44 @@ function noise_node_kinds() {
 }
 exports.noise_node_kinds = noise_node_kinds;
 
+/**
+ * Partial worldgen: generate only the selected worlds of a cluster.
+ * Cluster-level pre-passes (mixing, trait selection) run over every
+ * placement; per-world phases run only for the selected slots.
+ * Stateless; does not touch `CLUSTER_CACHE`.
+ *
+ * Geyser output matches a full generate exactly, and each world
+ * carries the digest-format geyser hashes. Verified element-wise by
+ * `tests/partial_parity.rs` and against the digest corpus by
+ * `scripts/partials_geyser_verify.mjs`.
+ *
+ * Story-trait templates and starmap locations are never produced;
+ * both depend on cross-world state a partial run lacks. Stock story
+ * traits carry no geysers, so geyser output is unaffected. Cell
+ * grids are pre-settle, as with `generate`; there is no partial
+ * settle (use `generate` + `advance` for settled state).
+ * @param {string} coordinate
+ * @param {string} options_json
+ * @returns {string}
+ */
+function partials_from_coordinate(coordinate, options_json) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(coordinate, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(options_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.partials_from_coordinate(ptr0, len0, ptr1, len1);
+        deferred3_0 = ret[0];
+        deferred3_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+exports.partials_from_coordinate = partials_from_coordinate;
+
 /**
  * Toggle template placement. WASM-side counterpart of the native
  * `SKIP_TEMPLATES` env var.

package/package.json

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