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

/**
 * A scene: an isolated pool of entities/components. `new Scene()`
 * creates an empty scene -- it is not made active automatically, call
 * `.setActive()` for that. `Entity`/`Component` always operate on
 * whichever scene is currently active, not on a specific Scene
 * instance.
 */
declare class Scene {
  constructor();

  /** The engine-assigned numeric scene ID. */
  readonly id: number;

  /** Makes this the active scene (see Scene.getActive()). */
  setActive(): void;

  /** Destroys this scene and all its entities/components. */
  dispose(): void;

  /** Gets the currently active scene, or undefined if none is active. */
  static getActive(): Scene | undefined;

  /**
   * Installs a scene module as the current scene, the mechanism for
   * switching scenes from script. Tears down whatever module a previous
   * Scene.set() call installed (calling its dispose(), then destroying
   * the scene it owned), then creates and activates a fresh Scene and
   * calls the new module's init() with it active -- so init() can use
   * `new Entity()`/etc. as usual. The module's update() and lateUpdate()
   * (if defined) are then each called once per engine frame -- update()
   * first, lateUpdate() after everything else has updated -- until
   * Scene.set() is called again.
   *
   * Typical usage (see require.d.ts):
   * ```js
   * var myScene = require('./myscene.js');
   * Scene.set(myScene);
   * ```
   */
  static set(module: SceneModule): void;
}

/**
 * The shape a scene module's `module.exports` should have to be usable
 * with Scene.set(). All three are optional -- a module that never moves
 * anything, for instance, can omit update().
 */
interface SceneModule {
  /** Called once, right after Scene.set() creates and activates the scene. */
  init?(): void;

  /** Called once per engine frame while this module is the active scene. */
  update?(): void;

  /**
   * Called once per engine frame, after every other update (entities,
   * physics, UI, etc.) has already run for that frame -- useful for
   * things like camera follow that need to react to where everything
   * else ended up this frame, rather than where it was at the start.
   */
  lateUpdate?(): void;

  /** Called once when this module is replaced by another Scene.set() call. */
  dispose?(): void;
}