/**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */

/**
 * The object a JS scene module must export.
 * All methods are optional.
 *
 * @example
 * // assets/scenes/game.js
 * var scene = {};
 *
 * scene.init    = function() { Console.print('scene started'); };
 * scene.update  = function() { /* per-frame logic *\/ };
 * scene.dispose = function() { };
 *
 * module.exports = scene;
 */
interface SceneObject {
  /** Called when this scene becomes active. Optional. */
  init?(): void;
  /** Called every frame while this scene is active. Optional. */
  update?(): void;
  /** Called when the scene is replaced or the engine shuts down. Optional. */
  dispose?(): void;
}

/** Scene management. */
interface SceneNamespace {
  /** The currently active scene object, or `null` if none. */
  current: SceneObject | null;

  /**
   * Replaces the active scene. Calls `dispose()` on the previous scene (if
   * any), then calls `init()` on the new one. Pass `null` to clear.
   *
   * @example
   * const myScene = require('./scenes/game');
   * Scene.set(myScene);
   */
  set(newScene: SceneObject | null): void;

  /** Called each frame by the engine — drives `current.update()`. */
  update(): void;

  /** Called each frame by the engine for dynamic/physics updates. */
  dynamicUpdate(): void;

  /** Disposes the current scene and sets `current` to `null`. */
  dispose(): void;
}

declare var Scene: SceneNamespace;