refactor(runtime)!: rename Player to Runtime and introduce GameInstance context (#152)

Author: fraxken

.changeset/thirty-ravens-crash.md

@@ -0,0 +1,5 @@
+---
+"@jolly-pixel/runtime": major
+---
+
+Rename Player to Runtime and introduce GameInstance context

packages/editors/model/src/index.ts

@@ -4,19 +4,19 @@ import {
   Camera3DControls,
   ModelRenderer
 } from "@jolly-pixel/engine";
-import { Player, loadPlayer } from "@jolly-pixel/runtime";
+import { Runtime, loadRuntime } from "@jolly-pixel/runtime";
 import * as THREE from "three";
 
 // Import Internal Dependencies
 import { PlayerBehavior } from "./PlayerBehavior.ts";
 
 const runtime = initRuntime();
-loadPlayer(runtime)
+loadRuntime(runtime)
   .catch(console.error);
 
 function initRuntime() {
   const canvasHTMLElement = document.querySelector("canvas") as HTMLCanvasElement;
-  const runtime = new Player(canvasHTMLElement, {
+  const runtime = new Runtime(canvasHTMLElement, {
     includePerformanceStats: true
   });
   const { gameInstance } = runtime;

packages/editors/voxel-map/src/index.ts

@@ -3,7 +3,7 @@ import {
   Actor,
   Camera3DControls
 } from "@jolly-pixel/engine";
-import { Player, loadPlayer } from "@jolly-pixel/runtime";
+import { Runtime, loadRuntime } from "@jolly-pixel/runtime";
 import { TreeView } from "@jolly-pixel/fs-tree/tree-view";
 
 // Import Internal Dependencies
@@ -14,12 +14,12 @@ const runtime = initRuntime();
 initTreeView();
 initCubeSelector();
 
-loadPlayer(runtime)
+loadRuntime(runtime)
   .catch(console.error);
 
 function initRuntime() {
   const canvasHTMLElement = document.querySelector("#game-container > canvas") as HTMLCanvasElement;
-  const runtime = new Player(canvasHTMLElement, {
+  const runtime = new Runtime(canvasHTMLElement, {
     includePerformanceStats: true
   });
   const { gameInstance } = runtime;

packages/editors/voxel-map/src/shapeEditor.ts

@@ -2,14 +2,14 @@
 import {
   Actor
 } from "@jolly-pixel/engine";
-import { Player, loadPlayer } from "@jolly-pixel/runtime";
+import { Runtime, loadRuntime } from "@jolly-pixel/runtime";
 import * as THREE from "three";
 
 // Import Internal Dependencies
 import { OrbitCameraControls } from "./components/OrbitCamera.ts";
 
 const canvasHTMLElement = document.querySelector("canvas") as HTMLCanvasElement;
-const runtime = new Player(canvasHTMLElement, {
+const runtime = new Runtime(canvasHTMLElement, {
   includePerformanceStats: true
 });
 const { gameInstance } = runtime;
@@ -30,7 +30,7 @@ const mesh = new THREE.Mesh(
 scene.add(new THREE.AmbientLight(new THREE.Color("#ffffff"), 3));
 scene.add(mesh);
 
-loadPlayer(runtime)
+loadRuntime(runtime)
   .catch(console.error);
 
 function createGeometry(size: number): THREE.BufferGeometry {

packages/experimental/src/index.ts

@@ -8,7 +8,7 @@ import {
   TextRenderer,
   createViewHelper
 } from "@jolly-pixel/engine";
-import { Player, loadPlayer } from "@jolly-pixel/runtime";
+import { Runtime, loadRuntime } from "@jolly-pixel/runtime";
 import * as THREE from "three";
 import { UnrealBloomPass } from "three/addons/postprocessing/UnrealBloomPass.js";
 import { OutputPass } from "three/addons/postprocessing/OutputPass.js";
@@ -17,7 +17,7 @@ import { OutputPass } from "three/addons/postprocessing/OutputPass.js";
 // import { SpriteRenderer } from "./components/sprite/SpriteRenderer.class.ts";
 
 const canvasHTMLElement = document.querySelector("canvas") as HTMLCanvasElement;
-const runtime = new Player(canvasHTMLElement, {
+const runtime = new Runtime(canvasHTMLElement, {
   includePerformanceStats: true
 });
 const { gameInstance } = runtime;
@@ -113,5 +113,5 @@ canvasHTMLElement.addEventListener("click", async() => {
   await ab.play("boss.tech-space");
 });
 
-loadPlayer(runtime)
+loadRuntime(runtime)
   .catch(console.error);

packages/experimental/src/indexUI.ts

@@ -4,10 +4,10 @@ import {
   UIRenderer,
   UISprite
 } from "@jolly-pixel/engine";
-import { Player, loadPlayer } from "@jolly-pixel/runtime";
+import { Runtime, loadRuntime } from "@jolly-pixel/runtime";
 
 const canvasHTMLElement = document.querySelector("canvas") as HTMLCanvasElement;
-const runtime = new Player(canvasHTMLElement, {
+const runtime = new Runtime(canvasHTMLElement, {
   includePerformanceStats: true
 });
 const { gameInstance } = runtime;
@@ -46,5 +46,5 @@ uiButton.onClick.connect(() => {
   console.log("Button clicked!");
 });
 
-loadPlayer(runtime)
+loadRuntime(runtime)
   .catch(console.error);

packages/runtime/ARCHITECTURE.md

@@ -7,8 +7,8 @@ and how its components interact during the lifecycle of a game session.
 
 ```
 src/
-├── index.ts               Entry point — exports Player and loadPlayer
-├── Player.ts              Core runtime class (game loop, renderer, clock)
+├── index.ts               Entry point — exports Runtime and loadRuntime
+├── Runtime.ts             Core runtime class (game loop, renderer, clock)
 ├── components/
 │   └── Loading.ts         <jolly-loading> Lit web component
 └── utils/
@@ -34,15 +34,15 @@ and the **engine** (`@jolly-pixel/engine`). It is responsible for:
                      │  provides <canvas>
                      ▼
 ┌─────────────────────────────────────────────────┐
-│                   loadPlayer()                  │
+│                   loadRuntime()                 │
 │  ┌───────────┐  ┌────────────┐  ┌────────────┐  │
 │  │  detect-  │  │  <jolly-   │  │   Assets   │  │
 │  │    gpu    │  │  loading>  │  │   loader   │  │
 │  └─────┬─────┘  └─────┬──────┘  └──────┬─────┘  │
 │        │              │                │        │
 │        ▼              ▼                ▼        │
 │  ┌──────────────────────────────────────────┐   │
-│  │                Player                    │   │
+│  │                Runtime                   │   │
 │  │  ┌────────────────────────────────────┐  │   │
 │  │  │          GameInstance              │  │   │
 │  │  │  (SceneEngine + ThreeRenderer)     │  │   │
@@ -54,11 +54,11 @@ and the **engine** (`@jolly-pixel/engine`). It is responsible for:
 
 ## Bootstrap sequence
 
-`loadPlayer()` orchestrates the full startup. Below is the ordered
+`loadRuntime()` orchestrates the full startup. Below is the ordered
 sequence of operations:
 
 ```
-loadPlayer(player)
+loadRuntime(runtime)
  │
  ├─ 1. Start GPU detection ─────────────── getGPUTier()  (async, runs in parallel)
  │
@@ -82,7 +82,7 @@ loadPlayer(player)
  │     ├─ fade-out ────────────────────── 500 ms
  │     └─ remove <jolly-loading>
  │
- └─ 8. Start player ───────────────────── player.start()
+ └─ 8. Start runtime ──────────────────── runtime.start()
        ├─ canvas opacity: 1               fade-in with CSS transition
        ├─ gameInstance.connect()
        └─ setAnimationLoop(tick)           game loop begins
@@ -93,7 +93,7 @@ loadPlayer(player)
 
 ## Game loop
 
-The `Player.tick` callback is called by Three.js via `setAnimationLoop`.
+The `Runtime.tick` callback is called by Three.js via `setAnimationLoop`.
 It implements a **fixed-timestep** pattern capped at the target FPS:
 
 ```
@@ -109,15 +109,15 @@ setAnimationLoop(tick)
      └─ if deltaTime >= interval
          ├─ stats.begin()
          ├─ gameInstance.update(deltaTime)
-         │   └─ returns true → player.stop()
+         │   └─ returns true → runtime.stop()
          ├─ gameInstance.render()
          ├─ deltaTime %= interval
          └─ stats.end()
 ```
 
 The loop stops when:
 - `gameInstance.update()` signals an exit
-- `player.stop()` is called manually
+- `runtime.stop()` is called manually
 
 ## Loading screen
 

packages/runtime/README.md

@@ -46,25 +46,25 @@ The runtime needs a `<canvas>` element to render into. Start by creating an HTML
 > [!TIP]
 > The `tabindex="-1"` attribute on the canvas allows it to receive keyboard focus, which is required for capturing input events.
 
-Then in your main script, create a `Player` instance and call `loadPlayer` to bootstrap everything (GPU detection, asset loading screen, game loop startup):
+Then in your main script, create a `Runtime` instance and call `loadRuntime` to bootstrap everything (GPU detection, asset loading screen, game loop startup):
 
 ```ts
-import { Player, loadPlayer } from "@jolly-pixel/runtime";
+import { Runtime, loadRuntime } from "@jolly-pixel/runtime";
 
 const canvas = document.querySelector("canvas")!;
 
-const player = new Player(canvas, {
+const runtime = new Runtime(canvas, {
   // Displays a stats.js FPS panel — useful during development
   includePerformanceStats: true
 });
 
 // The gameInstance gives you access to the engine systems
 // (scene, renderer, input, etc.)
-const { gameInstance } = player;
+const { gameInstance } = runtime;
 
-// loadPlayer will detect the GPU, show a loading screen,
+// loadRuntime will detect the GPU, show a loading screen,
 // load all registered assets, then start the game loop.
-loadPlayer(player)
+loadRuntime(runtime)
   .catch(console.error);
 ```
 
@@ -140,16 +140,16 @@ Finally, set the `main` field in your `package.json` to point to the Electron en
 
 ## 📚 API
 
-- [Player](./docs/Player.md)
+- [Runtime](./docs/Runtime.md)
 
-### `loadPlayer(player: Player, options?: LoadPlayerOptions)`
+### `loadRuntime(runtime: Runtime, options?: LoadRuntimeOptions)`
 
 Bootstraps the runtime by detecting GPU capabilities, displaying a loading screen, loading all registered assets, and starting the game loop.
 
 Returns a `Promise<void>` that resolves when loading completes, or shows an error on the loading screen if something fails.
 
 ```ts
-export interface LoadPlayerOptions {
+export interface LoadRuntimeOptions {
   /**
    * @default 850
    * Minimum delay (ms) before starting asset loading. Gives the loading UI time to render.

packages/runtime/docs/Player.md packages/runtime/docs/Runtime.mdpackages/runtime/docs/Player.md renamed to packages/runtime/docs/Runtime.md

@@ -1,4 +1,4 @@
-# Player
+# Runtime
 
 Main runtime class. Wraps a Three.js renderer, a game instance, and the
 update/render loop. Manages the full lifecycle: construction, starting,
@@ -9,16 +9,20 @@ stopping, and frame-rate control.
 - **setFps(fps)**: Clamps the target FPS between `1` and `60`. No-op if `fps` is falsy.
 
 ```ts
-interface PlayerOptions {
+interface RuntimeOptions<TContext = Record<string, unknown>> {
   /**
    * When true, a stats.js panel is appended to the document to show FPS.
    * @default false
    */
   includePerformanceStats?: boolean;
+  /**
+   * Optional context object passed to the GameInstance.
+   */
+  context?: TContext;
 }
 
-class Player {
-  gameInstance: Systems.GameInstance;
+class Runtime<TContext = Record<string, unknown>> {
+  gameInstance: Systems.GameInstance<THREE.WebGLRenderer, TContext>;
   canvas: HTMLCanvasElement;
   stats?: Stats;
   clock: THREE.Clock;
@@ -27,7 +31,7 @@ class Player {
 
   get running(): boolean;
 
-  constructor(canvas: HTMLCanvasElement, options?: PlayerOptions);
+  constructor(canvas: HTMLCanvasElement, options?: RuntimeOptions<TContext>);
 
   start(): void;
   stop(): void;
@@ -41,16 +45,35 @@ class Player {
 ## Usage
 
 ```ts
-import { Player, loadPlayer } from "@jolly-pixel/runtime";
+import { Runtime, loadRuntime } from "@jolly-pixel/runtime";
 
 const canvas = document.querySelector("canvas")!;
-const player = new Player(canvas, {
+const runtime = new Runtime(canvas, {
   includePerformanceStats: true
 });
 
-const { gameInstance } = player;
+const { gameInstance } = runtime;
 // Work with the gameInstance
 
-loadPlayer(player)
+loadRuntime(runtime)
   .catch(console.error);
 ```
+
+## Type-safe context
+
+The `TContext` generic lets you pass a typed context object to the
+underlying `GameInstance`:
+
+```ts
+interface MyContext {
+  score: number;
+  level: string;
+}
+
+const runtime = new Runtime<MyContext>(canvas, {
+  context: { score: 0, level: "intro" }
+});
+
+// runtime.gameInstance.context is typed as MyContext
+runtime.gameInstance.context.score; // number
+```

packages/runtime/src/Player.ts packages/runtime/src/Runtime.tspackages/runtime/src/Player.ts renamed to packages/runtime/src/Runtime.ts

@@ -3,18 +3,30 @@ import Stats from "stats.js";
 import * as THREE from "three";
 
 // Import Internal Dependencies
-import { Systems } from "@jolly-pixel/engine";
+import {
+  Systems,
+  type GlobalAudio
+} from "@jolly-pixel/engine";
 
-export interface PlayerOptions {
+export interface RuntimeOptions<TContext = Record<string, unknown>> {
   /**
    * @default false
    * Whether to include performance statistics (eg: FPS, memory usage).
    */
   includePerformanceStats?: boolean;
+  /**
+   * Optional context object passed to the GameInstance.
+   */
+  context?: TContext;
+  /**
+   * Optional global audio object passed to the GameInstance.
+   * If not provided, a default audio context will be created.
+   */
+  audio?: GlobalAudio;
 }
 
-export class Player {
-  gameInstance: Systems.GameInstance;
+export class Runtime<TContext = Record<string, unknown>> {
+  gameInstance: Systems.GameInstance<THREE.WebGLRenderer, TContext>;
   loop = new Systems.FixedTimeStep();
 
   canvas: HTMLCanvasElement;
@@ -25,7 +37,7 @@ export class Player {
 
   constructor(
     canvas: HTMLCanvasElement,
-    options: PlayerOptions = {}
+    options: RuntimeOptions<TContext> = Object.create(null)
   ) {
     if (!canvas) {
       throw new Error("Canvas element is required to create a Runtime instance.");
@@ -38,7 +50,9 @@ export class Player {
     ) as unknown as Systems.Renderer<THREE.WebGLRenderer>;
     this.gameInstance = new Systems.GameInstance(renderer, {
       enableOnExit: true,
-      scene
+      scene,
+      context: options.context,
+      audio: options.audio
     });
     this.gameInstance.setLoadingManager(this.manager);