@antha/asset 0.4.3 → 0.5.0

package/README.md

@@ -26,7 +26,7 @@ type GameState = AnthaAssetModState & {
 };
 
 const titleAsset = defineAsset({
-    name: 'title',
+    assetName: 'title',
     maxProgress: 1,
     load({incrementProgressCallback}) {
         incrementProgressCallback();

package/dist/antha-bootstrap.mod.d.ts

@@ -0,0 +1,41 @@
+import { type AnthaEngine, type AnthaMod } from '@antha/engine';
+import { type AnyObject, type MaybePromise, type PartialWithUndefined } from '@augment-vir/common';
+import { type AnthaAssetModState } from './antha-asset.mod.js';
+import { type AssetLoader, type AssetLoadSession } from './asset-loader.js';
+/** State used internally by {@link createAnthaBootstrapMod}. */
+export type AnthaBootstrapModState = {
+    hasStartedBootstrap: boolean;
+};
+/** Parameters passed to {@link AnthaBootstrapModOptions.bootstrap}. */
+export type AnthaBootstrapParams<Module, State extends AnyObject> = {
+    assetLoader: AssetLoader;
+    engine: AnthaEngine;
+    loadSession: AssetLoadSession;
+    module: Module;
+    state: Partial<State & AnthaAssetModState & AnthaBootstrapModState>;
+};
+/** Result returned by {@link AnthaBootstrapModOptions.bootstrap}. */
+export type AnthaBootstrapResult = {
+    /** Mods that Antha installs after bootstrapping finishes. */
+    mods: ReadonlyArray<AnthaMod>;
+};
+/** Options for {@link createAnthaBootstrapMod}. */
+export type AnthaBootstrapModOptions<Module, State extends AnyObject> = {
+    /**
+     * Bootstraps the loaded module and returns the mods that should be installed for it. Await any
+     * initial asset loading here, using the provided load session, before returning.
+     */
+    bootstrap: (this: void, params: Readonly<AnthaBootstrapParams<Module, State>>) => MaybePromise<AnthaBootstrapResult>;
+    /** Lazily imports the code required to bootstrap the game. */
+    loadModule: (this: void) => MaybePromise<Module>;
+} & PartialWithUndefined<{
+    /** Label shown for the code-loading task. */
+    assetName: string;
+}>;
+/**
+ * Creates a mod that tracks a lazy game-module import on Antha's loading screen, then installs the
+ * mods returned by the module's bootstrap callback.
+ *
+ * @category Pre-Built Mods
+ */
+export declare function createAnthaBootstrapMod<Module, State extends AnyObject = AnyObject>(options: Readonly<AnthaBootstrapModOptions<Module, State>>): AnthaMod<NoInfer<State & AnthaAssetModState & AnthaBootstrapModState>>;

package/dist/antha-bootstrap.mod.js

@@ -0,0 +1,54 @@
+import { defineAnthaMod, SkipExecution } from '@antha/engine';
+import { ensureErrorAndPrependMessage, } from '@augment-vir/common';
+import { defineAsset } from './asset-loader.js';
+/**
+ * Creates a mod that tracks a lazy game-module import on Antha's loading screen, then installs the
+ * mods returned by the module's bootstrap callback.
+ *
+ * @category Pre-Built Mods
+ */
+export function createAnthaBootstrapMod(options) {
+    const moduleAsset = defineAsset({
+        assetName: options.assetName || 'Game code',
+        maxProgress: 1,
+        async load({ incrementProgressCallback }) {
+            const module = await options.loadModule();
+            incrementProgressCallback();
+            return {
+                value: module,
+            };
+        },
+    });
+    return defineAnthaMod({
+        modName: 'antha-bootstrap',
+        execute({ engine, state }) {
+            const assetLoader = state.assetLoader;
+            if (!assetLoader || state.hasStartedBootstrap) {
+                return SkipExecution;
+            }
+            state.hasStartedBootstrap = true;
+            const loadSession = assetLoader.createLoadSession();
+            void assetLoader
+                .loadIndividualAsset({
+                asset: moduleAsset,
+                loadSession,
+            })
+                .then(async (module) => {
+                const bootstrapResult = await options.bootstrap({
+                    assetLoader,
+                    engine,
+                    loadSession,
+                    module,
+                    state,
+                });
+                engine.currentMods.push(...bootstrapResult.mods);
+                loadSession.complete();
+            })
+                .catch((error) => {
+                loadSession.complete();
+                engine.log.error(ensureErrorAndPrependMessage(error, 'Failed to bootstrap game.'));
+            });
+            return SkipExecution;
+        },
+    });
+}

package/dist/asset-loader.d.ts

@@ -50,7 +50,7 @@ export type AssetValue<SpecificAsset extends Pick<Asset, 'load'>> = Awaited<Retu
  * @category Asset
  */
 export type Asset<AssetValue = any> = {
-    name: string;
+    assetName: string;
     maxProgress: number;
     load: AssetLoaderCallback<AssetValue>;
 };

package/dist/asset-loader.js

@@ -173,7 +173,7 @@ export class AssetLoader {
         this.assetCache.set(asset, deferredLoadPromise.promise);
         loadSession?.reportProgress({
             current: 0,
-            currentResourceName: asset.name,
+            currentResourceName: asset.assetName,
             total: asset.maxProgress,
         });
         const loadedAsset = await asset.load({
@@ -181,7 +181,7 @@ export class AssetLoader {
                 incrementProgressCallback?.(progressParams);
                 loadSession?.incrementProgress({
                     amount: progressParams,
-                    currentResourceName: asset.name,
+                    currentResourceName: asset.assetName,
                 });
             },
         });
@@ -197,7 +197,7 @@ export class AssetLoader {
                     await entry.cleanup();
                 }
                 catch (error) {
-                    this.log.error(ensureErrorAndPrependMessage(error, `Failed to cleanup asset: ${asset.name}`));
+                    this.log.error(ensureErrorAndPrependMessage(error, `Failed to cleanup asset: ${asset.assetName}`));
                 }
             }
             this.assetCache.delete(asset);
@@ -233,7 +233,7 @@ export class AssetLoader {
                 progress: {
                     current: currentProgress,
                     total: maxProgress,
-                    currentResourceName: assetsToLoad[0]?.name,
+                    currentResourceName: assetsToLoad[0]?.assetName,
                 },
             });
         }
@@ -247,7 +247,7 @@ export class AssetLoader {
             progress: {
                 current: currentProgress,
                 total: maxProgress,
-                currentResourceName: assetsToLoad[0]?.name,
+                currentResourceName: assetsToLoad[0]?.assetName,
             },
         });
         const chunkedAssets = options.maxParallelism
