@scenography/engine 0.5.0 → 0.7.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { MeshStandardMaterial, Object3D, PerspectiveCamera, Scene, Vector3, WebGLRenderer } from "three";
+import { CompressedTexture, MeshStandardMaterial, Object3D, PerspectiveCamera, Scene, Vector3, WebGLRenderer } from "three";
 import { DataPlugin, Scene as Scene$1, SurfaceTexture, Vec2 } from "@scenography/scene";
 
 //#region src/camera/api.d.ts
@@ -111,6 +111,15 @@ interface SkyApi {
   getAzimuth(): number;
 }
 //#endregion
+//#region src/loading.d.ts
+interface LoadingState {
+  loaded: number;
+  total: number;
+  done: boolean;
+}
+/** Mark one initial asset as loaded; unknown URLs (lazy assets) are ignored. */
+declare const trackAsset: (url: string) => void;
+//#endregion
 //#region src/input/InputBus.d.ts
 /**
  * The shared analog-input channel: the current movement and look intent, each
@@ -249,6 +258,10 @@ interface BuiltElement {
 /** What the kernel hands a plugin while building. */
 interface EngineContext {
   capabilities: CapabilityRegistry;
+  /** Live camera, for plugins that choose detail by distance. */
+  camera: PerspectiveCamera;
+  /** Live renderer, for plugins that need GPU capabilities (e.g. KTX2). */
+  renderer: WebGLRenderer;
 }
 /**
  * An aggregate controller over all of an element plugin's live objects, exposing
@@ -483,6 +496,11 @@ interface GalleryOptions extends RenderOptions {
   canvas: HTMLCanvasElement;
   /** Background color. Defaults to a soft gray. */
   background?: string;
+  /**
+   * Base path of the KTX2 transcoder files (`basis_transcoder.js` and
+   * `basis_transcoder.wasm`). Without it, `.ktx2` textures are skipped.
+   */
+  ktx2Path?: string;
   /**
    * Runtime plugins: element plugins materialize a scene key; system plugins
    * (e.g. a camera) drive shared runtime state. Mixed freely — the kernel tells
@@ -573,6 +591,11 @@ interface Gallery {
   resize(width: number, height: number): void;
   /** Toggle rendering features (antialias, ssao, bloom, shadows) live. */
   setRender(options: RenderOptions): void;
+  /** Initial visual asset loading progress. */
+  readonly loading: {
+    get(): LoadingState;
+    subscribe(listener: (state: LoadingState) => void): () => void;
+  };
   readonly ctx: GalleryContext;
 }
 /**
@@ -594,9 +617,15 @@ declare class SceneManager {
   private readonly root;
   private readonly plugins;
   private readonly capabilities;
+  private readonly view;
   /** Mounted plugin elements, per kind, keyed by element id ("" for singletons). */
   private readonly pluginElements;
-  constructor(root: Scene, plugins?: EnginePlugin[], capabilities?: CapabilityRegistry);
+  constructor(root: Scene, plugins?: EnginePlugin[], capabilities?: CapabilityRegistry, view?: {
+    camera: PerspectiveCamera;
+    renderer: WebGLRenderer;
+  });
+  /** The build context handed to every plugin. */
+  private context;
   reconcile(scene: Scene$1): void;
   /**
    * Reconcile every registered plugin's elements by content: an element
@@ -624,6 +653,14 @@ declare class SceneManager {
  */
 declare const applyTexture: (material: MeshStandardMaterial, texture: SurfaceTexture) => boolean;
 //#endregion
