@codexo/exojs-tilemap 0.15.2 → 0.16.0

package/dist/esm/MapWorld.js

@@ -0,0 +1,150 @@
+//#region src/MapWorld.ts
+/**
+* Where a neighbouring level sits relative to the level that names it.
+*
+* `Overlap`, `Below` and `Above` describe depth relationships rather than
+* cardinal directions - a source format that stacks levels (LDtk's depth
+* layers) reports those. `Unknown` preserves an adjacency whose direction code
+* this version does not recognise: the levels are neighbours, but the side is
+* not interpretable.
+*/
+const MapLevelSide = {
+	North: "north",
+	South: "south",
+	West: "west",
+	East: "east",
+	Overlap: "overlap",
+	Below: "below",
+	Above: "above",
+	Unknown: "unknown"
+};
+const EMPTY_BOUNDS = Object.freeze({
+	x: 0,
+	y: 0,
+	width: 0,
+	height: 0
+});
+/**
+* A format-neutral description of how levels are laid out in a world.
+*
+* A `MapWorld` holds metadata only - no tiles, no textures, no runtime maps.
+* It is what a game reads to decide which levels it needs; loading them is
+* {@link import('./MapWorldRuntime').MapWorldRuntime}'s job.
+*
+* Adapters build one from their source document
+* (`@codexo/exojs-ldtk` does so from a `.ldtk` project). A format with no world
+* concept of its own - Tiled, today - can be described by constructing one
+* directly from whatever placement data the game keeps.
+*
+* @example
+* ```ts
+* const world = new MapWorld({
+*   name: 'overworld',
+*   levels: [
+*     { id: 'forest', name: 'Forest', index: 0, external: false,
+*       bounds: { x: 0, y: 0, width: 512, height: 512 },
+*       neighbours: [{ id: 'cave', side: MapLevelSide.East }], properties: {} },
+*   ],
+* });
+* ```
+*/
+var MapWorld = class {
+	/** World name; empty when the source format does not name it. */
+	name;
+	/** The world's levels, in source document order. */
+	levels;
+	_byId;
+	_byName;
+	_bounds;
+	constructor(options) {
+		this.name = options.name ?? "";
+		this.levels = Object.freeze([...options.levels]);
+		const byId = /* @__PURE__ */ new Map();
+		const byName = /* @__PURE__ */ new Map();
+		for (const level of this.levels) {
+			if (byId.has(level.id)) throw new Error(`MapWorld: duplicate level id "${level.id}" - level ids must be unique within a world.`);
+			byId.set(level.id, level);
+			if (!byName.has(level.name)) byName.set(level.name, level);
+		}
+		this._byId = byId;
+		this._byName = byName;
+	}
+	/**
+	* Union of every level's bounds, or a zero rectangle for an empty world.
+	* Computed once and cached - a `MapWorld` is immutable.
+	*/
+	get bounds() {
+		if (this._bounds !== void 0) return this._bounds;
+		if (this.levels.length === 0) {
+			this._bounds = EMPTY_BOUNDS;
+			return this._bounds;
+		}
+		let minX = Number.POSITIVE_INFINITY;
+		let minY = Number.POSITIVE_INFINITY;
+		let maxX = Number.NEGATIVE_INFINITY;
+		let maxY = Number.NEGATIVE_INFINITY;
+		for (const level of this.levels) {
+			const b = level.bounds;
+			if (b.x < minX) minX = b.x;
+			if (b.y < minY) minY = b.y;
+			if (b.x + b.width > maxX) maxX = b.x + b.width;
+			if (b.y + b.height > maxY) maxY = b.y + b.height;
+		}
+		this._bounds = Object.freeze({
+			x: minX,
+			y: minY,
+			width: maxX - minX,
+			height: maxY - minY
+		});
+		return this._bounds;
+	}
+	/** The level with this {@link MapLevel.id}, or `undefined`. Constant time. */
+	getLevel(id) {
+		return this._byId.get(id);
+	}
+	/**
+	* The first level in document order whose {@link MapLevel.name} matches, or
+	* `undefined`. Constant time. Names are not unique by contract.
+	*/
+	getLevelByName(name) {
+		return this._byName.get(name);
+	}
+	/**
+	* The levels `id` declares as adjacent, resolved to their metadata and in the
+	* order the source format declared them.
+	*
+	* A neighbour naming a level this world does not contain is skipped - LDtk
+	* can reference across worlds of a multi-world project, and each of those
+	* worlds is its own `MapWorld`. Returns an empty array for an unknown `id`.
+	*/
+	getNeighbours(id) {
+		const level = this._byId.get(id);
+		if (level === void 0) return [];
+		const out = [];
+		for (const neighbour of level.neighbours) {
+			const resolved = this._byId.get(neighbour.id);
+			if (resolved !== void 0) out.push(resolved);
+		}
+		return out;
+	}
+	/**
+	* Every level whose bounds intersect `bounds`, in document order. Edge
+	* contact alone does not count as an intersection, so two levels laid out
+	* side by side are not reported for a query that only touches the seam.
+	*
+	* Linear in the number of levels - intended for a per-camera-move query over
+	* a world of hundreds of levels, not for a per-frame query over thousands.
+	*/
+	getLevelsInBounds(bounds) {
+		const out = [];
+		for (const level of this.levels) {
+			const b = level.bounds;
+			if (b.x < bounds.x + bounds.width && bounds.x < b.x + b.width && b.y < bounds.y + bounds.height && bounds.y < b.y + b.height) out.push(level);
+		}
+		return out;
+	}
+};
+
+//#endregion
+export { MapLevelSide, MapWorld };
+//# sourceMappingURL=MapWorld.js.map

