@onimaxxing/worldgen-node 0.20.1 → 0.21.1

package/editor_settings.d.ts

@@ -9,10 +9,13 @@
 //     '@onimaxxing/worldgen';
 //
 //   await init();
+//   // snapshot.files() is keyed by Klei on-disk path (optionally
+//   // DLC-qualified, e.g. 'expansion1::worldgen/worlds/...') — NOT by
+//   // the short registry keys used inside WorldgenBundle.
 //   const files = worldgen.snapshot.files();
-//   const world: World = JSON.parse(files['worlds/SandstoneDefault']);
+//   const world: World = JSON.parse(files['worldgen/worlds/SandstoneDefault.yaml']);
 //   world.iconScale = 2.0;
-//   files['worlds/SandstoneDefault'] = JSON.stringify(world);
+//   files['worldgen/worlds/SandstoneDefault.yaml'] = JSON.stringify(world);
 //   worldgen.snapshot.load(files);
 //   // Cluster cache invalidated; next worldgen.generate(...) uses mutated settings.
 
@@ -60,11 +63,12 @@ export interface WorldgenBundle {
    * (`SNDST-C-42-0-4A-*`) names them.
    */
   story_traits: Record<string, WorldTrait>;
-  /** Per-feature configuration (geyser tables, ruins tables, etc.). */
+  /** Per-feature geometry + element choice groups keyed by feature path. */
   feature_settings: Record<string, FeatureSettings>;
   /**
    * DLC-level mixing settings keyed by DLC id (e.g. `"expansion1"`).
-   * Controls which mixing options are available per cluster.
+   * Holds starmap additions (space destinations, space POIs, lore
+   * unlocks) appended when that DLC's mixing setting is enabled.
    */
   dlc_mixing: Record<string, DlcMixingSettings>;
   /**
@@ -87,10 +91,41 @@ export interface LookupsBundle {
   rooms: Record<string, RoomConfig>;
   /** Named `[minKelvin, maxKelvin]` ranges. Subworlds reference these via `temperatureRange`. */
   temperatures: Record<string, [number, number]>;
+  /**
+   * Border-biome element bands keyed by border name (e.g. `"seaBed"`).
+   * Subworlds reference these via `borderOverride`.
+   */
+  borders: Record<string, WeightedSimHash[]>;
   /** Pre-authored templates (bases, geyser rooms, POIs) keyed by template path. */
   templates: Record<string, TemplateContainer>;
 }
 
+/**
+ * Per-entry mass/temperature overrides on a {@link WeightedSimHash}.
+ * Used by border entries like `seaBed.Lime { massOverride: 250 }`.
+ */
+export interface WeightedSimHashOverrides {
+  massOverride?: number | null;
+  temperatureOverride?: number | null;
+}
+
+/**
+ * Weighted element reference (ProcGen.WeightedSimHash). Used in border
+ * definitions and biome element bands.
+ */
+export interface WeightedSimHash {
+  /** Element name (e.g. `"SandStone"`). */
+  element: string;
+  /** Relative weight within the band. */
+  weight: number;
+  /** Disease name applied to spawned mass. Null for sterile. */
+  disease?: string | null;
+  /** Disease germ count. */
+  diseaseCount: number;
+  /** Optional per-entry mass/temperature overrides. */
+  overrides: WeightedSimHashOverrides;
+}
+
 /** Full snapshot: worldgen and lookups in one blob. */
 export interface FullBundle extends WorldgenBundle, LookupsBundle {}
 
@@ -125,9 +160,12 @@ export type WorldSize = Vector2I;
 
 /**
  * Overworld-cell layout algorithm.
- * - `Default`: standard Voronoi-tree layout (used by every stock world).
- * - `PowerTree`: weighted Voronoi via MIConvexHull, used by a handful of
- *   special worlds.
+ * - `PowerTree`: weighted Voronoi via MIConvexHull. This is what nearly
+ *   every stock world uses (94 of 96 world YAMLs set it explicitly).
+ * - `Default`: plain Voronoi-tree layout; only worlds that omit
+ *   `layoutMethod` entirely (Helicona, TheRock) fall back to it.
+ *
+ * Input also accepts the legacy alias `"VoronoiTree"` for `Default`.
  */
 export type LayoutMethod = 'Default' | 'PowerTree';
 
@@ -188,10 +226,16 @@ export type FilterCommand =
 /**
  * Point-sampling strategy used when placing subworld centroids and
  * mob/room sample points. `PoissonDisk` (the default) produces
- * evenly-spaced points; `UniformSquare` is a dense grid used by a
- * few special cases.
+ * evenly-spaced points; the `Uniform*` variants are regular lattices.
+ * Stock `defaults.yaml` sets `OverworldSampleBehaviour: UniformHex`.
  */