@@ -263,7 +263,7 @@ export class AssetLoader {
                     progress: {
                         current: currentProgress,
                         total: maxProgress,
-                        currentResourceName: asset.name,
+                        currentResourceName: asset.assetName,
                     },
                 });
             };
@@ -278,7 +278,7 @@ export class AssetLoader {
                     progress: {
                         current: currentProgress,
                         total: maxProgress,
-                        currentResourceName: asset.name,
+                        currentResourceName: asset.assetName,
                     },
                 });
                 return await this.loadIndividualAsset({
@@ -293,7 +293,7 @@ export class AssetLoader {
                     currentProgress,
                     maxProgress,
                     assetCount: assetsToLoad.length,
-                    assetNames: assetsToLoad.map((entry) => entry.name).filter(Boolean),
+                    assetNames: assetsToLoad.map((entry) => entry.assetName).filter(Boolean),
                 },
                 tags: {
                     mod: '@antha/asset',

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export * from './antha-asset.mod.js';
+export * from './antha-bootstrap.mod.js';
 export * from './asset-loader.js';

package/dist/index.js

@@ -1,2 +1,3 @@
 export * from './antha-asset.mod.js';
+export * from './antha-bootstrap.mod.js';
 export * from './asset-loader.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@antha/asset",
-    "version": "0.4.3",
+    "version": "0.5.0",
     "description": "An Antha mod for handling asset loading.",
     "keywords": [
         "vir",
@@ -45,10 +45,12 @@
         "@web/test-runner": "^1.0.0",
         "@web/test-runner-playwright": "^1.0.0",
         "istanbul-smart-text-reporter": "^1.1.5",
-        "pixi.js": "^8.19.0"
+        "markdown-code-example-inserter": "^3.0.6",
+        "pixi.js": "^8.19.0",
+        "typedoc": "^0.28.20"
     },
     "peerDependencies": {
-        "@antha/engine": "^0.4.3",
+        "@antha/engine": "^0.5.0",
         "element-vir": ">=26"
     },
     "engines": {