package/dist/esm/MapWorld.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapWorld.js","names":[],"sources":["../../src/MapWorld.ts"],"sourcesContent":["import type { TileProperties } from './types';\n\n/** An axis-aligned rectangle in world pixel space (+Y down). */\nexport interface MapBounds {\n  readonly x: number;\n  readonly y: number;\n  readonly width: number;\n  readonly height: number;\n}\n\n/**\n * Where a neighbouring level sits relative to the level that names it.\n *\n * `Overlap`, `Below` and `Above` describe depth relationships rather than\n * cardinal directions - a source format that stacks levels (LDtk's depth\n * layers) reports those. `Unknown` preserves an adjacency whose direction code\n * this version does not recognise: the levels are neighbours, but the side is\n * not interpretable.\n */\nexport const MapLevelSide = {\n  North: 'north',\n  South: 'south',\n  West: 'west',\n  East: 'east',\n  Overlap: 'overlap',\n  Below: 'below',\n  Above: 'above',\n  Unknown: 'unknown',\n} as const;\n\n/** Side discriminant for a {@link MapLevelNeighbour}. */\nexport type MapLevelSide = (typeof MapLevelSide)[keyof typeof MapLevelSide];\n\n/** One adjacency edge from a level to another level in the same {@link MapWorld}. */\nexport interface MapLevelNeighbour {\n  /** {@link MapLevel.id} of the neighbouring level. */\n  readonly id: string;\n  readonly side: MapLevelSide;\n}\n\n/**\n * Immutable metadata for one level of a {@link MapWorld} - everything needed to\n * decide whether to load it, without loading it.\n */\nexport interface MapLevel {\n  /**\n   * Stable identity, unique within the world. Carried from the source format\n   * (LDtk uses the level `iid`), so it survives re-ordering and re-export and\n   * is safe to persist in a savegame.\n   */\n  readonly id: string;\n  /** Human-readable level name. Not guaranteed unique. */\n  readonly name: string;\n  /** Position in source document order. */\n  readonly index: number;\n  /** Placement and size in world pixel space. */\n  readonly bounds: MapBounds;\n  /**\n   * Whether the level's layer payload lives outside the root document and has\n   * to be fetched separately when the level is loaded.\n   */\n  readonly external: boolean;\n  /** Adjacency edges declared by the source format; empty when it declares none. */\n  readonly neighbours: readonly MapLevelNeighbour[];\n  /** Level-level custom properties. */\n  readonly properties: TileProperties;\n}\n\n/** Construction options for a {@link MapWorld}. */\nexport interface MapWorldOptions {\n  /** World name. Defaults to an empty string. */\n  readonly name?: string;\n  /** The world's levels, in source document order. */\n  readonly levels: readonly MapLevel[];\n}\n\nconst EMPTY_BOUNDS: MapBounds = Object.freeze({ x: 0, y: 0, width: 0, height: 0 });\n\n/**\n * A format-neutral description of how levels are laid out in a world.\n *\n * A `MapWorld` holds metadata only - no tiles, no textures, no runtime maps.\n * It is what a game reads to decide which levels it needs; loading them is\n * {@link import('./MapWorldRuntime').MapWorldRuntime}'s job.\n *\n * Adapters build one from their source document\n * (`@codexo/exojs-ldtk` does so from a `.ldtk` project). A format with no world\n * concept of its own - Tiled, today - can be described by constructing one\n * directly from whatever placement data the game keeps.\n *\n * @example\n * ```ts\n * const world = new MapWorld({\n *   name: 'overworld',\n *   levels: [\n *     { id: 'forest', name: 'Forest', index: 0, external: false,\n *       bounds: { x: 0, y: 0, width: 512, height: 512 },\n *       neighbours: [{ id: 'cave', side: MapLevelSide.East }], properties: {} },\n *   ],\n * });\n * ```\n */\nexport class MapWorld {\n  /** World name; empty when the source format does not name it. */\n  public readonly name: string;\n  /** The world's levels, in source document order. */\n  public readonly levels: readonly MapLevel[];\n\n  private readonly _byId: ReadonlyMap<string, MapLevel>;\n  private readonly _byName: ReadonlyMap<string, MapLevel>;\n  private _bounds?: MapBounds;\n\n  public constructor(options: MapWorldOptions) {\n    this.name = options.name ?? '';\n    this.levels = Object.freeze([...options.levels]);\n\n    const byId = new Map<string, MapLevel>();\n    const byName = new Map<string, MapLevel>();\n\n    for (const level of this.levels) {\n      if (byId.has(level.id)) {\n        throw new Error(`MapWorld: duplicate level id \"${level.id}\" - level ids must be unique within a world.`);\n      }\n\n      byId.set(level.id, level);\n      // Names are not unique by contract; first in document order wins so the\n      // lookup stays deterministic instead of depending on iteration order.\n      if (!byName.has(level.name)) byName.set(level.name, level);\n    }\n\n    this._byId = byId;\n    this._byName = byName;\n  }\n\n  /**\n   * Union of every level's bounds, or a zero rectangle for an empty world.\n   * Computed once and cached - a `MapWorld` is immutable.\n   */\n  public get bounds(): MapBounds {\n    if (this._bounds !== undefined) return this._bounds;\n\n    if (this.levels.length === 0) {\n      this._bounds = EMPTY_BOUNDS;\n      return this._bounds;\n    }\n\n    let minX = Number.POSITIVE_INFINITY;\n    let minY = Number.POSITIVE_INFINITY;\n    let maxX = Number.NEGATIVE_INFINITY;\n    let maxY = Number.NEGATIVE_INFINITY;\n\n    for (const level of this.levels) {\n      const b = level.bounds;\n      if (b.x < minX) minX = b.x;\n      if (b.y < minY) minY = b.y;\n      if (b.x + b.width > maxX) maxX = b.x + b.width;\n      if (b.y + b.height > maxY) maxY = b.y + b.height;\n    }\n\n    this._bounds = Object.freeze({ x: minX, y: minY, width: maxX - minX, height: maxY - minY });\n    return this._bounds;\n  }\n\n  /** The level with this {@link MapLevel.id}, or `undefined`. Constant time. */\n  public getLevel(id: string): MapLevel | undefined {\n    return this._byId.get(id);\n  }\n\n  /**\n   * The first level in document order whose {@link MapLevel.name} matches, or\n   * `undefined`. Constant time. Names are not unique by contract.\n   */\n  public getLevelByName(name: string): MapLevel | undefined {\n    return this._byName.get(name);\n  }\n\n  /**\n   * The levels `id` declares as adjacent, resolved to their metadata and in the\n   * order the source format declared them.\n   *\n   * A neighbour naming a level this world does not contain is skipped - LDtk\n   * can reference across worlds of a multi-world project, and each of those\n   * worlds is its own `MapWorld`. Returns an empty array for an unknown `id`.\n   */\n  public getNeighbours(id: string): readonly MapLevel[] {\n    const level = this._byId.get(id);\n    if (level === undefined) return [];\n\n    const out: MapLevel[] = [];\n\n    for (const neighbour of level.neighbours) {\n      const resolved = this._byId.get(neighbour.id);\n      if (resolved !== undefined) out.push(resolved);\n    }\n\n    return out;\n  }\n\n  /**\n   * Every level whose bounds intersect `bounds`, in document order. Edge\n   * contact alone does not count as an intersection, so two levels laid out\n   * side by side are not reported for a query that only touches the seam.\n   *\n   * Linear in the number of levels - intended for a per-camera-move query over\n   * a world of hundreds of levels, not for a per-frame query over thousands.\n   */\n  public getLevelsInBounds(bounds: MapBounds): MapLevel[] {\n    const out: MapLevel[] = [];\n\n    for (const level of this.levels) {\n      const b = level.bounds;\n      if (b.x < bounds.x + bounds.width && bounds.x < b.x + b.width && b.y < bounds.y + bounds.height && bounds.y < b.y + b.height) {\n        out.push(level);\n      }\n    }\n\n    return out;\n  }\n}\n"],"mappings":";;;;;;;;;;AAmBA,MAAa,eAAe;CAC1B,OAAO;CACP,OAAO;CACP,MAAM;CACN,MAAM;CACN,SAAS;CACT,OAAO;CACP,OAAO;CACP,SAAS;AACX;AAgDA,MAAM,eAA0B,OAAO,OAAO;CAAE,GAAG;CAAG,GAAG;CAAG,OAAO;CAAG,QAAQ;AAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;AA0BjF,IAAa,WAAb,MAAsB;;CAEpB,AAAgB;;CAEhB,AAAgB;CAEhB,AAAiB;CACjB,AAAiB;CACjB,AAAQ;CAER,AAAO,YAAY,SAA0B;EAC3C,KAAK,OAAO,QAAQ,QAAQ;EAC5B,KAAK,SAAS,OAAO,OAAO,CAAC,GAAG,QAAQ,MAAM,CAAC;EAE/C,MAAM,uBAAO,IAAI,IAAsB;EACvC,MAAM,yBAAS,IAAI,IAAsB;EAEzC,KAAK,MAAM,SAAS,KAAK,QAAQ;GAC/B,IAAI,KAAK,IAAI,MAAM,EAAE,GACnB,MAAM,IAAI,MAAM,iCAAiC,MAAM,GAAG,6CAA6C;GAGzG,KAAK,IAAI,MAAM,IAAI,KAAK;GAGxB,IAAI,CAAC,OAAO,IAAI,MAAM,IAAI,GAAG,OAAO,IAAI,MAAM,MAAM,KAAK;EAC3D;EAEA,KAAK,QAAQ;EACb,KAAK,UAAU;CACjB;;;;;CAMA,IAAW,SAAoB;EAC7B,IAAI,KAAK,YAAY,QAAW,OAAO,KAAK;EAE5C,IAAI,KAAK,OAAO,WAAW,GAAG;GAC5B,KAAK,UAAU;GACf,OAAO,KAAK;EACd;EAEA,IAAI,OAAO,OAAO;EAClB,IAAI,OAAO,OAAO;EAClB,IAAI,OAAO,OAAO;EAClB,IAAI,OAAO,OAAO;EAElB,KAAK,MAAM,SAAS,KAAK,QAAQ;GAC/B,MAAM,IAAI,MAAM;GAChB,IAAI,EAAE,IAAI,MAAM,OAAO,EAAE;GACzB,IAAI,EAAE,IAAI,MAAM,OAAO,EAAE;GACzB,IAAI,EAAE,IAAI,EAAE,QAAQ,MAAM,OAAO,EAAE,IAAI,EAAE;GACzC,IAAI,EAAE,IAAI,EAAE,SAAS,MAAM,OAAO,EAAE,IAAI,EAAE;EAC5C;EAEA,KAAK,UAAU,OAAO,OAAO;GAAE,GAAG;GAAM,GAAG;GAAM,OAAO,OAAO;GAAM,QAAQ,OAAO;EAAK,CAAC;EAC1F,OAAO,KAAK;CACd;;CAGA,AAAO,SAAS,IAAkC;EAChD,OAAO,KAAK,MAAM,IAAI,EAAE;CAC1B;;;;;CAMA,AAAO,eAAe,MAAoC;EACxD,OAAO,KAAK,QAAQ,IAAI,IAAI;CAC9B;;;;;;;;;CAUA,AAAO,cAAc,IAAiC;EACpD,MAAM,QAAQ,KAAK,MAAM,IAAI,EAAE;EAC/B,IAAI,UAAU,QAAW,OAAO,CAAC;EAEjC,MAAM,MAAkB,CAAC;EAEzB,KAAK,MAAM,aAAa,MAAM,YAAY;GACxC,MAAM,WAAW,KAAK,MAAM,IAAI,UAAU,EAAE;GAC5C,IAAI,aAAa,QAAW,IAAI,KAAK,QAAQ;EAC/C;EAEA,OAAO;CACT;;;;;;;;;CAUA,AAAO,kBAAkB,QAA+B;EACtD,MAAM,MAAkB,CAAC;EAEzB,KAAK,MAAM,SAAS,KAAK,QAAQ;GAC/B,MAAM,IAAI,MAAM;GAChB,IAAI,EAAE,IAAI,OAAO,IAAI,OAAO,SAAS,OAAO,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,OAAO,IAAI,OAAO,UAAU,OAAO,IAAI,EAAE,IAAI,EAAE,QACpH,IAAI,KAAK,KAAK;EAElB;EAEA,OAAO;CACT;AACF"}

package/dist/esm/MapWorldRuntime.d.ts

@@ -0,0 +1,182 @@
+import type { Destroyable, LoaderScope } from '@codexo/exojs';
+import type { MapObjectSpawner } from './MapObjectSpawner';
+import type { MapSpawnSession } from './MapSpawnSession';
+import type { MapLevel, MapWorld } from './MapWorld';
+import type { TileMap } from './TileMap';
+/** What a {@link MapLevelProvider} is given for one level load. */
+export interface MapLevelLoadContext {
+    /** Metadata of the level being loaded. */
+    readonly level: MapLevel;
+    /**
+     * The level's own {@link LoaderScope}. Assets claimed through it are released
+     * when the level unloads, and claiming an asset another level also holds
+     * never takes it away from that level.
+     *
+     * Its lifetime ends when {@link signal} aborts: an unload releases the scope
+     * without waiting for a provider still in flight, so a provider that resumes
+     * after that point must not claim through it any more. Check `signal.aborted`
+     * after every `await` before touching the scope again.
+     */
+    readonly scope: LoaderScope;
+    /** Aborts when the level is unloaded or the load is cancelled. */
+    readonly signal: AbortSignal;
+}
+/**
+ * Produces the runtime {@link TileMap} for one level - the single seam where a
+ * source format meets the format-neutral world runtime.
+ *
+ * Anything awaitable is accepted, so a provider can hand back a
+ * {@link LoaderScope.load} queue directly.
+ *
+ * The returned map becomes **owned by that level runtime**, which destroys it
+ * on unload. Return a map built for this load; handing back a shared map (an
+ * entry of an eagerly converted document, say) makes the runtime destroy an
+ * object other code still holds.
+ */
+export type MapLevelProvider = (context: MapLevelLoadContext) => TileMap | PromiseLike<TileMap>;
+/** Options for {@link MapWorldRuntime}. */
+export interface MapWorldRuntimeOptions {
+    /** The world metadata to stream levels out of. */
+    readonly world: MapWorld;
+    /** Builds a level's runtime map. See {@link MapLevelProvider} for its ownership rule. */
+    readonly load: MapLevelProvider;
+    /**
+     * Parent scope for everything the runtime loads - typically `scene.loader`.
+     *
+     * The runtime creates its own child scope under it and never destroys the
+     * scope it was given: the caller keeps owning that lifetime.
+     */
+    readonly scope: LoaderScope;
+    /** Diagnostic name for the runtime's own scope. Defaults to the world's name. */
+    readonly name?: string;
+}
+/** Options for a {@link MapWorldRuntime.loadLevel} that spawns nothing. */
+export interface MapLevelCancelOptions {
+    /** Cancels this load. Unloading the level cancels it too. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Options for a {@link MapWorldRuntime.loadLevel} that also spawns the level's
+ * map objects. `spawner` and `context` travel together: the context exists to
+ * be handed to that spawner's factories.
+ */
+export interface MapLevelLoadOptions<Context, Result extends Destroyable> extends MapLevelCancelOptions {
+    /** Spawns the level's map objects as part of the load. */
+    readonly spawner: MapObjectSpawner<Context, Result>;
+    /** Value handed to every factory of `spawner`. */
+    readonly context: Context;
+}
+/**
+ * One loaded level and everything that load produced.
+ *
+ * Created by {@link MapWorldRuntime.loadLevel}; destroying it unloads the
+ * level. There is nothing else to release afterwards - the map, the spawned
+ * objects and the level's asset claims all end here.
+ *
+ * @typeParam Result - what the level's spawner produced, if it had one.
+ */
+export declare class MapLevelRuntime<Result extends Destroyable = Destroyable> implements Destroyable {
+    /** {@link MapLevel.id} of the loaded level. */
+    readonly id: string;
+    /** Metadata of the loaded level. */
+    readonly level: MapLevel;
+    /** The level's asset scope. Released last, after everything that could hold an asset is gone. */
+    readonly scope: LoaderScope;
+    /** The level's runtime map, owned by this runtime. */
+    readonly map: TileMap;
+    /** What the level's spawner produced, or `null` when the load ran without one. */
+    readonly spawns: MapSpawnSession<Result> | null;
+    private readonly _onDestroy;
+    private _destroyed;
+    /** Level runtimes are produced by {@link MapWorldRuntime.loadLevel}. @internal */
+    constructor(level: MapLevel, scope: LoaderScope, map: TileMap, spawns: MapSpawnSession<Result> | null, onDestroy: (runtime: MapLevelRuntime) => void);
+    /** Whether this level has been unloaded. */
+    get destroyed(): boolean;
+    /**
+     * Unload the level: destroy the spawned objects (reverse spawn order), then
+     * the map, then release the level's asset claims. Idempotent.
+     *
+     * The scope goes last because everything before it may still be reading a
+     * texture the scope keeps resident.
+     */
+    destroy(): void;
+}
+/**
+ * The live side of a {@link MapWorld}: loads and unloads levels on demand, each
+ * with its own asset scope and its own lifetime.
+ *
+ * ExoJS provides the mechanism, not the streaming policy. Nothing here watches
+ * a camera or guesses a radius: game code reads
+ * {@link MapWorld.getNeighbours} / {@link MapWorld.getLevelsInBounds} and calls
+ * {@link loadLevel} and {@link unloadLevel} when it decides to.
+ *
+ * Scope layout - the runtime owns everything below its own scope and nothing
+ * above it:
+ *
+ * ```text
+ * scene.loader          (given to the runtime, never destroyed by it)
+ *  └─ world             (the runtime's own scope)
+ *      ├─ level:forest
+ *      └─ level:cave
+ * ```
+ *
+ * @example
+ * ```ts
+ * const runtime = new MapWorldRuntime({
+ *   world,
+ *   scope: scene.loader,
+ *   load: ({ level, scope, signal }) => buildLevelMap(level, scope, signal),
+ * });
+ *
+ * const forest = await runtime.loadLevel('forest', { spawner, context });
+ * scene.addChild(forest.map.createView().root);
+ *
+ * runtime.unloadLevel('forest');
+ * ```
+ */
+export declare class MapWorldRuntime implements Destroyable {
+    /** The world this runtime streams levels out of. */
+    readonly world: MapWorld;
+    /** The runtime's own scope: parent of every level scope, child of the injected one. */
+    readonly scope: LoaderScope;
+    private readonly _load;
+    private readonly _live;
+    private readonly _inFlight;
+    private _destroyed;
+    constructor(options: MapWorldRuntimeOptions);
+    /** Whether {@link destroy} has run. */
+    get destroyed(): boolean;
+    /**
+     * Every currently **loaded** level, in load order - not the world's level
+     * set, which stays on {@link MapWorld.levels} (reachable as
+     * `runtime.world.levels`). Returns a fresh array.
+     */
+    get levels(): readonly MapLevelRuntime[];
+    /** The loaded level with this id, or `undefined` when it is not loaded. */
+    getLevel(id: string): MapLevelRuntime | undefined;
+    /** Whether the level is loaded. A load still in flight does not count as loaded. */
+    isLoaded(id: string): boolean;
+    /** Whether a load for this level is currently running. */
+    isLoading(id: string): boolean;
+    loadLevel(id: string, options?: MapLevelCancelOptions): Promise<MapLevelRuntime>;
+    loadLevel<Context, Result extends Destroyable>(id: string, options: MapLevelLoadOptions<Context, Result>): Promise<MapLevelRuntime<Result>>;
+    /**
+     * Unload a level, or cancel its load when one is in flight. Returns whether
+     * there was anything to unload.
+     *
+     * A cancelled load rejects with an `AbortError` for whoever started it, and
+     * the level is immediately loadable again - a `loadLevel` issued in the same
+     * turn starts a fresh load rather than joining the one just cancelled.
+     */
+    unloadLevel(id: string): boolean;
+    /**
+     * Cancel every load in flight, unload every loaded level in reverse load
+     * order, and release the runtime's own scope. Idempotent.
+     *
+     * The scope the runtime was constructed with is left alone - it belongs to
+     * whoever passed it in.
+     */
+    destroy(): void;
+    private _runLoad;
+}
+//# sourceMappingURL=MapWorldRuntime.d.ts.map

package/dist/esm/MapWorldRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapWorldRuntime.d.ts","sourceRoot":"","sources":["../../src/MapWorldRuntime.ts"],"names":[],"mappings":"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"}

package/dist/esm/MapWorldRuntime.js

@@ -0,0 +1,261 @@
+import { logger } from "@codexo/exojs";
+
+//#region src/MapWorldRuntime.ts
+/**
+* One loaded level and everything that load produced.
+*
+* Created by {@link MapWorldRuntime.loadLevel}; destroying it unloads the
+* level. There is nothing else to release afterwards - the map, the spawned
+* objects and the level's asset claims all end here.
+*
+* @typeParam Result - what the level's spawner produced, if it had one.
+*/
+var MapLevelRuntime = class {
+	/** {@link MapLevel.id} of the loaded level. */
+	id;
+	/** Metadata of the loaded level. */
+	level;
+	/** The level's asset scope. Released last, after everything that could hold an asset is gone. */
+	scope;
+	/** The level's runtime map, owned by this runtime. */
+	map;
+	/** What the level's spawner produced, or `null` when the load ran without one. */
+	spawns;
+	_onDestroy;
+	_destroyed = false;
+	/** Level runtimes are produced by {@link MapWorldRuntime.loadLevel}. @internal */
+	constructor(level, scope, map, spawns, onDestroy) {
+		this.id = level.id;
+		this.level = level;
+		this.scope = scope;
+		this.map = map;
+		this.spawns = spawns;
+		this._onDestroy = onDestroy;
+	}
+	/** Whether this level has been unloaded. */
+	get destroyed() {
+		return this._destroyed;
+	}
+	/**
+	* Unload the level: destroy the spawned objects (reverse spawn order), then
+	* the map, then release the level's asset claims. Idempotent.
+	*
+	* The scope goes last because everything before it may still be reading a
+	* texture the scope keeps resident.
+	*/
+	destroy() {
+		if (this._destroyed) return;
+		this._destroyed = true;
+		this._onDestroy(this);
+		if (this.spawns !== null) guardedDestroy(this.spawns, `spawn session of level "${this.id}"`);
+		guardedDestroy(this.map, `map of level "${this.id}"`);
+		this.scope.destroy();
+	}
+};
+/**
+* The live side of a {@link MapWorld}: loads and unloads levels on demand, each
+* with its own asset scope and its own lifetime.
+*
+* ExoJS provides the mechanism, not the streaming policy. Nothing here watches
+* a camera or guesses a radius: game code reads
+* {@link MapWorld.getNeighbours} / {@link MapWorld.getLevelsInBounds} and calls
+* {@link loadLevel} and {@link unloadLevel} when it decides to.
+*
+* Scope layout - the runtime owns everything below its own scope and nothing
+* above it:
+*
+* ```text
+* scene.loader          (given to the runtime, never destroyed by it)
+*  └─ world             (the runtime's own scope)
+*      ├─ level:forest
+*      └─ level:cave
+* ```
+*
+* @example
+* ```ts
+* const runtime = new MapWorldRuntime({
+*   world,
+*   scope: scene.loader,
+*   load: ({ level, scope, signal }) => buildLevelMap(level, scope, signal),
+* });
+*
+* const forest = await runtime.loadLevel('forest', { spawner, context });
+* scene.addChild(forest.map.createView().root);
+*
+* runtime.unloadLevel('forest');
+* ```
+*/
+var MapWorldRuntime = class {
+	/** The world this runtime streams levels out of. */
+	world;
+	/** The runtime's own scope: parent of every level scope, child of the injected one. */
+	scope;
+	_load;
+	_live = /* @__PURE__ */ new Map();
+	_inFlight = /* @__PURE__ */ new Map();
+	_destroyed = false;
+	constructor(options) {
+		this.world = options.world;
+		this._load = options.load;
+		this.scope = options.scope.createScope({ name: options.name ?? (this.world.name || "world") });
+	}
+	/** Whether {@link destroy} has run. */
+	get destroyed() {
+		return this._destroyed;
+	}
+	/**
+	* Every currently **loaded** level, in load order - not the world's level
+	* set, which stays on {@link MapWorld.levels} (reachable as
+	* `runtime.world.levels`). Returns a fresh array.
+	*/
+	get levels() {
+		return [...this._live.values()];
+	}
+	/** The loaded level with this id, or `undefined` when it is not loaded. */
+	getLevel(id) {
+		return this._live.get(id);
+	}
+	/** Whether the level is loaded. A load still in flight does not count as loaded. */
+	isLoaded(id) {
+		return this._live.has(id);
+	}
+	/** Whether a load for this level is currently running. */
+	isLoading(id) {
+		return this._inFlight.has(id);
+	}
+	/**
+	* Load a level, or return the one already loaded.
+	*
+	* At most one runtime exists per level id. Calling this while the level is
+	* loaded resolves to that runtime, and calling it while a load is in flight
+	* joins that load rather than starting a second one. **Options belong to the
+	* call that actually starts the load** - a joining call's `spawner`,
+	* `context` and `signal` are not applied, because the level being produced is
+	* the one the first call asked for.
+	*
+	* Pass `{ spawner, context }` to spawn the level's objects as part of the
+	* load, or just `{ signal }` to load a level without spawning anything.
+	*
+	* A failed or aborted load leaves nothing behind: the map, anything the
+	* spawner created, and the level's asset claims are all released before the
+	* rejection surfaces, and the level can be loaded again.
+	*
+	* @throws {Error} when the world has no level with this id, or the runtime is destroyed.
+	* @throws {DOMException} named `AbortError` when the load is cancelled.
+	*/
+	loadLevel(id, options) {
+		const typed = (promise) => promise;
+		if (this._destroyed) return Promise.reject(/* @__PURE__ */ new Error(`MapWorldRuntime: cannot load level "${id}" - the runtime is destroyed.`));
+		const live = this._live.get(id);
+		if (live !== void 0) return typed(Promise.resolve(live));
+		const pending = this._inFlight.get(id);
+		if (pending !== void 0) return typed(pending.promise);
+		const level = this.world.getLevel(id);
+		if (level === void 0) return Promise.reject(/* @__PURE__ */ new Error(`MapWorldRuntime: world "${this.world.name}" has no level with id "${id}".`));
+		const controller = new AbortController();
+		const signal = options?.signal;
+		const forward = () => controller.abort();
+		if (signal !== void 0) {
+			if (signal.aborted) return Promise.reject(new DOMException(`Level "${id}" load was cancelled.`, "AbortError"));
+			signal.addEventListener("abort", forward, { once: true });
+		}
+		const promise = this._runLoad(level, controller.signal, options).finally(() => {
+			signal?.removeEventListener("abort", forward);
+			if (this._inFlight.get(id)?.controller === controller) this._inFlight.delete(id);
+		});
+		this._inFlight.set(id, {
+			promise,
+			controller
+		});
+		return typed(promise);
+	}
+	/**
+	* Unload a level, or cancel its load when one is in flight. Returns whether
+	* there was anything to unload.
+	*
+	* A cancelled load rejects with an `AbortError` for whoever started it, and
+	* the level is immediately loadable again - a `loadLevel` issued in the same
+	* turn starts a fresh load rather than joining the one just cancelled.
+	*/
+	unloadLevel(id) {
+		const pending = this._inFlight.get(id);
+		if (pending !== void 0) {
+			this._inFlight.delete(id);
+			pending.controller.abort();
+			return true;
+		}
+		const live = this._live.get(id);
+		if (live !== void 0) {
+			live.destroy();
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Cancel every load in flight, unload every loaded level in reverse load
+	* order, and release the runtime's own scope. Idempotent.
+	*
+	* The scope the runtime was constructed with is left alone - it belongs to
+	* whoever passed it in.
+	*/
+	destroy() {
+		if (this._destroyed) return;
+		this._destroyed = true;
+		const pending = [...this._inFlight.values()];
+		this._inFlight.clear();
+		for (const load of pending) load.controller.abort();
+		for (const runtime of [...this._live.values()].reverse()) guardedDestroy(runtime, `level "${runtime.id}"`);
+		this._live.clear();
+		this.scope.destroy();
+	}
+	async _runLoad(level, signal, options) {
+		const scope = this.scope.createScope({ name: `level:${level.id}` });
+		let map;
+		let spawns = null;
+		try {
+			throwIfAborted(level.id, signal);
+			map = await this._load({
+				level,
+				scope,
+				signal
+			});
+			throwIfAborted(level.id, signal);
+			if (options !== void 0 && "spawner" in options) {
+				spawns = await options.spawner.spawn(map, options.context, { signal });
+				throwIfAborted(level.id, signal);
+			}
+		} catch (error) {
+			if (spawns !== null) guardedDestroy(spawns, `spawn session of level "${level.id}"`);
+			if (map !== void 0) guardedDestroy(map, `map of level "${level.id}"`);
+			scope.destroy();
+			throw error;
+		}
+		const runtime = new MapLevelRuntime(level, scope, map, spawns, (destroyed) => {
+			if (this._live.get(destroyed.id) === destroyed) this._live.delete(destroyed.id);
+		});
+		this._live.set(level.id, runtime);
+		return runtime;
+	}
+};
+/**
+* Teardown step that reports a failure instead of propagating it, so the steps
+* after it still run. Matches how the application reports a subsystem that
+* fails to dispose.
+*/
+const guardedDestroy = (target, what) => {
+	try {
+		target.destroy();
+	} catch (error) {
+		logger.error(`MapWorldRuntime: destroying the ${what} failed; continuing teardown.`, {
+			source: "tilemap",
+			...error instanceof Error && { error }
+		});
+	}
+};
+const throwIfAborted = (id, signal) => {
+	if (signal.aborted) throw new DOMException(`Level "${id}" load was cancelled.`, "AbortError");
+};
+
+//#endregion
+export { MapLevelRuntime, MapWorldRuntime };
+//# sourceMappingURL=MapWorldRuntime.js.map

package/dist/esm/MapWorldRuntime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapWorldRuntime.js","names":[],"sources":["../../src/MapWorldRuntime.ts"],"sourcesContent":["import type { Destroyable, LoaderScope } from '@codexo/exojs';\nimport { logger } from '@codexo/exojs';\n\nimport type { MapObjectSpawner } from './MapObjectSpawner';\nimport type { MapSpawnSession } from './MapSpawnSession';\nimport type { MapLevel, MapWorld } from './MapWorld';\nimport type { TileMap } from './TileMap';\n\n/** What a {@link MapLevelProvider} is given for one level load. */\nexport interface MapLevelLoadContext {\n  /** Metadata of the level being loaded. */\n  readonly level: MapLevel;\n  /**\n   * The level's own {@link LoaderScope}. Assets claimed through it are released\n   * when the level unloads, and claiming an asset another level also holds\n   * never takes it away from that level.\n   *\n   * Its lifetime ends when {@link signal} aborts: an unload releases the scope\n   * without waiting for a provider still in flight, so a provider that resumes\n   * after that point must not claim through it any more. Check `signal.aborted`\n   * after every `await` before touching the scope again.\n   */\n  readonly scope: LoaderScope;\n  /** Aborts when the level is unloaded or the load is cancelled. */\n  readonly signal: AbortSignal;\n}\n\n/**\n * Produces the runtime {@link TileMap} for one level - the single seam where a\n * source format meets the format-neutral world runtime.\n *\n * Anything awaitable is accepted, so a provider can hand back a\n * {@link LoaderScope.load} queue directly.\n *\n * The returned map becomes **owned by that level runtime**, which destroys it\n * on unload. Return a map built for this load; handing back a shared map (an\n * entry of an eagerly converted document, say) makes the runtime destroy an\n * object other code still holds.\n */\nexport type MapLevelProvider = (context: MapLevelLoadContext) => TileMap | PromiseLike<TileMap>;\n\n/** Options for {@link MapWorldRuntime}. */\nexport interface MapWorldRuntimeOptions {\n  /** The world metadata to stream levels out of. */\n  readonly world: MapWorld;\n  /** Builds a level's runtime map. See {@link MapLevelProvider} for its ownership rule. */\n  readonly load: MapLevelProvider;\n  /**\n   * Parent scope for everything the runtime loads - typically `scene.loader`.\n   *\n   * The runtime creates its own child scope under it and never destroys the\n   * scope it was given: the caller keeps owning that lifetime.\n   */\n  readonly scope: LoaderScope;\n  /** Diagnostic name for the runtime's own scope. Defaults to the world's name. */\n  readonly name?: string;\n}\n\n/** Options for a {@link MapWorldRuntime.loadLevel} that spawns nothing. */\nexport interface MapLevelCancelOptions {\n  /** Cancels this load. Unloading the level cancels it too. */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Options for a {@link MapWorldRuntime.loadLevel} that also spawns the level's\n * map objects. `spawner` and `context` travel together: the context exists to\n * be handed to that spawner's factories.\n */\nexport interface MapLevelLoadOptions<Context, Result extends Destroyable> extends MapLevelCancelOptions {\n  /** Spawns the level's map objects as part of the load. */\n  readonly spawner: MapObjectSpawner<Context, Result>;\n  /** Value handed to every factory of `spawner`. */\n  readonly context: Context;\n}\n\n/**\n * One loaded level and everything that load produced.\n *\n * Created by {@link MapWorldRuntime.loadLevel}; destroying it unloads the\n * level. There is nothing else to release afterwards - the map, the spawned\n * objects and the level's asset claims all end here.\n *\n * @typeParam Result - what the level's spawner produced, if it had one.\n */\nexport class MapLevelRuntime<Result extends Destroyable = Destroyable> implements Destroyable {\n  /** {@link MapLevel.id} of the loaded level. */\n  public readonly id: string;\n  /** Metadata of the loaded level. */\n  public readonly level: MapLevel;\n  /** The level's asset scope. Released last, after everything that could hold an asset is gone. */\n  public readonly scope: LoaderScope;\n  /** The level's runtime map, owned by this runtime. */\n  public readonly map: TileMap;\n  /** What the level's spawner produced, or `null` when the load ran without one. */\n  public readonly spawns: MapSpawnSession<Result> | null;\n\n  private readonly _onDestroy: (runtime: MapLevelRuntime) => void;\n  private _destroyed = false;\n\n  /** Level runtimes are produced by {@link MapWorldRuntime.loadLevel}. @internal */\n  public constructor(level: MapLevel, scope: LoaderScope, map: TileMap, spawns: MapSpawnSession<Result> | null, onDestroy: (runtime: MapLevelRuntime) => void) {\n    this.id = level.id;\n    this.level = level;\n    this.scope = scope;\n    this.map = map;\n    this.spawns = spawns;\n    this._onDestroy = onDestroy;\n  }\n\n  /** Whether this level has been unloaded. */\n  public get destroyed(): boolean {\n    return this._destroyed;\n  }\n\n  /**\n   * Unload the level: destroy the spawned objects (reverse spawn order), then\n   * the map, then release the level's asset claims. Idempotent.\n   *\n   * The scope goes last because everything before it may still be reading a\n   * texture the scope keeps resident.\n   */\n  public destroy(): void {\n    if (this._destroyed) return;\n\n    this._destroyed = true;\n    this._onDestroy(this);\n\n    // A failure in one step must not strand the next: the scope is what holds\n    // the level's asset claims, and skipping it leaks them for good.\n    if (this.spawns !== null) guardedDestroy(this.spawns, `spawn session of level \"${this.id}\"`);\n    guardedDestroy(this.map, `map of level \"${this.id}\"`);\n    this.scope.destroy();\n  }\n}\n\ninterface InFlightLoad {\n  readonly promise: Promise<MapLevelRuntime>;\n  readonly controller: AbortController;\n}\n\n/**\n * The live side of a {@link MapWorld}: loads and unloads levels on demand, each\n * with its own asset scope and its own lifetime.\n *\n * ExoJS provides the mechanism, not the streaming policy. Nothing here watches\n * a camera or guesses a radius: game code reads\n * {@link MapWorld.getNeighbours} / {@link MapWorld.getLevelsInBounds} and calls\n * {@link loadLevel} and {@link unloadLevel} when it decides to.\n *\n * Scope layout - the runtime owns everything below its own scope and nothing\n * above it:\n *\n * ```text\n * scene.loader          (given to the runtime, never destroyed by it)\n *  └─ world             (the runtime's own scope)\n *      ├─ level:forest\n *      └─ level:cave\n * ```\n *\n * @example\n * ```ts\n * const runtime = new MapWorldRuntime({\n *   world,\n *   scope: scene.loader,\n *   load: ({ level, scope, signal }) => buildLevelMap(level, scope, signal),\n * });\n *\n * const forest = await runtime.loadLevel('forest', { spawner, context });\n * scene.addChild(forest.map.createView().root);\n *\n * runtime.unloadLevel('forest');\n * ```\n */\nexport class MapWorldRuntime implements Destroyable {\n  /** The world this runtime streams levels out of. */\n  public readonly world: MapWorld;\n  /** The runtime's own scope: parent of every level scope, child of the injected one. */\n  public readonly scope: LoaderScope;\n\n  private readonly _load: MapLevelProvider;\n  private readonly _live = new Map<string, MapLevelRuntime>();\n  private readonly _inFlight = new Map<string, InFlightLoad>();\n  private _destroyed = false;\n\n  public constructor(options: MapWorldRuntimeOptions) {\n    this.world = options.world;\n    this._load = options.load;\n    this.scope = options.scope.createScope({ name: options.name ?? (this.world.name || 'world') });\n  }\n\n  /** Whether {@link destroy} has run. */\n  public get destroyed(): boolean {\n    return this._destroyed;\n  }\n\n  /**\n   * Every currently **loaded** level, in load order - not the world's level\n   * set, which stays on {@link MapWorld.levels} (reachable as\n   * `runtime.world.levels`). Returns a fresh array.\n   */\n  public get levels(): readonly MapLevelRuntime[] {\n    return [...this._live.values()];\n  }\n\n  /** The loaded level with this id, or `undefined` when it is not loaded. */\n  public getLevel(id: string): MapLevelRuntime | undefined {\n    return this._live.get(id);\n  }\n\n  /** Whether the level is loaded. A load still in flight does not count as loaded. */\n  public isLoaded(id: string): boolean {\n    return this._live.has(id);\n  }\n\n  /** Whether a load for this level is currently running. */\n  public isLoading(id: string): boolean {\n    return this._inFlight.has(id);\n  }\n\n  public loadLevel(id: string, options?: MapLevelCancelOptions): Promise<MapLevelRuntime>;\n  public loadLevel<Context, Result extends Destroyable>(id: string, options: MapLevelLoadOptions<Context, Result>): Promise<MapLevelRuntime<Result>>;\n  /**\n   * Load a level, or return the one already loaded.\n   *\n   * At most one runtime exists per level id. Calling this while the level is\n   * loaded resolves to that runtime, and calling it while a load is in flight\n   * joins that load rather than starting a second one. **Options belong to the\n   * call that actually starts the load** - a joining call's `spawner`,\n   * `context` and `signal` are not applied, because the level being produced is\n   * the one the first call asked for.\n   *\n   * Pass `{ spawner, context }` to spawn the level's objects as part of the\n   * load, or just `{ signal }` to load a level without spawning anything.\n   *\n   * A failed or aborted load leaves nothing behind: the map, anything the\n   * spawner created, and the level's asset claims are all released before the\n   * rejection surfaces, and the level can be loaded again.\n   *\n   * @throws {Error} when the world has no level with this id, or the runtime is destroyed.\n   * @throws {DOMException} named `AbortError` when the load is cancelled.\n   */\n  public loadLevel<Context = void, Result extends Destroyable = Destroyable>(\n    id: string,\n    options?: MapLevelLoadOptions<Context, Result> | MapLevelCancelOptions,\n  ): Promise<MapLevelRuntime<Result>> {\n    // The live map erases Result - one runtime holds levels loaded with\n    // different spawners - while every call site keeps its own through the\n    // signature above.\n    const typed = (promise: Promise<MapLevelRuntime>): Promise<MapLevelRuntime<Result>> => promise as Promise<MapLevelRuntime<Result>>;\n\n    if (this._destroyed) {\n      return Promise.reject(new Error(`MapWorldRuntime: cannot load level \"${id}\" - the runtime is destroyed.`));\n    }\n\n    const live = this._live.get(id);\n    if (live !== undefined) return typed(Promise.resolve(live));\n\n    const pending = this._inFlight.get(id);\n    if (pending !== undefined) return typed(pending.promise);\n\n    const level = this.world.getLevel(id);\n    if (level === undefined) {\n      return Promise.reject(new Error(`MapWorldRuntime: world \"${this.world.name}\" has no level with id \"${id}\".`));\n    }\n\n    const controller = new AbortController();\n    const signal = options?.signal;\n    const forward = (): void => controller.abort();\n\n    if (signal !== undefined) {\n      if (signal.aborted) {\n        return Promise.reject(new DOMException(`Level \"${id}\" load was cancelled.`, 'AbortError'));\n      }\n\n      signal.addEventListener('abort', forward, { once: true });\n    }\n\n    const promise = this._runLoad(level, controller.signal, options).finally(() => {\n      // The caller's signal can outlive the load by a lot - a scene-lifetime\n      // signal would otherwise accumulate one listener per level loaded.\n      signal?.removeEventListener('abort', forward);\n\n      // Only clear the entry this call installed: an unload during the load\n      // may already have started a fresh one under the same id.\n      if (this._inFlight.get(id)?.controller === controller) this._inFlight.delete(id);\n    });\n\n    this._inFlight.set(id, { promise, controller });\n\n    return typed(promise);\n  }\n\n  /**\n   * Unload a level, or cancel its load when one is in flight. Returns whether\n   * there was anything to unload.\n   *\n   * A cancelled load rejects with an `AbortError` for whoever started it, and\n   * the level is immediately loadable again - a `loadLevel` issued in the same\n   * turn starts a fresh load rather than joining the one just cancelled.\n   */\n  public unloadLevel(id: string): boolean {\n    const pending = this._inFlight.get(id);\n\n    if (pending !== undefined) {\n      // Drop the slot before aborting: the abort surfaces as a rejection one\n      // microtask later, so a same-turn reload would otherwise join the load\n      // that is on its way out and reject with it.\n      this._inFlight.delete(id);\n      pending.controller.abort();\n      return true;\n    }\n\n    const live = this._live.get(id);\n\n    if (live !== undefined) {\n      live.destroy();\n      return true;\n    }\n\n    return false;\n  }\n\n  /**\n   * Cancel every load in flight, unload every loaded level in reverse load\n   * order, and release the runtime's own scope. Idempotent.\n   *\n   * The scope the runtime was constructed with is left alone - it belongs to\n   * whoever passed it in.\n   */\n  public destroy(): void {\n    if (this._destroyed) return;\n\n    this._destroyed = true;\n\n    const pending = [...this._inFlight.values()];\n    this._inFlight.clear();\n\n    for (const load of pending) {\n      load.controller.abort();\n    }\n\n    // One level's teardown must not strand the levels after it, nor the\n    // runtime's own scope - the assets those still hold would leak.\n    for (const runtime of [...this._live.values()].reverse()) {\n      guardedDestroy(runtime, `level \"${runtime.id}\"`);\n    }\n\n    this._live.clear();\n    this.scope.destroy();\n  }\n\n  private async _runLoad<Context, Result extends Destroyable>(\n    level: MapLevel,\n    signal: AbortSignal,\n    options: MapLevelLoadOptions<Context, Result> | MapLevelCancelOptions | undefined,\n  ): Promise<MapLevelRuntime> {\n    const scope = this.scope.createScope({ name: `level:${level.id}` });\n    let map: TileMap | undefined;\n    let spawns: MapSpawnSession<Result> | null = null;\n\n    try {\n      throwIfAborted(level.id, signal);\n\n      map = await this._load({ level, scope, signal });\n\n      throwIfAborted(level.id, signal);\n\n      if (options !== undefined && 'spawner' in options) {\n        spawns = await options.spawner.spawn(map, options.context, { signal });\n        throwIfAborted(level.id, signal);\n      }\n    } catch (error) {\n      // The scope must be released even when tearing down what came before it\n      // fails, or the level's asset claims outlive the failed load forever.\n      if (spawns !== null) guardedDestroy(spawns, `spawn session of level \"${level.id}\"`);\n      if (map !== undefined) guardedDestroy(map, `map of level \"${level.id}\"`);\n      scope.destroy();\n      throw error;\n    }\n\n    const runtime = new MapLevelRuntime<Result>(level, scope, map, spawns, destroyed => {\n      if (this._live.get(destroyed.id) === destroyed) this._live.delete(destroyed.id);\n    });\n\n    this._live.set(level.id, runtime);\n\n    return runtime;\n  }\n}\n\n/**\n * Teardown step that reports a failure instead of propagating it, so the steps\n * after it still run. Matches how the application reports a subsystem that\n * fails to dispose.\n */\nconst guardedDestroy = (target: Destroyable, what: string): void => {\n  try {\n    target.destroy();\n  } catch (error) {\n    logger.error(`MapWorldRuntime: destroying the ${what} failed; continuing teardown.`, {\n      source: 'tilemap',\n      ...(error instanceof Error && { error }),\n    });\n  }\n};\n\nconst throwIfAborted = (id: string, signal: AbortSignal): void => {\n  if (signal.aborted) {\n    throw new DOMException(`Level \"${id}\" load was cancelled.`, 'AbortError');\n  }\n};\n"],"mappings":"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"}