@lightningjs/renderer 3.0.0-beta2 → 3.0.0-beta21

package/src/main-api/Renderer.ts

@@ -19,51 +19,173 @@
 
 import type { ExtractProps, TextureMap } from '../core/CoreTextureManager.js';
 import { EventEmitter } from '../common/EventEmitter.js';
-import { assertTruthy, isProductionEnvironment } from '../utils.js';
-import { Stage } from '../core/Stage.js';
+import { isProductionEnvironment } from '../utils.js';
+import { Stage, type StageOptions } from '../core/Stage.js';
 import { CoreNode, type CoreNodeProps } from '../core/CoreNode.js';
 import { type CoreTextNodeProps } from '../core/CoreTextNode.js';
 import type { INode, INodeProps, ITextNode, ITextNodeProps } from './INode.js';
 import type { TextureMemoryManagerSettings } from '../core/TextureMemoryManager.js';
-import type { CanvasTextRenderer } from '../core/text-rendering/renderers/CanvasTextRenderer.js';
-import type { SdfTextRenderer } from '../core/text-rendering/renderers/SdfTextRenderer/SdfTextRenderer.js';
-import type { WebGlRenderer } from '../core/renderers/webgl/WebGlRenderer.js';
+import type { TextRenderer } from '../core/text-rendering/TextRenderer.js';
 import type { CanvasRenderer } from '../core/renderers/canvas/CanvasRenderer.js';
-import type { Inspector } from './Inspector.js';
+import type { WebGlRenderer } from '../core/renderers/webgl/WebGlRenderer.js';
+import type { Inspector, InspectorOptions } from './Inspector.js';
 import type { CoreShaderNode } from '../core/renderers/CoreShaderNode.js';
 import type {
   ExtractShaderProps,
   OptionalShaderProps,
   ShaderMap,
 } from '../core/CoreShaderManager.js';
+import { WebPlatform } from '../core/platforms/web/WebPlatform.js';
+import { Platform } from '../core/platforms/Platform.js';
 
 /**
- * Configuration settings for {@link RendererMain}
+ * FPS Update Event Data
+ *
+ * @category Events
+ * @example
+ * ```typescript
+ * renderer.on('fpsUpdate', (data) => {
+ *   console.log(`Current FPS: ${data.fps}`);
+ *   if (data.contextSpyData) {
+ *     console.log('WebGL calls:', data.contextSpyData);
+ *   }
+ * });
+ * ```
+ */
+export interface RendererMainFpsUpdateEvent {
+  /** Current frames per second */
+  fps: number;
+  /** Context spy data (if enabled) - contains WebGL call statistics */
+  contextSpyData?: unknown;
+}
+
+/**
+ * Frame Tick Event Data
+ *
+ * @category Events
+ * @example
+ * ```typescript
+ * renderer.on('frameTick', (data) => {
+ *   console.log(`Frame time: ${data.time}ms, delta: ${data.delta}ms`);
+ * });
+ * ```
+ */
+export interface RendererMainFrameTickEvent {
+  /** Current timestamp */
+  time: number;
+  /** Time delta since last frame */
+  delta: number;
+}
+
+/**
+ * Quads Update Event Data
+ *
+ * @category Events
+ * @example
+ * ```typescript
+ * renderer.on('quadsUpdate', (data) => {
+ *   console.log(`Rendered quads: ${data.quads}`);
+ * });
+ * ```
+ */
+export interface RendererMainQuadsUpdateEvent {
+  /** Number of rendered quads */
+  quads: number;
+}
+
+/**
+ * Idle Event Data
+ *
+ * @category Events
+ * @remarks
+ * This event is emitted when the renderer has no scene updates to process.
+ * The event has no payload - use this for performance optimizations during idle periods.
+ *
+ * @example
+ * ```typescript
+ * renderer.on('idle', () => {
+ *   // Renderer is idle - perfect time for cleanup, analytics, etc.
+ *   console.log('Renderer is idle - no scene changes');
+ *
+ *   // Example: Perform background tasks
+ *   performBackgroundCleanup();
+ *   sendAnalytics();
+ * });
+ * ```
  */
