@onimaxxing/worldgen-node 0.15.0

package/index.d.ts

@@ -0,0 +1,682 @@
+// Consumer-facing type surface for
+// `@onimaxxing/worldgen`.
+//
+// This is the single types entry point for the package. The nested
+// settings types (World, Subworld, BiomeSettings, NoiseTree, etc.)
+// live in `editor_settings.d.ts` and are re-exported here so consumers
+// can import every type by name from the package root.
+
+// Klei-faithful YAML → JS parser. Pair with `worldgen.snapshot.merge`
+// to ingest mod content (which ships as `.yaml`):
+//
+//   const json = parseKleiYaml(readFileSync('mod/cluster.yaml', 'utf8'));
+//   worldgen.snapshot.merge({ 'expansion1::worldgen/clusters/X.yaml': JSON.stringify(json) });
+export { parseKleiYaml } from './yaml.js';
+
+// -----------------------------------------------------------------------
+// Settings types (imported and re-exported from editor_settings.d.ts).
+// `ClusterLayout`, `World`, `Subworld`, etc. are the typed schemas for
+// the JSON-string values in each entry of the `path → JSON-string`
+// snapshot files map.
+// -----------------------------------------------------------------------
+
+import type {
+  MinMax,
+  Vector2I,
+  WorldSize,
+  LayoutMethod,
+  WorldCategory,
+  ListRule,
+  TagCommand,
+  FilterCommand,
+  SampleBehaviour,
+  ZoneType,
+  TemperatureRange,
+  AllowedCellsFilter,
+  TraitRule,
+  SubworldMixingRule,
+  ModifyLayoutTagsRule,
+  TemplateSpawnRules,
+  World,
+  WeightedSubworldName,
+  Sampler,
+  Subworld,
+  Feature,
+  InternalMob,
+  CountRange,
+  WeightedBiome,
+  BaseLocation,
+  StartingWorldElement,
+  DefaultSettings,
+  MinMaxConfig,
+  MobLocation,
+  MobConfig,
+  RoomConfig,
+  TemplateVec2I,
+  TemplateInfo,
+  TemplateCell,
+  TemplateStorageItem,
+  TemplatePrefab,
+  TemplateContainer,
+  ClusterLayout,
+  NoiseTree,
+  BiomeSettings,
+  WorldTrait,
+  FeatureSettings,
+  DlcMixingSettings,
+  WorldMixingSettings,
+  SubworldMixingSettings,
+} from './editor_settings.js';
+
+export type {
+  MinMax,
+  Vector2I,
+  WorldSize,
+  LayoutMethod,
+  WorldCategory,
+  ListRule,
+  TagCommand,
+  FilterCommand,
+  SampleBehaviour,
+  ZoneType,
+  TemperatureRange,
+  AllowedCellsFilter,
+  TraitRule,
+  SubworldMixingRule,
+  ModifyLayoutTagsRule,
+  TemplateSpawnRules,
+  World,
+  WeightedSubworldName,
+  Sampler,
+  Subworld,
+  Feature,
+  InternalMob,
+  CountRange,
+  WeightedBiome,
+  BaseLocation,
+  StartingWorldElement,
+  DefaultSettings,
+  MinMaxConfig,
+  MobLocation,
+  MobConfig,
+  RoomConfig,
+  TemplateVec2I,
+  TemplateInfo,
+  TemplateCell,
+  TemplateStorageItem,
+  TemplatePrefab,
+  TemplateContainer,
+  ClusterLayout,
+  NoiseTree,
+  BiomeSettings,
+  WorldTrait,
+  FeatureSettings,
+  DlcMixingSettings,
+  WorldMixingSettings,
+  SubworldMixingSettings,
+};
+
+// -----------------------------------------------------------------------
+// Map data types (returned by worldgen.generate)
+// -----------------------------------------------------------------------
+
+/**
+ * Full map payload returned by `worldgen.generate(coordinate)`. One
+ * top-level envelope for cluster metadata plus a per-world array with
+ * element grid, biome polygons, and entity spawns.
+ */
+export interface MapData {
+  coordinate: string;
+  seed: number;
+  cluster_id: string;
+  /**
+   * Short cluster tag from the coord grammar, e.g. `SNDST-C`, `V-BAD-C`,
+   * `M-FRZ-C`, `VOLCA`. Matches the `coordinatePrefix` in the cluster
+   * YAML. Stable across seeds; use it to group results by cluster type
+   * without parsing the full coord string (prefixes can contain hyphens,
+   * so naive splitting is unreliable).
+   */
+  coordinate_prefix: string;
+  /** Element ids, indexed by the `element_idx` values in each world's cell grid. */
+  element_table: string[];
+  /** Spaced Out hex-grid world locations. One entry per asteroid. */
+  starmap: StarmapEntry[];
+  /** Spaced Out non-asteroid hex POIs (harvestable clouds, artifact sites, etc). */
+  starmap_pois: StarmapPoi[];
+  /** Basegame (non-SpacedOut) rocket destinations. Empty on SpacedOut clusters. */
+  vanilla_starmap: VanillaStarmapEntry[];
+  worlds: WorldMapData[];
+  /**
+   * Populated when the worldgen pipeline detected a fatal failure
+   * (e.g. "Could not guarantee minCount of Subworld X", story trait
+   * couldn't place on any world, layout collapse). Mirrors the game's
+   * `ReportWorldGenError` + abort path. `null` on successful generation.
+   */
+  failure: WorldgenFailure | null;
+  /**
+   * Recoverable per-world or cluster-level warnings that didn't abort
+   * worldgen. Per-world entries have the world index prepended to the
+   * message. Empty array on clean runs.
+   */
+  telemetry: WorldgenEvent[];
+}
+
+export interface WorldgenFailure {
+  /** Where in the pipeline the failure was detected (e.g. "AssignClusterLocations", "render_to_map"). */
+  stage: string;
+  /** World index where the failure happened. `-1` for cluster-level failures. */
+  world_index: number;
+  /** Human-readable description. */
+  message: string;
+}
+
+export interface WorldgenEvent {
+  /** Stable short tag for grouping (e.g. "layout", "noise", "mob_spawning", "template_rules"). */
+  category: string;
+  /** Free-form description. Per-world entries are prefixed with `world[N]:`. */
+  message: string;
+}
+
+export interface WorldMapData {
+  /**
+   * World config path — **post-substitution** when the placement was
+   * swapped via `WorldgenMixing.DoWorldMixing`. On seeds where a
+   * Ceres / Prehistoric / Aquatic Asteroid Mixing fragment took this
+   * slot, `name` is the fragment path (e.g.
+   * `"dlc5::worlds/MixingAquaticAsteroid"`). Use `remixed_from` to
+   * recover the vanilla identity that the cluster picker showed.
+   */
+  name: string;
+  /**
+   * Pre-substitution world path when this slot was swapped by
+   * world-mixing, else `null`. Set from the `MixingApplied.from_world`
+   * recorded during `Cluster.generate_with_settings`. Consumers that
+   * query by the world they see in the cluster picker
+   * (`"TundraMoonlet"`, `"MarshyMoonlet"`, …) should substring-match
+   * this field as a fallback when `name` — which is post-substitution
+   * — doesn't contain the vanilla needle. Mirrors
+   * `ClusterSummary.remixed_from` in the gambling wasm.
+   */
+  remixed_from: string | null;
+  /**
+   * CGM-style mixing source id when this slot was swapped, else
+   * `null`. One of `"CeresAsteroidMixing"`,
+   * `"PrehistoricAsteroidMixing"`, `"AquaticAsteroidMixing"`. Stable
+   * across builds; safe to use for badge-rendering.
+   */
+  remixed_source: string | null;
+  width: number;
+  height: number;
+  is_starting: boolean;
+  world_traits: string[];
+  /**
+   * u16 per cell, row-major (`width * height`). Backed by a
+   * freshly-allocated JS typed array (`wasm-bindgen` copies out of
+   * WASM linear memory), so it's safe to retain across subsequent
+   * `worldgen.generate` calls without being invalidated.
+   */
+  element_idx: Uint16Array;
+  mass: Float32Array;
+  temperature: Float32Array;
+  /** u8 per cell; 255 means no disease. */
+  disease_idx: Uint8Array;
+  /** i32 per cell. */
+  disease_count: Int32Array;
+  /**
+   * U59 backwall element ids, one u16 per cell. Vacuum-filled (the
+   * Vacuum element's index in `MapData.element_table`) for worlds
+   * whose subworld YAML doesn't declare a `backwallNoise` channel —
+   * only DLC5 aquatic biomes (Reef / Abyss / shallows) populate
+   * non-Vacuum backwall.
+   */
+  backwall_element_idx: Uint16Array;
+  /** U59 backwall mass per cell, in kg. Zero on Vacuum cells. */
+  backwall_mass: Float32Array;
+  /** U59 backwall temperature per cell, in K. Zero on Vacuum cells. */
+  backwall_temperature: Float32Array;
+  biome_cells: BiomeCell[];
+  geysers: GeyserSpawn[];
+  buildings: EntitySpawn[];
+  pickupables: EntitySpawn[];
+  other_entities: EntitySpawn[];
+}
+
+export interface BiomeCell {
+  id: number;
+  /** Subworld type path, e.g. `"expansion1::subworlds/jungle/med_Jungle"`. */
+  type: string;
+  /**
+   * The Subworld's `ZoneType` enum value as a string (matches the
+   * `ZoneType` union in `editor_settings.d.ts`). `null` when the
+   * subworld path couldn't be resolved in the current settings.
+   */
+  zone_type: ZoneType | null;
+  x: number;
+  y: number;
+  /** Flat polygon vertex array: `[x0, y0, x1, y1,...]`. */
+  poly: number[];
+  /**
+   * The layout tags this overworld node carries — e.g. `"AtSurface"`,
+   * `"AtDepths"`, `"AtEdge"`, distance tags (`"AtSurface_Distance2"`),
+   * the subworld's `ZoneType` tag, and its subworld tags. These are the
+   * keys `AllowedCellsFilter` matches against, so they let you
+   * visualize/explain why a subworld landed here and interpret the
+   * filter chain client-side. Not a closed vocabulary (subworld/world
+   * YAML can declare arbitrary tags).
+   */
+  tags: string[];
+}
+
+export interface EntitySpawn {
+  /** Game prefab name. */
+  tag: string;
+  /** Grid cell index. */
+  cell: number;
+  /** `cell % width`. */
+  x: number;
+  /** `cell / width`. */
+  y: number;
+  /**
+   * Connections bitmask preserved from the source
+   * `TemplatePrefab.connections`. Present only for template-placed
+   * conduit-aware buildings (LogicGate, LogicWire, etc.). Absent for
+   * ambient / terrain mob spawns and for prefabs that had no
+   * connections field in the YAML.
+   */
+  connections?: number;
+  /**
+   * Rotation / orientation preserved from
+   * `TemplatePrefab.rotationOrientation`. e.g. `"R90"`, `"R180"`,
+   * `"R270"`, `"FlipH"`. Present only for rotated template buildings
+   * (e.g. the R270 LiquidValve in `poi_old_pool`). Absent otherwise.
+   */
+  rotationOrientation?: string;
+}
+
+/**
+ * Geyser spawn. `type` is the resolved template id (what the game
+ * rolls `GeyserGeneric_*` into); `scaled_*` fields come from the
+ * per-geyser stats roll and are absent for non-random geysers.
+ */
+export interface GeyserSpawn extends EntitySpawn {
+  type: string;
+  scaled_rate?: number;
+  scaled_iter_len?: number;
+  scaled_iter_pct?: number;
+  scaled_year_len?: number;
+  scaled_year_pct?: number;
+}
+
+export interface StarmapEntry {
+  world_index: number;
+  q: number;
+  r: number;
+}
+
+export interface StarmapPoi {
+  /** e.g. `"HarvestableSpacePOI_*"`, `"ArtifactSpacePOI"`. */
+  poi_type: string;
+  q: number;
+  r: number;
+  // Present only on harvestable POIs:
+  capacity_roll?: number;
+  recharge_roll?: number;
+  total_capacity?: number;
+  recharge_time?: number;
+}
+
+export interface VanillaStarmapEntry {
+  type: string;
+  distance: number;
+}
+
+// -----------------------------------------------------------------------
+// Settle snapshot (returned by worldgen.advance)
+// -----------------------------------------------------------------------
+
+/**
+ * A per-tick snapshot of settle state, one decoded v4 binary frame.
+ * Arrays are parallel (indexed by row-major cell position).
+ */
+export interface SettleSnapshot {
+  /** Tick this snapshot was taken at. Monotonic, 1..=499. */
+  tick: number;
+  worlds: SettleWorld[];
+}
+
+export interface SettleWorld {
+  width: number;
+  height: number;
+  element_idx: Uint16Array;
+  mass: Float32Array;
+  temperature: Float32Array;
+  /** 255 = no disease on that cell. */
+  disease_idx: Uint8Array;
+  disease_count: Int32Array;
+  /**
+   * U59 backwall element ids, live at the snapshot's `tick`. Vacuum
+   * (`element_table.indexOf("Vacuum")` from `MapData`) on worlds
+   * without `backwallNoise` in their subworld YAML — populated only
+   * for DLC5 aquatic biomes.
+   */
+  backwall_element_idx: Uint16Array;
+  /** U59 backwall mass per cell, in kg. Zero on Vacuum cells. */
+  backwall_mass: Float32Array;
+  /** U59 backwall temperature per cell, in K. Zero on Vacuum cells. */
+  backwall_temperature: Float32Array;
+}
+
+// -----------------------------------------------------------------------
+// Entity spawners (returned by worldgen.entities)
+// -----------------------------------------------------------------------
+
+/**
+ * Refreshed entity spawns against the cached cluster's current sim
+ * state. Shape mirrors the per-world entity arrays in `MapData`.
+ */
+export interface EntitySpawners {
+  worlds: EntitySpawnerWorld[];
+}
+
+export interface EntitySpawnerWorld {
+  geysers: GeyserSpawn[];
+  buildings: EntitySpawn[];
+  pickupables: EntitySpawn[];
+  other_entities: EntitySpawn[];
+}
+
+// -----------------------------------------------------------------------
+// init + worldgen singleton
+// -----------------------------------------------------------------------
+
+export interface InitOptions {
+  /**
+   * Custom URL / Request / pre-compiled module for the .wasm binary.
+   * Omit to use the bundler-rewritten default.
+   */
+  module_or_path?:
+    | string
+    | URL
+    | Request
+    | Response
+    | BufferSource
+    | WebAssembly.Module
+    | Promise<
+        string | URL | Request | Response | BufferSource | WebAssembly.Module
+      >;
+
+  /**
+   * - `'auto'` (default): pick parallel when `crossOriginIsolated` and
+   *   `SharedArrayBuffer` are available, with
+   *   `navigator.hardwareConcurrency` workers. Otherwise serial.
+   * - `'serial'`: force the serial build.
+   * - `number`: force parallel with this many workers (falls back to
+   *   serial when parallel isn't available).
+   */
+  threads?: number | 'auto' | 'serial';
+}
+
+/**
+ * Initialise the WASM module. The web package ships both a serial and
+ * 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.
+ */
+export default function init(options?: InitOptions): Promise<void>;
+
+/** `true` for parallel, `false` for serial, `null` before init resolves. */
+export function isParallel(): boolean | null;
+
+/**
+ * Singleton that wraps the one-slot cluster cache in WASM. All methods
+ * (except `generate`, `reset`, and `version`) operate on whatever
+ * cluster is currently cached; call `generate(coord)` first to populate.
+ */
+export const worldgen: {
+  /**
+   * Generate a cluster from a game coordinate. Caches the cluster in
+   * the WASM thread-local slot, replacing any previously cached cluster.
+   */
+  generate(coordinate: string): MapData;
+
+  /**
+   * Advance the cached cluster's settle sim to `targetTick` (in
+   * `1..=499`) and return a decoded snapshot at that tick. Call
+   * repeatedly with increasing ticks for progressive rendering. The
+   * settle runs 499 ticks total; the final call with `targetTick = 499`
+   * finalises the cluster.
+   *
+   * Throws if the cache is empty or `targetTick` is out of range.
+   */
+  advance(targetTick: number): SettleSnapshot;
+
+  /**
+   * Re-run ambient mob spawning against the cached cluster's current
+   * 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.
+   */
+  entities(): EntitySpawners;
+
+  /**
+   * Drop the cached generated cluster. Editor settings (if mutated)
+   * are preserved.
+   */
+  clear(): void;
+
+  /**
+   * Snapshot-based settings I/O. Each entry of the `files` map keys a
+   * Klei config path (e.g.
+   * `expansion1::worldgen/clusters/CGMCluster.yaml`) to that file's
+   * JSON-encoded content — the same shape Klei's YAML loader produces
+   * after parsing. `load*` / `merge` / `remove` calls evict the
+   * cluster cache; the next `generate()` rebuilds with the new
+   * settings.
+   *
+   * ### Stability contracts
+   *
+   * - **Canonical stringification.** `files()[path]` for an unchanged
+   *   file is byte-equivalent across calls and across processes.
+   *   JSON object-key order is alphabetical for `HashMap`-backed
+   *   storage (the four `ComposableDict<K,V>` tables — mobs, rooms,
+   *   borders, temperatures); `IndexMap`-backed fields preserve
+   *   insertion order (the load order from the source bytes); struct
+   *   fields use declared order. No floating-point reformatting.
+   * - **Idempotent `load(files())`.** Calling `load(files())` is a
+   *   no-op against engine state; the very next `files()` returns
+   *   byte-equivalent strings to the input. Verified across all 913
+   *   vanilla paths.
+   * - **Deep-copy returns.** `files()` returns a fresh, freely
+   *   mutable plain object (the engine `JSON.parse`s its internal
+   *   string representation per call). Mutating the returned map
+   *   does not affect the engine's snapshot. The `Readonly<...>`
+   *   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.
+   * - **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
+   *   semantics apply: later entries in the input map win over
+   *   earlier ones for the same path.
+   */
+  snapshot: {
+    /** Reset SETTINGS to the embedded vanilla baseline. Strict mode
+     *  (closed parity surface — rejects mod-defined enum extensions
+     *  like custom TemperatureRange values). */
+    loadVanilla(): void;
+    /** Extensions-mode `loadVanilla`. Identical bytes for the vanilla
+     *  case; the difference surfaces on subsequent `merge(modFiles)`
+     *  calls, where Extensions mode accepts `TemperatureRange::Custom(X)`
+     *  and similar mod-defined enum extensions provided the mod also
+     *  registers them in `tables.temperatures.add`. Use this when
+     *  bootstrapping the slot for a mod-overlay flow (e.g. Baator's
+     *  HellHot temperature, custom Tag definitions). */
+    loadVanillaExtensions(): void;
+    /** Replace SETTINGS with the `path → JSON-string` `files` map.
+     *  Strict mode. The next `files()` call returns byte-equivalent
+     *  strings to the input (idempotent round-trip; see contract
+     *  above). */
+    load(files: Readonly<Record<string, string>>): void;
+    /** Extensions-mode counterpart of `load`. Accepts mod-defined
+     *  enum extensions when the mod registers them in the
+     *  corresponding `add` table. Subsequent `merge`s on the slot
+     *  inherit the Extensions mode — no need to call `_extensions`
+     *  variants for merges. */
+    loadExtensions(files: Readonly<Record<string, string>>): void;
+    /**
+     * Merge `files` into the active SETTINGS (last-wins on duplicate
+     * paths — both vs. existing SETTINGS and within the same input
+     * map). Auto-loads vanilla as the base if SETTINGS hasn't been
+     * initialised. Typical mod-overlay entry point.
+     */
+    merge(files: Readonly<Record<string, string>>): void;
+    /**
+     * Return the active SETTINGS as a `path → JSON-string` files map.
+     * Auto-loads vanilla if SETTINGS hasn't been initialised.
+     *
+     * Returns a fresh deep copy each call — the engine does not share
+     * state with the returned object. Mutate it freely; it won't
+     * affect the engine. Subsequent `files()` calls re-emit from the
+     * engine state, not the previously-returned object.
+     */
+    files(): Readonly<Record<string, string>>;
+    /**
+     * Stable hex hash of the active snapshot's canonical projection
+     * (the same projection `files()` returns). Auto-loads vanilla if
+     * SETTINGS hasn't been initialised.
+     *
+     * Contract: two snapshots with the same logical content produce
+     * the same hash regardless of HashMap/IndexMap iteration order or
+     * load history. `client.load(server.files())` followed by
+     * `client.checksum()` reproduces `server.checksum()` — that's the
+     * worker fast-path: client posts its checksum, worker fast-paths
+     * if equal instead of demanding a full `load(fullMap)`.
+     *
+     * Use to decide between `merge(delta)` (fast-path) and
+     * `load(fullMap)` (re-sync) when reconciling client + worker
+     * 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
+     * snapshot; steady-state cache hit is a single property read.
+     */
+    checksum(): string;
+    /**
+     * Drop `paths` from the active SETTINGS. Auto-loads vanilla as
+     * the base if SETTINGS hasn't been initialised. Paths not present
+     * in the snapshot are silently ignored.
+     *
+     * Closes the additive-only gap in `merge` — lets the worker
+     * apply a "user deleted a custom world" delta without forcing a
+     * full re-sync. Surgical: O(paths × categories) in-place drops
+     * on the engine-side snapshot, no `to_files` / `from_files`
+     * round-trip.
+     */
+    remove(paths: readonly string[]): void;
+    /**
+     * The ONI game build this WASM was baselined against (e.g.
+     * `"737195"`). Same value as `worldgen.version()`; exposed under
+     * `snapshot` for persistence flows.
+     *
+     * Recommended use: editors persist
+     * `{snapshot: files(), schemaVersion: snapshot.schemaVersion()}`
+     * to IndexedDB / share URLs / disk. On load, compare the
+     * persisted `schemaVersion` against the current
+     * `snapshot.schemaVersion()` and warn / migrate / refuse before
+     * calling `load(snapshot)`. Without the stamp, a checkpoint from
+     * an older engine silently coerces missing or renamed fields.
+     */
+    schemaVersion(): string;
+  };
+
+  /**
+   * Drop both the editor settings and the cluster cache. Next
+   * `generate()` reloads the embedded stock settings from scratch.
+   */
+  reset(): void;
+
+  /**
+   * Evaluate a noise tree over a `width × height` 2D grid and return one
+   * scalar per cell, row-major (`y * width + x`). Values are
+   * **unnormalised** — the consumer applies any colour ramp / contrast
+   * on the JS side, avoiding a hidden contract about how a particular
+   * range maps to biomes.
+   *
+   * Pass `{ kind: "named", name }` to evaluate one of the trees in the
+   * live SETTINGS' noise map (sourced from `worldgen/noise/*.yaml`
+   * — preview reflects pending edits made via `snapshot.merge` /
+   * `snapshot.load` without re-running cluster generation). Pass
+   * `{ kind: "inline", yaml }` to evaluate a YAML document parsed in
+   * isolation, useful for previewing edits that haven't been merged
+   * 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.
+   *
+   * Throws if the named tree doesn't exist, the inline YAML fails to
+   * parse, or the tree has no terminator link.
+   */
+  evaluateNoise(
+    tree: NoiseTreeRef,
+    width: number,
+    height: number,
+    seed: number,
+  ): Float32Array;
+
+  /**
+   * Enumerate every noise-node variant the engine recognises plus its
+   * param schema. Drives the editor's "Add node" palette + per-node
+   * form generation in worldgen-editor; without this, the editor would
+   * hard-code the node list and drift from the engine whenever a new
+   * generator is added.
+   *
+   * The list is static across the lifetime of the build — call once
+   * and cache the result.
+   */
+  noiseNodeKinds(): NoiseNodeKindSpec[];
+
+  /**
+   * The ONI game build this WASM was parity-baselined against (e.g.
+   * `"737195"`).
+   */
+  version(): string;
+};
+
+/** Discriminated union accepted by `worldgen.evaluateNoise`. */
+export type NoiseTreeRef =
+  /** Look up `name` in the active SETTINGS' noise map (sourced from
+   *  `worldgen/noise/*.yaml`). */
+  | { kind: "named"; name: string }
+  /** Parse the YAML document in isolation. */
+  | { kind: "inline"; yaml: string };
+
+/** One entry returned by `worldgen.noiseNodeKinds()`. */
+export interface NoiseNodeKindSpec {
+  /** Which `NoiseTree.<category>s` map this node variant lives in. */
+  category: "primitive" | "filter" | "modifier" | "transformer" | "selector" | "combiner";
+  /** Discriminator value (e.g. `"ImprovedPerlin"`, `"SumFractal"`, `"Add"`). */
+  kind: string;
+  /** Number of input links this node consumes. `0` for primitives. */
+  sources: number;
+  /** Param-form schema. Field names match the YAML field on the corresponding struct. */
+  params: NoiseNodeParam[];
+}
+
+/** One field in a `NoiseNodeKindSpec.params` array. */
+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";
+  /** 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. */
+  enumValues?: string[];
+}
+