@aethervtt/shard-procgen 0.0.1

package/dist/importer.js

@@ -0,0 +1,122 @@
+import {
+  defineAssetSchema,
+  defineImportDependency,
+  defineImporter
+} from "@aethervtt/shard-assets";
+import { defineSchema, isPlainObject, ShardError } from "@aethervtt/shard-core";
+import { codeHashOf, findGenerator, requestOf, requireGenerator } from "./generator.js";
+import { paramHandles, runJob } from "./runtime.js";
+import { genFileSchema } from "./schema.js";
+const NoSettings = defineSchema(
+  "procgen/NoSettings",
+  {},
+  { description: "None: the generator, seed, and params are the file." }
+);
+function generatorHash(gen) {
+  return `${gen.version}:${codeHashOf(gen)}`;
+}
+const generatorDependency = defineImportDependency("generator:", (id) => {
+  const gen = findGenerator(id.slice("generator:".length));
+  return gen ? generatorHash(gen) : void 0;
+});
+const generatorSchema = defineAssetSchema("gen.schema.json", genFileSchema);
+function parseGenFile(text, path) {
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch (cause) {
+    throw new ShardError("procgen/bad-file", `${path} isn't valid JSON`, { path: "", cause });
+  }
+  if (!isPlainObject(json)) {
+    throw new ShardError("procgen/bad-file", `${path} must be a JSON object`, { path: "" });
+  }
+  for (const key of Object.keys(json)) {
+    if (!["$schema", "generator", "seed", "params"].includes(key)) {
+      throw new ShardError("procgen/bad-file", `Unknown field "${key}"`, {
+        path: `/${key}`,
+        hint: 'A generator file has "generator", "seed", and "params".'
+      });
+    }
+  }
+  if (typeof json.generator !== "string" || json.generator === "") {
+    throw new ShardError("procgen/bad-file", '"generator" must name a generator', {
+      path: "/generator",
+      hint: 'e.g. "star-explorer/Rock" (.agents/generators.md lists them).'
+    });
+  }
+  const seed = json.seed ?? 0;
+  if (typeof seed !== "number" || !Number.isInteger(seed) || seed < 0 || seed > 4294967295) {
+    throw new ShardError("procgen/bad-params", '"seed" must be an integer from 0 to 4294967295', {
+      path: "/seed"
+    });
+  }
+  const params = json.params ?? {};
+  if (!isPlainObject(params)) {
+    throw new ShardError("procgen/bad-params", '"params" must be an object', { path: "/params" });
+  }
+  return { generator: json.generator, seed, params };
+}
+const GeneratorImporter = defineImporter({
+  name: "procgen",
+  version: 1,
+  extensions: [".gen.json"],
+  settings: NoSettings,
+  async import(source, ctx) {
+    const file = parseGenFile(source.text(), source.path);
+    let gen;
+    try {
+      gen = requireGenerator(file.generator);
+    } catch (err) {
+      throw new ShardError("procgen/unknown-generator", err.message, {
+        path: "/generator",
+        hint: err.hint
+      });
+    }
+    let request;
+    try {
+      request = requestOf(gen, file.params, file.seed);
+    } catch (err) {
+      const e = err;
+      throw new ShardError(e.code, e.message, {
+        path: e.path === "/seed" ? "/seed" : `/params${e.path ?? ""}`,
+        hint: e.hint,
+        details: e.details
+      });
+    }
+    ctx.depend(`generator:${gen.name}`, generatorHash(gen));
+    const deps = [];
+    for (const ref of paramHandles(gen, request.params)) {
+      if (!ref.path) continue;
+      const asset = await ctx.asset(`/${ref.path}`);
+      deps.push({ guid: asset.guid, path: ref.path, type: asset.type, artifact: asset.artifact });
+    }
+    const result = await runJob({ ...request, deps, chain: [] });
+    for (const w of result.warnings) ctx.warn(w.message, w.path);
+    const assets = result.assets.map((a) => {
+      const out = { label: a.label, type: a.type };
+      if (a.bytes) out.bytes = a.bytes;
+      if (a.json !== void 0) out.json = a.json;
+      const info = { ...a.info ?? {} };
+      if (a.label === "") {
+        info.generator = gen.name;
+        info.seed = request.seed;
+        info.ms = Math.round(result.ms * 10) / 10;
+        if (result.children.length > 0) info.generated = result.children.length;
+      }
+      out.info = info;
+      return out;
+    });
+    assets.push({
+      label: "Generator",
+      type: "Generator",
+      json: { generator: gen.name, seed: request.seed, params: request.params }
+    });
+    return { assets };
+  }
+});
+export {
+  GeneratorImporter,
+  generatorDependency,
+  generatorSchema,
+  parseGenFile
+};

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { findNondeterminism, type NondeterministicCall } from './check.js';
+export { type ContextState, createContext, type GenContext, guardNondeterminism, type LoadedDependency, type NoiseApi, } from './context.js';
+export { allGenerators, canonicalParams, codeHashOf, defineGenerator, type Fragment, type FragmentEntity, findGenerator, type Generator, type GeneratorOptions, type GenParams, type GenRequest, guidOf, hashString, identityOf, type MeshResult, type OutputAsset, type OutputSpec, parseProceduralRef, proceduralPath, type RunResult, requestOf, requireGenerator, setGeneratorCodeHashes, type TextureData, } from './generator.js';
+export { GeneratorImporter, type GenFile, parseGenFile } from './importer.js';
+export { Generated, GeneratorInstance, instanceRequest } from './instance.js';
+export { executeJob, type GenJob, type GenResult, type JobDependency, jobError, } from './job.js';
+export { type MeshBuilderApi, meshBuilder } from './mesh-builder.js';
+export { previewOutput, procgenMethods, type RunSummary, resolveGenerator, runGenerator, } from './methods.js';
+export { encodeOutput, type GenOutputAsset, toJson } from './outputs.js';
+export { type ProcgenPluginOptions, procgenPlugin } from './plugin.js';
+export { decodeRecord, encodeRecord, type OutputRecord } from './record.js';
+export { type CacheResult, configureProcgenHost, DataAssetType, GeneratedData, GeneratorAssetType, type GeneratorBinding, GeneratorBindings, generate, mainThreadTurn, type ProcgenHost, type ProcgenOptions, ProcgenResource, ProcgenRuntime, type ProcgenStats, paramHandles, procgen, procgenHost, procgenMainThreadMs, runJob, warmGeneratorWorkers, } from './runtime.js';
+export { genFileSchema } from './schema.js';
+export { contactSheet, drawLabel, parseSeeds } from './sheet.js';