-export interface RendererMainSettings {
+export interface RendererMainIdleEvent {
+  /** This event has no payload - listen without parameters */
+  readonly __eventHasNoPayload?: never;
+}
+
+/**
+ * Critical Cleanup Event Data
+ *
+ * @category Events
+ * @example
+ * ```typescript
+ * renderer.on('criticalCleanup', (data) => {
+ *   console.log(`Memory cleanup triggered!`);
+ *   console.log(`Memory used: ${data.memUsed} bytes`);
+ *   console.log(`Critical threshold: ${data.criticalThreshold} bytes`);
+ * });
+ * ```
+ */
+export interface RendererMainCriticalCleanupEvent {
+  /** Memory used before cleanup (bytes) */
+  memUsed: number;
+  /** Critical threshold (bytes) */
+  criticalThreshold: number;
+}
+
+/**
+ * Critical Cleanup Failed Event Data
+ *
+ * @category Events
+ * @example
+ * ```typescript
+ * renderer.on('criticalCleanupFailed', (data) => {
+ *   console.warn(`Memory cleanup failed!`);
+ *   console.log(`Memory still used: ${data.memUsed} bytes`);
+ *   console.log(`Critical threshold: ${data.criticalThreshold} bytes`);
+ *   // Consider reducing texture usage or forcing cleanup
+ * });
+ * ```
+ */
+export interface RendererMainCriticalCleanupFailedEvent {
+  /** Memory used after cleanup (bytes) */
+  memUsed: number;
+  /** Critical threshold (bytes) */
+  criticalThreshold: number;
+}
+
+/**
+ * Settings for the Renderer that can be updated during runtime.
+ */
+export interface RendererRuntimeSettings {
   /**
    * Authored logical pixel width of the application
    *
    * @defaultValue `1920`
    */
-  appWidth?: number;
+  appWidth: number;
 
   /**
    * Authored logical pixel height of the application
    *
    * @defaultValue `1080`
    */
-  appHeight?: number;
+  appHeight: number;
 
   /**
    * Texture Memory Manager Settings
    */
-  textureMemory?: Partial<TextureMemoryManagerSettings>;
+  textureMemory: Partial<TextureMemoryManagerSettings>;
 
   /**
    * Bounds margin to extend the boundary in which a Node is added as Quad.
    */
-  boundsMargin?: number | [number, number, number, number];
+  boundsMargin: number | [number, number, number, number];
 
   /**
    * Factor to convert app-authored logical coorindates to device logical coordinates
@@ -80,7 +202,7 @@ export interface RendererMainSettings {
    *
    * @defaultValue `1`
    */
-  deviceLogicalPixelRatio?: number;
+  deviceLogicalPixelRatio: number;
 
   /**
    * Factor to convert device logical coordinates to device physical coordinates
@@ -97,14 +219,14 @@ export interface RendererMainSettings {
    *
    * @defaultValue `window.devicePixelRatio`
    */
-  devicePhysicalPixelRatio?: number;
+  devicePhysicalPixelRatio: number;
 
   /**
    * RGBA encoded number of the background to use
    *
    * @defaultValue `0x00000000`
    */
-  clearColor?: number;
+  clearColor: number;
 
   /**
    * Interval in milliseconds to receive FPS updates
@@ -114,8 +236,71 @@ export interface RendererMainSettings {
    *
    * @defaultValue `0` (disabled)
    */
-  fpsUpdateInterval?: number;
+  fpsUpdateInterval: number;
+
+  /**
+   * Clears the render buffer on reset
+   *
+   * @remarks
+   * If false, the renderer will not clear the buffer before rendering a new frame.
+   * This is useful if you want to preserve the previous frame.
+   *
+   * @defaultValue `true`
+   */
+  enableClear: boolean;
+
+  /**
+   * DOM Inspector
+   *
+   * @remarks
+   * The inspector will replicate the state of the Nodes created
+   * in the renderer and allow inspection of the state of the nodes.
+   *
+   */
+  inspector: typeof Inspector | false;
+
+  /**
+   * Inspector Options
+   *
+   * @remarks
+   * Configuration options for the Inspector's performance monitoring features.
+   * Only used when inspector is enabled.
+   */
+  inspectorOptions?: Partial<InspectorOptions>;
+
+  /**
+   * Texture Processing Limit (in milliseconds)
+   *
+   * @remarks
+   * The maximum amount of time the renderer is allowed to process textures in a
+   * single frame. If the processing time exceeds this limit, the renderer will
+   * skip processing the remaining textures and continue rendering the frame.
+   *
+   * @defaultValue `10`
+   */
+  textureProcessingTimeLimit: number;
 
+  /**
+   * Target FPS for the global render loop
+   *
+   * @remarks
+   * Controls the maximum frame rate of the entire rendering system.
+   * When set to 0, no throttling is applied (use display refresh rate).
+   * When set to a positive number, the global requestAnimationFrame loop
+   * will be throttled to this target FPS, affecting all animations and rendering.
+   *
+   * This provides global performance control for the entire application,
+   * useful for managing performance on lower-end devices.
+   *
+   * @defaultValue `0` (no throttling, use display refresh rate)
+   */
+  targetFPS: number;
+}
+
+/**
+ * Configuration settings for {@link RendererMain}
+ */
+export type RendererMainSettings = RendererRuntimeSettings & {
   /**
    * Include context call (i.e. WebGL) information in FPS updates
    *
@@ -129,7 +314,7 @@ export interface RendererMainSettings {
    *
    * @defaultValue `false` (disabled)
    */
-  enableContextSpy?: boolean;
+  enableContextSpy: boolean;
 
   /**
    * Number or Image Workers to use
@@ -141,17 +326,7 @@ export interface RendererMainSettings {
    *
    * @defaultValue `2`
    */
-  numImageWorkers?: number;
-
-  /**
-   * DOM Inspector
-   *
-   * @remarks
-   * The inspector will replicate the state of the Nodes created
-   * in the renderer and allow inspection of the state of the nodes.
-   *
-   */
-  inspector?: typeof Inspector | false;
+  numImageWorkers: number;
 
   /**
    * Renderer Engine
@@ -173,7 +348,7 @@ export interface RendererMainSettings {
    *
    * @defaultValue 4 * 1024 * 1024
    */
-  quadBufferSize?: number;
+  quadBufferSize: number;
 
   /**
    * Font Engines
@@ -203,7 +378,7 @@ export interface RendererMainSettings {
    *
    *
    */
-  fontEngines: (typeof SdfTextRenderer | typeof CanvasTextRenderer)[];
+  fontEngines: TextRenderer[];
 
   /**
    * Force WebGL2
@@ -214,30 +389,7 @@ export interface RendererMainSettings {
    *
    * @defaultValue `false`
    */
-  forceWebGL2?: boolean;
-
-  /**
-   * Enable strictBounds
-   *
-   * @remarks
-   * Enable strict bounds for the renderer. This will ensure that the renderer
-   * will not render outside the bounds of the canvas.
-   *
-   * @defaultValue `true`
-   */
-  strictBounds?: boolean;
-
-  /**
-   * Texture Processing Limit (in milliseconds)
-   *
-   * @remarks
-   * The maximum amount of time the renderer is allowed to process textures in a
-   * single frame. If the processing time exceeds this limit, the renderer will
-   * skip processing the remaining textures and continue rendering the frame.
-   *
-   * @defaultValue `10`
-   */
-  textureProcessingTimeLimit?: number;
+  forceWebGL2: boolean;
 
   /**
    * Canvas object to use for rendering
@@ -246,7 +398,7 @@ export interface RendererMainSettings {
    * This is used to render the scene graph. If not provided, a new canvas
    * element will be created and appended to the target element.
    */
-  canvas?: HTMLCanvasElement;
+  canvas: HTMLCanvasElement;
 
   /**
    * createImageBitmap support for the runtime
@@ -271,8 +423,34 @@ export interface RendererMainSettings {
    *
    * @defaultValue `full`
    */
-  createImageBitmapSupport?: 'auto' | 'basic' | 'options' | 'full';
-}
+  createImageBitmapSupport: 'auto' | 'basic' | 'options' | 'full';
+
+  /**
+   * Provide an alternative platform abstraction layer
+   *
+   * @remarks
+   * By default the Lightning 3 renderer will load a webplatform, assuming it runs
+   * inside a web browsr. However for special cases there might be a need to provide
+   * an abstracted platform layer to run on non-web or non-standard JS engines
+   *
+   * @defaultValue `null`
+   */
+  platform: typeof Platform | null;
+
+  /**
+   * Number of times to retry loading a failed texture
+   *
+   * @remarks
+   * When a texture fails to load, Lightning will retry up to this many times
+   * before permanently giving up. Each retry will clear the texture ownership
+   * and then re-establish it to trigger a new load attempt.
+   *
+   * Set to null to disable retries. Set to 0 to always try once and never retry.
+   * This is typically only used on ImageTexture instances.
+   *
+   */
+  maxRetryCount?: number;
+};
 
 /**
  * The Renderer Main API
@@ -298,36 +476,36 @@ export interface RendererMainSettings {
  * );
  * ```
  *
- * ## Events
- * - `fpsUpdate`
- *   - Emitted every `fpsUpdateInterval` milliseconds with the current FPS
- * - `frameTick`
- *   - Emitted every frame tick
- * - `quadsUpdate`
- *  - Emitted when number of quads rendered is updated
- * - `idle`
- *   - Emitted when the renderer is idle (no changes to the scene
- *     graph/animations running)
- * - `criticalCleanup`
- *  - Emitted when the Texture Memory Manager Cleanup process is triggered
- *  - Payload: { memUsed: number, criticalThreshold: number }
- *    - `memUsed` - The amount of memory (in bytes) used by textures before the
- *       cleanup process
- *    - `criticalThreshold` - The critical threshold (in bytes)
- * - `criticalCleanupFailed`
- *   - Emitted when the Texture Memory Manager Cleanup process is unable to free
- *     up enough texture memory to reach below the critical threshold.
- *     This can happen when there is not enough non-renderable textures to
- *     free up.
- *   - Payload (object with keys):
- *     - `memUsed` - The amount of memory (in bytes) used by textures after
- *       the cleanup process
- *     - `criticalThreshold` - The critical threshold (in bytes)
+ * ## Event Handling
+ *
+ * Listen to events using the standard EventEmitter API:
+ * ```typescript
+ * renderer.on('fpsUpdate', (data: RendererMainFpsUpdateEvent) => {
+ *   console.log(`FPS: ${data.fps}`);
+ * });
+ *
+ * renderer.on('idle', (data: RendererMainIdleEvent) => {
+ *   // Renderer is idle - no scene changes
+ * });
+ * ```
+ *
+ * @see {@link RendererMainFpsUpdateEvent}
+ * @see {@link RendererMainFrameTickEvent}
+ * @see {@link RendererMainQuadsUpdateEvent}
+ * @see {@link RendererMainIdleEvent}
+ * @see {@link RendererMainCriticalCleanupEvent}
+ * @see {@link RendererMainCriticalCleanupFailedEvent}
+ *
+ * @fires RendererMain#fpsUpdate
+ * @fires RendererMain#frameTick
+ * @fires RendererMain#quadsUpdate
+ * @fires RendererMain#idle
+ * @fires RendererMain#criticalCleanup
+ * @fires RendererMain#criticalCleanupFailed
  */
 export class RendererMain extends EventEmitter {
   readonly root: INode;
   readonly canvas: HTMLCanvasElement;
-  readonly settings: Readonly<Required<RendererMainSettings>>;
   readonly stage: Stage;
   private inspector: Inspector | null = null;
 
@@ -338,44 +516,43 @@ export class RendererMain extends EventEmitter {
    * @param target Element ID or HTMLElement to insert the canvas into
    * @param driver Core Driver to use
    */
-  constructor(settings: RendererMainSettings, target: string | HTMLElement) {
+  constructor(
+    settings: Partial<RendererMainSettings>,
+    target?: string | HTMLElement,
+  ) {
     super();
 
-    const resolvedTxSettings: TextureMemoryManagerSettings = {
-      criticalThreshold: settings.textureMemory?.criticalThreshold || 124e6,
-      targetThresholdLevel: settings.textureMemory?.targetThresholdLevel || 0.5,
-      cleanupInterval: settings.textureMemory?.cleanupInterval || 5000,
-      debugLogging: settings.textureMemory?.debugLogging || false,
-      baselineMemoryAllocation:
-        settings.textureMemory?.baselineMemoryAllocation || 26e6,
-      doNotExceedCriticalThreshold:
-        settings.textureMemory?.doNotExceedCriticalThreshold || false,
-    };
+    const resolvedTxSettings = this.resolveTxSettings(
+      settings.textureMemory || {},
+    );
 
-    const resolvedSettings: Required<RendererMainSettings> = {
+    settings = {
       appWidth: settings.appWidth || 1920,
       appHeight: settings.appHeight || 1080,
       textureMemory: resolvedTxSettings,
       boundsMargin: settings.boundsMargin || 0,
       deviceLogicalPixelRatio: settings.deviceLogicalPixelRatio || 1,
       devicePhysicalPixelRatio:
-        settings.devicePhysicalPixelRatio || window.devicePixelRatio,
+        settings.devicePhysicalPixelRatio || window.devicePixelRatio || 1,
       clearColor: settings.clearColor ?? 0x00000000,
       fpsUpdateInterval: settings.fpsUpdateInterval || 0,
+      enableClear: settings.enableClear ?? true,
+      targetFPS: settings.targetFPS || 0,
       numImageWorkers:
         settings.numImageWorkers !== undefined ? settings.numImageWorkers : 2,
       enableContextSpy: settings.enableContextSpy ?? false,
       forceWebGL2: settings.forceWebGL2 ?? false,
       inspector: settings.inspector ?? false,
+      inspectorOptions: settings.inspectorOptions ?? {},
       renderEngine: settings.renderEngine,
       quadBufferSize: settings.quadBufferSize ?? 4 * 1024 * 1024,
-      fontEngines: settings.fontEngines,
-      strictBounds: settings.strictBounds ?? true,
-      textureProcessingTimeLimit: settings.textureProcessingTimeLimit || 10,
-      canvas: settings.canvas || document.createElement('canvas'),
+      fontEngines: settings.fontEngines ?? [],
+      textureProcessingTimeLimit: settings.textureProcessingTimeLimit || 42,
+      canvas: settings.canvas,
       createImageBitmapSupport: settings.createImageBitmapSupport || 'full',
+      platform: settings.platform || null,
+      maxRetryCount: settings.maxRetryCount ?? 5,
     };
-    this.settings = resolvedSettings;
 
     const {
       appWidth,
@@ -383,8 +560,21 @@ export class RendererMain extends EventEmitter {
       deviceLogicalPixelRatio,
       devicePhysicalPixelRatio,
       inspector,
-      canvas,
-    } = resolvedSettings;
+    } = settings as RendererMainSettings;
+
+    let platform;
+    if (
+      settings.platform !== undefined &&
+      settings.platform !== null &&
+      settings.platform.prototype instanceof Platform === true
+    ) {
+      // @ts-ignore - if Platform is a valid class, it will be used
+      platform = new settings.platform();
+    } else {
+      platform = new WebPlatform();
+    }
+
+    const canvas = settings.canvas || platform.createCanvas();
 
     const deviceLogicalWidth = appWidth * deviceLogicalPixelRatio;
     const deviceLogicalHeight = appHeight * deviceLogicalPixelRatio;
@@ -398,51 +588,98 @@ export class RendererMain extends EventEmitter {
 
     // Initialize the stage
     this.stage = new Stage({
-      appWidth: this.settings.appWidth,
-      appHeight: this.settings.appHeight,
-      boundsMargin: this.settings.boundsMargin,
-      clearColor: this.settings.clearColor,
+      appWidth,
+      appHeight,
+      boundsMargin: settings.boundsMargin!,
+      clearColor: settings.clearColor!,
       canvas: this.canvas,
-      deviceLogicalPixelRatio: this.settings.deviceLogicalPixelRatio,
-      devicePhysicalPixelRatio: this.settings.devicePhysicalPixelRatio,
-      enableContextSpy: this.settings.enableContextSpy,
-      forceWebGL2: this.settings.forceWebGL2,
-      fpsUpdateInterval: this.settings.fpsUpdateInterval,
-      numImageWorkers: this.settings.numImageWorkers,
-      renderEngine: this.settings.renderEngine,
+      deviceLogicalPixelRatio,
+      devicePhysicalPixelRatio,
+      enableContextSpy: settings.enableContextSpy!,
+      forceWebGL2: settings.forceWebGL2!,
+      fpsUpdateInterval: settings.fpsUpdateInterval!,
+      enableClear: settings.enableClear!,
+      numImageWorkers: settings.numImageWorkers!,
+      renderEngine: settings.renderEngine!,
       textureMemory: resolvedTxSettings,
       eventBus: this,
-      quadBufferSize: this.settings.quadBufferSize,
-      fontEngines: this.settings.fontEngines,
-      inspector: this.settings.inspector !== null,
-      strictBounds: this.settings.strictBounds,
-      textureProcessingTimeLimit: this.settings.textureProcessingTimeLimit,
-      createImageBitmapSupport: this.settings.createImageBitmapSupport,
+      quadBufferSize: settings.quadBufferSize!,
+      fontEngines: settings.fontEngines!,
+      inspector: settings.inspector !== null,
+      targetFPS: settings.targetFPS!,
+      textureProcessingTimeLimit: settings.textureProcessingTimeLimit!,
+      createImageBitmapSupport: settings.createImageBitmapSupport!,
+      platform,
+      maxRetryCount: settings.maxRetryCount ?? 5,
     });
 
     // Extract the root node
     this.root = this.stage.root as unknown as INode;
 
     // Get the target element and attach the canvas to it
-    let targetEl: HTMLElement | null;
-    if (typeof target === 'string') {
-      targetEl = document.getElementById(target);
-    } else {
-      targetEl = target;
-    }
+    if (target) {
+      let targetEl: HTMLElement | null;
+      if (typeof target === 'string') {
+        targetEl = document.getElementById(target);
+      } else {
+        targetEl = target;
+      }
 
-    if (!targetEl) {
-      throw new Error('Could not find target element');
-    }
+      if (!targetEl) {
+        throw new Error('Could not find target element');
+      }
 
-    targetEl.appendChild(canvas);
+      targetEl.appendChild(canvas);
+    } else if (settings.canvas !== canvas) {
+      throw new Error(
+        'New canvas element could not be appended to undefined target',
+      );
+    }
 
     // Initialize inspector (if enabled)
-    if (inspector && !isProductionEnvironment()) {
-      this.inspector = new inspector(canvas, resolvedSettings);
+    if (inspector && isProductionEnvironment === false) {
+      this.inspector = new inspector(canvas, settings as RendererMainSettings);
     }
   }
 
+  /**
+   * Resolves the Texture Memory Manager values
+   *
+   * @param props
+   * @returns
+   */
+  private resolveTxSettings(
+    textureMemory: Partial<TextureMemoryManagerSettings>,
+  ): TextureMemoryManagerSettings {
+    const currentTxSettings =
+      (this.stage && this.stage.options.textureMemory) || {};
+
+    return {
+      criticalThreshold:
+        textureMemory?.criticalThreshold ??
+        currentTxSettings?.criticalThreshold ??
+        124e6,
+      targetThresholdLevel:
+        textureMemory?.targetThresholdLevel ??
+        currentTxSettings?.targetThresholdLevel ??
+        0.5,
+      cleanupInterval:
+        textureMemory?.cleanupInterval ??
+        currentTxSettings?.cleanupInterval ??
+        5000,
+      debugLogging:
+        textureMemory?.debugLogging ?? currentTxSettings?.debugLogging ?? false,
+      baselineMemoryAllocation:
+        textureMemory?.baselineMemoryAllocation ??
+        currentTxSettings?.baselineMemoryAllocation ??
+        26e6,
+      doNotExceedCriticalThreshold:
+        textureMemory?.doNotExceedCriticalThreshold ??
+        currentTxSettings?.doNotExceedCriticalThreshold ??
+        false,
+    };
+  }
+
   /**
    * Create a new scene graph node
    *
@@ -461,16 +698,12 @@ export class RendererMain extends EventEmitter {
   createNode<ShNode extends CoreShaderNode<any>>(
     props: Partial<INodeProps<ShNode>>,
   ): INode<ShNode> {
-    assertTruthy(this.stage, 'Stage is not initialized');
-
     const node = this.stage.createNode(props as Partial<CoreNodeProps>);
 
     if (this.inspector) {
       return this.inspector.createNode(node) as unknown as INode<ShNode>;
     }
 
-    // FIXME onDestroy event? node.once('beforeDestroy'
-    // FIXME onCreate event?
     return node as unknown as INode<ShNode>;
   }
 
@@ -557,7 +790,7 @@ export class RendererMain extends EventEmitter {
     props?: OptionalShaderProps<ShType>,
   ) {
     return this.stage.shManager.createShader(shType, props) as CoreShaderNode<
-      ExtractShaderProps<ShType>
+      NonNullable<ExtractShaderProps<ShType>>
     >;
   }
 
@@ -634,8 +867,8 @@ export class RendererMain extends EventEmitter {
    * **NOTE3**: This will not cleanup textures that are marked as `preventCleanup`.
    * **NOTE4**: This has nothing to do with the garbage collection of JavaScript.
    */
-  cleanup(aggressive: boolean = false) {
-    this.stage.cleanup(aggressive);
+  cleanup() {
+    this.stage.cleanup();
   }
 
   /**
@@ -646,4 +879,150 @@ export class RendererMain extends EventEmitter {
   setClearColor(color: number) {
     this.stage.setClearColor(color);
   }
+
+  /**
+   * Set options for the renderer
+   *
+   * @param options
+   */
+  setOptions(options: Partial<RendererRuntimeSettings>) {
+    const stage = this.stage;
+    if (options.textureMemory !== undefined) {
+      const textureMemory = (options.textureMemory = this.resolveTxSettings(
+        options.textureMemory,
+      ));
+      stage.txMemManager.updateSettings(textureMemory);
+      stage.txMemManager.cleanup();
+    }
+
+    if (options.boundsMargin !== undefined) {
+      let bm = options.boundsMargin!;
+      options.boundsMargin = Array.isArray(bm) ? bm : [bm, bm, bm, bm];
+    }
+
+    const stageOptions = stage.options;
+    for (let key in options) {
+      stageOptions[key] = options[key]!;
+    }
+
+    if (options.inspector !== undefined && !isProductionEnvironment) {
+      if (options.inspector === false) {
+        this.inspector?.destroy();
+        this.inspector = null;
+      } else if (
+        this.inspector === null ||
+        this.inspector.constructor !== options.inspector
+      ) {
+        this.inspector = new options.inspector(
+          this.canvas,
+          stage.options as unknown as RendererMainSettings,
+        );
+        this.inspector?.createNodes(this.root as unknown as CoreNode);
+      }
+    }
+
+    let needDimensionsUpdate = false;
+
+    if (
+      options.deviceLogicalPixelRatio ||
+      options.devicePhysicalPixelRatio !== undefined
+    ) {
+      this.stage.pixelRatio =
+        stageOptions.devicePhysicalPixelRatio *
+        stageOptions.deviceLogicalPixelRatio;
+      this.inspector?.updateViewport(
+        stageOptions.appWidth,
+        stageOptions.appHeight,
+        stageOptions.deviceLogicalPixelRatio,
+      );
+      needDimensionsUpdate = true;
+    }
+
+    if (options.appWidth !== undefined || options.appHeight !== undefined) {
+      this.inspector?.updateViewport(
+        stageOptions.appWidth,
+        stageOptions.appHeight,
+        stageOptions.deviceLogicalPixelRatio,
+      );
+      needDimensionsUpdate = true;
+    }
+
+    if (options.boundsMargin !== undefined) {
+      this.stage.setBoundsMargin(options.boundsMargin);
+    }
+
+    if (options.clearColor !== undefined) {
+      this.stage.setClearColor(options.clearColor);
+    }
+
+    if (needDimensionsUpdate) {
+      this.updateAppDimensions();
+    }
+  }
+
+  private updateAppDimensions() {
+    const {
+      appWidth,
+      appHeight,
+      deviceLogicalPixelRatio,
+      devicePhysicalPixelRatio,
+    } = this.stage.options;
+
+    const deviceLogicalWidth = appWidth * deviceLogicalPixelRatio;
+    const deviceLogicalHeight = appHeight * deviceLogicalPixelRatio;
+
+    this.canvas.width = deviceLogicalWidth * devicePhysicalPixelRatio;
+    this.canvas.height = deviceLogicalHeight * devicePhysicalPixelRatio;
+
+    this.canvas.style.width = `${deviceLogicalWidth}px`;
+    this.canvas.style.height = `${deviceLogicalHeight}px`;
+
+    this.stage.renderer.updateViewport();
+
+    this.root.w = appWidth;
+    this.root.h = appHeight;
+    this.stage.updateViewportBounds();
+  }
+
+  get settings(): Readonly<StageOptions> {
+    return this.stage.options;
+  }
+
+  /**
+   * Gets the target FPS for the global render loop
+   *
+   * @returns The current target FPS (0 means no throttling)
+   *
+   * @remarks
+   * This controls the maximum frame rate of the entire rendering system.
+   * When 0, the system runs at display refresh rate.
+   */
+  get targetFPS(): number {
+    return this.stage.options.targetFPS || 0;
+  }
+
+  /**
+   * Sets the target FPS for the global render loop
+   *
+   * @param fps - The target FPS to set for the global render loop.
+   *              Set to 0 or a negative value to disable throttling.
+   *
+   * @remarks
+   * This setting affects the entire rendering system immediately.
+   * All animations, rendering, and frame updates will be throttled
+   * to this target FPS. Provides global performance control.
+   *
+   * @example
+   * ```typescript
+   * // Set global target to 30fps for better performance
+   * renderer.targetFPS = 30;
+   *
+   * // Disable global throttling (use display refresh rate)
+   * renderer.targetFPS = 0;
+   * ```
+   */
+  set targetFPS(fps: number) {
+    this.stage.options.targetFPS = fps > 0 ? fps : 0;
+    this.stage.updateTargetFrameTime();
+  }
 }