@skewedaspect/sage 0.10.0 → 0.11.0

package/dist/classes/gameEngine.d.ts

@@ -20,8 +20,13 @@ import { GameTimer } from "../utils/timer.js";
  * Type definition for game lifecycle hook functions
  */
 export type GameHook<Registry extends NodeEntityRegistry = NodeEntityRegistry> = (gameEngine: GameEngine<Registry>) => Promise<void>;
+/** What a simulation is built with beside its scene and its name (design/architecture.md#how-a-game-consumes-sage). */
+export interface RebuildSimulationOptions {
+    meshSource?: MeshLoader;
+    fixedStepDuration?: number;
+}
 /** Builds a NodeSimulation named and bound to a scene and a mesh source -- a fresh one for every level that loads. */
-export type SimulationFactory<Registry extends NodeEntityRegistry = NodeEntityRegistry> = (scene: Scene, name: string, meshSource?: MeshLoader) => NodeSimulation<Registry>;
+export type SimulationFactory<Registry extends NodeEntityRegistry = NodeEntityRegistry> = (scene: Scene, name: string, options?: RebuildSimulationOptions) => NodeSimulation<Registry>;
 /**
  * Interface representing the engines used in the game.
  * All engines must implement Disposable for proper cleanup.
@@ -82,7 +87,7 @@ export declare class GameEngine<Registry extends NodeEntityRegistry = NodeEntity
      * NodeEntity it spawns gets a node in that scene and loads its mesh through that source; left unset, a spawned
      * entity gets a node with no mesh (design/simulation.md#the-simulations-name).
      */
-    rebuildSimulation(scene: Scene, name: string, meshSource?: MeshLoader): NodeSimulation<Registry>;
+    rebuildSimulation(scene: Scene, name: string, options?: RebuildSimulationOptions): NodeSimulation<Registry>;
     /**
      * Binds the engine to a simulation, or to none. The one bound before detaches from the bus and the new one
      * attaches, carrying its entities' subscriptions and held emissions across

package/dist/interfaces/game.d.ts

@@ -18,8 +18,8 @@ export type RenderEngineOptions = (BabylonEngineOptions | NullEngineOptions | We
  */
 export interface SageOptions {
     /**
-     * Babylon's own engine options, plus `engine`. Antialiasing and device pixel ratio adaptation are on
-     * unless these say otherwise.
+     * Babylon's own engine options, plus `engine`. Antialiasing, device pixel ratio adaptation, and
+     * `enableAllFeatures` are on unless these say otherwise. WebGL ignores `enableAllFeatures`.
      */
     renderOptions?: RenderEngineOptions;
     /** The level every logger starts at. */

package/dist/interfaces/level.d.ts

@@ -96,6 +96,8 @@ export interface LevelConfig {
      * entity this level spawns gets a node with no mesh.
      */
     meshSource?: MeshLoader;
+    /** The fixed-step duration, in seconds, of the simulation this level builds. Left unset, the engine's. */
+    fixedStepDuration?: number;
     /** Scene file path, or configuration object with path and options */
     scene?: string | SceneConfig;
     /** Name of a registered custom Level class to use instead of GameLevel */

package/dist/managers/asset.d.ts

@@ -1,4 +1,4 @@
-import { Mesh, AbstractMesh, AssetContainer, InstancedMesh, Scene } from '@babylonjs/core';
+import { Mesh, AbstractMesh, AssetContainer, InstancedMesh, InstantiatedEntries, Scene } from '@babylonjs/core';
 import { EventBus } from '@skewedaspect/sage-core';
 import { SceneEngine } from "../engines/scene.js";
 import { Disposable } from "../interfaces/lifecycle.js";
@@ -19,6 +19,11 @@ export declare class AssetManager implements Disposable {
     private _sourceMeshes;
     /** Container loads still in flight, keyed by base path, so concurrent callers share one load */
     private _pendingContainers;
+    /**
+     * Containers `instantiate` read for a caller's scene, keyed by that scene and then by base path. Each one is
+     * the scene's: Babylon disposes it with the scene, and a scene no one holds takes its entry with it.
+     */
+    private _sceneContainers;
     constructor(bus: EventBus, sceneEngine: SceneEngine, logger?: LoggingUtility);
     /**
      * Split a path on `#` into base path and optional fragment name.
@@ -39,6 +44,11 @@ export declare class AssetManager implements Disposable {
      * (design/engine.md#the-asset-manager).
      */
     private _fetchContainer;
+    /**
+     * The container for a base path read into the given scene, reading it on the first call. Calls made while
+     * the read is in flight share it. A read that fails is not remembered, so the next call reads again.
+     */
+    private _containerForScene;
     /**
      * Find a mesh by name inside a container. Throws if not found.
      */
@@ -67,6 +77,11 @@ export declare class AssetManager implements Disposable {
      * (design/engine.md#the-asset-manager).
      */
     clone(path: string, into: Scene): Mesh;
+    /**
+     * Copies a whole file into the scene it is handed: every mesh and node, with the file's skeletons and animation
+     * groups. The meshes are cloned and share the container's materials. The copy is the caller's to dispose.
+     */
+    instantiate(path: string, scene: Scene): Promise<InstantiatedEntries>;
     /**
      * Preload a batch of asset paths, up to `MAX_CONCURRENT_LOADS` at a time, so a batch costs about as
      * long as its slowest asset rather than the sum of them all.

package/dist/sage.d.ts

@@ -19,7 +19,7 @@ export declare function createGameEngine<Registry extends NodeEntityRegistry = N
 export * from "./interfaces/game.js";
 export * from "./interfaces/logger.js";
 export { AssetManager, AudioEngine, GameEngine, GameManager, LevelManager, SceneEngine };
-export type { DebugTools, Engines, GameHook, Managers, SimulationFactory } from "./classes/gameEngine.js";
+export type { DebugTools, Engines, GameHook, Managers, RebuildSimulationOptions, SimulationFactory, } from "./classes/gameEngine.js";
 export * from "./classes/level.js";
 export * from "./classes/gameLevel.js";
 export type { AssetCompletePayload, AssetProgressPayload, GamePausedPayload, GameResumedPayload, LevelCompletePayload, LevelErrorPayload, LevelProgressPayload, LevelTransitionCompletePayload, LevelTransitionErrorPayload, LevelTransitionProgressPayload, LevelTransitionStartPayload, TriggerEnterPayload, TriggerExitPayload, } from "./events/payloads.js";