package/dist/index.js

@@ -0,0 +1,109 @@
+import { findNondeterminism } from "./check.js";
+import {
+  createContext,
+  guardNondeterminism
+} from "./context.js";
+import {
+  allGenerators,
+  canonicalParams,
+  codeHashOf,
+  defineGenerator,
+  findGenerator,
+  guidOf,
+  hashString,
+  identityOf,
+  parseProceduralRef,
+  proceduralPath,
+  requestOf,
+  requireGenerator,
+  setGeneratorCodeHashes
+} from "./generator.js";
+import { GeneratorImporter, parseGenFile } from "./importer.js";
+import { Generated, GeneratorInstance, instanceRequest } from "./instance.js";
+import {
+  executeJob,
+  jobError
+} from "./job.js";
+import { meshBuilder } from "./mesh-builder.js";
+import {
+  previewOutput,
+  procgenMethods,
+  resolveGenerator,
+  runGenerator
+} from "./methods.js";
+import { encodeOutput, toJson } from "./outputs.js";
+import { procgenPlugin } from "./plugin.js";
+import { decodeRecord, encodeRecord } from "./record.js";
+import {
+  configureProcgenHost,
+  DataAssetType,
+  GeneratedData,
+  GeneratorAssetType,
+  GeneratorBindings,
+  generate,
+  mainThreadTurn,
+  ProcgenResource,
+  ProcgenRuntime,
+  paramHandles,
+  procgen,
+  procgenHost,
+  procgenMainThreadMs,
+  runJob,
+  warmGeneratorWorkers
+} from "./runtime.js";
+import { genFileSchema } from "./schema.js";
+import { contactSheet, drawLabel, parseSeeds } from "./sheet.js";
+export {
+  DataAssetType,
+  Generated,
+  GeneratedData,
+  GeneratorAssetType,
+  GeneratorBindings,
+  GeneratorImporter,
+  GeneratorInstance,
+  ProcgenResource,
+  ProcgenRuntime,
+  allGenerators,
+  canonicalParams,
+  codeHashOf,
+  configureProcgenHost,
+  contactSheet,
+  createContext,
+  decodeRecord,
+  defineGenerator,
+  drawLabel,
+  encodeOutput,
+  encodeRecord,
+  executeJob,
+  findGenerator,
+  findNondeterminism,
+  genFileSchema,
+  generate,
+  guardNondeterminism,
+  guidOf,
+  hashString,
+  identityOf,
+  instanceRequest,
+  jobError,
+  mainThreadTurn,
+  meshBuilder,
+  paramHandles,
+  parseGenFile,
+  parseProceduralRef,
+  parseSeeds,
+  previewOutput,
+  proceduralPath,
+  procgen,
+  procgenHost,
+  procgenMainThreadMs,
+  procgenMethods,
+  procgenPlugin,
+  requestOf,
+  requireGenerator,
+  resolveGenerator,
+  runGenerator,
+  runJob,
+  setGeneratorCodeHashes,
+  toJson,
+  warmGeneratorWorkers
+};