+//#region src/builders/ktx2.d.ts
+/** The part of three's KTX2Loader the engine and plugins use. */
+interface Ktx2Loader {
+  load(url: string, onLoad: (texture: CompressedTexture) => void, onProgress?: (event: ProgressEvent) => void, onError?: (error: unknown) => void): void;
+}
+/** The configured loader, or null when the gallery did not set `ktx2Path`. */
+declare const getKtx2Loader: () => Promise<Ktx2Loader> | null;
+//#endregion
 //#region src/interaction/InteractionController.d.ts
 /**
  * Pointer picking for artworks: hovering a piece's click target (its label, or
@@ -677,5 +714,5 @@ declare class InteractionController {
   private buildHighlight;
 }
 //#endregion
-export { type Antialias, type BuiltElement, COLLIDERS, type CameraApi, CapabilityRegistry, type Collider, type ControlFlags, type ControlMode, ControlSettings, type ControlsApi, DEFAULT_CONTROL_FLAGS, EDGES, EYE_HEIGHT, type EdgeAnchor, type EdgeIndex, type ElementController, type EngineContext, type EnginePlugin, type EnvironmentApi, type FocusOptions, type Gallery, type GalleryContext, type GalleryOptions, InputBus, InteractionController, type LightSet, type LightSetOptions, type LightsApi, MODE_PRESETS, type MediaController, ROAM_CONTROL, type RenderOptions, type RoamControl, SceneManager, type SkyApi, type SystemContext, type SystemInstance, type SystemPlugin, TERRAIN, type TerrainCapability, type TerrainDefinition, type VideoApi, applyMode, applyTexture, createGallery, isSystemPlugin, modeOf };
+export { type Antialias, type BuiltElement, COLLIDERS, type CameraApi, CapabilityRegistry, type Collider, type ControlFlags, type ControlMode, ControlSettings, type ControlsApi, DEFAULT_CONTROL_FLAGS, EDGES, EYE_HEIGHT, type EdgeAnchor, type EdgeIndex, type ElementController, type EngineContext, type EnginePlugin, type EnvironmentApi, type FocusOptions, type Gallery, type GalleryContext, type GalleryOptions, InputBus, InteractionController, type LightSet, type LightSetOptions, type LightsApi, type LoadingState, MODE_PRESETS, type MediaController, ROAM_CONTROL, type RenderOptions, type RoamControl, SceneManager, type SkyApi, type SystemContext, type SystemInstance, type SystemPlugin, TERRAIN, type TerrainCapability, type TerrainDefinition, type VideoApi, applyMode, applyTexture, createGallery, getKtx2Loader, isSystemPlugin, modeOf, trackAsset };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,4 +1,47 @@
 import { BoxGeometry, Clock, EquirectangularReflectionMapping, Group, HalfFloatType, Mesh, MeshBasicMaterial, NoColorSpace, PCFShadowMap, PerspectiveCamera, Quaternion, Raycaster, RepeatWrapping, SRGBColorSpace, Scene, StereoCamera, TextureLoader, Vector2, Vector3, WebGLRenderTarget, WebGLRenderer } from "three";
+//#region src/loading.ts
+const pending = /* @__PURE__ */ new Set();
+const listeners = /* @__PURE__ */ new Set();
+let state = {
+	loaded: 0,
+	total: 0,
+	done: true
+};
+const notify = () => {
+	for (const listener of listeners) listener(state);
+};
+/** Begin tracking a new initial asset set; resets the previous one. */
+const startLoading = (urls) => {
+	pending.clear();
+	for (const url of urls) pending.add(url);
+	state = {
+		loaded: 0,
+		total: pending.size,
+		done: pending.size === 0
+	};
+	notify();
+};
+/** Mark one initial asset as loaded; unknown URLs (lazy assets) are ignored. */
+const trackAsset = (url) => {
+	if (!pending.delete(url)) return;
+	state = {
+		loaded: state.total - pending.size,
+		total: state.total,
+		done: pending.size === 0
+	};
+	notify();
+};
+/** Current loading progress. */
+const loadingState = () => state;
+/** Subscribe to progress; the listener runs immediately with the current state. */
+const onLoading = (listener) => {
+	listeners.add(listener);
+	listener(state);
+	return () => {
+		listeners.delete(listener);
+	};
+};
+//#endregion
 //#region src/environment/EnvironmentController.ts
 /** Load an equirectangular HDRI, picking the loader by extension. */
 const loadHDRI = (src, onLoad) => {
@@ -30,6 +73,7 @@ var EnvironmentController = class {
 		this.clear();
 		if (!env) return;
 		loadHDRI(env.src, (tex) => {
+			trackAsset(env.src);
 			if (this.hash !== hash) {
 				tex.dispose();
 				return;
@@ -59,6 +103,189 @@ var EnvironmentController = class {
 	}
 };
 //#endregion
+//#region src/builders/ktx2.ts
+let loader = null;
+/**
+* Configure the shared KTX2 loader. Called by the kernel once the renderer
+* exists; `.ktx2` textures and glTF models then decode through it.
+*/
+const configureKtx2 = (renderer, path) => {
+	loader = import("three/examples/jsm/loaders/KTX2Loader.js").then(({ KTX2Loader }) => {
+		const instance = new KTX2Loader();
+		instance.setTranscoderPath(path);
+		instance.detectSupport(renderer);
+		return instance;
+	});
+};
+/** The configured loader, or null when the gallery did not set `ktx2Path`. */
+const getKtx2Loader = () => loader;
+//#endregion
+//#region src/builders/textureCache.ts
+/** Two surfaces can share a texture only at the same tiling and color space. */
+const textureKey = (src, repeat, srgb) => `${src}|${repeat[0]}x${repeat[1]}|${srgb ? "srgb" : "linear"}`;
+/** Tiling and color space of a texture; the image arrives later from the loader. */
+const configureTexture = (texture, repeat, srgb) => {
+	texture.wrapS = RepeatWrapping;
+	texture.wrapT = RepeatWrapping;
+	texture.repeat.set(repeat[0], repeat[1]);
+	texture.colorSpace = srgb ? SRGBColorSpace : NoColorSpace;
+};
+/**
+* Shares textures between materials: the same source at the same tiling and
+* color space becomes one texture, loaded once and uploaded to the GPU once.
+* Reference counted, so releasing a material keeps the texture alive while
+* another one still samples it.
+*/
+var TextureCache = class {
+	source;
+	entries = /* @__PURE__ */ new Map();
+	owners = /* @__PURE__ */ new Map();
+	constructor(source) {
+		this.source = source;
+	}
+	/** The shared texture for a source, created on first use. */
+	acquire(src, repeat, srgb) {
+		const key = textureKey(src, repeat, srgb);
+		const existing = this.entries.get(key);
+		if (existing) {
+			existing.refs += 1;
+			return existing.texture;
+		}
+		const texture = this.source(src);
+		configureTexture(texture, repeat, srgb);
+		const entry = {
+			key,
+			texture,
+			refs: 1
+		};
+		this.entries.set(key, entry);
+		this.owners.set(texture, entry);
+		return texture;
+	}
+	/** Drop one reference; the texture is disposed when the last one goes. */
+	release(texture) {
+		const entry = this.owners.get(texture);
+		if (!entry) {
+			texture.dispose();
+			return;
+		}
+		entry.refs -= 1;
+		if (entry.refs > 0) return;
+		this.entries.delete(entry.key);
+		this.owners.delete(texture);
+		texture.dispose();
+	}
+	/** Textures currently shared. */
+	get size() {
+		return this.entries.size;
+	}
+};
+//#endregion
+//#region src/builders/texture.ts
+const textureLoader = new TextureLoader();
+const cache = new TextureCache((src) => textureLoader.load(src, () => trackAsset(src)));
+const ktx2Entries = /* @__PURE__ */ new Map();
+const ktx2Owners = /* @__PURE__ */ new Map();
+/**
+* KTX2 textures resolve asynchronously, so the material slot is filled through
+* a waiter list. One entry per source and tiling is shared by every material
+* that samples it, just like the image cache.
+*/
+const loadKtx2 = (material, slot, src, repeat, srgb) => {
+	const loader = getKtx2Loader();
+	if (!loader) {
+		console.warn(`KTX2 texture "${src}" needs the gallery's ktx2Path option.`);
+		return;
+	}
+	const key = textureKey(src, repeat, srgb);
+	let entry = ktx2Entries.get(key);
+	if (!entry) {
+		entry = {
+			key,
+			refs: 0,
+			waiters: []
+		};
+		ktx2Entries.set(key, entry);
+		const created = entry;
+		loader.then((ktx2) => ktx2.load(src, (texture) => {
+			configureTexture(texture, repeat, srgb);
+			texture.needsUpdate = true;
+			trackAsset(src);
+			created.texture = texture;
+			ktx2Owners.set(texture, created);
+			for (const assign of created.waiters) assign(texture);
+			created.waiters = [];
+		}, void 0, (error) => console.error(`Failed to load KTX2 texture "${src}".`, error)));
+	}
+	entry.refs += 1;
+	if (entry.texture) {
+		material[slot] = entry.texture;
+		material.needsUpdate = true;
+	} else entry.waiters.push((texture) => {
+		material[slot] = texture;
+		material.needsUpdate = true;
+	});
+};
+/**
+* Load one map into `material[slot]`. Textures are shared: every material that
+* samples the same source at the same tiling reuses one texture object. `.exr`
+* maps go through EXRLoader, imported on demand, and are not shared because
+* they resolve asynchronously; `.ktx2` maps share through their own cache.
+*/
+const loadMap = (material, slot, src, repeat, srgb) => {
+	if (src.toLowerCase().endsWith(".ktx2")) {
+		loadKtx2(material, slot, src, repeat, srgb);
+		return;
+	}
+	if (src.toLowerCase().endsWith(".exr")) {
+		import("three/examples/jsm/loaders/EXRLoader.js").then(({ EXRLoader }) => {
+			new EXRLoader().load(src, (texture) => {
+				configureTexture(texture, repeat, srgb);
+				texture.needsUpdate = true;
+				trackAsset(src);
+				material[slot] = texture;
+				material.needsUpdate = true;
+			});
+		});
+		return;
+	}
+	material[slot] = cache.acquire(src, repeat, srgb);
+};
+/**
+* Apply a `SurfaceTexture` to a standard material. Returns whether a second UV
+* set (`uv1`) is needed — three samples `aoMap` from it, so the geometry must
+* provide one.
+*/
+const applyTexture = (material, texture) => {
+	const repeat = texture.repeat ?? [1, 1];
+	loadMap(material, "map", texture.src, repeat, true);
+	if (texture.normal) {
+		loadMap(material, "normalMap", texture.normal, repeat, false);
+		const scale = texture.normalScale ?? 1;
+		material.normalScale = new Vector2(scale, scale);
+	}
+	if (texture.roughness) loadMap(material, "roughnessMap", texture.roughness, repeat, false);
+	if (texture.ao) loadMap(material, "aoMap", texture.ao, repeat, false);
+	material.needsUpdate = true;
+	return texture.ao !== void 0;
+};
+/**
+* Release one reference to a texture assigned by `applyTexture`. Shared
+* textures stay alive while another material still samples them.
+*/
+const releaseTexture = (texture) => {
+	const ktx2 = ktx2Owners.get(texture);
+	if (!ktx2) {
+		cache.release(texture);
+		return;
+	}
+	ktx2.refs -= 1;
+	if (ktx2.refs > 0) return;
+	ktx2Owners.delete(texture);
+	ktx2Entries.delete(ktx2.key);
+	texture.dispose();
+};
+//#endregion
 //#region src/interaction/InteractionController.ts
 const HIGHLIGHT_COLOR = "#ef4444";
 const HIGHLIGHT_THICKNESS = 1.5;
@@ -502,116 +729,6 @@ const EDGES = "edges";
 */
 const EYE_HEIGHT = "eyeHeight";
 //#endregion
-//#region src/builders/textureCache.ts
-/** Two surfaces can share a texture only at the same tiling and color space. */
-const textureKey = (src, repeat, srgb) => `${src}|${repeat[0]}x${repeat[1]}|${srgb ? "srgb" : "linear"}`;
-/** Tiling and color space of a texture; the image arrives later from the loader. */
-const configureTexture = (texture, repeat, srgb) => {
-	texture.wrapS = RepeatWrapping;
-	texture.wrapT = RepeatWrapping;
-	texture.repeat.set(repeat[0], repeat[1]);
-	texture.colorSpace = srgb ? SRGBColorSpace : NoColorSpace;
-};
-/**
-* Shares textures between materials: the same source at the same tiling and
-* color space becomes one texture, loaded once and uploaded to the GPU once.
-* Reference counted, so releasing a material keeps the texture alive while
-* another one still samples it.
-*/
-var TextureCache = class {
-	source;
-	entries = /* @__PURE__ */ new Map();
-	owners = /* @__PURE__ */ new Map();
-	constructor(source) {
-		this.source = source;
-	}
-	/** The shared texture for a source, created on first use. */
-	acquire(src, repeat, srgb) {
-		const key = textureKey(src, repeat, srgb);
-		const existing = this.entries.get(key);
-		if (existing) {
-			existing.refs += 1;
-			return existing.texture;
-		}
-		const texture = this.source(src);
-		configureTexture(texture, repeat, srgb);
-		const entry = {
-			key,
-			texture,
-			refs: 1
-		};
-		this.entries.set(key, entry);
-		this.owners.set(texture, entry);
-		return texture;
-	}
-	/** Drop one reference; the texture is disposed when the last one goes. */
-	release(texture) {
-		const entry = this.owners.get(texture);
-		if (!entry) {
-			texture.dispose();
-			return;
-		}
-		entry.refs -= 1;
-		if (entry.refs > 0) return;
-		this.entries.delete(entry.key);
-		this.owners.delete(texture);
-		texture.dispose();
-	}
-	/** Textures currently shared. */
-	get size() {
-		return this.entries.size;
-	}
-};
-//#endregion
-//#region src/builders/texture.ts
-const textureLoader = new TextureLoader();
-const cache = new TextureCache((src) => textureLoader.load(src));
-/**
-* Load one map into `material[slot]`. Textures are shared: every material that
-* samples the same source at the same tiling reuses one texture object. `.exr`
-* maps go through EXRLoader, imported on demand, and are not shared because
-* they resolve asynchronously.
-*/
-const loadMap = (material, slot, src, repeat, srgb) => {
-	if (src.toLowerCase().endsWith(".exr")) {
-		import("three/examples/jsm/loaders/EXRLoader.js").then(({ EXRLoader }) => {
-			new EXRLoader().load(src, (texture) => {
-				configureTexture(texture, repeat, srgb);
-				texture.needsUpdate = true;
-				material[slot] = texture;
-				material.needsUpdate = true;
-			});
-		});
-		return;
-	}
-	material[slot] = cache.acquire(src, repeat, srgb);
-};
-/**
-* Apply a `SurfaceTexture` to a standard material. Returns whether a second UV
-* set (`uv1`) is needed — three samples `aoMap` from it, so the geometry must
-* provide one.
-*/
-const applyTexture = (material, texture) => {
-	const repeat = texture.repeat ?? [1, 1];
-	loadMap(material, "map", texture.src, repeat, true);
-	if (texture.normal) {
-		loadMap(material, "normalMap", texture.normal, repeat, false);
-		const scale = texture.normalScale ?? 1;
-		material.normalScale = new Vector2(scale, scale);
-	}
-	if (texture.roughness) loadMap(material, "roughnessMap", texture.roughness, repeat, false);
-	if (texture.ao) loadMap(material, "aoMap", texture.ao, repeat, false);
-	material.needsUpdate = true;
-	return texture.ao !== void 0;
-};
-/**
-* Release one reference to a texture assigned by `applyTexture`. Shared
-* textures stay alive while another material still samples them.
-*/
-const releaseTexture = (texture) => {
-	cache.release(texture);
-};
-//#endregion
 //#region src/SceneManager.ts
 const TEXTURE_SLOTS = [
 	"map",
@@ -655,12 +772,24 @@ var SceneManager = class {
 	root;
 	plugins;
 	capabilities;
+	view;
 	/** Mounted plugin elements, per kind, keyed by element id ("" for singletons). */
 	pluginElements = /* @__PURE__ */ new Map();
-	constructor(root, plugins = [], capabilities = new CapabilityRegistry()) {
+	constructor(root, plugins = [], capabilities = new CapabilityRegistry(), view = {
+		camera: new PerspectiveCamera(),
+		renderer: {}
+	}) {
 		this.root = root;
 		this.plugins = plugins;
 		this.capabilities = capabilities;
+		this.view = view;
+	}
+	/** The build context handed to every plugin. */
+	context() {
+		return {
+			capabilities: this.capabilities,
+			...this.view
+		};
 	}
 	reconcile(scene) {
 		const eye = scene.camera.start.position[1];
@@ -693,7 +822,7 @@ var SceneManager = class {
 				const existing = mounted.get(key);
 				if (existing?.hash === hash) continue;
 				if (existing) this.removePluginElement(mounted, key, existing);
-				const built = plugin.build(value, { capabilities: this.capabilities });
+				const built = plugin.build(value, this.context());
 				if (built.object) this.root.add(built.object);
 				mounted.set(key, {
 					...built,
@@ -701,7 +830,7 @@ var SceneManager = class {
 				});
 			}
 			for (const [key, entry] of mounted) if (!seen.has(key)) this.removePluginElement(mounted, key, entry);
-			plugin.provide?.(items.map(([, value]) => value), { capabilities: this.capabilities });
+			plugin.provide?.(items.map(([, value]) => value), this.context());
 		}
 	}
 	removePluginElement(mounted, key, entry) {
@@ -792,7 +921,20 @@ function createGallery(scene, options) {
 	const systemPlugins = allPlugins.filter(isSystemPlugin);
 	const elementPlugins = allPlugins.filter((p) => !isSystemPlugin(p));
 	const capabilities = new CapabilityRegistry();
-	const manager = new SceneManager(threeScene, elementPlugins, capabilities);
+	if (options.ktx2Path) configureKtx2(renderer, options.ktx2Path);
+	const assets = /* @__PURE__ */ new Set();
+	for (const plugin of elementPlugins) {
+		const { kind, cardinality } = plugin.data;
+		const raw = scene[kind];
+		const values = cardinality === "many" ? Array.isArray(raw) ? raw : [] : raw !== void 0 ? [raw] : [];
+		for (const value of values) for (const url of plugin.data.assets?.(value) ?? []) assets.add(url);
+	}
+	if (scene.environment?.src) assets.add(scene.environment.src);
+	startLoading(assets);
+	const manager = new SceneManager(threeScene, elementPlugins, capabilities, {
+		camera,
+		renderer
+	});
 	manager.reconcile(scene);
 	const input = new InputBus();
 	const controlSettings = new ControlSettings(loadControlFlags() ?? (options.cardboard ? MODE_PRESETS.cardboard : {}));
@@ -1011,6 +1153,10 @@ function createGallery(scene, options) {
 				renderer
 			}
 		},
+		loading: {
+			get: loadingState,
+			subscribe: onLoading
+		},
 		setScene(next) {
 			manager.reconcile(next);
 			interaction.setRadii(radiiOf(next));
@@ -1092,6 +1238,6 @@ function createGallery(scene, options) {
 	};
 }
 //#endregion
-export { COLLIDERS, CapabilityRegistry, ControlSettings, DEFAULT_CONTROL_FLAGS, EDGES, EYE_HEIGHT, InputBus, InteractionController, MODE_PRESETS, ROAM_CONTROL, SceneManager, TERRAIN, applyMode, applyTexture, createGallery, isSystemPlugin, modeOf };
+export { COLLIDERS, CapabilityRegistry, ControlSettings, DEFAULT_CONTROL_FLAGS, EDGES, EYE_HEIGHT, InputBus, InteractionController, MODE_PRESETS, ROAM_CONTROL, SceneManager, TERRAIN, applyMode, applyTexture, createGallery, getKtx2Loader, isSystemPlugin, modeOf, trackAsset };
 
 //# sourceMappingURL=index.mjs.map