@onimaxxing/worldgen 0.21.2 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -10,6 +10,7 @@ same cluster the game would generate for a given coordinate.
10
10
  - Geyser, building, pickupable, and other entity spawn positions.
11
11
  - Per-cell mass, temperature, and disease (raw after `worldgen.generate`; settled after `worldgen.advance`).
12
12
  - Both basegame and Spaced Out clusters, including story traits, mixing codes, and DLC toggles.
13
+ - Partial generation of selected worlds (`worldgen.partials`).
13
14
 
14
15
  Output is verified cell-by-cell against snapshots captured from the
15
16
  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
133
134
  map (see [`MapData` shape](#mapdata-shape)). Caches the cluster
134
135
  internally, replacing anything previously cached.
135
136
 
137
+ ```ts
138
+ worldgen.partials(coord: string, opts: PartialsOptions): PartialsResult
139
+ ```
140
+
141
+ Generate only the selected worlds of a cluster. Stateless; does not
142
+ touch the cluster cache.
143
+
144
+ `opts.worlds` selects by placement index or world path (full path or
145
+ last segment, matched after mixing). Selectors that match nothing come
146
+ back in `absent` rather than erroring. Cell grids are pre-settle; for
147
+ settled state use `worldgen.generate` + `worldgen.advance`.
148
+
149
+ ```ts
150
+ const r = worldgen.partials('V-SNDST-C-42-0-4A-MUWF1', {
151
+ worlds: ['VanillaSandstoneDefault'],
152
+ });
153
+ for (const g of r.worlds[0]?.geysers ?? []) console.log(g.type, g.x, g.y);
154
+ ```
155
+
156
+ Geyser output matches a full generate exactly. Story-trait templates
157
+ and starmap locations are not generated in partial mode.
158
+
136
159
  ```ts
137
160
  worldgen.entities(): EntitySpawners
138
161
  ```
package/index.d.ts CHANGED
@@ -451,6 +451,99 @@ export interface EntitySpawnerWorld {
451
451
  other_entities: EntitySpawn[];
452
452
  }
453
453
 
454
+ // -----------------------------------------------------------------------
455
+ // Partial worldgen
456
+ // -----------------------------------------------------------------------
457
+
458
+ export interface PartialsOptions {
459
+ /**
460
+ * Placement indices and/or world-path strings. A string matches the
461
+ * POST-mixing world path for this seed, in full
462
+ * (`"expansion1::worlds/SandstoneDefault"`) or by its last segment,
463
+ * case-insensitive, not the localized display name ("Terra").
464
+ * Selectors that match nothing land in the result's `absent` list
465
+ * instead of erroring.
466
+ */
467
+ worlds: Array<number | string>;
468
+ /** `"templates"` (default) or `"notemplates"` (skip template placement). */
469
+ mode?: 'templates' | 'notemplates';
470
+ }
471
+
472
+ /**
473
+ * One generated world from `worldgen.partials`. Grid fields arrive as
474
+ * plain JSON arrays (not the typed arrays `generate` uses) and hold
475
+ * pre-settle state.
476
+ */
477
+ export interface PartialWorld {
478
+ /** Placement index in the cluster layout (stable slot identity). */
479
+ index: number;
480
+ /** Post-mixing world path; see `WorldMapData.name`. */
481
+ name: string;
482
+ remixed_from: string | null;
483
+ remixed_source: string | null;
484
+ width: number;
485
+ height: number;
486
+ is_starting: boolean;
487
+ world_traits: string[];
488
+ geysers: GeyserSpawn[];
489
+ /**
490
+ * Digest-format per-world geyser hashes (FNV-1a-64, uppercase hex,
491
+ * empty when count is 0): the exact values the committed parity
492
+ * digests store. The counts hash a fixed tag allowlist that excludes
493
+ * some DLC5 spawners (e.g. SmallReefGeyser), so `geyser_spawns_count`
494
+ * can be less than `geysers.length`; the `geysers` array is the
495
+ * complete list.
496
+ */
497
+ geyser_spawns_sha: string;
498
+ geyser_spawns_count: number;
499
+ geyser_stats_sha: string;
500
+ geyser_stats_count: number;
501
+ element_idx: number[];
502
+ mass: number[];
503
+ temperature: number[];
504
+ disease_idx: number[];
505
+ disease_count: number[];
506
+ backwall_element_idx: number[];
507
+ backwall_mass: number[];
508
+ backwall_temperature: number[];
509
+ zone_idx: number[];
510
+ zone_table: string[];
511
+ subworld_idx: number[];
512
+ subworld_table: string[];
513
+ biome_cells: BiomeCell[];
514
+ buildings: EntitySpawn[];
515
+ pickupables: EntitySpawn[];
516
+ other_entities: EntitySpawn[];
517
+ }
518
+
519
+ export interface PartialsMixingApplied {
520
+ /** Placement index whose vanilla world was substituted. */
521
+ slot: number;
522
+ from: string;
523
+ to: string;
524
+ source: string;
525
+ }
526
+
527
+ export interface PartialsResult {
528
+ coordinate: string;
529
+ seed: number;
530
+ cluster: string;
531
+ /**
532
+ * Markers: story-trait templates were skipped, so cell grids on
533
+ * worlds that would have received one differ from a full `generate`.
534
+ * Geysers are unaffected.
535
+ */
536
+ partial: true;
537
+ story_traits_skipped: true;
538
+ /** World-mixing substitutions applied for this seed (all slots). */
539
+ mixing_applied: PartialsMixingApplied[];
540
+ /** Generated worlds, one per selected slot present this seed. */
541
+ worlds: PartialWorld[];
542
+ /** Requested selectors that matched no slot this seed. */
543
+ absent: string[];
544
+ failure?: { stage: string; world_index: number; message: string } | null;
545
+ }
546
+
454
547
  // -----------------------------------------------------------------------
455
548
  // init + worldgen singleton
456
549
  // -----------------------------------------------------------------------
@@ -536,6 +629,17 @@ export const worldgen: {
536
629
  */
537
630
  entities(): EntitySpawners | { error: string };
538
631
 
632
+ /**
633
+ * Partial worldgen: generate only the selected worlds of a cluster.
634
+ * Geyser output is bit-identical to a full generate. Partial mode
635
+ * never places story-trait templates or assigns starmap locations.
636
+ * Stateless: does not populate the cluster cache used by
637
+ * `advance()` / `entities()`.
638
+ *
639
+ * Returns `{ error }` (not a throw) on parse/config failures.
640
+ */
641
+ partials(coordinate: string, opts: PartialsOptions): PartialsResult | { error: string };
642
+
539
643
  /**
540
644
  * Drop the cached generated cluster. Editor settings (if mutated)
541
645
  * are preserved.
package/index.js CHANGED
@@ -168,6 +168,14 @@ export const worldgen = {
168
168
  entities() {
169
169
  return JSON.parse(_requireInit('entities').get_entity_spawners());
170
170
  },
171
+ // Partial worldgen: generate only the selected worlds of a cluster.
172
+ // See PartialsOptions/PartialsResult in index.d.ts and the README.
173
+ // Stateless; does not populate the cache used by advance()/entities().
174
+ partials(coord, opts) {
175
+ return JSON.parse(
176
+ _requireInit('partials').partials_from_coordinate(coord, JSON.stringify(opts ?? {}))
177
+ );
178
+ },
171
179
  clear() {
172
180
  _requireInit('clear').clear_cluster_cache();
173
181
  },
package/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "name": "@onimaxxing/worldgen",
3
3
  "type": "module",
4
4
  "description": "WASM entry point for ONI worldgen",
5
- "version": "0.21.2",
5
+ "version": "0.22.0",
6
6
  "license": "MIT",
7
7
  "repository": {
8
8
  "type": "git",