package/dist/instance.d.ts

@@ -0,0 +1,28 @@
+import { type AssetEntry } from '@aethervtt/shard-assets';
+import { type AssetRef, type JsonValue, type World } from '@aethervtt/shard-core';
+import { type Generator, type GenRequest } from './generator.js';
+/**
+ * Spawns an `entities` generator's fragment as this entity's children (and merges the fragment
+ * root's components into it), like a PrefabInstance. Changing `seed` or `params` regenerates; the
+ * children whose path is unchanged keep their entity.
+ */
+export declare const GeneratorInstance: import("@aethervtt/shard-core").ComponentDef<{
+    readonly generator: import("@aethervtt/shard-core").FieldType<AssetRef<"Generator"> | null, "object">;
+    readonly seed: import("@aethervtt/shard-core").FieldType<number, "u32">;
+    readonly params: import("@aethervtt/shard-core").FieldType<JsonValue, "object">;
+    readonly overrides: import("@aethervtt/shard-core").FieldType<JsonValue, "object">;
+}>;
+/** On every entity a GeneratorInstance spawned. Such entities are never written to scene files. */
+export declare const Generated: import("@aethervtt/shard-core").TagDef;
+/** The request an instance's value makes, or undefined while its generator file loads. */
+export declare function instanceRequest(world: World, value: {
+    generator?: unknown;
+    seed?: unknown;
+    params?: unknown;
+}): {
+    request: GenRequest;
+    gen: Generator;
+} | {
+    pending: AssetEntry;
+} | undefined;
+export declare const generatorInstanceKind: import("@aethervtt/shard-scene").InstanceKind;

package/dist/instance.js

