@scenography/engine 0.3.1 → 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier López Úbeda
+
+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/dist/index.cjs

@@ -65,6 +65,7 @@ const HIGHLIGHT_COLOR = "#ef4444";
 const HIGHLIGHT_THICKNESS = 1.5;
 const HIGHLIGHT_MARGIN = 1.5;
 const CLICK_SLOP = 4;
+const PICK_INTERVAL = 60;
 /**
 * Pointer picking for artworks: hovering a piece's click target (its label, or
 * the piece itself when it has none) draws a pulsing red frame and shows a
@@ -86,6 +87,8 @@ var InteractionController = class {
 	radii = /* @__PURE__ */ new Map();
 	hovered = null;
 	time = 0;
+	pickElapsed = 0;
+	pointerMoved = false;
 	highlight = new three.Group();
 	highlightMat = null;
 	handlers = [];
@@ -128,6 +131,7 @@ var InteractionController = class {
 		const rect = this.canvas.getBoundingClientRect();
 		this.pointer.set((e.clientX - rect.left) / rect.width * 2 - 1, -((e.clientY - rect.top) / rect.height) * 2 + 1);
 		this.over = true;
+		this.pointerMoved = true;
 	}
 	onMove(e) {
 		this.setPointer(e);
@@ -169,18 +173,38 @@ var InteractionController = class {
 		}
 		return null;
 	}
-	/** Recompute hover state and animate the highlight. Call once per frame. */
+	/**
+	* Recompute hover state and animate the highlight. Call once per frame.
+	* Hover picking is throttled: a full-scene raycast runs at most once every
+	* `PICK_INTERVAL` ms, or immediately after the pointer moves. The camera can
+	* move without the pointer, so the interval keeps hovering correct while
+	* walking.
+	*/
 	update(deltaMs) {
 		this.time += deltaMs;
-		const pick = this.over && this.canInteract() ? this.raycast() : null;
-		if ((pick?.id ?? null) !== this.hovered) {
-			this.hovered = pick?.id ?? null;
-			this.canvas.style.cursor = pick ? "pointer" : "";
-			if (pick) this.buildHighlight(pick);
-			else this.highlight.visible = false;
+		if (!this.over || !this.canInteract()) {
+			this.pickElapsed = PICK_INTERVAL;
+			this.pointerMoved = false;
+			this.applyPick(null);
+		} else {
+			this.pickElapsed += deltaMs;
+			if (this.pointerMoved) this.pickElapsed = PICK_INTERVAL;
+			this.pointerMoved = false;
+			if (this.pickElapsed >= PICK_INTERVAL) {
+				this.pickElapsed = 0;
+				this.applyPick(this.raycast());
+			}
 		}
 		if (this.highlight.visible && this.highlightMat) this.highlightMat.opacity = .45 + .45 * (.5 + .5 * Math.sin(this.time / 320));
 	}
+	/** Swap the hovered piece, touching the canvas and the highlight only on change. */
+	applyPick(pick) {
+		if ((pick?.id ?? null) === this.hovered) return;
+		this.hovered = pick?.id ?? null;
+		this.canvas.style.cursor = pick ? "pointer" : "";
+		if (pick) this.buildHighlight(pick);
+		else this.highlight.visible = false;
+	}
 	clearHighlight() {
 		for (const child of [...this.highlight.children]) {
 			this.highlight.remove(child);
@@ -479,8 +503,126 @@ 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 = three.RepeatWrapping;
+	texture.wrapT = three.RepeatWrapping;
+	texture.repeat.set(repeat[0], repeat[1]);
+	texture.colorSpace = srgb ? three.SRGBColorSpace : three.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 three.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 three.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",
+	"normalMap",
+	"roughnessMap",
+	"aoMap",
+	"metalnessMap"
+];
 const disposeObject = (object) => {
+	const materials = /* @__PURE__ */ new Set();
 	object.traverse((child) => {
 		const video = child.userData?.video;
 		if (video) {
@@ -490,21 +632,18 @@ const disposeObject = (object) => {
 		}
 		const mesh = child;
 		mesh.geometry?.dispose?.();
-		const dispose = (m) => {
-			const material = m;
-			for (const slot of [
-				"map",
-				"normalMap",
-				"roughnessMap",
-				"aoMap",
-				"metalnessMap"
-			]) (material?.[slot])?.dispose?.();
-			material?.dispose?.();
-		};
 		const material = mesh.material;
-		if (Array.isArray(material)) material.forEach(dispose);
-		else dispose(material);
+		if (Array.isArray(material)) for (const entry of material) materials.add(entry);
+		else if (material) materials.add(material);
 	});
+	for (const entry of materials) {
+		const material = entry;
+		for (const slot of TEXTURE_SLOTS) {
+			const texture = material[slot];
+			if (texture) releaseTexture(texture);
+		}
+		material.dispose?.();
+	}
 };
 /**
 * Owns the live three.js scene graph and keeps it in sync with a `Scene`
@@ -954,50 +1093,6 @@ function createGallery(scene, options) {
 	};
 }
 //#endregion
-//#region src/builders/texture.ts
-const textureLoader = new three.TextureLoader();
-/** Configure a loaded texture: tiling + color space (sRGB only for color maps). */
-const configure = (tex, repeat, srgb) => {
-	tex.wrapS = three.RepeatWrapping;
-	tex.wrapT = three.RepeatWrapping;
-	tex.repeat.set(repeat[0], repeat[1]);
-	tex.colorSpace = srgb ? three.SRGBColorSpace : three.NoColorSpace;
-	tex.needsUpdate = true;
-};
-/**
-* Load one map and assign it to `material[slot]` once ready. `.exr` maps go
-* through EXRLoader, imported on demand so it only ships in the bundle when a
-* scene actually uses an EXR map; everything else uses the image loader.
-*/
-const loadMap = (material, slot, src, repeat, srgb) => {
-	const assign = (tex) => {
-		configure(tex, repeat, srgb);
-		material[slot] = tex;
-		material.needsUpdate = true;
-	};
-	if (src.toLowerCase().endsWith(".exr")) import("three/examples/jsm/loaders/EXRLoader.js").then(({ EXRLoader }) => {
-		new EXRLoader().load(src, assign);
-	});
-	else textureLoader.load(src, assign);
-};
-/**
-* 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 s = texture.normalScale ?? 1;
-		material.normalScale = new three.Vector2(s, s);
-	}
-	if (texture.roughness) loadMap(material, "roughnessMap", texture.roughness, repeat, false);
-	if (texture.ao) loadMap(material, "aoMap", texture.ao, repeat, false);
-	return texture.ao !== void 0;
-};
-//#endregion
 exports.COLLIDERS = COLLIDERS;
 exports.CapabilityRegistry = CapabilityRegistry;
 exports.ControlSettings = ControlSettings;