@gnsx/three 0.185.14 → 0.185.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gnsx/three",
-  "version": "0.185.14",
+  "version": "0.185.16",
   "description": "JavaScript 3D library",
   "type": "module",
   "main": "./build/three.cjs",

package/src/Three.Core.js

@@ -102,6 +102,20 @@ export { InstancedBufferAttribute } from './core/InstancedBufferAttribute.js';
 export { GLBufferAttribute } from './core/GLBufferAttribute.js';
 export * from './core/BufferAttribute.js';
 export { Object3D } from './core/Object3D.js';
+// WITH_GENESYS
+export { NodePath } from './core/NodePath.js';
+export {
+	isValidNodeId,
+	nodeIdToString,
+	nodeIdFromString,
+	configureNodeIdSeed,
+	generateNodeId,
+	allocateNodeId,
+	nodeIdFromKey,
+	collectSiblingNodeIds,
+	ensureUniqueNodeIdAmongParentChildren
+} from './core/nodeId.js';
+// !WITH_GENESYS
 export { Raycaster } from './core/Raycaster.js';
 export { Layers } from './core/Layers.js';
 export { EventDispatcher } from './core/EventDispatcher.js';
@@ -115,6 +129,9 @@ export { BezierInterpolant } from './math/interpolants/BezierInterpolant.js';
 export { Interpolant } from './math/Interpolant.js';
 export { Triangle } from './math/Triangle.js';
 export { MathUtils } from './math/MathUtils.js';
+// WITH_GENESYS
+export { hashStringToUint32, xorshift32, randomSeedUint32, XorShift32 } from './math/XorShift32.js';
+// !WITH_GENESYS
 export { Spherical } from './math/Spherical.js';
 export { Cylindrical } from './math/Cylindrical.js';
 export { Plane } from './math/Plane.js';

package/src/core/NodePath.js

@@ -0,0 +1,208 @@
+// WITH_GENESYS
+/**
+ * Path of sibling-local nodeIds identifying a node in the scene tree.
+ * String form: `"a1b2/c3d4"` (4-hex segments separated by `/`).
+ */
+
+import { isValidNodeId, nodeIdFromString, nodeIdToString } from './nodeId.js';
+
+class NodePath {
+
+	/**
+	 * @param {readonly number[]} [ids]
+	 */
+	constructor( ids = [] ) {
+
+		const normalized = [];
+		for ( const id of ids ) {
+
+			if ( ! isValidNodeId( id ) ) {
+
+				throw new Error( `[NodePath] Invalid NodeId segment: ${ String( id ) }` );
+
+			}
+
+			normalized.push( id & 0xffff );
+
+		}
+
+		this.ids = normalized;
+
+	}
+
+	/**
+	 * @param {...number} ids
+	 * @return {NodePath}
+	 */
+	static fromIds( ...ids ) {
+
+		return new NodePath( ids );
+
+	}
+
+	/**
+	 * Parses `"a1b2/c3d4"`. Empty / whitespace-only string yields {@link NodePath.empty}.
+	 * @param {string} path
+	 * @return {NodePath}
+	 */
+	static fromString( path ) {
+
+		const trimmed = path.trim();
+		if ( trimmed.length === 0 ) {
+
+			return NodePath.empty;
+
+		}
+
+		const parts = trimmed.split( '/' );
+		const ids = [];
+		for ( const part of parts ) {
+
+			if ( part.length === 0 ) {
+
+				throw new Error( `[NodePath] Empty segment in path "${ path }"` );
+
+			}
+
+			const id = nodeIdFromString( part );
+			if ( id === null ) {
+
+				throw new Error( `[NodePath] Invalid segment "${ part }" in path "${ path }"` );
+
+			}
+
+			ids.push( id );
+
+		}
+
+		return new NodePath( ids );
+
+	}
+
+	/**
+	 * @param {NodePath|string} path
+	 * @return {NodePath}
+	 */
+	static coerce( path ) {
+
+		return typeof path === 'string' ? NodePath.fromString( path ) : path;
+
+	}
+
+	/** @return {number} */
+	get length() {
+
+		return this.ids.length;
+
+	}
+
+	/** @return {boolean} */
+	get isEmpty() {
+
+		return this.ids.length === 0;
+
+	}
+
+	/** @return {string} */
+	toString() {
+
+		return this.ids.map( nodeIdToString ).join( '/' );
+
+	}
+
+	/**
+	 * @param {NodePath} other
+	 * @return {boolean}
+	 */
+	equals( other ) {
+
+		if ( this.ids.length !== other.ids.length ) {
+
+			return false;
+
+		}
+
+		for ( let i = 0; i < this.ids.length; i ++ ) {
+
+			if ( this.ids[ i ] !== other.ids[ i ] ) {
+
+				return false;
+
+			}
+
+		}
+
+		return true;
+
+	}
+
+	/**
+	 * @param {NodePath} prefix
+	 * @return {boolean}
+	 */
+	startsWith( prefix ) {
+
+		if ( prefix.ids.length > this.ids.length ) {
+
+			return false;
+
+		}
+
+		for ( let i = 0; i < prefix.ids.length; i ++ ) {
+
+			if ( this.ids[ i ] !== prefix.ids[ i ] ) {
+
+				return false;
+
+			}
+
+		}
+
+		return true;
+
+	}
+
+	/**
+	 * @param {number} start
+	 * @param {number} [end]
+	 * @return {NodePath}
+	 */
+	slice( start, end ) {
+
+		return new NodePath( this.ids.slice( start, end ) );
+
+	}
+
+	/**
+	 * @param {NodePath} relative
+	 * @return {NodePath}
+	 */
+	concat( relative ) {
+
+		return new NodePath( [ ...this.ids, ...relative.ids ] );
+
+	}
+
+	/**
+	 * If this path starts with `ancestor`, returns the remainder; otherwise `null`.
+	 * @param {NodePath} ancestor
+	 * @return {?NodePath}
+	 */
+	relativeFrom( ancestor ) {
+
+		if ( ! this.startsWith( ancestor ) ) {
+
+			return null;
+
+		}
+
+		return this.slice( ancestor.length );
+
+	}
+
+}
+
+NodePath.empty = new NodePath( [] );
+
+export { NodePath };
+// !WITH_GENESYS

