Merge pull request #173 from JollyPixel/minimal-scene-implementation

Minimal scene implementation

Author: fraxken

.changeset/yellow-camels-add.md

@@ -0,0 +1,5 @@
+---
+"@jolly-pixel/engine": minor
+---
+
+Refactor SceneManager and implement minimal scene management

.claude/settings.local.json

@@ -135,3 +135,5 @@ dist
 .yarn/build-state.yml
 .yarn/install-state.gz
 .pnp.*
+
+.claude

.gitignore

@@ -0,0 +1,60 @@
+/* eslint-disable no-empty-function */
+// Import Third-party Dependencies
+import { EventEmitter } from "@posva/event-emitter";
+
+// Import Internal Dependencies
+import type { World, WorldDefaultContext } from "./World.ts";
+import { IntegerIncrement } from "./generators/IntegerIncrement.ts";
+
+export type SceneLifecycleEvents = {
+  awake: [];
+  start: [];
+  destroy: [];
+};
+
+export abstract class Scene<
+  TContext = WorldDefaultContext
+> extends EventEmitter<SceneLifecycleEvents> {
+  static readonly Id = new IntegerIncrement();
+
+  readonly id: number;
+  readonly name: string;
+
+  /** Set by SceneManager when the scene is activated. */
+  world!: World<any, TContext>;
+
+  constructor(name: string) {
+    super();
+    this.id = Scene.Id.incr();
+    this.name = name;
+  }
+
+  /**
+   * Called once when the scene is first activated (before the first start/update).
+   * Populate actors here.
+   */
+  awake(): void {}
+
+  /**
+   * Called once at the beginning of the first frame after awake.
+   * Useful for cross-actor initialization that requires all awake() calls to have run.
+   */
+  start(): void {}
+
+  /**
+   * Called every frame (variable rate).
+   */
+  update(_deltaTime: number): void {}
+
+  /**
+   * Called every fixed step (deterministic rate).
+   */
+  fixedUpdate(_deltaTime: number): void {}
+
+  /**
+   * Called when the scene is being replaced or explicitly unloaded.
+   * Clean up timers, subscriptions, etc. Actor destruction is handled
+   * automatically by SceneManager.
+   */
+  destroy(): void {}
+}

packages/engine/src/systems/Scene.ts

@@ -8,16 +8,30 @@ import {
   ActorComponent,
   ActorTree
 } from "../actor/index.ts";
-import type { WorldDefaultContext } from "./World.ts";
+import type { World, WorldDefaultContext } from "./World.ts";
 import type { Component } from "../components/types.ts";
+import type { Scene } from "./Scene.ts";
+
+export type AppendedSceneEntry<TContext> = {
+  scene: Scene<TContext>;
+  /**
+   * All actors created during the scene's awake(),
+   * tracked for cleanup on removeScene.
+   **/
+  ownedActors: ReadonlySet<Actor<TContext>>;
+};
 
