fix: deprecate CoreNode.preventCleanup and re-introduce preload option (#486)

The `textureOptions.preload` was removed during the Texture Throttling
refactor, reintroduced it even though its loading will be throttled.

While looking at the properties, decided to move `preventCleanup` to
`textureOptions` instead of as a property on the `CoreNode`. Technically
this controls the behaviour of the texture, not the core node. Hence it
better belongs on `textureOptions`.

Will throw a deprecation warning in dev mode for a couple of releases
and then we'll drop it.

Author: wouterlucas

src/core/CoreNode.ts

@@ -20,6 +20,7 @@
 import {
   assertTruthy,
   getNewId,
+  isProductionEnvironment,
   mergeColorAlphaPremultiplied,
 } from '../utils.js';
 import type { TextureOptions } from './CoreTextureManager.js';
@@ -413,7 +414,11 @@ export interface CoreNodeProps {
   texture: Texture | null;
 
   /**
-   * Whether to prevent the node from being cleaned up
+   * [Deprecated]: Prevents the texture from being cleaned up when the Node is removed
+   *
+   * @remarks
+   * Please use the `preventCleanup` property on {@link TextureOptions} instead.
+   *
    * @default false
    */
   preventCleanup: boolean;
@@ -768,6 +773,12 @@ export class CoreNode extends EventEmitter {
         UpdateType.RenderState,
     );
 
+    if (isProductionEnvironment() === false && props.preventCleanup === true) {
+      console.warn(
+        'CoreNode.preventCleanup: Is deprecated and will be removed in upcoming release, please use textureOptions.preventCleanup instead',
+      );
+    }
+
     // if the default texture isn't loaded yet, wait for it to load
     // this only happens when the node is created before the stage is ready
     if (
@@ -790,7 +801,12 @@ export class CoreNode extends EventEmitter {
     // We do this in a microtask to allow listeners to be attached in the same
     // synchronous task after calling loadTexture()
     queueMicrotask(() => {
-      texture.preventCleanup = this.props.preventCleanup;
+      if (this.textureOptions.preload === true) {
+        this.stage.txManager.loadTexture(texture);
+      }
+
+      texture.preventCleanup =
+        this.props.textureOptions?.preventCleanup ?? false;
       texture.on('loaded', this.onTextureLoaded);
       texture.on('failed', this.onTextureFailed);
       texture.on('freed', this.onTextureFreed);
@@ -2027,11 +2043,17 @@ export class CoreNode extends EventEmitter {
   }
 
   get preventCleanup(): boolean {
-    return this.props.preventCleanup;
+    return this.props.textureOptions.preventCleanup || false;
   }
 
   set preventCleanup(value: boolean) {
-    this.props.preventCleanup = value;
+    if (isProductionEnvironment() === false) {
+      console.warn(
+        'CoreNode.preventCleanup: Is deprecated and will be removed in upcoming release, please use textureOptions.preventCleanup instead',
+      );
+    }
+
+    this.props.textureOptions.preventCleanup = value;
   }
 
   get rtt(): boolean {

src/core/CoreTextureManager.ts

@@ -107,6 +107,32 @@ export type ResizeModeOptions =
  * multiple Nodes each using a different set of options.
  */
 export interface TextureOptions {
+  /**
+   * Preload the texture immediately even if it's not being rendered to the
+   * screen.
+   *
+   * @remarks
+   * This allows the texture to be used immediately without any delay when it
+   * is first needed for rendering. Otherwise the loading process will start
+   * when the texture is first rendered, which may cause a delay in that texture
+   * being shown properly.
+   *
+   * @defaultValue `false`
+   */
+  preload?: boolean;
+
+  /**
+   * Prevent clean up of the texture when it is no longer being used.
+   *
+   * @remarks
+   * This is useful when you want to keep the texture in memory for later use.
+   * Regardless of whether the texture is being used or not, it will not be
+   * cleaned up.
+   *
+   * @defaultValue `false`
+   */
+  preventCleanup?: boolean;
+
   /**
    * Flip the texture horizontally when rendering
    *