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

/**
 * An array-like proxy over one of an asset entry's events.
 * Assign a function to a numbered slot to subscribe; assign `null` to
 * unsubscribe that slot.
 *
 * @example
 * entry.onLoaded[0] = () => Console.print('loaded!');
 * entry.onLoaded[0] = null; // unsubscribe
 */
interface AssetEventProxy {
  readonly length: number;
  0: (() => void) | null;
  1: (() => void) | null;
  2: (() => void) | null;
  3: (() => void) | null;
  toString(): string;
}

/**
 * A live reference to an entry in the asset cache.
 * Holds a lock that keeps the entry alive; the lock is released automatically
 * when the object is garbage collected, or immediately via `unlock()`.
 */
interface AssetEntry {
  /** Archive-relative path used as the cache key. */
  readonly name: string;
  /** Current loading state — compare against `AssetEntry.*` state constants. */
  readonly state: number;
  /** Loader type — one of the `AssetEntry.TYPE_*` constants. */
  readonly type: number;
  /** `true` when the entry has fully loaded (`state === AssetEntry.LOADED`). */
  readonly isLoaded: boolean;
  /**
   * Returns a `Texture` for this entry when it is a loaded texture asset.
   * The `Texture` holds its own asset lock — independent of this `AssetEntry`.
   * Returns `undefined` if the entry is not of type `Asset.TYPE_TEXTURE` or
   * is not yet loaded.
   */
  readonly texture: Texture | undefined;
  /** Event proxy — subscribe up to 4 callbacks for when loading completes. */
  readonly onLoaded: AssetEventProxy;
  /** Event proxy — subscribe up to 4 callbacks for when the entry is disposed. */
  readonly onUnloaded: AssetEventProxy;
  /** Event proxy — subscribe up to 4 callbacks for when loading fails. */
  readonly onError: AssetEventProxy;
  /**
   * Blocks until the entry reaches `LOADED` (or `ERROR`).
   * Returns `this` for chaining.
   * @throws If the load fails.
   */
  requireLoaded(): this;
  /**
   * Releases the lock immediately.
   * After this call the object is invalid — do not use it again.
   */
  unlock(): void;
  toString(): string;
}

interface AssetEntryConstructor {
  // Loading state constants
  readonly NOT_STARTED: number;
  readonly PENDING:     number;
  readonly LOADING:     number;
  readonly LOADED:      number;
  readonly ERROR:       number;

  new(): never;
}

declare var AssetEntry: AssetEntryConstructor;