-export type SampleBehaviour = 'PoissonDisk' | 'UniformSquare';
+export type SampleBehaviour =
+  | 'PoissonDisk'
+  | 'UniformSquare'
+  | 'UniformHex'
+  | 'UniformScaledHex'
+  | 'UniformSpiral'
+  | 'UniformCircle';
 
 /**
  * Subworld zone type. Drives the game's zone colour, the
@@ -230,12 +274,11 @@ export type ZoneType =
   | 'Reef';
 
 /**
- * Named temperature band that subworlds reference. The actual Kelvin
- * range for each name lives in `LookupsBundle.temperatures`. Stock
- * ONI defines 13 bands spanning extremely cold → extremely hot; the
- * last few aliases are kept for older configs.
+ * The temperature band names stock ONI defines: 14 bands spanning
+ * extremely cold → extremely hot, plus 5 legacy aliases kept for
+ * older configs.
  */
-export type TemperatureRange =
+export type KnownTemperatureRange =
   | 'ExtremelyCold'
   | 'VeryVeryCold'
   | 'VeryCold'
@@ -246,6 +289,7 @@ export type TemperatureRange =
   | 'Room'
   | 'HumanWarm'
   | 'HumanHot'
+  | 'SomewhatHot'
   | 'Hot'
   | 'VeryHot'
   | 'ExtremelyHot'
@@ -255,6 +299,15 @@ export type TemperatureRange =
   | 'Warm'
   | 'CoolMarginal';
 
+/**
+ * Named temperature band that subworlds reference. The actual Kelvin
+ * range for each name lives in `LookupsBundle.temperatures`. In
+ * `SnapshotMode: 'Strict'` only {@link KnownTemperatureRange} names
+ * are accepted; in `'Extensions'` mode any string is valid provided
+ * it resolves to a `tables.temperatures.add` entry.
+ */
+export type TemperatureRange = KnownTemperatureRange | (string & {});
+
 /**
  * A constraint on which overworld cells a subworld/template is
  * allowed to occupy. Multiple filters chain via `command`; the
@@ -264,7 +317,7 @@ export type TemperatureRange =
 export interface AllowedCellsFilter {
   /** How to interpret the `tag` reference (see {@link TagCommand}). */
   tagcommand?: TagCommand;
-  /** Layout tag this filter keys off. Omitted when `tagcommand` is `Default`. */
+  /** Layout tag this filter keys off. Serialized as `null` (not omitted) when unset. */
   tag?: string | null;
   /** Minimum cell distance when `tagcommand` is `DistanceFromTag`. */
   minDistance?: number;
