Test sprite from script

2026-06-02 09:32:07 -05:00
parent 57766a9104
commit a25871a849
38 changed files with 1913 additions and 377 deletions
@@ -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;