Test sprite from script

types/asset/asset.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+/** Asset archive queries and cache management. */
+interface AssetNamespace {
+  // Loader type constants
+  readonly TYPE_MESH:    number;
+  readonly TYPE_TEXTURE: number;
+  readonly TYPE_TILESET: number;
+  readonly TYPE_LOCALE:  number;
+  readonly TYPE_JSON:    number;
+  readonly TYPE_SCRIPT:  number;
+
+  // Mesh axis input constants (pass as `input` to lock with TYPE_MESH)
+  readonly MESH_AXIS_Y_UP:   number;
+  readonly MESH_AXIS_Z_UP:   number;
+  readonly MESH_AXIS_X_UP:   number;
+  readonly MESH_AXIS_Y_DOWN: number;
+  readonly MESH_AXIS_Z_DOWN: number;
+  readonly MESH_AXIS_X_DOWN: number;
+
+  /**
+   * Returns `true` if the given path exists in the asset archive (`dusk.dsk`).
+   *
+   * @param path - Archive-relative path, e.g. `"init.js"` or `"ui/hud.png"`.
+   */
+  exists(path: string): boolean;
+
+  /**
+   * Locks an entry in the asset cache and returns an `AssetEntry`.
+   * The entry begins loading in the background. Call `entry.requireLoaded()`
+   * to block until it is ready.
+   *
+   * The lock is released when the `AssetEntry` is GC'd or `entry.unlock()`
+   * is called explicitly.
+   *
+   * @param path - Archive-relative path.
+   * @param type  - Loader type constant (`Asset.TYPE_*`).
+   * @param input - Optional loader-specific input constant.
+   *                `TYPE_TEXTURE` → `Texture.FORMAT_*`
+   *                `TYPE_MESH`    → `Asset.MESH_AXIS_*`
+   *
+   * @example
+   * const entry = Asset.lock('data/map.json');
+   * entry.requireLoaded();
+   */
+  lock(path: string, type: number, input?: number): AssetEntry;
+
+  /**
+   * Blocks until the given entry is fully loaded.
+   * Returns the entry for chaining.
+   * @throws If the load fails.
+   *
+   * @example
+   * const entry = Asset.requireLoaded(Asset.lock('map.json', Asset.TYPE_JSON));
+   */
+  requireLoaded(entry: AssetEntry): AssetEntry;
+
+  /**
+   * Releases the lock on an asset by path.
+   * Prefer calling `entry.unlock()` on the `AssetEntry` object directly.
+   *
+   * @param path - The path originally passed to `lock`.
+   */
+  unlock(path: string): void;
+}
+
+declare var Asset: AssetNamespace;

types/asset/assetentry.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+/**
+ * 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;
+  /**
+   * 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;