@aethervtt/shard-project 0.0.1

package/dist/host.d.ts

@@ -0,0 +1,47 @@
+import type { GpuContext } from '@aethervtt/shard-gpu';
+import type { AudioBackend, InputSource, Platform } from '@aethervtt/shard-platform';
+import { type RenderTarget } from '@aethervtt/shard-render';
+import { App, type Plugin } from '@aethervtt/shard-runtime';
+import { type LoadedSceneHandle } from '@aethervtt/shard-scene';
+import type { ManifestValue } from './manifest.js';
+export interface BuildAppOptions {
+    manifest: ManifestValue;
+    /** The project plugin (default export of `entry`), once loaded by the host. */
+    project?: Plugin;
+    gpu?: GpuContext;
+    canvas?: HTMLCanvasElement | OffscreenCanvas;
+    /** Headless stand-in for the window (CLI screenshots). */
+    target?: RenderTarget;
+    inputSource?: InputSource;
+    /** Where sound goes (`platform.audio`). Without one, audio records voices (headless). */
+    audio?: AudioBackend;
+    /**
+     * The host: saves and settings go to its `storage`, and saved scenes reload from its files.
+     * Without one, saves live in memory.
+     */
+    platform?: Platform;
+}
+/** An app with the manifest's engine plugins and the project plugin, not yet initialized. */
+export declare function buildApp(options: BuildAppOptions): App;
+/**
+ * Loads every string table (`locales/*.strings.json`) so keyed text resolves from the first frame.
+ * Call after the asset scan, before loading scenes. Does nothing without text or UI.
+ */
+export declare function loadProjectStrings(app: App): Promise<void>;
+/** Initializes the app and loads the start scene (id = its path). */
+export declare function startProject(app: App, platform: Platform, manifest: ManifestValue): Promise<LoadedSceneHandle>;
+/**
+ * Loads the project's `shaders/` folder into the shader library as `project::…`, and with `watch`
+ * reloads a file when it changes (the running game picks it up once it compiles). Returns a
+ * function that stops watching.
+ */
+export declare function loadProjectShaders(app: App, platform: Platform, options?: {
+    watch?: boolean;
+    dir?: string;
+}): Promise<() => void>;
+/**
+ * Reads the project's baked navmesh tiles (`.shard/cache/nav`) so navmeshes whose geometry hasn't
+ * changed load without running Recast, and lets `nav.bake` save there. Call after `app.init()`,
+ * before loading scenes. Does nothing without a nav plugin.
+ */
+export declare function loadProjectNavCache(app: App, platform: Platform): Promise<void>;

package/dist/host.js

