@onimaxxing/worldgen 0.15.0

package/index.js

@@ -0,0 +1,286 @@
+// Façade for the dual-build web package: serial/ and parallel/ each
+// hold a complete wasm-bindgen build. `init()` feature-detects
+// `crossOriginIsolated && SharedArrayBuffer`, picks one, and memoizes
+// it. Every `worldgen.*` call routes through the chosen instance, so
+// the WASM module's thread-local / static state lives in exactly one
+// place per page.
+
+export { parseKleiYaml } from './yaml.js';
+
+let _wasm = null;
+let _initPromise = null;
+let _isParallel = false;
+
+// JS-side checksum cache. The resident snapshot lives WASM-side (in
+// the SNAPSHOT_SLOT thread-local); WASM also caches per-version, so
+// this JS cache exists purely to skip the JS↔WASM boundary cross on
+// the hot path. Mutator methods set `_checksumDirty = true`; the
+// cache is also rebuilt after `worldgen.reset()`.
+//
+// Caveat: this relies on the wrapper being the only path that
+// mutates the slot. Direct calls to `_wasm.snapshot_state_*` from
+// consumer code would bypass the dirty flag and produce a stale
+// checksum. Those raw exports are intended as the wrapper's
+// internals, not a public API.
+let _lastChecksum = null;
+let _checksumDirty = true;
+
+function _requireInit(method) {
+  if (_wasm === null) {
+    throw new Error(
+      `worldgen.${method}: call \`await init()\` first to instantiate the WASM module.`
+    );
+  }
+  return _wasm;
+}
+
+/**
+ * Initialise the WASM module. Memoized.
+ *
+ * @param {Object} [opts]
+ * @param {string | URL | Request} [opts.module_or_path] Custom .wasm URL
+ *   passed through to wasm-bindgen's init.
+ * @param {number | 'auto' | 'serial'} [opts.threads='auto'] `'serial'`
+ *   forces the serial build; a number sets an explicit rayon worker
+ *   count; `'auto'` uses `navigator.hardwareConcurrency`.
+ * @returns {Promise<void>}
+ */
+async function init(opts) {
+  if (_initPromise) return _initPromise;
+  _initPromise = (async () => {
+    const wantParallel =
+      opts?.threads !== 'serial' &&
+      globalThis.crossOriginIsolated === true &&
+      typeof SharedArrayBuffer !== 'undefined';
+
+    const mod = wantParallel
+      ? await import('./parallel/oni_wasm.js')
+      : await import('./serial/oni_wasm.js');
+
+    if (typeof mod.default === 'function') {
+      await mod.default(opts?.module_or_path ? { module_or_path: opts.module_or_path } : undefined);
+    }
+
+    if (wantParallel && typeof mod.initThreadPool === 'function') {
+      const threads = typeof opts?.threads === 'number'
+        ? opts.threads
+        : (globalThis.navigator?.hardwareConcurrency ?? 4);
+      await mod.initThreadPool(threads);
+    }
+
+    _wasm = mod;
+    _isParallel = wantParallel;
+  })();
+  return _initPromise;
+}
+
+export default init;
+
+/** `true` for parallel, `false` for serial, `null` before `init()` resolves. */
+export function isParallel() {
+  return _wasm === null ? null : _isParallel;
+}
+
+// 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(
+      'settle_cluster_advance returned an empty buffer — no cached cluster, or tick out of range. Did you call worldgen.generate(coord) first?'
+    );
+  }
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+  let offset = 0;
+  const version = view.getUint32(offset, true); offset += 4;
+  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;
+
+  const worlds = [];
+  for (let w = 0; w < worldCount; w++) {
+    const width = view.getUint32(offset, true); offset += 4;
+    const height = view.getUint32(offset, true); offset += 4;
+    const cells = width * height;
+
+    const element_idx = new Uint16Array(cells);
+    const mass = new Float32Array(cells);
+    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;
+      mass[c] = view.getFloat32(offset, true); offset += 4;
+      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,
+    });
+  }
+
+  return { tick, worlds };
+}
+
+// Singleton that backs the one-slot CLUSTER_CACHE in WASM. All methods
+// except `generate` operate on whatever's currently cached; call
+// `generate(coord)` first to populate it.
+export const worldgen = {
+  generate(coord) {
+    // Typed-array transport: per-cell grids arrive as Uint16Array /
+    // Float32Array / Uint8Array / Int32Array — no JSON.parse.
+    return _requireInit('generate').generate_map_data(coord);
+  },
+  advance(tick) {
+    return decodeSnapshot(_requireInit('advance').settle_cluster_advance(tick));
+  },
+  entities() {
+    return JSON.parse(_requireInit('entities').get_entity_spawners());
+  },
+  clear() {
+    _requireInit('clear').clear_cluster_cache();
+  },
+
+  // 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. `load*`/`merge`/`remove` calls
+  // evict the cluster cache.
+  //
+  // The resident snapshot lives WASM-side in a thread-local slot —
+  // mutations operate in-place on the slot without round-tripping the
+  // ~10 MB snapshot JSON across the JS↔WASM boundary. Each mutation
+  // returns a new monotonic version number; JS uses it to invalidate
+  // the local checksum cache. `files()` and `checksum()` are
+  // additionally cached on the WASM side per version.
+  snapshot: {
+    /** Reset SETTINGS to the embedded vanilla baseline. Strict mode
+     *  (closed parity surface — rejects mod-defined enum extensions
+     *  like custom TemperatureRange values). */
+    loadVanilla() {
+      _requireInit('snapshot.loadVanilla').snapshot_state_vanilla();
+      _checksumDirty = true;
+    },
+    /** Extensions-mode `loadVanilla`. Identical bytes for the vanilla
+     *  case; the difference surfaces on subsequent `merge(modFiles)`
+     *  calls, where Extensions mode accepts `TemperatureRange::Custom(X)`
+     *  etc. as long as the mod also registers them in
+     *  `tables.temperatures.add`. Use this when bootstrapping for a
+     *  mod overlay (Baator HellHot, custom-tag flows). */
+    loadVanillaExtensions() {
+      _requireInit('snapshot.loadVanillaExtensions').snapshot_state_vanilla_extensions();
+      _checksumDirty = true;
+    },
+    /** Replace SETTINGS with the `path → JSON-string` `files` map.
+     *  Strict mode. Atomic — invalid input leaves SETTINGS untouched
+     *  and throws. */
+    load(files) {
+      _requireInit('snapshot.load').snapshot_state_load(JSON.stringify(files));
+      _checksumDirty = true;
+    },
+    /** Extensions-mode counterpart of `load`. Accepts mod-defined
+     *  enum extensions when the mod registers them. Subsequent
+     *  `merge`s inherit the Extensions mode automatically. */
+    loadExtensions(files) {
+      _requireInit('snapshot.loadExtensions').snapshot_state_load_extensions(JSON.stringify(files));
+      _checksumDirty = true;
+    },
+    /** Merge `files` into the active SETTINGS (last-wins on duplicate
+     *  paths). Auto-loads vanilla as the base if SETTINGS hasn't been
+     *  initialised. Atomic — invalid input leaves SETTINGS untouched
+     *  and throws. */
+    merge(files) {
+      _requireInit('snapshot.merge').snapshot_state_merge(JSON.stringify(files));
+      _checksumDirty = true;
+    },
+    /** Return the active SETTINGS as a `path → JSON-string` files map.
+     *  Auto-loads vanilla if SETTINGS hasn't been initialised. Fresh
+     *  deep copy on each call. */
+    files() {
+      // WASM caches the emitted JSON string per version; we JSON.parse
+      // each call to honor the "fresh deep copy" contract.
+      return JSON.parse(_requireInit('snapshot.files').snapshot_state_files());
+    },
+    /** Engine-side stable hex hash of the active SETTINGS, canonical
+     *  across HashMap/IndexMap iteration noise. Auto-loads vanilla if
+     *  SETTINGS hasn't been initialised. Two-tier cache: WASM-side
+     *  (per snapshot version) + JS-side (no boundary cross). Hot path
+     *  is a boolean check + cached string return. */
+    checksum() {
+      if (!_checksumDirty && _lastChecksum !== null) {
+        return _lastChecksum;
+      }
+      _lastChecksum = _requireInit('snapshot.checksum').snapshot_state_checksum();
+      _checksumDirty = false;
+      return _lastChecksum;
+    },
+    /** Drop `paths` from the active SETTINGS. Auto-loads vanilla as
+     *  the base if SETTINGS hasn't been initialised. Paths not present
+     *  are silently ignored. Closes the additive-only gap in `merge`. */
+    remove(paths) {
+      if (!paths || paths.length === 0) return;
+      _requireInit('snapshot.remove').snapshot_state_drop_paths(JSON.stringify(paths));
+      _checksumDirty = true;
+    },
+    /** Engine schema version stamp — the ONI game build this WASM was
+     *  baselined against (e.g. `"737195"`). Same value as
+     *  `worldgen.version()`. */
+    schemaVersion() {
+      return _requireInit('snapshot.schemaVersion').game_version();
+    },
+  },
+
+  // Drop both the SettingsCache and the cluster cache. Next generate()
+  // reloads the embedded defaults. Also clears the snapshot slot via
+  // settings_reset's cascade.
+  reset() {
+    _requireInit('reset').settings_reset();
+    _lastChecksum = null;
+    _checksumDirty = true;
+  },
+
+  // Noise editor preview. `tree` is either `{kind:'named', name:'noise/Heat'}`
+  // (read from the live SettingsCache the editor mutates) or
+  // `{kind:'inline', yaml:'<yaml document>'}` (parsed in isolation). The
+  // returned Float32Array is row-major `y * width + x`, unnormalised.
+  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 _requireInit('evaluateNoise').evaluate_noise(kind, value, width, height, seed);
+  },
+
+  // Enumerate every noise-node variant the engine recognises plus its
+  // param schema. Drives the editor's "Add node" palette + per-node
+  // form generation. Static across the lifetime of the build.
+  noiseNodeKinds() {
+    return JSON.parse(_requireInit('noiseNodeKinds').noise_node_kinds());
+  },
+
+  version() {
+    return _requireInit('version').game_version();
+  },
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@onimaxxing/worldgen",
+  "type": "module",
+  "description": "WASM entry point for ONI worldgen",
+  "version": "0.15.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tigin-backwards/help-i-want-to-customize-my-oxygen-not-included-worldgen.git"
+  },
+  "files": [
+    "index.js",
+    "yaml.js",
+    "index.d.ts",
+    "yaml.d.ts",
+    "editor_settings.d.ts",
+    "README.md",
+    "serial",
+    "serial/**",
+    "parallel",
+    "parallel/**"
+  ],
+  "main": "index.js",
+  "types": "index.d.ts",
+  "sideEffects": [
+    "./parallel/snippets/**"
+  ],
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/parallel/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tigin-backwards
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/parallel/index.js

@@ -0,0 +1,13 @@
+// Worker-bootstrap shim. wasm-bindgen-rayon's workerHelpers.js does
+// `await import('../../..')` from
+// `parallel/snippets/wasm-bindgen-rayon-<hash>/src/workerHelpers.js`,
+// which resolves to `parallel/`, not the package root. Without an
+// index here, worker spawn fails with a module resolution error.
+//
+// `default` MUST be re-exported alongside `wbg_rayon_start_worker`:
+// workerHelpers calls `pkg.default(init)` to initialise wasm in the
+// worker thread. Omitting `default` here makes that property reach
+// for an undefined export, which under rsbuild/webpack tree-shaking
+// surfaces as `o.default is not a function` at worker start.
+
+export { default, wbg_rayon_start_worker } from './oni_wasm.js';