-export type SceneEvents = {
+export type SceneEvents<TContext = WorldDefaultContext> = {
   awake: [];
+  sceneChanged: [scene: Scene<TContext>];
+  sceneDestroyed: [scene: Scene<TContext>];
+  sceneAppended: [scene: Scene<TContext>];
+  sceneRemoved: [scene: Scene<TContext>];
 };
 
 export class SceneManager<
   TContext = WorldDefaultContext
-> extends EventEmitter<SceneEvents> {
+> extends EventEmitter<SceneEvents<TContext>> {
   default: THREE.Scene;
 
   componentsToBeStarted: Component[] = [];
@@ -27,6 +41,14 @@ export class SceneManager<
   #actorsByName: Map<string, Actor<TContext>[]> = new Map();
   #cachedActors: Actor<TContext>[] = [];
 
+  #currentScene: Scene<TContext> | null = null;
+  #pendingScene: Scene<TContext> | null = null;
+  #sceneStartPending = false;
+  #world: World<any, TContext> | null = null;
+
+  #appendedScenes: Map<number, AppendedSceneEntry<TContext>> = new Map();
+  #appendedScenesPendingStart: Set<number> = new Set();
+
   readonly tree = new ActorTree<TContext>({
     addCallback: (actor) => this.default.add(actor.object3D),
     removeCallback: (actor) => this.default.remove(actor.object3D)
@@ -39,10 +61,24 @@ export class SceneManager<
     this.default = scene ?? new THREE.Scene();
   }
 
+  get currentScene(): Scene<TContext> | null {
+    return this.#currentScene;
+  }
+
+  get hasPendingScene(): boolean {
+    return this.#pendingScene !== null;
+  }
+
   getSource() {
     return this.default;
   }
 
+  bindWorld(
+    world: World<any, TContext>
+  ): void {
+    this.#world = world;
+  }
+
   awake() {
     for (const { actor } of this.tree.walk()) {
       if (!actor.awoken) {
@@ -53,7 +89,158 @@ export class SceneManager<
     this.emit("awake");
   }
 
+  setScene(
+    scene: Scene<TContext>
+  ): void {
+    if (this.#currentScene !== null) {
+      for (const entry of this.#appendedScenes.values()) {
+        this.emit("sceneRemoved", entry.scene);
+        entry.scene.destroy();
+      }
+      this.#appendedScenes.clear();
+      this.#appendedScenesPendingStart.clear();
+
+      this.emit("sceneDestroyed", this.#currentScene);
+      this.#currentScene.destroy();
+
+      const allActors = Array.from(this.#registeredActors);
+      for (const actor of allActors) {
+        this.destroyActor(actor);
+      }
+
+      this.componentsToBeStarted.length = 0;
+      this.componentsToBeDestroyed.length = 0;
+
+      this.default.clear();
+      this.#registeredActors.clear();
+      this.#actorsByName.clear();
+    }
+
+    scene.world = this.#world!;
+    this.#currentScene = scene;
+
+    scene.awake();
+    this.awake();
+
+    this.#sceneStartPending = true;
+    this.emit("sceneChanged", scene);
+  }
+
+  loadScene(
+    scene: Scene<TContext>
+  ): void {
+    this.#pendingScene = scene;
+  }
+
+  /**
+   * Inserts a scene as a prefab into the current scene.
+   * The scene's awake() is called immediately; start() is deferred to the next beginFrame.
+   * All actors created during awake() are tracked and will be destroyed on removeScene().
+   */
+  appendScene(
+    scene: Scene<TContext>
+  ): void {
+    const snapshot = new Set(this.#registeredActors);
+
+    scene.world = this.#world!;
+    scene.awake();
+
+    const ownedActors = new Set<Actor<TContext>>();
+    for (const actor of this.#registeredActors) {
+      if (!snapshot.has(actor)) {
+        ownedActors.add(actor);
+      }
+    }
+
+    // Awaken any actors created during awake() that haven't been woken yet
+    this.awake();
+
+    this.#appendedScenes.set(scene.id, { scene, ownedActors });
+    this.#appendedScenesPendingStart.add(scene.id);
+
+    this.emit("sceneAppended", scene);
+  }
+
+  removeScene(scene: Scene<TContext>): void;
+  removeScene(name: string): void;
+  removeScene(
+    target: Scene<TContext> | string
+  ): void {
+    if (typeof target === "string") {
+      for (const [id, entry] of this.#appendedScenes) {
+        if (entry.scene.name === target) {
+          this.#teardownAppendedScene(id, entry);
+        }
+      }
+    }
+    else {
+      const entry = this.#appendedScenes.get(target.id);
+      if (entry !== undefined) {
+        this.#teardownAppendedScene(target.id, entry);
+      }
+    }
+  }
+
+  #teardownAppendedScene(
+    id: number,
+    entry: AppendedSceneEntry<TContext>
+  ): void {
+    this.emit("sceneRemoved", entry.scene);
+    entry.scene.destroy();
+
+    // Destroy only root-level owned actors; destroyActor cascades to children
+    for (const actor of entry.ownedActors) {
+      if (actor.parent === null || !entry.ownedActors.has(actor.parent)) {
+        this.destroyActor(actor);
+      }
+    }
+
+    this.#appendedScenes.delete(id);
+    this.#appendedScenesPendingStart.delete(id);
+  }
+
+  getScene(): Scene<TContext> | null;
+  getScene(id: number): Scene<TContext> | null;
+  getScene(name: string): Scene<TContext>[];
+  getScene(
+    target?: number | string
+  ): Scene<TContext> | null | Scene<TContext>[] {
+    if (target === undefined) {
+      return this.#currentScene;
+    }
+
+    if (typeof target === "number") {
+      return this.#appendedScenes.get(target)?.scene ?? null;
+    }
+
+    const result: Scene<TContext>[] = [];
+    for (const entry of this.#appendedScenes.values()) {
+      if (entry.scene.name === target) {
+        result.push(entry.scene);
+      }
+    }
+
+    return result;
+  }
+
   beginFrame() {
+    if (this.#pendingScene !== null) {
+      this.setScene(this.#pendingScene);
+      this.#pendingScene = null;
+    }
+
+    if (this.#sceneStartPending) {
+      this.#currentScene?.start();
+      this.#sceneStartPending = false;
+    }
+
+    if (this.#appendedScenesPendingStart.size > 0) {
+      for (const id of this.#appendedScenesPendingStart) {
+        this.#appendedScenes.get(id)?.scene.start();
+      }
+      this.#appendedScenesPendingStart.clear();
+    }
+
     this.#cachedActors = Array.from(this.#registeredActors);
 
     let i = 0;
@@ -78,6 +265,11 @@ export class SceneManager<
     this.#cachedActors.forEach((actor) => {
       actor.fixedUpdate(deltaTime);
     });
+    this.#currentScene?.fixedUpdate(deltaTime);
+
+    for (const { scene } of this.#appendedScenes.values()) {
+      scene.fixedUpdate(deltaTime);
+    }
   }
 
   update(
@@ -86,6 +278,11 @@ export class SceneManager<
     this.#cachedActors.forEach((actor) => {
       actor.update(deltaTime);
     });
+    this.#currentScene?.update(deltaTime);
+
+    for (const { scene } of this.#appendedScenes.values()) {
+      scene.update(deltaTime);
+    }
   }
 
   endFrame() {
@@ -117,7 +314,10 @@ export class SceneManager<
 
     this.unregisterActor(actor);
 
-    // NOTE: make sure to remove deeply into the tree
+    // For root actors (parent === null): removes from tree.children and fires
+    // the removeCallback that detaches actor.object3D from the THREE.Scene.
+    // For non-root actors this is a no-op; actor.destroy() handles removal
+    // from the parent's children list via parent.remove(this).
     this.tree.remove(actor);
     actor.destroy();
   }

packages/engine/src/systems/SceneManager.ts

@@ -78,6 +78,7 @@ export class World<
     this.context = context;
     this.loop = new FixedTimeStep();
 
+    sceneManager.bindWorld(this);
     globalsAdapter.setGame(this);
   }
 

packages/engine/src/systems/World.ts

@@ -12,6 +12,7 @@ export type {
 } from "./asset/Registry.ts";
 
 export * from "./World.ts";
+export * from "./Scene.ts";
 export * from "./FixedTimeStep.ts";
 export * from "./rendering/index.ts";
 export * from "./SceneManager.ts";