@@ -0,0 +1,118 @@
+import { animationPlugin } from "@aethervtt/shard-animation";
+import { audioPlugin } from "@aethervtt/shard-audio";
+import { gltfPlugin } from "@aethervtt/shard-gltf";
+import { inputPlugin } from "@aethervtt/shard-input";
+import { loadNavCache, Nav, navGridPlugin, navPlugin } from "@aethervtt/shard-nav";
+import { noisePlugin } from "@aethervtt/shard-noise";
+import { particlesPlugin } from "@aethervtt/shard-particles";
+import { physics2dPlugin, physics3dPlugin } from "@aethervtt/shard-physics";
+import { procgenPlugin } from "@aethervtt/shard-procgen";
+import { forwardPlugin, renderPlugin, Shaders } from "@aethervtt/shard-render";
+import { materialNoisePlugin } from "@aethervtt/shard-render/noise";
+import { App, LogResource } from "@aethervtt/shard-runtime";
+import { savePlugin } from "@aethervtt/shard-save";
+import { loadScene, ScenePlugin } from "@aethervtt/shard-scene";
+import { spritePlugin } from "@aethervtt/shard-sprite";
+import { terrainPlugin } from "@aethervtt/shard-terrain";
+import { LocaleState, loadStringTables, textPlugin } from "@aethervtt/shard-text";
+import { TransformPlugin } from "@aethervtt/shard-transform";
+import { uiPlugin } from "@aethervtt/shard-ui";
+function buildApp(options) {
+  const { manifest } = options;
+  const names = new Set(manifest.plugins);
+  if (names.has("sprite") || names.has("text") || names.has("particles") || names.has("animation"))
+    names.add("render/forward");
+  if (names.has("render/forward")) {
+    names.add("render");
+    names.add("core/transform");
+  }
+  if (names.has("physics3d") || names.has("physics2d") || names.has("audio") || names.has("ui") || names.has("nav") || names.has("nav/grid") || names.has("terrain"))
+    names.add("core/transform");
+  const app = new App({ seed: manifest.seed });
+  app.addPlugin(gltfPlugin);
+  if (names.has("core/transform")) app.addPlugin(TransformPlugin);
+  if (names.has("render")) {
+    app.addPlugin(
+      renderPlugin({ gpu: options.gpu, canvas: options.canvas, target: options.target })
+    );
+  }
+  if (names.has("render/forward")) {
+    app.addPlugin(forwardPlugin({ msaa: manifest.window.msaa === 1 ? 1 : 4 }));
+    app.addPlugin(materialNoisePlugin);
+  }
+  if (names.has("sprite")) app.addPlugin(spritePlugin);
+  if (names.has("text")) app.addPlugin(textPlugin);
+  if (names.has("particles")) app.addPlugin(particlesPlugin);
+  if (names.has("animation")) app.addPlugin(animationPlugin);
+  if (names.has("physics3d")) app.addPlugin(physics3dPlugin);
+  if (names.has("physics2d")) app.addPlugin(physics2dPlugin);
+  if (names.has("input")) app.addPlugin(inputPlugin({ source: options.inputSource }));
+  if (names.has("audio")) app.addPlugin(audioPlugin({ backend: options.audio }));
+  if (names.has("ui")) app.addPlugin(uiPlugin);
+  if (names.has("nav")) app.addPlugin(navPlugin);
+  else if (names.has("nav/grid")) app.addPlugin(navGridPlugin);
+  if (names.has("terrain")) app.addPlugin(terrainPlugin({ workers: options.platform?.workers }));
+  app.addPlugin(noisePlugin);
+  app.addPlugin(ScenePlugin);
+  app.addPlugin(
+    procgenPlugin({
+      fs: options.platform?.fs,
+      storage: options.platform?.storage,
+      cacheSize: (manifest.procgen?.cacheSize ?? 256) * 1024 * 1024
+    })
+  );
+  app.addPlugin(
+    savePlugin({
+      storage: options.platform?.storage,
+      fs: options.platform?.fs,
+      engine: manifest.engine
+    })
+  );
+  if (options.project) app.addPlugin(options.project);
+  return app;
+}
+async function loadProjectStrings(app) {
+  if (!app.world.hasResource(LocaleState)) return;
+  try {
+    await loadStringTables(app.world);
+  } catch (err) {
+    app.world.tryResource(LogResource)?.error(err);
+  }
+}
+async function startProject(app, platform, manifest) {
+  await app.init();
+  await loadProjectNavCache(app, platform);
+  const json = JSON.parse(await platform.fs.readText(manifest.startScene));
+  return loadScene(app.world, json, { id: manifest.startScene });
+}
+async function loadProjectShaders(app, platform, options = {}) {
+  const shaders = app.world.tryResource(Shaders);
+  if (!shaders) return () => {
+  };
+  const dir = options.dir ?? "shaders";
+  try {
+    await shaders.loadDir(platform, dir, "project");
+  } catch (err) {
+    app.world.tryResource(LogResource)?.error(err);
+  }
+  if (options.watch && platform.fs.watch && await platform.fs.exists(dir)) {
+    return shaders.watch(platform, dir, "project");
+  }
+  return () => {
+  };
+}
+async function loadProjectNavCache(app, platform) {
+  if (!app.world.hasResource(Nav)) return;
+  try {
+    await loadNavCache(app.world, platform.fs);
+  } catch (err) {
+    app.world.tryResource(LogResource)?.error(err);
+  }
+}
+export {
+  buildApp,
+  loadProjectNavCache,
+  loadProjectShaders,
+  loadProjectStrings,
+  startProject
+};

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { defineProject, type ProjectDef, type ProjectOptions } from './define.js';
+export { type ErrorCode, GENERATED_END, GENERATED_START, generateDocs, mergeAgentsMd, renderAssetCatalog, renderComponentCatalog, renderErrorCatalog, renderGeneratorCatalog, } from './docs.js';
+export { type BuildAppOptions, buildApp, loadProjectNavCache, loadProjectShaders, loadProjectStrings, startProject, } from './host.js';
+export { BUILTIN_PLUGINS, loadProject, Manifest, type ManifestValue, manifestJsonSchema, type ProjectInfo, validateManifest, } from './manifest.js';
+export { createProjectReloader, ProjectReloaded, type ProjectReloader, type ReloadReport, } from './reload.js';
+export { ProjectMethodParams, ProjectSession, type ProjectStatus } from './session.js';
+export { inlineSourceMap, locateInBundle, SourceMap, type SourcePosition } from './sourcemap.js';
+export { projectTemplate, type TemplateName, type TemplateOptions } from './templates.js';