@@ -0,0 +1,147 @@
+import { assetServer } from "@aethervtt/shard-assets";
+import {
+  defineComponent,
+  defineTag,
+  isPlainObject,
+  pointer,
+  ShardError,
+  t
+} from "@aethervtt/shard-core";
+import { LogResource } from "@aethervtt/shard-runtime";
+import { defineInstanceKind } from "@aethervtt/shard-scene";
+import { findGenerator, requestOf } from "./generator.js";
+import { GeneratorBindings, procgen } from "./runtime.js";
+const GeneratorInstance = defineComponent(
+  "procgen/GeneratorInstance",
+  {
+    generator: t.handle("Generator", {
+      description: `The generator, by name ({ "path": "star-explorer/StarSystem" }), or a generator file's #Generator ({ "path": "generators/sol.gen.json#Generator" }), whose seed and params are defaults.`
+    }),
+    seed: t.u32({
+      description: "The seed. 0 uses the generator file's seed (0 for a generator by name)."
+    }),
+    params: t.json({
+      default: {},
+      description: "Params, checked against the generator's schema; missing ones take the file's or the defaults."
+    }),
+    overrides: t.json({
+      default: {},
+      description: "Changes to generated entities by path relative to this entity, as in scene/PrefabInstance. Saves write the children's runtime changes here."
+    })
+  },
+  {
+    description: "Spawns an entities generator's output as children (procgen/Generated). Patching seed or params regenerates on the pool; children at unchanged paths keep their entity ids. Saves write only this component."
+  }
+);
+const Generated = defineTag("procgen/Generated", {
+  description: "Spawned by a GeneratorInstance; rebuilt from the generator, never saved.",
+  serialize: false
+});
+function instanceRequest(world, value) {
+  const ref = value.generator;
+  if (!ref) return void 0;
+  const server = assetServer(world);
+  const entry = server.entry(ref);
+  if (!entry) {
+    throw new ShardError(
+      "procgen/unknown-generator",
+      `No generator ${JSON.stringify(ref.path ?? ref.guid)}`,
+      { hint: 'Name a generator ("star-explorer/StarSystem") or a *.gen.json#Generator.' }
+    );
+  }
+  if (entry.state !== "loaded") {
+    if (entry.state === "unloaded") server.request(entry.guid);
+    return { pending: entry };
+  }
+  const binding = world.resource(GeneratorBindings).get(entry);
+  const gen = binding && findGenerator(binding.generator);
+  if (!gen) {
+    throw new ShardError("procgen/unknown-generator", `No generator "${binding?.generator}"`, {
+      hint: "Define it with project.generator in scripts/."
+    });
+  }
+  if (gen.output !== "entities") {
+    throw new ShardError(
+      "procgen/output-mismatch",
+      `GeneratorInstance needs an entities generator; ${gen.name} makes a ${gen.outputType}`,
+      {
+        hint: 'Use its output as a handle instead (a mesh: render/Mesh3d { "mesh": { "path": "procedural:\u2026" } }).'
+      }
+    );
+  }
+  const params = {
+    ...binding.params ?? {},
+    ...isPlainObject(value.params) ? value.params : {}
+  };
+  const seed = value.seed || binding.seed || 0;
+  return { request: requestOf(gen, params, seed), gen };
+}
+const reported = /* @__PURE__ */ new WeakMap();
+const generatorInstanceKind = defineInstanceKind({
+  def: GeneratorInstance,
+  mark: Generated,
+  keepIds: true,
+  nested: true,
+  source(world, value, entity) {
+    let seen = reported.get(world);
+    if (!seen) {
+      seen = /* @__PURE__ */ new Map();
+      reported.set(world, seen);
+    }
+    try {
+      const made = instanceRequest(world, value);
+      if (!made) return void 0;
+      if ("pending" in made) return made.pending;
+      seen.delete(entity);
+      return procgen(world).entryFor(made.request);
+    } catch (err) {
+      const message = err.message;
+      if (seen.get(entity) !== message) {
+        seen.set(entity, message);
+        world.tryResource(LogResource)?.error(err);
+      }
+      return void 0;
+    }
+  },
+  validate(world, json, base, errors, options) {
+    if (!options.catalog) return;
+    const ref = json.generator;
+    if (!isPlainObject(ref)) return;
+    const entry = assetServer(world).entry(ref);
+    if (!entry) return;
+    const binding = entry.state === "loaded" ? world.resource(GeneratorBindings).get(entry) : void 0;
+    const gen = binding && findGenerator(binding.generator);
+    if (!gen) return;
+    if (gen.output !== "entities") {
+      errors.push(
+        new ShardError(
+          "procgen/output-mismatch",
+          `${gen.name} makes a ${gen.outputType}, not entities`,
+          {
+            path: pointer(base, "generator"),
+            hint: "GeneratorInstance spawns entities generators; put other outputs in a handle field (procedural:\u2026)."
+          }
+        )
+      );
+      return;
+    }
+    const params = {
+      ...binding.params ?? {},
+      ...isPlainObject(json.params) ? json.params : {}
+    };
+    for (const e of gen.params.validate(params)) {
+      errors.push(
+        new ShardError("procgen/bad-params", `${gen.name}: ${e.message}`, {
+          path: `${pointer(base, "params")}${e.path ?? ""}`,
+          hint: e.hint ?? `${gen.name}'s params are in .agents/generators.md.`
+        })
+      );
+    }
+  }
+});
+export {
+  Generated,
+  GeneratorInstance,
+  generatorInstanceKind,
+  instanceRequest
+};

