@aethervtt/shard-scene 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Dias
+
+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/README.md

@@ -0,0 +1,3 @@
+# @aethervtt/shard-scene
+
+Part of [Shard](https://github.com/aethervtt/shard), a WebGPU-first 2D/3D game engine in TypeScript. See the repository for documentation.

package/dist/components.d.ts

@@ -0,0 +1,47 @@
+import { AssetStore } from '@aethervtt/shard-assets';
+import { type Entity, type JsonValue } from '@aethervtt/shard-core';
+import type { PrefabFile, SceneEntity, SceneFile } from './format.js';
+/** Marks entities that came from a scene file. */
+export declare const SceneMember: import("@aethervtt/shard-core").ComponentDef<{
+    readonly scene: import("@aethervtt/shard-core").FieldType<string, "object">;
+    readonly path: import("@aethervtt/shard-core").FieldType<string, "object">;
+}>;
+export interface LoadedScene {
+    id: string;
+    file: SceneFile;
+    /** Paths in file order (depth-first), and their entities. */
+    order: string[];
+    entities: Map<string, Entity>;
+    authored: Map<Entity, SceneEntity>;
+    /** Serialized component values right after load, to tell which fields changed since. */
+    loaded: Map<Entity, Map<string, Record<string, JsonValue>>>;
+    loadedResources: Map<string, JsonValue>;
+    /** Guids of every asset the scene referenced, requested at load. */
+    assets: Set<string>;
+}
+export declare const SceneIndex: import("@aethervtt/shard-core").ResourceDef<Map<string, LoadedScene>>;
+/** Scene files loaded as assets (a glTF's node tree), by guid. */
+export declare const SceneAssets: import("@aethervtt/shard-core").ResourceDef<AssetStore<SceneFile, "Scene">>;
+/**
+ * Scene assets. References inside them written as `#Label` point at sibling sub-assets of the same
+ * source; they're resolved against the source's current path at load, so moving the file is safe.
+ */
+export declare const SceneAssetType: import("@aethervtt/shard-assets").AssetTypeDef<SceneFile>;
+/** Prefabs by guid: the resolved tree (variants already flattened onto their base). */
+export declare const PrefabAssets: import("@aethervtt/shard-core").ResourceDef<AssetStore<PrefabFile, "Prefab">>;
+export declare const PrefabAssetType: import("@aethervtt/shard-assets").AssetTypeDef<PrefabFile>;
+/** Places a scene asset (e.g. `assets/ship.glb#Scene`) as generated children of this entity. */
+export declare const SceneInstance: import("@aethervtt/shard-core").ComponentDef<{
+    readonly scene: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Scene"> | null, "object">;
+    readonly overrides: import("@aethervtt/shard-core").FieldType<JsonValue, "object">;
+}>;
+/** Makes this entity an instance of a prefab: the prefab root's components and children. */
+export declare const PrefabInstance: import("@aethervtt/shard-core").ComponentDef<{
+    readonly prefab: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Prefab"> | null, "object">;
+    readonly overrides: import("@aethervtt/shard-core").FieldType<JsonValue, "object">;
+}>;
+/** Marks entities an instance generated (they're rebuilt from the prefab or model, never saved). */
+export declare const InstancePart: import("@aethervtt/shard-core").ComponentDef<{
+    readonly instance: import("@aethervtt/shard-core").FieldType<number | null, "f64">;
+    readonly path: import("@aethervtt/shard-core").FieldType<string, "object">;
+}>;

package/dist/components.js

@@ -0,0 +1,93 @@
+import { AssetStore, defineAssetType } from "@aethervtt/shard-assets";
+import {
+  defineComponent,
+  defineResource,
+  t
+} from "@aethervtt/shard-core";
+const SceneMember = defineComponent(
+  "scene/SceneMember",
+  {
+    scene: t.string({ description: "Id of the scene this entity was loaded from." }),
+    path: t.string({ description: 'Path within the scene, e.g. "ship/camera".' })
+  },
+  { description: "Set by the scene loader.", serialize: false }
+);
+const SceneIndex = defineResource("scene/Index", {
+  description: "Loaded scenes: paths, entities, and what was authored.",
+  init: () => /* @__PURE__ */ new Map()
+});
+const SceneAssets = defineResource("scene/SceneAssets", {
+  description: "Scene assets (node trees) by guid.",
+  init: () => new AssetStore("Scene")
+});
+const SceneAssetType = defineAssetType("Scene", {
+  store: SceneAssets,
+  load: (artifact, ctx) => {
+    const base = ctx.path.split("#")[0];
+    const resolve = (value) => {
+      if (Array.isArray(value)) return value.map(resolve);
+      if (!value || typeof value !== "object") return value;
+      const out = {};
+      for (const [k, v] of Object.entries(value)) {
+        out[k] = k === "path" && typeof v === "string" && v.startsWith("#") ? `${base}${v}` : resolve(v);
+      }
+      return out;
+    };
+    return resolve(artifact.json);
+  }
+});
+const PrefabAssets = defineResource("scene/PrefabAssets", {
+  description: "Prefab assets (resolved entity trees) by guid.",
+  init: () => new AssetStore("Prefab")
+});
+const PrefabAssetType = defineAssetType("Prefab", {
+  store: PrefabAssets,
+  load: (artifact) => artifact.json
+});
+const overridesField = () => t.json({
+  default: {},
+  description: 'Changes to generated entities by path relative to this entity: { "Exhaust": { "particles/ParticleSystem": { "timeScale": 2 } } } sets fields, { "Hull/Antenna": null } removes an entity, { "Exhaust/particles/ParticleEmitterOverrides": null } removes a component. Paths reach into nested instances.'
+});
+const SceneInstance = defineComponent(
+  "scene/SceneInstance",
+  {
+    scene: t.handle("Scene", {
+      description: 'The scene to place, e.g. { "path": "assets/ship.glb#Scene" }.'
+    }),
+    overrides: overridesField()
+  },
+  {
+    description: "Spawns a scene asset (a model's node tree) as children, addressable by path (ship/Hull). The children are generated: saving writes only this entity and its overrides, and they respawn when the asset changes."
+  }
+);
+const PrefabInstance = defineComponent(
+  "scene/PrefabInstance",
+  {
+    prefab: t.handle("Prefab", {
+      description: 'The prefab to place, e.g. { "path": "prefabs/ship.prefab.json" }.'
+    }),
+    overrides: overridesField()
+  },
+  {
+    description: "Makes this entity an instance of a prefab. The prefab root's components merge into it (fields the entity sets win) and the root's children spawn under it, addressable by path (player-ship/Exhaust). Changes to the children are saved as overrides."
+  }
+);
+const InstancePart = defineComponent(
+  "scene/InstancePart",
+  {
+    instance: t.entity({ description: "The instance entity that generated this one." }),
+    path: t.string({ description: 'Path relative to the instance, e.g. "Hull/Cockpit".' })
+  },
+  { description: "Set on entities a SceneInstance or PrefabInstance spawned.", serialize: false }
+);
+export {
+  InstancePart,
+  PrefabAssetType,
+  PrefabAssets,
+  PrefabInstance,
+  SceneAssetType,
+  SceneAssets,
+  SceneIndex,
+  SceneInstance,
+  SceneMember
+};

package/dist/format.d.ts

@@ -0,0 +1,53 @@
+import type { JsonValue } from '@aethervtt/shard-core';
+/** A `*.scene.json` file. */
+export interface SceneFile {
+    $schema?: string;
+    version: number;
+    /** Scene-local assets, referenced as `{ "path": "#name" }`. */
+    assets?: Record<string, SceneAsset>;
+    /** Resource values by registered name, merged into the world's resources on load. */
+    resources?: Record<string, JsonValue>;
+    entities: SceneEntity[];
+}
+export type SceneAsset = {
+    type: 'Material';
+    value: Record<string, JsonValue>;
+} | {
+    type: 'Mesh';
+    procedural: string;
+    params?: Record<string, number>;
+};
+export interface SceneEntity {
+    /** Unique among siblings; joined with '/' into the entity's path. */
+    name: string;
+    components?: Record<string, Record<string, JsonValue>>;
+    children?: SceneEntity[];
+}
+export declare const SCENE_VERSION = 1;
+/**
+ * Changes to an instance's generated entities, keyed by path relative to the instance:
+ * `{ "Exhaust": { "particles/ParticleSystem": { "timeScale": 2 } } }` sets fields (adding the
+ * component if missing), `{ "Hull/Antenna": null }` removes an entity and its subtree, and
+ * `{ "Exhaust/particles/ParticleEmitterOverrides": null }` removes one component.
+ */
+export type Overrides = Record<string, Record<string, Record<string, JsonValue> | null> | null>;
+/** A `*.prefab.json` file: one root entity, or a variant that extends another prefab. */
+export interface PrefabFile {
+    $schema?: string;
+    version: number;
+    /** Prefab-local assets, referenced as `{ "path": "#name" }`. */
+    assets?: Record<string, SceneAsset>;
+    root?: SceneEntity;
+    /** Variants only: the base prefab. */
+    extends?: {
+        path?: string;
+        guid?: string;
+    };
+    /** Variants only: fields set on the base's root components (added if missing). */
+    rootComponents?: Record<string, Record<string, JsonValue>>;
+    /** Variants only: overrides applied to the base's entities. */
+    overrides?: Overrides;
+    /** Variants only: extra children under the root. */
+    children?: SceneEntity[];
+}
+export declare const PREFAB_VERSION = 1;

package/dist/format.js

@@ -0,0 +1,6 @@
+const SCENE_VERSION = 1;
+const PREFAB_VERSION = 1;
+export {
+  PREFAB_VERSION,
+  SCENE_VERSION
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { InstancePart, PrefabAssets, PrefabAssetType, PrefabInstance, SceneAssets, SceneAssetType, SceneIndex, SceneInstance, SceneMember, } from './components.js';
+export { type Overrides, PREFAB_VERSION, type PrefabFile, SCENE_VERSION, type SceneAsset, type SceneEntity, type SceneFile, } from './format.js';
+export { currentOverrides, defineInstanceKind, hookInstances, type InstanceKind, instanceEntities, instanceKindOf, instanceKinds, instanceOf, loadInstanceAssets, loadPrefab, mergeOverridesIntoPrefab, prefabOfInstance, prefabRootComponents, releaseSceneHooks, ScenePlugin, type SpawnPrefabOptions, sceneInstancesSystem, settleInstances, spawnPrefab, updateInstances, } from './instances.js';
+export { applyToPrefab, applyVariant, type PrefabFiles, PrefabImporter, registeredPrefab, registerPrefab, validatePrefab, } from './prefab-file.js';
+export { allProceduralSources, defineProceduralSource, PROCEDURAL_MESHES, type ProceduralRef, type ProceduralSource, parseProcedural, proceduralSourceFor, } from './procedural.js';
+export { addSceneReadyCheck, expandComponentAliases, findEntityByPath, type LoadedSceneHandle, loadScene, pathOfEntity, reloadScene, saveScene, stringifyScene, unloadScene, validateScene, whenSceneReady, worldSchemaContext, } from './scene.js';
+export { prefabJsonSchema, sceneJsonSchema } from './schema.js';

package/dist/index.js

@@ -0,0 +1,121 @@
+import {
+  InstancePart,
+  PrefabAssets,
+  PrefabAssetType,
+  PrefabInstance,
+  SceneAssets,
+  SceneAssetType,
+  SceneIndex,
+  SceneInstance,
+  SceneMember
+} from "./components.js";
+import {
+  PREFAB_VERSION,
+  SCENE_VERSION
+} from "./format.js";
+import {
+  currentOverrides,
+  defineInstanceKind,
+  hookInstances,
+  instanceEntities,
+  instanceKindOf,
+  instanceKinds,
+  instanceOf,
+  loadInstanceAssets,
+  loadPrefab,
+  mergeOverridesIntoPrefab,
+  prefabOfInstance,
+  prefabRootComponents,
+  releaseSceneHooks,
+  ScenePlugin,
+  sceneInstancesSystem,
+  settleInstances,
+  spawnPrefab,
+  updateInstances
+} from "./instances.js";
+import {
+  applyToPrefab,
+  applyVariant,
+  PrefabImporter,
+  registeredPrefab,
+  registerPrefab,
+  validatePrefab
+} from "./prefab-file.js";
+import {
+  allProceduralSources,
+  defineProceduralSource,
+  PROCEDURAL_MESHES,
+  parseProcedural,
+  proceduralSourceFor
+} from "./procedural.js";
+import {
+  addSceneReadyCheck,
+  expandComponentAliases,
+  findEntityByPath,
+  loadScene,
+  pathOfEntity,
+  reloadScene,
+  saveScene,
+  stringifyScene,
+  unloadScene,
+  validateScene,
+  whenSceneReady,
+  worldSchemaContext
+} from "./scene.js";
+import { prefabJsonSchema, sceneJsonSchema } from "./schema.js";
+export {
+  InstancePart,
+  PREFAB_VERSION,
+  PROCEDURAL_MESHES,
+  PrefabAssetType,
+  PrefabAssets,
+  PrefabImporter,
+  PrefabInstance,
+  SCENE_VERSION,
+  SceneAssetType,
+  SceneAssets,
+  SceneIndex,
+  SceneInstance,
+  SceneMember,
+  ScenePlugin,
+  addSceneReadyCheck,
+  allProceduralSources,
+  applyToPrefab,
+  applyVariant,
+  currentOverrides,
+  defineInstanceKind,
+  defineProceduralSource,
+  expandComponentAliases,
+  findEntityByPath,
+  hookInstances,
+  instanceEntities,
+  instanceKindOf,
+  instanceKinds,
+  instanceOf,
+  loadInstanceAssets,
+  loadPrefab,
+  loadScene,
+  mergeOverridesIntoPrefab,
+  parseProcedural,
+  pathOfEntity,
+  prefabJsonSchema,
+  prefabOfInstance,
+  prefabRootComponents,
+  proceduralSourceFor,
+  registerPrefab,
+  registeredPrefab,
+  releaseSceneHooks,
+  reloadScene,
+  saveScene,
+  sceneInstancesSystem,
+  sceneJsonSchema,
+  settleInstances,
+  spawnPrefab,
+  stringifyScene,
+  unloadScene,
+  updateInstances,
+  validatePrefab,
+  validateScene,
+  whenSceneReady,
+  worldSchemaContext
+};

package/dist/instances.d.ts

@@ -0,0 +1,120 @@
+import { type AssetEntry } from '@aethervtt/shard-assets';
+import { type AssetRef, Commands, type ComponentDef, type Entity, type JsonValue, ShardError, World } from '@aethervtt/shard-core';
+import { type Plugin } from '@aethervtt/shard-runtime';
+import type { Overrides, PrefabFile } from './format.js';
+import { type FlatEntity } from './scene.js';
+type InstanceDef = ComponentDef;
+/**
+ * A component that spawns a Prefab or Scene asset as generated children: SceneInstance,
+ * PrefabInstance, and kinds other packages add (procgen's GeneratorInstance). The component needs
+ * an `overrides` json field; saves write the children's changes there.
+ */
+export interface InstanceKind {
+    readonly def: ComponentDef;
+    /**
+     * The Prefab or Scene asset an instance with this value spawns: registered (it may still be
+     * loading; unloaded ones are requested), or undefined when there's nothing to spawn.
+     */
+    source(world: World, value: Record<string, unknown>, entity: Entity): AssetEntry | undefined;
+    /** Respawns reuse the entities whose path is unchanged, so references to them survive. */
+    readonly keepIds?: boolean;
+    /** A tag added to every entity this kind spawns (procgen/Generated). */
+    readonly mark?: ComponentDef;
+    /**
+     * Instances on generated entities spawn their own children (lazily, as part of nothing). Without
+     * it, instances inside a prefab are inlined into it.
+     */
+    readonly nested?: boolean;
+    /** Extra checks of the component's JSON in scene and prefab files. */
+    validate?(world: World, json: Record<string, JsonValue>, base: string, errors: ShardError[], options: {
+        catalog: boolean;
+    }): void;
+}
+export declare const sceneInstanceKind: InstanceKind;
+export declare const prefabInstanceKind: InstanceKind;
+/** Adds a kind of instance component (see InstanceKind). */
+export declare function defineInstanceKind(kind: InstanceKind): InstanceKind;
+/** Every instance kind: SceneInstance, PrefabInstance, then added ones. */
+export declare function instanceKinds(): readonly InstanceKind[];
+export declare function instanceKindOf(def: ComponentDef): InstanceKind | undefined;
+/** Installs the instance hooks for a world (asset reloads respawn instances, even between frames). */
+export declare function hookInstances(world: World): void;
+/** Detaches a world's scene hooks from its asset server (for worlds that share another's server). */
+export declare function releaseSceneHooks(world: World): void;
+/** Spawns instances system: does nothing on frames without instance or asset changes. */
+export declare const sceneInstancesSystem: import("@aethervtt/shard-core").SystemDef<undefined>;
+/** Scene support for apps: spawns instance children added while the app runs. */
+export declare const ScenePlugin: Plugin;
+/**
+ * Spawns the children of every SceneInstance and PrefabInstance whose asset is loaded (requesting
+ * it otherwise), respawns those whose asset, dependencies, or overrides changed, and cleans up after
+ * removed instances. Instances inlined into another instance are part of it and skipped.
+ */
+export declare function updateInstances(world: World): void;
+/** Waits for instance assets to load and spawns them (repeatedly, for nested instances). */
+export declare function settleInstances(world: World): Promise<void>;
+export interface SpawnPrefabOptions {
+    /** Fields of the root's Transform (the rest come from the prefab). */
+    transform?: {
+        translation?: readonly number[];
+        rotation?: readonly number[];
+        scale?: readonly number[];
+    };
+    /** Changes to generated entities, as in a scene's `PrefabInstance.overrides`. */
+    overrides?: Overrides;
+    parent?: Entity;
+}
+type PrefabRef = string | AssetRef | {
+    guid?: string;
+    path?: string;
+};
+/**
+ * Loads a prefab (and everything it uses) so `spawnPrefab` can spawn it. Resolves with its
+ * template ready.
+ */
+export declare function loadPrefab(world: World, ref: PrefabRef): Promise<void>;
+/**
+ * Spawns a prefab instance now (or, given a system's Commands, when they apply) and returns its
+ * root. The prefab must be loaded (`loadPrefab`); spawning copies a compiled template, so it's cheap
+ * enough for bullets. Scene files place prefabs with `scene/PrefabInstance`, which waits for loading.
+ */
+export declare function spawnPrefab(target: World | Commands, ref: PrefabRef, options?: SpawnPrefabOptions): Entity;
+/** The generated entities of an instance, by path relative to it (e.g. "Hull/Cockpit"). */
+export declare function instanceEntities(world: World, entity: Entity): Map<string, Entity>;
+/**
+ * The components a prefab instance's root got from its prefab, as JSON (entity fields as paths
+ * relative to the instance, "." for itself). Undefined for entities that aren't spawned prefab
+ * instances. Saves compare against it to write only what changed.
+ */
+export declare function prefabRootComponents(world: World, entity: Entity): ReadonlyMap<string, Record<string, JsonValue>> | undefined;
+/** The instance entity (prefab or model) at the top of a generated entity, or the entity itself. */
+export declare function instanceOf(world: World, entity: Entity): Entity | undefined;
+/**
+ * An instance's current differences from its prefab or model, as overrides: what a save writes.
+ * Overrides already in the file keep their order and authored form while unchanged; stale ones
+ * (paths that no longer exist) are kept. Undefined for entities that aren't spawned instances.
+ */
+export declare function currentOverrides(world: World, entity: Entity): Overrides | undefined;
+/** What `applyToPrefab` needs from the host: the prefab file's JSON, and where to write it. */
+export interface PrefabSource {
+    read(path: string): Promise<unknown>;
+    write(path: string, json: unknown): Promise<void>;
+}
+/**
+ * Merges overrides into a prefab file's JSON: component patches merge into the authored components,
+ * removals delete, and paths inside a nested instance land in that instance's overrides. Variants
+ * (files with "extends") merge into their own "overrides". Returns the new JSON.
+ */
+export declare function mergeOverridesIntoPrefab(file: PrefabFile, overrides: Overrides, onUnknown?: (key: string) => void): PrefabFile;
+/** The prefab asset an instance entity places, or undefined. */
+export declare function prefabOfInstance(world: World, entity: Entity): AssetEntry | undefined;
+/**
+ * Checks an instance component's overrides in a scene or prefab file: shape always; paths and
+ * values when the asset is loaded (so `shard validate` preloads them with `loadInstanceAssets`).
+ */
+export declare function validateInstance(world: World, def: InstanceDef, json: Record<string, JsonValue>, base: string, f: FlatEntity, errors: ShardError[], options: {
+    catalog: boolean;
+}): void;
+/** Loads the prefab and model assets a scene's instances use, so validation can check overrides. */
+export declare function loadInstanceAssets(world: World, json: unknown): Promise<void>;
+export {};