Node: Add `.customCacheKey()` (#30062)

* add custom-cachekey

* docs

* doc

src/nodes/core/Node.js

@@ -1,5 +1,5 @@
 import { NodeUpdateType } from './constants.js';
-import { getNodeChildren, getCacheKey } from './NodeUtils.js';
+import { getNodeChildren, getCacheKey, hash } from './NodeUtils.js';
 
 import { EventDispatcher } from '../../core/EventDispatcher.js';
 import { MathUtils } from '../../math/MathUtils.js';
@@ -320,7 +320,7 @@ class Node extends EventDispatcher {
 
 		if ( force === true || this._cacheKey === null ) {
 
-			this._cacheKey = getCacheKey( this, force );
+			this._cacheKey = hash( getCacheKey( this, force ), this.customCacheKey() );
 			this._cacheKeyVersion = this.version;
 
 		}
@@ -329,6 +329,18 @@ class Node extends EventDispatcher {
 
 	}
 
+	/**
+	 * Generate a custom cache key for this node.
+	 *
+	 * @return {Number} The cache key of the node.
+	 * @default 0
+	 */
+	customCacheKey() {
+
+		return 0;
+
+	}
+
 	/**
 	 * Returns the references to this node which is by default `this`.
 	 *

src/nodes/display/ToneMappingNode.js

@@ -55,14 +55,14 @@ class ToneMappingNode extends TempNode {
 	}
 
 	/**
-	 * Overwrites the default `getCacheKey()` implementation by including the tone
+	 * Overwrites the default `customCacheKey()` implementation by including the tone
 	 * mapping type into the cache key.
 	 *
 	 * @return {Number} The hash.
 	 */
-	getCacheKey() {
+	customCacheKey() {
 
-		return hash( super.getCacheKey(), this.toneMapping );
+		return hash( this.toneMapping );
 
 	}
 

src/nodes/lighting/AnalyticLightNode.js

@@ -35,9 +35,15 @@ class AnalyticLightNode extends LightingNode {
 
 	}
 
-	getCacheKey() {
-
-		return hash( super.getCacheKey(), this.light.id, this.light.castShadow ? 1 : 0 );
+	/**
+	 * Overwrites the default `customCacheKey()` implementation by including the
+	 * light.id and light.castShadow into the cache key.
+	 *
+	 * @return {Number} The hash.
+	 */
+	customCacheKey() {
+
+		return hash( this.light.id, this.light.castShadow ? 1 : 0 );
 
 	}
 

src/nodes/lighting/LightsNode.js

@@ -52,26 +52,23 @@ class LightsNode extends Node {
 
 	}
 
-	getCacheKey( force ) {
+	/**
+	 * Overwrites the default `customCacheKey()` implementation by including the
+	 * light IDs into the cache key.
+	 *
+	 * @return {Number} The hash.
+	 */
+	customCacheKey() {
 
-		force = force || this.version !== this._cacheKeyVersion;
+		const lightIDs = [];
 
-		if ( force === true || this._cacheKey === null ) {
+		for ( let i = 0; i < lights.length; i ++ ) {
 
-			const lightIDs = [];
-
-			for ( let i = 0; i < this._lights.length; i ++ ) {
-
-				lightIDs.push( this._lights[ i ].id );
-
-			}
-
-			this._cacheKey = hashArray( lightIDs );
-			this._cacheKeyVersion = this.version;
+			lightIDs.push( lights[ i ].id );
 
 		}
 
-		return this._cacheKey;
+		return hashArray( lightIDs );
 
 	}