@gnsx/three 0.185.14 → 0.185.16

package/build/three.cjs

@@ -11723,6 +11723,488 @@ class Layers {
 
 }
 
+// WITH_GENESYS
+/**
+ * Shared deterministic PRNG helpers (FNV-1a seed hash + xorshift32).
+ * Used by sibling-local nodeId allocation and other deterministic streams.
+ */
+
+/**
+ * Lightweight FNV-1a hash for converting strings into a deterministic 32-bit seed.
+ * @param {string} input
+ * @return {number}
+ */
+function hashStringToUint32( input ) {
+
+	let hash = 0x811c9dc5;
+
+	for ( let i = 0; i < input.length; i ++ ) {
+
+		hash ^= input.charCodeAt( i );
+		hash = Math.imul( hash, 0x01000193 );
+
+	}
+
+	return ( hash >>> 0 ) || 0x9e3779b9;
+
+}
+
+/**
+ * Xorshift32 step; deterministic and fast for ID generation. Never returns 0.
+ * @param {number} state
+ * @return {number}
+ */
+function xorshift32( state ) {
+
+	let next = state | 0;
+	next ^= next << 13;
+	next ^= next >>> 17;
+	next ^= next << 5;
+	return ( next >>> 0 ) || 0x9e3779b9;
+
+}
+
+/**
+ * Random non-zero uint32 seed for non-deterministic streams.
+ * @return {number}
+ */
+function randomSeedUint32() {
+
+	return ( ( Math.random() * 0x100000000 ) >>> 0 ) || 0x9e3779b9;
+
+}
+
+/**
+ * Deterministic xorshift32 stream. Internal state is never 0.
+ */
+class XorShift32 {
+
+	/**
+	 * @param {number|string} [seed]
+	 */
+	constructor( seed = randomSeedUint32() ) {
+
+		this._state = typeof seed === 'string'
+			? hashStringToUint32( seed )
+			: ( ( seed >>> 0 ) || 0x9e3779b9 );
+
+	}
+
+	/**
+	 * Advance and return the next non-zero uint32.
+	 * @return {number}
+	 */
+	nextUint32() {
+
+		this._state = xorshift32( this._state );
+		return this._state;
+
+	}
+
+	/**
+	 * Advance and return the low 16 bits (0 is allowed).
+	 * @return {number}
+	 */
+	nextUint16() {
+
+		return this.nextUint32() & 0xffff;
+
+	}
+
+	/**
+	 * @return {number}
+	 */
+	getState() {
+
+		return this._state >>> 0;
+
+	}
+
+	/**
+	 * @param {number} state
+	 */
+	setState( state ) {
+
+		this._state = ( state >>> 0 ) || 0x9e3779b9;
+
+	}
+
+	/**
+	 * @return {XorShift32}
+	 */
+	clone() {
+
+		return new XorShift32( this._state );
+
+	}
+
+}
+// !WITH_GENESYS
+
+// WITH_GENESYS
+/**
+ * Sibling-local 16-bit node identities.
+ *
+ * `null` / `undefined` mean unset. `0` is a valid NodeId.
+ */
+
+
+/**
+ * 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 );
+
+	}
+
+}
+// !WITH_GENESYS
+
+// WITH_GENESYS
+/**
+ * Path of sibling-local nodeIds identifying a node in the scene tree.
+ * String form: `"a1b2/c3d4"` (4-hex segments separated by `/`).
+ */
+
+
+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( [] );
+// !WITH_GENESYS
+
+// !WITH_GENESYS
+
 let _object3DId = 0;
 
 const _v1$6 = /*@__PURE__*/ new Vector3();
@@ -11811,6 +12293,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.
 		 *
@@ -12493,6 +12985,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 );
 
@@ -12618,6 +13113,9 @@ class Object3D extends EventDispatcher {
 		object.applyMatrix4( _m1$3 );
 
 		object.removeFromParent();
+		// WITH_GENESYS
+		ensureUniqueNodeIdAmongParentChildren( object, this );
+		// !WITH_GENESYS
 		object.parent = this;
 		this.children.push( object );
 
@@ -12633,6 +13131,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.
@@ -13035,6 +13693,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;
@@ -13345,6 +14007,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;
@@ -49581,6 +50245,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 ) {
@@ -81720,6 +82388,7 @@ exports.NoBlending = NoBlending;
 exports.NoColorSpace = NoColorSpace;
 exports.NoNormalPacking = NoNormalPacking;
 exports.NoToneMapping = NoToneMapping;
+exports.NodePath = NodePath;
 exports.NormalAnimationBlendMode = NormalAnimationBlendMode;
 exports.NormalBlending = NormalBlending;
 exports.NormalGAPacking = NormalGAPacking;
@@ -81910,16 +82579,29 @@ exports.WebGPUCoordinateSystem = WebGPUCoordinateSystem;
 exports.WebXRController = WebXRController;
 exports.WireframeGeometry = WireframeGeometry;
 exports.WrapAroundEnding = WrapAroundEnding;
+exports.XorShift32 = XorShift32;
 exports.ZeroCurvatureEnding = ZeroCurvatureEnding;
 exports.ZeroFactor = ZeroFactor;
 exports.ZeroSlopeEnding = ZeroSlopeEnding;
 exports.ZeroStencilOp = ZeroStencilOp;
+exports.allocateNodeId = allocateNodeId;
+exports.collectSiblingNodeIds = collectSiblingNodeIds;
+exports.configureNodeIdSeed = configureNodeIdSeed;
 exports.createCanvasElement = createCanvasElement;
+exports.ensureUniqueNodeIdAmongParentChildren = ensureUniqueNodeIdAmongParentChildren;
 exports.error = error;
+exports.generateNodeId = generateNodeId;
 exports.getConsoleFunction = getConsoleFunction;
+exports.hashStringToUint32 = hashStringToUint32;
+exports.isValidNodeId = isValidNodeId;
 exports.log = log;
+exports.nodeIdFromKey = nodeIdFromKey;
+exports.nodeIdFromString = nodeIdFromString;
+exports.nodeIdToString = nodeIdToString;
 exports.profile = profile;
 exports.profileClass = profileClass;
+exports.randomSeedUint32 = randomSeedUint32;
 exports.setConsoleFunction = setConsoleFunction;
 exports.warn = warn;
 exports.warnOnce = warnOnce;
+exports.xorshift32 = xorshift32;