package/dist/job.d.ts

@@ -0,0 +1,51 @@
+import { type Artifact } from '@aethervtt/shard-assets';
+import { type JsonValue } from '@aethervtt/shard-core';
+import { type GenRequest } from './generator.js';
+import { type GenOutputAsset } from './outputs.js';
+/** An asset a job's params point at: its artifact (workers rebuild it) or the loaded object. */
+export interface JobDependency {
+    guid: string | undefined;
+    path: string | undefined;
+    type: string;
+    artifact?: Artifact;
+    object?: unknown;
+}
+/** One generator run, as posted to a worker: all of it is structured-clonable. */
+export interface GenJob extends GenRequest {
+    deps: JobDependency[];
+    /** Identities of the generators that asked for this one (cycle checks). */
+    chain: string[];
+    /** The noise kernel module, so a worker samples without fetching the .wasm. */
+    noise?: WebAssembly.Module;
+    noiseSimd?: boolean;
+    /** Guard the clock and Math.random for the whole run (workers), not just its first turn. */
+    guardAll?: boolean;
+    /** Check entities' components here (default true). Workers leave it to the main thread. */
+    checkComponents?: boolean;
+}
+export interface GenResult {
+    assets: GenOutputAsset[];
+    /** Outputs this one referenced through `ctx.generate`. */
+    children: GenRequest[];
+    warnings: {
+        message: string;
+        path?: string;
+    }[];
+    /** Time in `run` and encoding, in ms. */
+    ms: number;
+}
+/**
+ * Runs a generator job and encodes its output: the same code inline and on a worker. Throws
+ * `procgen/*` errors; anything else the generator throws becomes `procgen/generator-failed`.
+ */
+export declare function executeJob(job: GenJob): Promise<GenResult>;
+/** Plain-object errors cross the worker boundary; this keeps code, hint, and path. */
+export declare function jobError(err: unknown): {
+    code: string;
+    message: string;
+    hint?: string;
+    path?: string;
+};
+export type { GenOutputAsset, JsonValue };
+/** The identity of a job's request (for logs and stats). */
+export declare function jobIdentity(job: GenJob): string;

package/dist/job.js

