refactor(engine)!: refactor AssetManager and loaders (#246)

Author: fraxken

.changeset/hip-hoops-tell.md

@@ -0,0 +1,7 @@
+---
+"@jolly-pixel/engine": major
+"@jolly-pixel/voxel.renderer": minor
+"@jolly-pixel/runtime": minor
+---
+
+Major refactor of AssetManager and loaders

packages/engine/src/audio/AudioLibrary.ts

@@ -1,17 +1,24 @@
 // Import Internal Dependencies
-import { Assets } from "../systems/index.ts";
+import type { AssetManager } from "../systems/index.ts";
 import type { LazyAsset } from "../systems/asset/Base.ts";
 
 export class AudioLibrary<
   TKeys extends string = string
 > {
+  #assetManager: AssetManager;
   #assets = new Map<TKeys, LazyAsset<AudioBuffer>>();
 
+  constructor(
+    assetManager: AssetManager
+  ) {
+    this.#assetManager = assetManager;
+  }
+
   register(
     name: TKeys,
     path: string
   ): LazyAsset<AudioBuffer> {
-    const lazy = Assets.load<AudioBuffer>(path);
+    const lazy = this.#assetManager.load<AudioBuffer>(path);
     this.#assets.set(name, lazy);
 
     return lazy;

packages/engine/src/audio/AudioManager.ts

@@ -3,8 +3,8 @@ import * as THREE from "three";
 
 // Import Internal Dependencies
 import {
-  type World,
-  Assets
+  AssetLoader,
+  type World
 } from "../systems/index.ts";
 import {
   type AudioListenerAdapter
@@ -18,6 +18,16 @@ import {
 const kDefaultVolume = 1;
 const kDefaultLoop = false;
 
+export const AudioAssetLoader = new AssetLoader<AudioBuffer>({
+  type: "audio",
+  extensions: [".mp3", ".ogg", ".wav", ".aac", ".flac"],
+  load: async(asset, context) => {
+    const loader = new THREE.AudioLoader(context.manager);
+
+    return loader.loadAsync(asset.toString());
+  }
+});
+
 export type AudioManager = {
   loadAudio: (url: string, options?: AudioLoadingOptions) => Promise<THREE.Audio>;
   loadPositionalAudio: (url: string, options?: AudioLoadingOptions) => Promise<THREE.PositionalAudio>;
@@ -54,17 +64,7 @@ export class GlobalAudioManager implements AudioManager {
       listener: world.audio.listener
     });
 
-    Assets.registry.loader(
-      {
-        extensions: [".mp3", ".ogg", ".wav", ".aac", ".flac"],
-        type: "audio"
-      },
-      async(asset, context) => {
-        const loader = new THREE.AudioLoader(context.manager);
-
-        return loader.loadAsync(asset.toString());
-      }
-    );
+    world.assetManager.register(AudioAssetLoader);
 
     return audioManager;
   }

packages/engine/src/components/renderers/index.ts

@@ -4,17 +4,17 @@ export * from "./text/TextRenderer.class.ts";
 
 // Import Internal Dependencies
 import {
-  model,
+  ModelAssetLoader,
   type Model
 } from "./model/loader.ts";
 import {
-  font,
+  FontAssetLoader,
   type Font
 } from "./text/loader.ts";
 
 export const Loaders = {
-  model,
-  font
+  model: ModelAssetLoader,
+  font: FontAssetLoader
 } as const;
 
 export type {

packages/engine/src/components/renderers/model/ModelRenderer.ts

@@ -4,7 +4,7 @@ import * as THREE from "three";
 // Import Internal Dependencies
 import * as Systems from "../../../systems/index.ts";
 import { Actor, ActorComponent } from "../../../actor/index.ts";
-import { model, type Model } from "./loader.ts";
+import { type Model } from "./loader.ts";
 
 import {
   ModelAnimation,
@@ -49,7 +49,7 @@ export class ModelRenderer<
       typeName: "ModelRenderer"
     });
 
-    this.#asset = model(options.path);
+    this.#asset = actor.world.assetManager.load<Model>(options.path);
     this.#debug = options.debug ?? false;
 
     const { animations } = options;

packages/engine/src/components/renderers/model/loader.ts

@@ -8,7 +8,7 @@ import { GLTFLoader } from "three/addons/loaders/GLTFLoader.js";
 // Import Internal Dependencies
 import {
   Asset,
-  Assets,
+  AssetLoader,
   type AssetLoaderContext
 } from "../../../systems/index.ts";
 
@@ -17,12 +17,10 @@ export type Model = {
   animations: THREE.AnimationClip[];
 };
 
-Assets.registry.loader(
-  {
-    extensions: [".obj", ".fbx", ".glb", ".gltf"],
-    type: "model"
-  },
-  (asset, context) => {
+export const ModelAssetLoader = new AssetLoader<Model>({
+  type: "model",
+  extensions: [".obj", ".fbx", ".glb", ".gltf"],
+  load: (asset, context) => {
     switch (asset.ext) {
       case ".obj":
         return safeLoad(asset, objectLoader(asset, context));
@@ -35,8 +33,7 @@ Assets.registry.loader(
         throw new Error(`Unsupported model type: ${asset.ext}`);
     }
   }
-);
-export const model = Assets.lazyLoad<Model>();
+});
 
 async function objectLoader(
   asset: Asset,

packages/engine/src/components/renderers/text/TextRenderer.class.ts

@@ -8,7 +8,7 @@ import {
   Text3D,
   type Text3DOptions
 } from "./Text3D.class.ts";
-import { font, type Font } from "./loader.ts";
+import { type Font } from "./loader.ts";
 
 export interface TextRendererOptions extends Omit<Text3DOptions, "font"> {
   path: string;
@@ -36,7 +36,7 @@ export class TextRenderer extends ActorComponent<any> {
       material = new THREE.MeshBasicMaterial()
     } = options;
 
-    this.#asset = font(path);
+    this.#asset = actor.world.assetManager.load<Font>(path);
     this.text = new Text3D({
       material,
       textGeometryOptions

packages/engine/src/components/renderers/text/loader.ts

@@ -5,23 +5,17 @@ import {
 } from "three/examples/jsm/loaders/FontLoader.js";
 
 // Import Internal Dependencies
-import {
-  Assets
-} from "../../../systems/index.ts";
+import { AssetLoader } from "../../../systems/index.ts";
 
-Assets.registry.loader(
-  {
-    extensions: [".typeface.json"],
-    type: "font"
-  },
-  (asset, context) => {
+export const FontAssetLoader = new AssetLoader<Font>({
+  type: "font",
+  extensions: [".typeface.json"],
+  load: (asset, context) => {
     const fontLoader = new FontLoader(context.manager)
       .setPath(asset.path);
 
     return fontLoader.loadAsync(asset.name + asset.ext);
   }
-);
-
-export const font = Assets.lazyLoad<Font>();
+});
 
 export type { Font };

packages/engine/src/components/types.ts

@@ -1,5 +1,6 @@
 // Import Internal Dependencies
 import { Actor } from "../actor/Actor.ts";
+import type { AssetManager } from "../systems/index.ts";
 
 export type StrictComponentEnum =
   | "ScriptBehavior"
@@ -11,11 +12,16 @@ export type StrictComponentEnum =
 
 export type FreeComponentEnum = StrictComponentEnum | (string & {});
 
+export interface ComponentInitializeContext {
+  assetManager: AssetManager;
+}
+
 export interface Component {
   actor: Actor<any>;
   typeName: FreeComponentEnum;
   needUpdate: boolean;
 
+  initialize?(context: ComponentInitializeContext): Promise<void>;
   awake?(): void;
   start?(): void;
   update?(deltaTime: number): void;

packages/engine/src/systems/Scene.ts

@@ -6,8 +6,10 @@ import { EventEmitter } from "@posva/event-emitter";
 import type { World, WorldDefaultContext } from "./World.ts";
 import { IntegerIncrement } from "./generators/IntegerIncrement.ts";
 import type { Logger } from "./Logger.ts";
+import type { ComponentInitializeContext } from "../components/types.ts";
 
 export type SceneLifecycleEvents = {
+  initialize: [];
   awake: [];
   start: [];
   destroy: [];
@@ -44,6 +46,13 @@ export abstract class Scene<
     return this.#logger;
   }
 
+  /**
+   * Called once before awake(), asynchronously. Use this to declare asset dependencies
+   * via context.assetManager.load(). All declared assets will be fully loaded before
+   * awake() is called.
+   */
+  async initialize(_context: ComponentInitializeContext): Promise<void> {}
+
   /**
    * Called once when the scene is first activated (before the first start/update).
    * Populate actors here.