@aethervtt/shard-scene 0.0.1

package/dist/scene.d.ts

@@ -0,0 +1,93 @@
+import { type AssetRef, type ComponentDef, type Entity, type JsonValue, type ResolvedAsset, type SchemaContext, ShardError, type World } from '@aethervtt/shard-core';
+import { type SceneAsset, type SceneEntity, type SceneFile } from './format.js';
+export interface LoadedSceneHandle {
+    id: string;
+    /** Scene path → entity. */
+    entities: ReadonlyMap<string, Entity>;
+}
+/** Authoring-only fields: written in files, converted on load, written back when unchanged. */
+export declare const ALIASES: Record<string, Record<string, {
+    field: string;
+    decode(json: unknown): JsonValue;
+}>>;
+export declare function expandAliases(name: string, json: Record<string, JsonValue>, base: string, errors: ShardError[] | undefined): Record<string, JsonValue>;
+export declare function resolveAssets(world: World, file: {
+    assets?: Record<string, SceneAsset>;
+}, sceneId: string, mode: 'check' | 'create', requested?: Set<string>): (ref: {
+    guid?: string;
+    path?: string;
+}) => ResolvedAsset | undefined;
+/**
+ * Schema context for component JSON outside a scene file (protocol, tools): entity fields accept
+ * scene paths, handles accept asset paths, procedural refs (`procedural:sphere?radius=1`), and guids.
+ */
+export declare function worldSchemaContext(world: World): SchemaContext;
+/** Expands authoring aliases (e.g. Transform `rotationEuler`) in one component's JSON. */
+export declare function expandComponentAliases(name: string, json: Record<string, JsonValue>): Record<string, JsonValue>;
+export interface FlatEntity {
+    path: string;
+    parent: string | undefined;
+    entity: SceneEntity;
+    pointer: string;
+}
+export declare function flatten(entities: readonly SceneEntity[], base: string, parent: string | undefined, out: FlatEntity[]): void;
+export declare function rebase(err: ShardError, base: string): ShardError;
+export declare function componentDef(name: string): ComponentDef | undefined;
+/** Every problem in a scene file, each with a JSON pointer. Empty means it will load. */
+export declare function validateScene(world: World, json: unknown, options?: {
+    id?: string;
+}): ShardError[];
+/** Checks a file's `assets` block (scene-local materials and procedural meshes). */
+export declare function validateAssetsBlock(assets: Record<string, SceneAsset> | undefined, errors: ShardError[]): void;
+export interface TreeOptions {
+    id: string;
+    /**
+     * False when there's no catalog to check asset paths against (importing a prefab): only
+     * file-local `#name` refs are checked; the rest are checked when a scene using it validates.
+     */
+    catalog?: boolean;
+    /** Entity paths that resolve besides the tree's own (a prefab's root is "."). */
+    extraPaths?: readonly string[];
+    /** A prefab tree: the first entity is the root, at path ".". */
+    root?: boolean;
+    /** A variant: `#name` refs may name the base's assets, so missing ones aren't errors here. */
+    inheritsAssets?: boolean;
+}
+/** Names, components, entity paths, and instance overrides of a flattened entity tree. */
+export declare function validateTree(world: World, file: {
+    assets?: Record<string, SceneAsset>;
+}, flat: readonly FlatEntity[], errors: ShardError[], options: TreeOptions): void;
+/** A specific scene error beats the generic asset-not-found for the same field; drop duplicates. */
+export declare function dedupeErrors(errors: ShardError[]): ShardError[];
+/** Validates, then spawns the scene. Throws `scene/invalid` (with every error in `details`) if invalid. */
+export declare function loadScene(world: World, json: unknown, options?: {
+    id?: string;
+}): LoadedSceneHandle;
+/**
+ * Resolves once every asset the scene referenced has loaded or failed (following their
+ * dependencies). Tools wait for this before capturing, so screenshots never show half a scene.
+ */
+export declare function whenSceneReady(world: World, id: string): Promise<void>;
+export declare function addSceneReadyCheck(check: (world: World, sceneId: string) => Promise<void>): void;
+/** Despawns a loaded scene's entities and loads the new file under the same id. */
+export declare function reloadScene(world: World, id: string, json: unknown): LoadedSceneHandle;
+/** Despawns a scene's entities, then unloads assets nothing references any more. */
+export declare function unloadScene(world: World, id: string, options?: {
+    collect?: boolean;
+}): void;
+/** Finds a scene entity by path (`ship/camera`), or `sceneId:path` when several scenes are loaded. */
+export declare function findEntityByPath(world: World, path: string): Entity | undefined;
+/** The scene path of an entity, if it came from a scene. */
+export declare function pathOfEntity(world: World, entity: Entity): string | undefined;
+export declare function toJson(value: unknown): JsonValue;
+export declare function equal(a: unknown, b: unknown): boolean;
+export declare function serializeComponents(world: World, entity: Entity): Map<string, Record<string, JsonValue>>;
+/**
+ * Serializes a loaded scene back to its file format. Fields unchanged since load are written exactly
+ * as authored (preset names, hex colors, "#asset" refs, rotationEuler, key order), so saving an
+ * untouched scene reproduces the file and edits make minimal diffs.
+ */
+export declare function saveScene(world: World, id: string): SceneFile;
+/** Scene JSON as written to disk: 2-space indent, trailing newline. */
+export declare function stringifyScene(file: SceneFile): string;
+export type { AssetRef };