package/dist/index.js

@@ -0,0 +1,61 @@
+import { defineProject } from "./define.js";
+import {
+  GENERATED_END,
+  GENERATED_START,
+  generateDocs,
+  mergeAgentsMd,
+  renderAssetCatalog,
+  renderComponentCatalog,
+  renderErrorCatalog,
+  renderGeneratorCatalog
+} from "./docs.js";
+import {
+  buildApp,
+  loadProjectNavCache,
+  loadProjectShaders,
+  loadProjectStrings,
+  startProject
+} from "./host.js";
+import {
+  BUILTIN_PLUGINS,
+  loadProject,
+  Manifest,
+  manifestJsonSchema,
+  validateManifest
+} from "./manifest.js";
+import {
+  createProjectReloader,
+  ProjectReloaded
+} from "./reload.js";
+import { ProjectMethodParams, ProjectSession } from "./session.js";
+import { inlineSourceMap, locateInBundle, SourceMap } from "./sourcemap.js";
+import { projectTemplate } from "./templates.js";
+export {
+  BUILTIN_PLUGINS,
+  GENERATED_END,
+  GENERATED_START,
+  Manifest,
+  ProjectMethodParams,
+  ProjectReloaded,
+  ProjectSession,
+  SourceMap,
+  buildApp,
+  createProjectReloader,
+  defineProject,
+  generateDocs,
+  inlineSourceMap,
+  loadProject,
+  loadProjectNavCache,
+  loadProjectShaders,
+  loadProjectStrings,
+  locateInBundle,
+  manifestJsonSchema,
+  mergeAgentsMd,
+  projectTemplate,
+  renderAssetCatalog,
+  renderComponentCatalog,
+  renderErrorCatalog,
+  renderGeneratorCatalog,
+  startProject,
+  validateManifest
+};

package/dist/manifest.d.ts

@@ -0,0 +1,49 @@
+import { type Infer, type JsonSchema, ShardError } from '@aethervtt/shard-core';
+import type { Platform } from '@aethervtt/shard-platform';
+/** The `shard.json` schema. Defined with the schema system so validation and JSON Schema match. */
+export declare const Manifest: import("@aethervtt/shard-core").ComponentDef<{
+    readonly $schema: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly name: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly version: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly engine: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly entry: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly startScene: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly seed: import("@aethervtt/shard-core").FieldType<number, "u32">;
+    readonly window: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        width: import("@aethervtt/shard-core").FieldType<number, "u32">;
+        height: import("@aethervtt/shard-core").FieldType<number, "u32">;
+        msaa: import("@aethervtt/shard-core").FieldType<number, "u8">;
+    }>, "object">;
+    readonly assetRoots: import("@aethervtt/shard-core").FieldType<string[], "object">;
+    readonly procgen: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        cacheSize: import("@aethervtt/shard-core").FieldType<number, "u32">;
+    }>, "object">;
+    readonly plugins: import("@aethervtt/shard-core").FieldType<string[], "object">;
+}>;
+export type ManifestValue = Infer<typeof Manifest>;
+/** Validates a manifest: the schema plus rules the schema can't express. Collects every error. */
+export declare function validateManifest(json: unknown): ShardError[];
+/** Built-in engine plugins a manifest can name, with what they bring. */
+export declare const BUILTIN_PLUGINS: {
+    readonly render: 'GPU device, render graph, views, shaders';
+    readonly 'render/forward': 'cameras, meshes, standard material, lights (includes render and core/transform)';
+    readonly sprite: 'sprites, atlases, frame animation, tilemaps (includes render/forward)';
+    readonly text: 'Text and ScreenText with imported fonts (includes render/forward)';
+    readonly particles: 'GPU particle effects from *.particles.json (includes render/forward)';
+    readonly animation: 'AnimationPlayer: glTF and .anim.json clips on joints and fields, blending, root motion; Animator graphs from .animgraph.json (includes render/forward)';
+    readonly physics3d: 'Rapier 3D rigid bodies, colliders, joints, raycasts (includes core/transform)';
+    readonly physics2d: 'Rapier 2D physics in the XY plane (includes core/transform)';
+    readonly input: 'keyboard, mouse, gamepad, touch, action maps';
+    readonly audio: 'AudioSource, AudioListener, playSound, buses and ducking, spatial audio, voice limits (includes core/transform)';
+    readonly ui: 'UiNode trees under a UiRoot: flexbox layout, text, images, buttons, sliders, text fields, world-anchored markers, themes (includes core/transform)';
+    readonly nav: 'navigation: NavGrid A* (2D), NavMesh baked by Recast from NavSource geometry, OffMeshLink, path queries, NavAgent steering (includes core/transform)';
+    readonly 'nav/grid': 'navigation on NavGrids only, without loading the Recast WASM (includes core/transform)';
+    readonly terrain: 'planets: Planet cube-sphere terrain from noise graphs with LOD, geomorphing, oceans, biomes, collider chunks around characters, navmeshes on the surface; terrain.* methods (includes core/transform; add render/forward to draw it, physics3d for colliders)';
+    readonly 'core/transform': 'Transform and hierarchy propagation';
+};
+export declare function manifestJsonSchema(): JsonSchema;
+export interface ProjectInfo {
+    manifest: ManifestValue;
+}
+/** Reads and validates `shard.json` through the platform (rooted at the project folder). */
+export declare function loadProject(platform: Platform): Promise<ProjectInfo>;