@@ -582,6 +635,12 @@ export interface Subworld {
   overrideNoise?: string | null;
   /** Path into `noise`: optional density modulation. */
   densityNoise?: string | null;
+  /**
+   * Backwall noise tree key (e.g. `dlc5::noise/reefNoise`). When set,
+   * the subworld's cells get a `<biome>_backwall` element band applied
+   * to populate the backwall layer.
+   */
+  backwallNoise?: string | null;
   /** Name of the border-biome config applied around this subworld. */
   borderOverride?: string | null;
   /** Higher wins when two neighbouring subworlds both claim a border. */
@@ -632,7 +691,11 @@ export interface Subworld {
   minEnergy?: number;
   /** Template-spawn rules scoped to this subworld's cells. */
   subworldTemplateRules?: TemplateSpawnRules[] | null;
-  /** Catch-all for Subworld fields not enumerated above. */
+  /**
+   * Index signature for forward compatibility when reading. Note:
+   * the Rust struct is closed — keys it doesn't declare are silently
+   * dropped on `snapshot.load()`, not round-tripped.
+   */
   [key: string]: unknown;
 }
 
@@ -739,7 +802,7 @@ export interface DefaultSettings {
 // Mob & room configs.
 // ---------------------------------------------------------------------------
 
-/** Integer count range used by mob/room `density`. */
+/** Float count range used by mob/room `density`. */
 export interface MinMaxConfig {
   min: number;
   max: number;
@@ -766,14 +829,16 @@ export type MobLocation =
   | 'AnyFloor'
   | 'LiquidCeiling'
   | 'Liquid'
-  | 'EntombedFloorPeek';
+  | 'EntombedFloorPeek'
+  | 'AnchoredToBackWall'
+  | 'LiquidFloorCavityNoRequired';
 
 /**
  * Mob spawn configuration (ProcGen.Mob). Controls how many copies of
  * a mob prefab get scattered across the grid after layout.
  */
 export interface MobConfig {
-  /** Prefab-selection strategy name (e.g. `"WeightedRandom"`). */
+  /** Prefab-selection strategy name: `"RandomPoints"` or `"Centroid"`. */
   selectMethod?: string;
   /** Roll range for the count of this mob placed per world. */
   density?: MinMaxConfig;
@@ -829,8 +894,21 @@ export interface TemplateInfo {
   area: number;
   /** Lower-left cell of the bounding box, relative to the template origin. */
   min: TemplateVec2I;
-  /** Upper-right cell of the bounding box. */
+  /**
+   * Upper-right cell of the bounding box. Legacy: the game's
+   * `TemplateContainer.Info` has no `max` — it is kept only for
+   * back-compat with snapshots this package already emitted, and no
+   * game YAML sets it.
+   */
   max: TemplateVec2I;
+  /** Game `Info.tags`. Rare; omitted when absent. */
+  tags?: string[] | null;
+  /**
+   * Game `Info.discover_tags` — resource tags revealed to the player
+   * when the template is discovered (e.g. ceresBase declares
+   * `Pemmican`). Omitted when absent.
+   */
+  discover_tags?: string[] | null;
 }
 
 /**
@@ -858,6 +936,18 @@ export interface TemplateCell {
    * templates are normally pre-revealed. Used by puzzle/POI cells.
    */
   preventFoWReveal?: boolean | null;
+  /**
+   * Backwall element name behind this cell (e.g. `"Salt"`). Defaults
+   * to Vacuum when absent, and `TemplateLoader` stamps backwall data
+   * for EVERY template cell — omitting this field actively CLEARS the
+   * backwall behind the template footprint (the vacuum cavity around
+   * the printing pod is exactly that).
+   */
+  backwallElement?: string | null;
+  /** Backwall mass in kg. Default 0 (Vacuum backwall). */
+  backwallMass?: number;
+  /** Backwall temperature in K. Default 0 (Vacuum backwall). */
+  backwallTemperature?: number;
 }
 
 /**
@@ -871,12 +961,28 @@ export interface TemplateStorageItem {
   element?: string | null;
   /** Quantity (mass for elements, count for creatures/items). */
   units: number;
+  /** True when the stored item is raw ore (C# `StorageItem.isOre`). Omitted when false. */
+  isOre?: boolean;
   /** Temperature in Kelvin. */
   temperature: number;
-  /** Free-form rottable state; carried through verbatim. */
+  /** Disease on the stored item (e.g. `"SlimeLung"`). Omitted when absent. */
+  diseaseName?: string | null;
+  /** Disease germ count on the stored item. Omitted when 0. */
+  diseaseCount?: number;
+  /** Free-form rottable state (`{ rotAmount: number }`); carried through verbatim. */
   rottable?: unknown;
 }
 
+/**
+ * One `{ id, value }` override pair applied to a spawned prefab
+ * (C# `Prefab.template_amount_value`) — e.g. ocean geyser POIs preset
+ * `AirPressure` / `Temperature` this way.
+ */
+export interface TemplateAmountValue {
+  id?: string | null;
+  value: number;
+}
+
 /**
  * A prefab placed by a template (building, pickupable, ore deposit,
  * or other entity). Which `TemplateContainer` array it lives in
@@ -885,9 +991,9 @@ export interface TemplateStorageItem {
 export interface TemplatePrefab {
   /** Prefab id (e.g. `"Tile"`, `"Headquarters"`, `"Hatch"`). */
   id?: string | null;
-  /** X offset from template origin (can be fractional). */
+  /** X offset from template origin. Integer in game files (C# `int`). */
   location_x: number;
-  /** Y offset from template origin (can be fractional). */
+  /** Y offset from template origin. Integer in game files (C# `int`). */
   location_y: number;
   /** Element override (for ore-like prefabs). */
   element?: string | null;
@@ -897,12 +1003,36 @@ export interface TemplatePrefab {
   units: number;
   /** Prefab type hint (e.g. `"Pickupable"`, `"Ore"`). */
   type?: string | null;
+  /** Disease on the spawned prefab (e.g. `"SlimeLung"`). Omitted when absent. */
+  diseaseName?: string | null;
+  /** Disease germ count on the spawned prefab. Omitted when 0. */
+  diseaseCount?: number;
   /** Container contents (for storage buildings like RationBox). */
   storage?: TemplateStorageItem[];
   /** Rotation hint for orientable buildings. */
   rotationOrientation?: string | null;
+  /** Building skin/facade id (C# `Prefab.facadeId`). Omitted when absent. */
+  facadeId?: string | null;
   /** Connections bitfield for connectable prefabs (pipes, wires). */
   connections?: number | null;
+  /** Lore-unlock id granted when this prefab is discovered. Omitted when absent. */
+  loreUnlockId?: string | null;
+  /** Display text for the lore unlock. Omitted when absent. */
+  loreDisplayText?: string | null;
+  /** Next collection id in the lore chain. Omitted when absent. */
+  loreNextCollectionId?: string | null;
+  /**
+   * Rottable state on the prefab itself (`{ rotAmount: number }`);
+   * carried through verbatim. Omitted when absent.
+   */
+  rottable?: unknown;
+  /**
+   * Amount overrides applied at spawn — e.g. geyser `AirPressure` /
+   * `Temperature` presets in ocean POI templates. Omitted when empty.
+   */
+  amounts?: TemplateAmountValue[];
+  /** Non-Amount value overrides (same shape as `amounts`). Omitted when empty. */
+  other_values?: TemplateAmountValue[];
 }
 
 /**
@@ -914,9 +1044,14 @@ export interface TemplatePrefab {
 export interface TemplateContainer {
   /** Internal template name. Usually matches the config path's last segment. */
   name?: string | null;
+  /**
+   * Template stamping priority (C# `TemplateContainer.priority`). No
+   * stock worldgen YAML sets it; carried for round-trip. Omitted when 0.
+   */
+  priority?: number;
   /** Bounding-box metadata. */
   info: TemplateInfo;
-  /** Element/mass/temperature per cell. */
+  /** Element/mass/temperature per cell, including backwall data. */
   cells: TemplateCell[];
   /** Building prefabs (tiles, machines). */
   buildings: TemplatePrefab[];
@@ -924,6 +1059,12 @@ export interface TemplateContainer {
   pickupables: TemplatePrefab[];
   /** Elemental-ore deposits. */
   elementalOres: TemplatePrefab[];
+  /**
+   * Backwall entity prefabs. Written when the game saves a template
+   * that captures backwall decor; no stock worldgen YAML uses it yet.
+   * Omitted when empty.
+   */
+  backwallEntities?: TemplatePrefab[];
   /** Other entities (lights, furniture, decor). */
   otherEntities: TemplatePrefab[];
 }
@@ -937,22 +1078,33 @@ export interface TemplateContainer {
 export interface ClusterLayout { [key: string]: unknown }
 
 /**
- * Noise-tree definition (base / override / density). Editing primitive
- * frequencies and seeds changes every cell of every world that
- * references the tree.
+ * Noise-tree definition (base / override / density). Editing filter
+ * frequencies or primitive seeds changes every cell of every world
+ * that references the tree.
  */
 export interface NoiseTree { [key: string]: unknown }
 
-/** Element/mass bands keyed on noise-field thresholds. */
+/**
+ * Biome element bands. Shape: `{ lookup_table: { <variantName>:
+ * band[] } }` keyed by biome variant name (e.g. `"Basic"`, `"Snowy"`);
+ * each band is `{ content, bandSize, overrides? }` where `bandSize`
+ * is a probability weight.
+ */
 export interface BiomeSettings { [key: string]: unknown }
 
 /** Trait definition: names, tags, and modifiers applied when a roll picks it. */
 export interface WorldTrait { [key: string]: unknown }
 
-/** Per-feature configuration (geyser type pool, ruins content tables, etc.). */
+/**
+ * Feature configuration: shape, blob size, borders, tags, internal
+ * mobs, and `ElementChoiceGroups`.
+ */
 export interface FeatureSettings { [key: string]: unknown }
 
-/** DLC-level mixing settings: which asteroid/subworld substitutions are eligible. */
+/**
+ * DLC-level mixing settings: starmap space destinations, space POIs,
+ * and lore unlocks appended when the DLC mixing setting is enabled.
+ */
 export interface DlcMixingSettings { [key: string]: unknown }
 
 /** Whole-world mixing option (substitute asteroid type A for B). */
@@ -988,8 +1140,10 @@ export type FilePath = string;
  * the `add` maps (last-wins) and unioning `remove`.
  */
 export interface ComposableDict<V> {
-  add: Record<string, V>;
-  remove: string[];
+  /** Optional on input; always present on output. */
+  add?: Record<string, V>;
+  /** Optional on input; always present on output. */
+  remove?: string[];
 }
 
 /** Whole-file-replace categories, keyed by the on-disk Klei path. */
@@ -1014,7 +1168,87 @@ export interface SnapshotTables {
   rivers: ComposableDict<unknown>;
   rooms: ComposableDict<RoomConfig>;
   temperatures: ComposableDict<[number, number]>;
-  borders: ComposableDict<Array<unknown>>;
+  borders: ComposableDict<WeightedSimHash[]>;
+  /**
+   * `worldgen/layers.yaml` (ProcGen.LevelLayerSettings). Stored
+   * verbatim for round-trip; not consumed by Rust worldgen.
+   */
+  layers: LevelLayerSettings;
+  /**
+   * `elements/*.yaml` runtime overlay, in load order. First entry
+   * wins for a given elementId (base elements beat DLC duplicates),
+   * matching Klei's `ElementLoader.Load`.
+   */
+  extra_elements: ElementYaml[];
+}
+
+/** `worldgen/layers.yaml` — vertical biome band list. */
+export interface LevelLayerSettings {
+  LevelLayers: LevelLayer[];
+}
+
+/** One vertical band: element/feature tokens + height fraction. */
+export interface LevelLayer {
+  content: string[];
+  bandSize: number;
+}
+
+/**
+ * Runtime element definition parsed from `elements/*.yaml`. Field set
+ * mirrors the compile-time element table; keys are Klei's camelCase.
+ */
+export interface ElementYaml {
+  elementId: string;
+  state: 'Vacuum' | 'Solid' | 'Liquid' | 'Gas';
+  defaultTemperature: number;
+  defaultMass: number;
+  defaultPressure: number;
+  maxMass: number;
+  specificHeatCapacity: number;
+  thermalConductivity: number;
+  highTemp: number;
+  highTempTransitionTarget: string;
+  lowTemp: number;
+  lowTempTransitionTarget: string;
+  lowTempTransitionOreId: string;
+  lowTempTransitionOreMassConversion: number;
+  highTempTransitionOreId: string;
+  highTempTransitionOreMassConversion: number;
+  hardness: number;
+  isDisabled: boolean;
+  strength: number;
+  molarMass: number;
+  lightAbsorptionFactor: number;
+  radiationAbsorptionFactor: number;
+  radiationPer1000Mass: number;
+  solidSurfaceAreaMultiplier: number;
+  liquidSurfaceAreaMultiplier: number;
+  gasSurfaceAreaMultiplier: number;
+  flow: number;
+  toxicity: number;
+  materialCategory: string;
+  dlcId: string;
+  tags: string[];
+  sublimateId: string;
+  sublimateProbability: number;
+  sublimateRate: number;
+  sublimateEfficiency: number;
+  offGasPercentage: number;
+  speed: number;
+  minHorizontalFlow: number;
+  minVerticalFlow: number;
+}
+
+/**
+ * One element-field override carried by a mod wrapper that can't be
+ * expressed in YAML (mod DLLs patch `Element` at runtime). Keys are
+ * snake_case on the wire.
+ */
+export interface ElementOverride {
+  /** Element name as in Klei's element YAML (e.g. `"Radium"`). */
+  element_name: string;
+  /** New `Element.radiationPer1000Mass`; omitted means unchanged. */
+  radiation_per1000_mass?: number;
 }
 
 /** Wholesale-replace singletons: defaults + DLC/world/subworld mixing. */
@@ -1025,10 +1259,16 @@ export interface SnapshotMixing {
   subworld_mixing: Record<string, SubworldMixingSettings>;
 }
 
-/** The mod-ingestion snapshot returned and accepted by the snapshot helpers. */
+/**
+ * The mod-ingestion snapshot returned and accepted by the snapshot
+ * helpers. Every field (here and in the nested Snapshot* shapes) is
+ * optional on input — missing fields default to empty.
+ */
 export interface WorldgenSnapshot {
   mode: SnapshotMode;
   files: SnapshotFiles;
   tables: SnapshotTables;
   mixing: SnapshotMixing;
+  /** Runtime element patches from mod wrappers. Omitted when empty. */
+  element_overrides?: ElementOverride[];
 }

package/index.cjs

@@ -19,6 +19,10 @@ let _checksumDirty = true;
 // nothing to await.
 async function init(_opts) {}
 
+// Decode a v5 `settle_cluster_advance` binary snapshot.
+// v5 extends v4 with the U59 backwall layer (u16 elem + f32 mass +
+// f32 temp = +10 bytes per cell, 25 bytes total). Worlds without
+// `backwallNoise` in their subworld YAML emit Vacuum / 0 / 0.
 function decodeSnapshot(buf) {
   if (!buf || buf.length === 0) {
     throw new Error(
@@ -28,8 +32,8 @@ function decodeSnapshot(buf) {
   const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
   let offset = 0;
   const version = view.getUint32(offset, true); offset += 4;
-  if (version !== 4) {
-    throw new Error(`decodeSnapshot: expected version 4, got ${version}`);
+  if (version !== 5) {
+    throw new Error(`decodeSnapshot: expected version 5, got ${version}`);
   }
   const tick = view.getUint32(offset, true); offset += 4;
   const worldCount = view.getUint32(offset, true); offset += 4;
@@ -45,6 +49,9 @@ function decodeSnapshot(buf) {
     const temperature = new Float32Array(cells);
     const disease_idx = new Uint8Array(cells);
     const disease_count = new Int32Array(cells);
+    const backwall_element_idx = new Uint16Array(cells);
+    const backwall_mass = new Float32Array(cells);
+    const backwall_temperature = new Float32Array(cells);
 
     for (let c = 0; c < cells; c++) {
       element_idx[c] = view.getUint16(offset, true); offset += 2;
@@ -52,12 +59,16 @@ function decodeSnapshot(buf) {
       temperature[c] = view.getFloat32(offset, true); offset += 4;
       disease_idx[c] = view.getUint8(offset); offset += 1;
       disease_count[c] = view.getInt32(offset, true); offset += 4;
+      backwall_element_idx[c] = view.getUint16(offset, true); offset += 2;
+      backwall_mass[c] = view.getFloat32(offset, true); offset += 4;
+      backwall_temperature[c] = view.getFloat32(offset, true); offset += 4;
     }
 
     worlds.push({
       width, height,
       element_idx, mass, temperature,
       disease_idx, disease_count,
+      backwall_element_idx, backwall_mass, backwall_temperature,
     });
   }
 
@@ -131,11 +142,38 @@ const worldgen = {
     _checksumDirty = true;
   },
 
+  // Noise editor preview. See index.js for the tree-descriptor contract.
+  evaluateNoise(tree, width, height, seed) {
+    if (!tree || typeof tree !== 'object') {
+      throw new TypeError("evaluateNoise: tree must be { kind: 'named'|'inline', ... }");
+    }
+    const kind = tree.kind;
+    let value;
+    if (kind === 'named') {
+      value = tree.name;
+    } else if (kind === 'inline') {
+      value = tree.yaml;
+    } else {
+      throw new TypeError(`evaluateNoise: unknown tree.kind '${kind}'`);
+    }
+    return _wasm.evaluate_noise(kind, value, width, height, seed);
+  },
+
+  noiseNodeKinds() {
+    return JSON.parse(_wasm.noise_node_kinds());
+  },
+
   version() {
     return _wasm.game_version();
   },
 };
 
+// The nodejs build is always serial; mirrors index.js's signature
+// (null before init is impossible here — WASM loads at require time).
+function isParallel() {
+  return false;
+}
+
 // Re-export the Klei-faithful YAML parser so consumers have a
 // one-stop import for the full ingestion pipeline (YAML → JSON →
 // worldgen.snapshot.merge). Mirrors the ESM variant in `index.js`.
@@ -144,4 +182,5 @@ const { parseKleiYaml } = require('./yaml.cjs');
 module.exports = init;
 module.exports.default = init;
 module.exports.worldgen = worldgen;
+module.exports.isParallel = isParallel;
 module.exports.parseKleiYaml = parseKleiYaml;

package/index.d.ts

@@ -66,6 +66,24 @@ import type {
   DlcMixingSettings,
   WorldMixingSettings,
   SubworldMixingSettings,
+  KnownTemperatureRange,
+  WeightedSimHash,
+  WeightedSimHashOverrides,
+  TemplateAmountValue,
+  WorldgenBundle,
+  LookupsBundle,
+  FullBundle,
+  SnapshotMode,
+  FilePath,
+  ComposableDict,
+  SnapshotFiles,
+  SnapshotTables,
+  SnapshotMixing,
+  LevelLayerSettings,
+  LevelLayer,
+  ElementYaml,
+  ElementOverride,
+  WorldgenSnapshot,
 } from './editor_settings.js';
 
 export type {
@@ -114,6 +132,24 @@ export type {
   DlcMixingSettings,
   WorldMixingSettings,
   SubworldMixingSettings,
+  KnownTemperatureRange,
+  WeightedSimHash,
+  WeightedSimHashOverrides,
+  TemplateAmountValue,
+  WorldgenBundle,
+  LookupsBundle,
+  FullBundle,
+  SnapshotMode,
+  FilePath,
+  ComposableDict,
+  SnapshotFiles,
+  SnapshotTables,
+  SnapshotMixing,
+  LevelLayerSettings,
+  LevelLayer,
+  ElementYaml,
+  ElementOverride,
+  WorldgenSnapshot,
 };
 
 // -----------------------------------------------------------------------
@@ -438,10 +474,11 @@ export interface InitOptions {
   /**
    * - `'auto'` (default): pick parallel when `crossOriginIsolated` and
    *   `SharedArrayBuffer` are available, with
-   *   `navigator.hardwareConcurrency` workers. Otherwise serial.
+   *   `navigator.hardwareConcurrency` workers (4 when unavailable).
+   *   Otherwise serial.
    * - `'serial'`: force the serial build.
-   * - `number`: force parallel with this many workers (falls back to
-   *   serial when parallel isn't available).
+   * - `number`: worker count to use *if* feature detection picks
+   *   parallel. Cannot force parallel on a host that fails detection.
    */
   threads?: number | 'auto' | 'serial';
 }
@@ -451,6 +488,10 @@ export interface InitOptions {
  * a parallel (rayon + SharedArrayBuffer) build; `init()` feature-detects
  * the runtime, loads the appropriate one, and on parallel hosts also
  * spawns the worker pool. Memoized — extra calls short-circuit.
+ *
+ * On the node package (`@onimaxxing/worldgen-node`) this is a no-op:
+ * the WASM loads synchronously at require time and `InitOptions` is
+ * ignored (always serial).
  */
 export default function init(options?: InitOptions): Promise<void>;
 
@@ -466,8 +507,12 @@ export const worldgen: {
   /**
    * Generate a cluster from a game coordinate. Caches the cluster in
    * the WASM thread-local slot, replacing any previously cached cluster.
+   *
+   * Returns `{ error }` (not a throw) when the coordinate fails to
+   * parse, the cluster isn't found, or serialization fails — check
+   * for the `error` key before reading `MapData` fields.
    */
-  generate(coordinate: string): MapData;
+  generate(coordinate: string): MapData | { error: string };
 
   /**
    * Advance the cached cluster's settle sim to `targetTick` (in
@@ -485,8 +530,11 @@ export const worldgen: {
    * cell state and return the refreshed entity lists. Pairs with
    * `advance()`. liquid/gas settling can invalidate earlier mob
    * placements. Template-placed entities persist across calls.
+   *
+   * Returns `{ error }` when no cluster is cached (call `generate`
+   * first).
    */
-  entities(): EntitySpawners;
+  entities(): EntitySpawners | { error: string };
 
   /**
    * Drop the cached generated cluster. Editor settings (if mutated)
@@ -523,9 +571,13 @@ export const worldgen: {
    *   typing below is advisory: it nudges callers toward
    *   defensive-copy hygiene at the API surface even though the
    *   underlying object is yours to mutate.
-   * - **Path-set preservation.** `load(filesMap)` neither adds nor
-   *   drops paths. The set of keys in the next `files()` exactly
-   *   matches the keys you passed in.
+   * - **Path-set near-preservation.** After `load(filesMap)`, the
+   *   next `files()` returns the paths you passed in, except:
+   *   `_snapshot/manifest.json`, `worldgen/defaults.yaml`, and
+   *   per-DLC `worldgen/mixing.yaml` are always emitted (added if
+   *   you omitted them), while empty table files
+   *   (`worldgen/borders.yaml`, `worldgen/rivers.yaml`,
+   *   `_snapshot/element_overrides.json`) are dropped.
    * - **Merge collision = last-wins.** When `merge(files)` is called
    *   with a path already present in SETTINGS, the new value
    *   replaces the old one. Within a single `merge()` call the same
@@ -590,9 +642,10 @@ export const worldgen: {
      * settings.
      *
      * Cached: the hash is computed once per snapshot version, on the
-     * first call after any `loadVanilla` / `load` / `merge` / `remove`
-     * / `reset`. Subsequent calls return the cached string until the
-     * next mutation. Cold recompute is ≈80 ms on the full vanilla
+     * first call after any mutation (`loadVanilla` /
+     * `loadVanillaExtensions` / `load` / `loadExtensions` / `merge` /
+     * `remove` / `reset`). Subsequent calls return the cached string
+     * until the next mutation. Cold recompute is ≈80 ms on the full vanilla
      * snapshot; steady-state cache hit is a single property read.
      */
     checksum(): string;
@@ -646,8 +699,10 @@ export const worldgen: {
    * back into the active SETTINGS yet.
    *
    * Sample coords map `width × height` linearly onto the tree's
-   * `settings.lowerBound..upperBound` rectangle (cell-centred), so the
-   * preview honours the editor's `SampleSettings.zoom` / bounds.
+   * `settings.lowerBound..upperBound` rectangle (cell-centred). The
+   * preview honours the editor's bounds but NOT `SampleSettings.zoom`
+   * — real worldgen sampling applies zoom, so previews of zoomed
+   * trees differ from engine output.
    *
    * Throws if the named tree doesn't exist, the inline YAML fails to
    * parse, or the tree has no terminator link.
@@ -702,8 +757,9 @@ export interface NoiseNodeKindSpec {
 export interface NoiseNodeParam {
   /** YAML field name (e.g. `"frequency"`, `"modifyType"`). */
   name: string;
-  /** Scalar type the editor should render. */
-  type: "f32" | "i32" | "bool" | "enum" | "vec2" | "vec3" | "string";
+  /** Scalar type the editor should render. `"array"` is emitted for
+   *  list-valued params (none in the current node structs). */
+  type: "f32" | "i32" | "bool" | "enum" | "vec2" | "vec3" | "string" | "array";
   /** Default value matching the corresponding struct's `Default` impl. */
   default: number | string | boolean | { X: number; Y: number } | { X: number; Y: number; Z: number };
   /** When `type === "enum"`, the allowed string values. */

package/package.json

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

package/yaml.cjs

@@ -1,7 +1,7 @@
-// CommonJS variant of yaml.js. The published wrapper ships one or
-// the other depending on `--target` (web → yaml.js, nodejs →
-// yaml.cjs). The logic is identical; only the module syntax differs.
-// See yaml.js for the full Klei-compatibility commentary.
+// CommonJS variant of yaml.js — keep the two in lockstep. The
+// published wrapper ships one or the other depending on `--target`
+// (web → yaml.js, nodejs → yaml.cjs). See yaml.js for the full
+// Klei-compatibility commentary.
 
 const yaml = require('js-yaml');
 
@@ -14,9 +14,15 @@ const KleiBool = new yaml.Type('tag:yaml.org,2002:bool', {
 
 const KleiSchema = yaml.DEFAULT_SCHEMA.extend({ implicit: [KleiBool] });
 
+// Leading-dot floats (`.5`, `-.5`, `+.5`) that js-yaml's default
+// resolver leaves as strings. Klei ships them (e.g.
+// `worldgen/traits/MisalignedStart.yaml`: `min: -.2`).
+const LEADING_DOT_FLOAT = /^[-+]?\.[0-9]+(?:[eE][-+]?[0-9]+)?$/;
+
 function parseKleiYaml(text) {
     const preprocessed = text.replace(/\t/g, '    ');
-    const raw = yaml.load(preprocessed, { schema: KleiSchema });
+    // `json: true` gives YamlDotNet's last-wins on duplicate keys.
+    const raw = yaml.load(preprocessed, { schema: KleiSchema, json: true });
     return stripNulls(raw);
 }
 
@@ -38,6 +44,9 @@ function stripNulls(node) {
         }
         return out;
     }
+    if (typeof node === 'string' && LEADING_DOT_FLOAT.test(node)) {
+        return parseFloat(node);
+    }
     return node;
 }
 

package/yaml.d.ts

@@ -8,11 +8,16 @@
  *
  *   1. Tabs are pre-expanded to 4 spaces (Klei's `readText.Replace`).
  *   2. YAML 1.1 boolean sentinels (`yes/no/on/off`) on plain scalars
- *      become booleans; quoted forms stay as strings.
+ *      become booleans; quoted forms stay as strings. Single-letter
+ *      `y`/`n` deliberately stay strings (`Y:` is a vector key).
  *   3. Duplicate mapping keys: last-wins.
- *   4. Unknown YAML tags are silently stripped.
- *   5. Null mapping values are dropped recursively (Klei's reflection-
- *      based loader treats `key:` as "field not present").
+ *   4. Null values are dropped recursively — mapping values (Klei's
+ *      reflection-based loader treats `key:` as "field not present")
+ *      and array elements alike.
+ *   5. Leading-dot floats (`.5`, `-.2`) become numbers; js-yaml's
+ *      default resolver leaves them as strings.
+ *
+ * Unknown YAML tags (`!Foo`) throw a js-yaml parse error.
  *
  * Returns a plain JS object/array/scalar suitable for JSON.stringify.
  */