/**
 * 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 = {};
 * var batch = AssetBatch([{ path: 'tex/bg.png', type: Asset.TYPE_TEXTURE }]);
 *
 * scene.load    = function() { return batch; };
 * scene.init    = function() { Console.print('scene started'); };
 * scene.update  = function() { /* per-frame logic *\/ };
 * scene.dispose = function() { batch.unlock(); };
 *
 * module.exports = scene;
 */
interface SceneObject {
  /** Return an AssetBatch to preload before init is called. Optional. */
  load?(): AssetBatch | undefined;
  /** 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 {
  /** `true` while a JS script scene is running. */
  readonly active: boolean;

  /**
   * Loads the JS module at `path`, waits for any `AssetBatch` returned by
   * `scene.load()`, then activates the scene (calling `scene.init()`).
   * The previous scene's `dispose()` is called just before `init()`.
   *
   * Returns immediately — the transition is asynchronous.
   *
   * @example
   * Scene.set('assets/scenes/game.js');
   */
  set(path: string): void;
}

declare var Scene: SceneNamespace;