@@ -0,0 +1,93 @@
+import { findAssetType } from "@aethervtt/shard-assets";
+import { ShardError } from "@aethervtt/shard-core";
+import { useNoiseKernel } from "@aethervtt/shard-noise";
+import {
+  createContext,
+  guardNondeterminism
+} from "./context.js";
+import { identityOf, requireGenerator } from "./generator.js";
+import { encodeOutput } from "./outputs.js";
+function wrap(err, job) {
+  if (err instanceof ShardError && err.code.startsWith("procgen/")) return err;
+  const message = err?.message ?? String(err);
+  return new ShardError(
+    "procgen/generator-failed",
+    `${job.generator} failed (seed ${job.seed}, params ${JSON.stringify(job.params)}): ${message}`,
+    {
+      hint: "The error is in the generator; procgen.run with the same seed and params reproduces it.",
+      cause: err
+    }
+  );
+}
+async function loadDependencies(job) {
+  const out = [];
+  for (const d of job.deps) {
+    if (d.object !== void 0) {
+      out.push({ guid: d.guid, path: d.path, type: d.type, object: d.object });
+      continue;
+    }
+    const type = findAssetType(d.type);
+    if (!type || !d.artifact) {
+      throw new ShardError(
+        "procgen/dependency-failed",
+        `${job.generator} needs ${d.path ?? d.guid}, a ${d.type}, which can't be loaded here`,
+        { hint: "Add the plugin that defines the asset type to the project." }
+      );
+    }
+    const object = await type.load(d.artifact, {
+      guid: d.guid ?? "",
+      path: d.path ?? "",
+      resolve: () => void 0
+    });
+    out.push({ guid: d.guid, path: d.path, type: d.type, object });
+  }
+  return out;
+}
+async function executeJob(job) {
+  const gen = requireGenerator(job.generator);
+  if (job.noise) useNoiseKernel(job.noise, job.noiseSimd ?? true);
+  const deps = await loadDependencies(job);
+  const state = { children: [], warnings: [] };
+  const params = gen.params.deserialize(job.params);
+  const ctx = createContext(gen, job, deps, job.chain, state);
+  const start = performance.now();
+  let restore = guardNondeterminism(gen.name);
+  try {
+    let result = gen.run(ctx, params);
+    if (!job.guardAll) {
+      restore();
+      restore = void 0;
+    }
+    if (result instanceof Promise) result = await result;
+    const assets = encodeOutput(gen, result, { checkComponents: job.checkComponents });
+    restore?.();
+    restore = void 0;
+    return {
+      assets,
+      children: state.children,
+      warnings: state.warnings,
+      ms: performance.now() - start
+    };
+  } catch (err) {
+    throw wrap(err, job);
+  } finally {
+    restore?.();
+  }
+}
+function jobError(err) {
+  const e = err;
+  return {
+    code: e?.code ?? "procgen/generator-failed",
+    message: e?.message ?? String(err),
+    ...e?.hint ? { hint: e.hint } : {},
+    ...e?.path ? { path: e.path } : {}
+  };
+}
+function jobIdentity(job) {
+  return identityOf(job);
+}
+export {
+  executeJob,
+  jobError,
+  jobIdentity
+};

package/dist/mesh-builder.d.ts

@@ -0,0 +1,27 @@
+import { type MeshData } from '@aethervtt/shard-mesh';
+import type { MeshResult } from './generator.js';
+/**
+ * Mesh building inside a generator. Deterministic across hosts: only +, *, and sqrt (no trig),
+ * so the same inputs give the same bytes in Node, Chrome, and WebKit.
+ */
+export interface MeshBuilderApi {
+    /**
+     * A unit icosphere (radius 1) subdivided `detail` times: 12 · 4^detail vertices (well, 10 · 4^d
+     * + 2), shared between faces, with normals.
+     */
+    icosphere(detail: number): MeshData;
+    /** One of the built-in primitives (the `procedural:` meshes) as data you can change. */
+    primitive(name: 'box' | 'cube' | 'sphere' | 'plane' | 'cylinder' | 'cone' | 'capsule' | 'torus', params?: Record<string, number>): MeshData;
+    /** Recomputes smooth normals from the triangles (area-weighted). */
+    computeNormals(mesh: MeshData): MeshData;
+    /**
+     * Finishes a mesh: optional normals and tangents, and levels of detail as fractions of the
+     * triangle count (`lods: [0.5, 0.2]`), made by vertex clustering.
+     */
+    finish(mesh: MeshData, options?: {
+        normals?: boolean;
+        tangents?: boolean;
+        lods?: readonly number[];
+    }): MeshResult;
+}
+export declare const meshBuilder: MeshBuilderApi;