package/dist/manifest.js

@@ -0,0 +1,147 @@
+import { defineSchema, ShardError, t } from "@aethervtt/shard-core";
+const NAMESPACE = /^[a-z][a-z0-9-]*$/;
+const Manifest = defineSchema(
+  "project/Manifest",
+  {
+    $schema: t.string({ description: "Path to the generated schema, for editor validation." }),
+    name: t.string({
+      required: true,
+      description: "Project name: lowercase letters, digits, dashes. Also the namespace of project components."
+    }),
+    version: t.string({ default: "0.1.0" }),
+    engine: t.string({ default: "0.x", description: "Engine version range." }),
+    entry: t.string({ default: "scripts/main.ts", description: "The project plugin module." }),
+    startScene: t.string({
+      default: "scenes/main.scene.json",
+      description: "Scene loaded at startup."
+    }),
+    seed: t.u32({ default: 1, description: "Root seed for GlobalRng. Same seed, same world." }),
+    window: t.struct(
+      {
+        width: t.u32({ default: 1280, min: 1 }),
+        height: t.u32({ default: 720, min: 1 }),
+        msaa: t.u8({ default: 4, min: 1, max: 4, description: "1 or 4." })
+      },
+      { description: "Window (or headless render target) size and anti-aliasing." }
+    ),
+    assetRoots: t.list(t.string, {
+      default: ["assets", "materials", "data", "prefabs", "locales", "generators"],
+      description: "Folders the asset database imports from. Nothing outside them is imported."
+    }),
+    procgen: t.struct(
+      {
+        cacheSize: t.u32({
+          default: 256,
+          min: 1,
+          unit: "MB",
+          description: "Generator outputs kept in memory (and in browser storage), in megabytes."
+        })
+      },
+      { description: "Generators (0042): output cache limits." }
+    ),
+    plugins: t.list(t.string, {
+      default: ["render/forward", "input"],
+      description: "Engine plugins to enable, by name: render, render/forward, sprite, text, particles, animation, physics3d, physics2d, input, audio, ui, nav, nav/grid, core/transform."
+    })
+  },
+  { description: "shard.json: the project manifest." }
+);
+function validateManifest(json) {
+  const errors = Manifest.validate(json);
+  const value = json;
+  if (typeof value?.name === "string" && !NAMESPACE.test(value.name)) {
+    errors.push(
+      new ShardError(
+        "project/invalid-name",
+        `Project name "${value.name}" isn't a valid namespace`,
+        {
+          path: "/name",
+          hint: 'Use lowercase letters, digits, and dashes, starting with a letter (e.g. "star-explorer").'
+        }
+      )
+    );
+  }
+  const msaa = value?.window?.msaa;
+  if (msaa !== void 0 && msaa !== 1 && msaa !== 4) {
+    errors.push(
+      new ShardError("schema/out-of-range", "window.msaa must be 1 or 4", { path: "/window/msaa" })
+    );
+  }
+  for (const [i, plugin] of (value?.plugins ?? []).entries()) {
+    if (typeof plugin === "string" && !(plugin in BUILTIN_PLUGINS)) {
+      errors.push(
+        new ShardError("project/unknown-plugin", `Unknown engine plugin "${plugin}"`, {
+          path: `/plugins/${i}`,
+          hint: `Built-in plugins: ${Object.keys(BUILTIN_PLUGINS).join(", ")}.`
+        })
+      );
+    }
+  }
+  return errors;
+}
+const BUILTIN_PLUGINS = {
+  render: "GPU device, render graph, views, shaders",
+  "render/forward": "cameras, meshes, standard material, lights (includes render and core/transform)",
+  sprite: "sprites, atlases, frame animation, tilemaps (includes render/forward)",
+  text: "Text and ScreenText with imported fonts (includes render/forward)",
+  particles: "GPU particle effects from *.particles.json (includes render/forward)",
+  animation: "AnimationPlayer: glTF and .anim.json clips on joints and fields, blending, root motion; Animator graphs from .animgraph.json (includes render/forward)",
+  physics3d: "Rapier 3D rigid bodies, colliders, joints, raycasts (includes core/transform)",
+  physics2d: "Rapier 2D physics in the XY plane (includes core/transform)",
+  input: "keyboard, mouse, gamepad, touch, action maps",
+  audio: "AudioSource, AudioListener, playSound, buses and ducking, spatial audio, voice limits (includes core/transform)",
+  ui: "UiNode trees under a UiRoot: flexbox layout, text, images, buttons, sliders, text fields, world-anchored markers, themes (includes core/transform)",
+  nav: "navigation: NavGrid A* (2D), NavMesh baked by Recast from NavSource geometry, OffMeshLink, path queries, NavAgent steering (includes core/transform)",
+  "nav/grid": "navigation on NavGrids only, without loading the Recast WASM (includes core/transform)",
+  terrain: "planets: Planet cube-sphere terrain from noise graphs with LOD, geomorphing, oceans, biomes, collider chunks around characters, navmeshes on the surface; terrain.* methods (includes core/transform; add render/forward to draw it, physics3d for colliders)",
+  "core/transform": "Transform and hierarchy propagation"
+};
+function manifestJsonSchema() {
+  const schema = Manifest.jsonSchema();
+  schema.title = "shard.json";
+  schema.properties.name.pattern = NAMESPACE.source;
+  return schema;
+}
+async function loadProject(platform) {
+  let text;
+  try {
+    text = await platform.fs.readText("shard.json");
+  } catch (cause) {
+    throw new ShardError("project/not-found", "No shard.json in the project folder", {
+      hint: "Run `shard init <dir>` to create a project, or run from a project folder.",
+      cause
+    });
+  }
+  let json;
+  try {
+    json = JSON.parse(text);
+  } catch (cause) {
+    throw new ShardError(
+      "project/invalid-json",
+      `shard.json is not valid JSON: ${cause.message}`,
+      {
+        path: "shard.json"
+      }
+    );
+  }
+  const errors = validateManifest(json);
+  if (errors.length > 0) {
+    throw new ShardError(
+      "project/invalid-manifest",
+      `shard.json has ${errors.length} error(s); first: ${errors[0].message}`,
+      {
+        path: errors[0].path,
+        hint: errors[0].hint,
+        details: errors
+      }
+    );
+  }
+  return { manifest: Manifest.deserialize(json) };
+}
+export {
+  BUILTIN_PLUGINS,
+  Manifest,
+  loadProject,
+  manifestJsonSchema,
+  validateManifest
+};