package/src/core/Object3D.js

@@ -7,6 +7,15 @@ import { Layers } from './Layers.js';
 import { Matrix3 } from '../math/Matrix3.js';
 import { generateUUID } from '../math/MathUtils.js';
 import { error } from '../utils.js';
+// WITH_GENESYS
+import {
+	allocateNodeId,
+	ensureUniqueNodeIdAmongParentChildren,
+	generateNodeId,
+	isValidNodeId
+} from './nodeId.js';
+import { NodePath } from './NodePath.js';
+// !WITH_GENESYS
 
 let _object3DId = 0;
 
@@ -96,6 +105,16 @@ class Object3D extends EventDispatcher {
 		 */
 		this.uuid = generateUUID();
 
+		// WITH_GENESYS
+		/**
+		 * Sibling-local 16-bit identity for scene-graph addressing ({@link NodePath}).
+		 * `0` is valid. Reminted on parent attach when colliding with a sibling.
+		 *
+		 * @type {number}
+		 */
+		this.nodeId = generateNodeId();
+		// !WITH_GENESYS
+
 		/**
 		 * The name of the 3D object.
 		 *
@@ -778,6 +797,9 @@ class Object3D extends EventDispatcher {
 		if ( object && object.isObject3D ) {
 
 			object.removeFromParent();
+			// WITH_GENESYS
+			ensureUniqueNodeIdAmongParentChildren( object, this );
+			// !WITH_GENESYS
 			object.parent = this;
 			this.children.push( object );
 
@@ -903,6 +925,9 @@ class Object3D extends EventDispatcher {
 		object.applyMatrix4( _m1 );
 
 		object.removeFromParent();
+		// WITH_GENESYS
+		ensureUniqueNodeIdAmongParentChildren( object, this );
+		// !WITH_GENESYS
 		object.parent = this;
 		this.children.push( object );
 
@@ -918,6 +943,166 @@ class Object3D extends EventDispatcher {
 
 	}
 
+	// WITH_GENESYS
+	/**
+	 * Assigns a {@link nodeId} when unset or outside the uint16 range.
+	 * @return {number}
+	 */
+	ensureNodeId() {
+
+		if ( ! isValidNodeId( this.nodeId ) ) {
+
+			this.nodeId = generateNodeId();
+
+		}
+
+		return this.nodeId;
+
+	}
+
+	/**
+	 * Replaces {@link nodeId} with a newly generated value (e.g. prefab instance roots).
+	 * @param {Iterable<number>} [existingSiblingIds]
+	 * @return {number}
+	 */
+	remintNodeId( existingSiblingIds ) {
+
+		this.nodeId = existingSiblingIds !== undefined
+			? allocateNodeId( existingSiblingIds )
+			: generateNodeId();
+		return this.nodeId;
+
+	}
+
+	/**
+	 * Direct child with the given {@link nodeId}, or `null`.
+	 * @param {number} id
+	 * @return {?Object3D}
+	 */
+	findChildByNodeId( id ) {
+
+		for ( let i = 0; i < this.children.length; i ++ ) {
+
+			const child = this.children[ i ];
+			if ( child.nodeId === id ) {
+
+				return child;
+
+			}
+
+		}
+
+		return null;
+
+	}
+
+	/**
+	 * Resolves a path relative to this node. An empty path returns `this`.
+	 * @param {NodePath|string} path
+	 * @return {?Object3D}
+	 */
+	resolvePath( path ) {
+
+		const nodePath = NodePath.coerce( path );
+		if ( nodePath.isEmpty ) {
+
+			return this;
+
+		}
+
+		let current = this;
+		for ( let i = 0; i < nodePath.ids.length; i ++ ) {
+
+			const next = current.findChildByNodeId( nodePath.ids[ i ] );
+			if ( ! next ) {
+
+				return null;
+
+			}
+
+			current = next;
+
+		}
+
+		return current;
+
+	}
+
+	/**
+	 * Builds a {@link NodePath} for this node.
+	 * - Without `root`: absolute path from the topmost non-Scene ancestor down to this node.
+	 * - With `root`: path relative to `root` (empty when `this === root`); `null` when not under `root`.
+	 * @param {Object3D} [root]
+	 * @return {?NodePath}
+	 */
+	getNodePath( root ) {
+
+		if ( root !== undefined ) {
+
+			if ( this === root ) {
+
+				return NodePath.empty;
+
+			}
+
+			const absolute = this.getNodePath();
+			const rootAbsolute = root.getNodePath();
+			if ( ! absolute || ! rootAbsolute ) {
+
+				return null;
+
+			}
+
+			return absolute.relativeFrom( rootAbsolute );
+
+		}
+
+		const ids = [];
+		let current = this;
+		while ( current ) {
+
+			ids.push( current.ensureNodeId() );
+			const parent = current.parent;
+			// Scene / World containers are not part of authored NodePaths.
+			if ( parent === null || parent.isScene === true ) {
+
+				break;
+
+			}
+
+			current = parent;
+
+		}
+
+		ids.reverse();
+		return new NodePath( ids );
+
+	}
+
+	/**
+	 * Ensures every Object3D in this subtree has a valid {@link nodeId}, unique among its siblings.
+	 */
+	ensureNodeIdsInSubtree() {
+
+		this.ensureNodeId();
+		const taken = new Set();
+		for ( let i = 0; i < this.children.length; i ++ ) {
+
+			const child = this.children[ i ];
+			if ( ! isValidNodeId( child.nodeId ) || taken.has( child.nodeId ) ) {
+
+				child.nodeId = allocateNodeId( taken );
+
+			}
+
+			taken.add( child.nodeId );
+			child.ensureNodeIdsInSubtree();
+
+		}
+
+	}
+	// !WITH_GENESYS
+
 	/**
 	 * Searches through the 3D object and its children, starting with the 3D object
 	 * itself, and returns the first with a matching ID.
@@ -1320,6 +1505,10 @@ class Object3D extends EventDispatcher {
 		object.uuid = this.uuid;
 		object.type = this.type;
 
+		// WITH_GENESYS
+		object.nodeId = this.nodeId;
+		// !WITH_GENESYS
+
 		if ( this.name !== '' ) object.name = this.name;
 		if ( this.castShadow === true ) object.castShadow = true;
 		if ( this.receiveShadow === true ) object.receiveShadow = true;
@@ -1630,6 +1819,8 @@ class Object3D extends EventDispatcher {
 		this.visible = source.visible;
 		// WITH_GENESYS
 		this.selfHidden = source.selfHidden;
+		// Keep nodeId; reminted on attach if it collides with a sibling.
+		this.nodeId = source.nodeId;
 		// !WITH_GENESYS
 
 		this.castShadow = source.castShadow;

package/src/core/nodeId.js

@@ -0,0 +1,168 @@
+// WITH_GENESYS
+/**
+ * Sibling-local 16-bit node identities.
+ *
+ * `null` / `undefined` mean unset. `0` is a valid NodeId.
+ */
+
+import { hashStringToUint32, randomSeedUint32, XorShift32 } from '../math/XorShift32.js';
+
+/**
+ * True when `id` is a finite integer in the uint16 range (including 0).
+ * @param {unknown} id
+ * @return {boolean}
+ */
+function isValidNodeId( id ) {
+
+	return typeof id === 'number' && Number.isInteger( id ) && id >= 0 && id <= 0xffff;
+
+}
+
+/**
+ * Canonical display form: 4 lowercase hex characters.
+ * @param {number} id
+ * @return {string}
+ */
+function nodeIdToString( id ) {
+
+	return ( id & 0xffff ).toString( 16 ).padStart( 4, '0' );
+
+}
+
+/**
+ * Parses a hex node-id segment (1–4 hex digits).
+ * @param {string} value
+ * @return {?number}
+ */
+function nodeIdFromString( value ) {
+
+	const trimmed = value.trim();
+	if ( ! /^[0-9a-fA-F]{1,4}$/.test( trimmed ) ) {
+
+		return null;
+
+	}
+
+	return Number.parseInt( trimmed, 16 ) & 0xffff;
+
+}
+
+const defaultNodeIdRng = new XorShift32();
+
+/**
+ * Seeds the process-wide NodeId RNG for deterministic construction.
+ * Pass `undefined` / omit to restore a non-deterministic stream.
+ * @param {string} [seed]
+ */
+function configureNodeIdSeed( seed ) {
+
+	if ( seed == null ) {
+
+		defaultNodeIdRng.setState( randomSeedUint32() );
+		return;
+
+	}
+
+	defaultNodeIdRng.setState( hashStringToUint32( seed ) );
+
+}
+
+/**
+ * Generates a random NodeId from the process-wide default RNG.
+ * @param {XorShift32} [rng]
+ * @return {number}
+ */
+function generateNodeId( rng = defaultNodeIdRng ) {
+
+	return rng.nextUint16();
+
+}
+
+/**
+ * Allocates a NodeId not present in `existing`.
+ * @param {Iterable<number>|ReadonlySet<number>} existing
+ * @param {XorShift32} [rng]
+ * @return {number}
+ */
+function allocateNodeId( existing, rng = defaultNodeIdRng ) {
+
+	const taken = existing instanceof Set ? existing : new Set( existing );
+	if ( taken.size >= 0x10000 ) {
+
+		throw new Error( '[nodeId] Cannot allocate NodeId: all 65536 sibling ids are in use' );
+
+	}
+
+	let id = rng.nextUint16();
+	while ( taken.has( id ) ) {
+
+		id = rng.nextUint16();
+
+	}
+
+	return id;
+
+}
+
+/**
+ * Deterministic NodeId from a stable key (first-try candidate for remints).
+ * @param {string} key
+ * @return {number}
+ */
+function nodeIdFromKey( key ) {
+
+	return new XorShift32( key ).nextUint16();
+
+}
+
+/**
+ * Collects nodeId values from a sibling set.
+ * @param {Iterable<{nodeId?: ?number}>} nodes
+ * @param {Object} [except]
+ * @return {Set<number>}
+ */
+function collectSiblingNodeIds( nodes, except ) {
+
+	const taken = new Set();
+	for ( const node of nodes ) {
+
+		if ( node !== except && isValidNodeId( node.nodeId ) ) {
+
+			taken.add( node.nodeId );
+
+		}
+
+	}
+
+	return taken;
+
+}
+
+/**
+ * Ensures `object.nodeId` is unique among `parent.children`.
+ * @param {import('./Object3D.js').Object3D} object
+ * @param {import('./Object3D.js').Object3D} parent
+ */
+function ensureUniqueNodeIdAmongParentChildren( object, parent ) {
+
+	const taken = collectSiblingNodeIds( parent.children, object );
+	if ( ! isValidNodeId( object.nodeId ) || taken.has( object.nodeId ) ) {
+
+		object.nodeId = allocateNodeId( taken );
+
+	}
+
+}
+
+export {
+	isValidNodeId,
+	nodeIdToString,
+	nodeIdFromString,
+	configureNodeIdSeed,
+	generateNodeId,
+	allocateNodeId,
+	nodeIdFromKey,
+	collectSiblingNodeIds,
+	ensureUniqueNodeIdAmongParentChildren
+};
+// !WITH_GENESYS

package/src/loaders/ObjectLoader.js

@@ -1128,6 +1128,10 @@ class ObjectLoader extends Loader {
 
 		object.uuid = data.uuid;
 
+		// WITH_GENESYS
+		if ( data.nodeId !== undefined ) object.nodeId = data.nodeId;
+		// !WITH_GENESYS
+
 		if ( data.name !== undefined ) object.name = data.name;
 
 		if ( data.matrix !== undefined ) {