package/dist/reload.d.ts

@@ -0,0 +1,53 @@
+import { type EventDef } from '@aethervtt/shard-core';
+import type { App, Plugin } from '@aethervtt/shard-runtime';
+export interface ReloadReport {
+    ok: boolean;
+    ms: number;
+    /** Components whose layout changed and whose data was migrated. */
+    migrated: string[];
+    /** Components the new code no longer defines; kept in the world with their old definition. */
+    orphaned: string[];
+    systems: {
+        added: string[];
+        removed: string[];
+        changed: string[];
+    };
+    /** Data files re-imported because their type changed (and those that no longer validate). */
+    assets: {
+        imported: string[];
+        failed: string[];
+    };
+    /**
+     * Generator outputs whose generator's code changed: generator files re-imported, and loaded
+     * runtime outputs regenerating in the background (each swaps in place when ready).
+     */
+    procgen: {
+        regenerated: string[];
+    };
+    error?: {
+        code: string;
+        message: string;
+        path?: string;
+        hint?: string;
+        source?: string;
+    };
+}
+/** Sent after every successful project reload, with its report. */
+export declare const ProjectReloaded: EventDef<ReloadReport>;
+type ModuleLoader = () => Promise<{
+    default?: unknown;
+}>;
+/**
+ * Hot reload for a project's code. `reload` evaluates the new bundle inside a redefinition scope,
+ * migrates component data whose layout changed, swaps the project's systems and observers, and
+ * keeps entities and resources. Any failure rolls everything back and the old code keeps running.
+ */
+export declare function createProjectReloader(app: App, options: {
+    namespace: string;
+    current: Plugin;
+}): {
+    readonly current: Plugin;
+    reload(load: ModuleLoader): Promise<ReloadReport>;
+};
+export type ProjectReloader = ReturnType<typeof createProjectReloader>;
+export {};