@fonsecabarreto/genesis-gl-core 0.1.0 → 0.1.1

package/README.md

@@ -8,7 +8,7 @@ GenesisGL is a lightweight browser-side WebGL 3D engine written in TypeScript.
 npm install @fonsecabarreto/genesis-gl-core
 ```
 
-## Usage
+## Quick Start
 
 ```ts
 import { WebGLCore, Scene, Renderer, Viewport } from '@fonsecabarreto/genesis-gl-core';
@@ -19,7 +19,20 @@ const viewport = new Viewport(canvas, window.innerWidth, window.innerHeight, web
 const renderer = new Renderer(webglCore, viewport);
 const scene = Scene.withDefaultLights(webglCore);
 
-// Add models and render loop...
+// Add models, implement render loop, etc.
+```
+
+## Sub-path Imports
+
+```ts
+// Editor utilities (visual editor, scene/material stores)
+import { MaterialStore, SceneStore } from '@fonsecabarreto/genesis-gl-core/Editor';
+
+// Game utilities (characters, physics, animations)
+import { Character, InteractiveActor } from '@fonsecabarreto/genesis-gl-core/Game';
+
+// OBJ/GLB loaders
+import { loadOBJWithMTL, GLBLoader } from '@fonsecabarreto/genesis-gl-core/Core/utils';
 ```
 
 ## Build
@@ -28,6 +41,10 @@ const scene = Scene.withDefaultLights(webglCore);
 yarn build
 ```
 
+## API Documentation
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for a detailed API overview.
+
 ## License
 
 MIT

package/dist/{Camera-DY_8gx3C.d.ts → Camera-CJVYy9fH.d.ts}

@@ -19,11 +19,22 @@ declare class Camera {
     far: number;
     lastViewMatrix?: Float32Array;
     lastProjectionMatrix?: Float32Array;
+    private readonly _view;
+    private readonly _proj;
+    private readonly _mvp;
+    private _viewDirty;
+    private _projDirty;
     constructor(viewportWidth: number, viewportHeight: number);
     /** Translate the camera by a delta. */
     move(dx: number, dy: number, dz?: number): void;
     /** Clamp-set the zoom level. */
     setZoom(zoom: number): void;
+    /**
+     * Mark the view matrix as dirty so it is rebuilt on the next
+     * {@link getViewMatrix} call.  Call this after directly mutating
+     * {@link target} or {@link position} (e.g. from a follow-camera update).
+     */
+    invalidate(): void;
     /** Zoom by a signed delta (positive = zoom in). */
     zoomBy(delta: number): void;
     worldToNDC(x: number, y: number): [number, number];
@@ -31,9 +42,9 @@ declare class Camera {
     setViewport(width: number, height: number): void;
     /** Compute the eye position from yaw/pitch/distance to target. */
     getComputedPosition(): vec3;
-    /** Build the view matrix (lookAt). */
+    /** Build the view matrix (lookAt). Returns a cached matrix rebuilt only when the camera moves. */
     getViewMatrix(): mat4;
-    /** Build the perspective projection matrix. */
+    /** Build the perspective projection matrix. Returns a cached matrix rebuilt only when viewport/zoom changes. */
     getProjectionMatrix(): mat4;
     worldToNDC3D(x: number, y: number, z?: number): [number, number, number];
     worldScale3D(scale: [number, number, number]): [number, number, number];

package/dist/Core/classes/Material.d.ts

@@ -1,3 +1,3 @@
 import '../domain/interfaces/Vectors.js';
-export { M as MAX_LIGHTS, b as Material } from '../../Material-BGLkldxv.js';
+export { M as MAX_LIGHTS, b as Material } from '../../Material-DhwSRbP2.js';
 import '../../WebGLCore-DR7ZHJB0.js';

package/dist/Core/classes/Material.js

@@ -1,7 +1,7 @@
 import {
   MAX_LIGHTS,
   Material
-} from "../../chunk-6LS6AO5H.js";
+} from "../../chunk-L66K4AZU.js";
 export {
   MAX_LIGHTS,
   Material

package/dist/Core/classes/Model.d.ts

@@ -1,5 +1,5 @@
-export { i as Model } from '../../Model-CQvDXd-b.js';
+import 'gl-matrix';
+export { i as Model } from '../../Model-BBZHnUp1.js';
 import '../domain/interfaces/Vectors.js';
 import '../../WebGLCore-DR7ZHJB0.js';
-import '../../Material-BGLkldxv.js';
-import 'gl-matrix';
+import '../../Material-DhwSRbP2.js';

package/dist/Core/classes/Model.js

@@ -1,6 +1,6 @@
 import {
   Model
-} from "../../chunk-JK2HEZAT.js";
+} from "../../chunk-QOAQVTAB.js";
 export {
   Model
 };

package/dist/Core/classes/Renderer.d.ts

@@ -1,11 +1,11 @@
-import { mat4 } from 'gl-matrix';
 import { W as WebGLCore } from '../../WebGLCore-DR7ZHJB0.js';
 import { Scene } from './Scene.js';
-import { i as Model } from '../../Model-CQvDXd-b.js';
+import { i as Model } from '../../Model-BBZHnUp1.js';
 import { Viewport } from './Viewport.js';
-import '../../Material-BGLkldxv.js';
+import '../../Material-DhwSRbP2.js';
 import '../domain/interfaces/Vectors.js';
-import '../../Camera-DY_8gx3C.js';
+import 'gl-matrix';
+import '../../Camera-CJVYy9fH.js';
 
 declare class Renderer {
     private webglCore;
@@ -14,6 +14,12 @@ declare class Renderer {
     debug: boolean;
     private _modelHitboxMaterial;
     private _meshHitboxMaterial;
+    private readonly _modelWireBoxCache;
+    private readonly _meshWireBoxCache;
+    /** Pre-allocated identity matrix for world-space hitbox draws. */
+    private readonly _identity;
+    /** Cached `gl instanceof WebGL2RenderingContext` — computed once at construction. */
+    private readonly _isWebGL2;
     constructor(webglCore: WebGLCore, viewport: Viewport);
     /** Lazily-created material for model-level hitboxes (red). */
     private get modelHitboxMaterial();
@@ -23,7 +29,7 @@ declare class Renderer {
     render(scene: Scene): void;
     private drawModel;
     private drawMesh;
-    drawHitBox(model: Model, modelMatrix: mat4, activeProgram: WebGLProgram | null): void;
+    drawHitBox(model: Model, activeProgram: WebGLProgram | null): void;
     private drawHitBoxForMesh;
 }
 

package/dist/Core/classes/Renderer.js

@@ -1,10 +1,10 @@
 import {
   Renderer
-} from "../../chunk-QCQVJCSR.js";
-import "../../chunk-6LS6AO5H.js";
-import "../../chunk-JK2HEZAT.js";
+} from "../../chunk-ZCJ3MJZD.js";
+import "../../chunk-L66K4AZU.js";
+import "../../chunk-QOAQVTAB.js";
 import "../../chunk-3ULETMWF.js";
-import "../../chunk-5TAAXI6S.js";
+import "../../chunk-XMW2MS66.js";
 export {
   Renderer
 };

package/dist/Core/classes/Scene.d.ts

@@ -1,5 +1,5 @@
-import { L as Light } from '../../Material-BGLkldxv.js';
-import { i as Model } from '../../Model-CQvDXd-b.js';
+import { L as Light } from '../../Material-DhwSRbP2.js';
+import { i as Model } from '../../Model-BBZHnUp1.js';
 import { W as WebGLCore } from '../../WebGLCore-DR7ZHJB0.js';
 import '../domain/interfaces/Vectors.js';
 import 'gl-matrix';

package/dist/Core/classes/Viewport.d.ts

@@ -1,4 +1,4 @@
-import { C as Camera } from '../../Camera-DY_8gx3C.js';
+import { C as Camera } from '../../Camera-CJVYy9fH.js';
 import { W as WebGLCore } from '../../WebGLCore-DR7ZHJB0.js';
 import 'gl-matrix';
 import '../domain/interfaces/Vectors.js';

package/dist/Core/classes/Viewport.js

@@ -1,6 +1,6 @@
 import {
   Viewport
-} from "../../chunk-5TAAXI6S.js";
+} from "../../chunk-XMW2MS66.js";
 export {
   Viewport
 };

package/dist/Core/index.d.ts

@@ -1,10 +1,10 @@
-export { A as AnimationChannel, a as AnimationClip, b as AnimationPath, c as AnimationSampler, G as GL_LINES, d as GL_TRIANGLES, I as INITIAL_BOUNDING_BOX, e as InterpolationMode, J as Joint, f as JointPose, M as MAX_JOINTS, g as Mesh, h as MeshBuffers, i as Model, S as Skeleton } from '../Model-CQvDXd-b.js';
+export { A as AnimationChannel, a as AnimationClip, b as AnimationPath, c as AnimationSampler, G as GL_LINES, d as GL_TRIANGLES, I as INITIAL_BOUNDING_BOX, e as InterpolationMode, J as Joint, f as JointPose, M as MAX_JOINTS, g as Mesh, h as MeshBuffers, i as Model, S as Skeleton } from '../Model-BBZHnUp1.js';
 export { R as RenderCallback, W as WebGLCore } from '../WebGLCore-DR7ZHJB0.js';
-export { C as Camera } from '../Camera-DY_8gx3C.js';
-export { L as Light, a as LightType, M as MAX_LIGHTS, b as Material } from '../Material-BGLkldxv.js';
+export { C as Camera } from '../Camera-CJVYy9fH.js';
+export { L as Light, a as LightType, M as MAX_LIGHTS, b as Material } from '../Material-DhwSRbP2.js';
 export { Renderer } from './classes/Renderer.js';
 export { Scene } from './classes/Scene.js';
 export { Viewport } from './classes/Viewport.js';
 export { K as KeyboardControl } from '../KeyboardControl-5w7Vm0J0.js';
-import './domain/interfaces/Vectors.js';
 import 'gl-matrix';
+import './domain/interfaces/Vectors.js';

package/dist/Core/index.js

@@ -12,14 +12,14 @@ import {
   Renderer,
   Skeleton,
   WebGLCore
-} from "../chunk-QCQVJCSR.js";
+} from "../chunk-ZCJ3MJZD.js";
 import {
   MAX_LIGHTS,
   Material
-} from "../chunk-6LS6AO5H.js";
+} from "../chunk-L66K4AZU.js";
 import {
   Model
-} from "../chunk-JK2HEZAT.js";
+} from "../chunk-QOAQVTAB.js";
 import {
   Light,
   Scene
@@ -27,7 +27,7 @@ import {
 import {
   Camera,
   Viewport
-} from "../chunk-5TAAXI6S.js";
+} from "../chunk-XMW2MS66.js";
 export {
   AnimationClip,
   Camera,

package/dist/Core/utils/load-glb.d.ts

@@ -1,8 +1,8 @@
 import { W as WebGLCore } from '../../WebGLCore-DR7ZHJB0.js';
-import { i as Model, S as Skeleton, a as AnimationClip } from '../../Model-CQvDXd-b.js';
-import '../domain/interfaces/Vectors.js';
-import '../../Material-BGLkldxv.js';
+import { i as Model, S as Skeleton, a as AnimationClip } from '../../Model-BBZHnUp1.js';
 import 'gl-matrix';
+import '../domain/interfaces/Vectors.js';
+import '../../Material-DhwSRbP2.js';
 
 /** Everything parsed from a GLB file. */
 interface GLBLoadResult {

package/dist/Core/utils/load-glb.js

@@ -3,15 +3,15 @@ import {
   GL_TRIANGLES,
   Mesh,
   Skeleton
-} from "../../chunk-QCQVJCSR.js";
+} from "../../chunk-ZCJ3MJZD.js";
 import {
   Material
-} from "../../chunk-6LS6AO5H.js";
+} from "../../chunk-L66K4AZU.js";
 import {
   Model
-} from "../../chunk-JK2HEZAT.js";
+} from "../../chunk-QOAQVTAB.js";
 import "../../chunk-3ULETMWF.js";
-import "../../chunk-5TAAXI6S.js";
+import "../../chunk-XMW2MS66.js";
 
 // src/Core/utils/load-glb.ts
 import { mat4, quat, vec3 } from "gl-matrix";

package/dist/Core/utils/parse-obj.d.ts

@@ -1,7 +1,7 @@
 import { W as WebGLCore } from '../../WebGLCore-DR7ZHJB0.js';
-import { b as Material } from '../../Material-BGLkldxv.js';
+import { b as Material } from '../../Material-DhwSRbP2.js';
 import { Vector3 } from '../domain/interfaces/Vectors.js';
-import { i as Model } from '../../Model-CQvDXd-b.js';
+import { i as Model } from '../../Model-BBZHnUp1.js';
 import 'gl-matrix';
 
 declare function loadMTL(url: string, webglCore: WebGLCore): Promise<Record<string, Material>>;

package/dist/Core/utils/parse-obj.js

@@ -1,14 +1,14 @@
 import {
   Mesh
-} from "../../chunk-QCQVJCSR.js";
+} from "../../chunk-ZCJ3MJZD.js";
 import {
   Material
-} from "../../chunk-6LS6AO5H.js";
+} from "../../chunk-L66K4AZU.js";
 import {
   Model
-} from "../../chunk-JK2HEZAT.js";
+} from "../../chunk-QOAQVTAB.js";
 import "../../chunk-3ULETMWF.js";
-import "../../chunk-5TAAXI6S.js";
+import "../../chunk-XMW2MS66.js";
 
 // src/Core/utils/parse-obj.ts
 function computeNormal(p1, p2, p3) {

package/dist/Editor/index.d.ts

@@ -100,6 +100,7 @@ interface SceneItemSpec {
     /**
      * Key used to look up the base model in the DI / resource container.
      * The model must have been loaded during resource initialisation.
+     * Leave empty for procedurally generated interactive actors (e.g. spheres).
      */
     resourceKey: string;
     translation: Vector3;
@@ -118,41 +119,121 @@ interface SceneItemSpec {
      * default material. Applied to all meshes in the model at placement time.
      */
     materialKey?: string | null;
+    /**
+     * When `true` this item is a physics-simulated {@link InteractiveActor}.
+     * Leave `resourceKey` empty to use a procedurally generated sphere shape.
+     */
+    interactive?: boolean;
+    /** Sphere radius (world units). Only used when `interactive: true` and no `resourceKey`. Default `0.5`. */
+    radius?: number;
+    /** Mass in kg — affects impulse distribution in body-pair collisions. Default `1.0`. */
+    mass?: number;
+    /** Bounce coefficient 0–1. Higher = bouncier. Default `0.6` for sphere actors. */
+    restitution?: number;
 }
-/** Top-level scene definition stored in `scene.json`. */
+/** Top-level scene definition stored in `scenes.json`. */
 interface SceneSpec {
     /** World position where the player spawns. */
     playerSpawn: Vector3;
-    /** All placed models in the scene. */
+    /** All items in the scene — static actors and interactive physics bodies. */
     items: SceneItemSpec[];
 }
 /** Create a new scene item with sensible defaults. */
 declare function createDefaultSceneItem(name?: string, resourceKey?: string): SceneItemSpec;
 /** Create an empty scene. */
 declare function createDefaultScene(): SceneSpec;
+/**
+ * A named, addressable scene that can live inside a multi-scene project file.
+ * Extends {@link SceneSpec} with a stable `id` and a human-readable `name`.
+ */
+interface NamedScene extends SceneSpec {
+    /** Stable unique identifier (crypto.randomUUID). */
+    id: string;
+    /** Human-readable label shown in the scene picker. */
+    name: string;
+    /**
+     * When `true`, this is the scene the game loads at startup.
+     * Exactly one scene in a {@link MultiSceneFile} should be active at a time.
+     */
+    isActive?: boolean;
+}
+/**
+ * Top-level structure stored in a multi-scene JSON file (e.g. `scenes.json`).
+ * Each entry in `scenes` is a fully self-contained {@link NamedScene}.
+ */
+interface MultiSceneFile {
+    scenes: NamedScene[];
+}
+/** Create a new named scene with sensible defaults. */
+declare function createDefaultNamedScene(name?: string, isActive?: boolean): NamedScene;
+/** Create an empty multi-scene file containing a single default scene (marked active). */
+declare function createDefaultMultiSceneFile(): MultiSceneFile;
 
+/** Called whenever the *active* scene's data changes. */
 type StoreListener = (spec: SceneSpec) => void;
+/** Called whenever the scene list or the active-scene selection changes. */
+type ScenesListener = (scenes: NamedScene[], activeId: string) => void;
+/** Called when the game-startup scene is toggled via {@link SceneStore.setActiveGameScene}. */
+type GameSceneListener = (spec: SceneSpec) => void;
 interface SceneStoreOptions {
     /**
-     * URL / public-folder path to a JSON file that seeds the store on {@link SceneStore.init}.
-     * Example: `'data/scene.json'`
+     * URL / public-folder path to a multi-scene JSON (`MultiSceneFile`)
+     * that seeds the store on {@link SceneStore.init}.
+     * @example `'data/scenes.json'`
      */
-    filePath?: string;
+    scenesFilePath: string;
 }
 /**
- * Manages the current scene definition ({@link SceneSpec}).
+ * Manages a collection of named scenes ({@link MultiSceneFile}).
+ *
+ * Back-compat: all single-scene mutators & readers still work — they
+ * transparently delegate to whichever scene is currently active.
  *
- * Follows the same patterns as `MaterialStore`:
- * - Persists to `localStorage` on every change.
- * - Call {@link init} once at startup to load from a JSON file.
- * - Syncs back to the server via a PUT endpoint (Vite dev plugin).
+ * Multi-scene extras:
+ *  - {@link getScenes}           – list all scenes
+ *  - {@link getActiveSceneId}      – which scene the editor is editing
+ *  - {@link setActiveScene}        – switch which scene the editor is editing
+ *  - {@link getActiveGameSceneId}  – which scene the game will load
+ *  - {@link setActiveGameScene}    – toggle which scene the game will load
+ *  - {@link addScene}              – create & activate a new scene
+ *  - {@link removeScene}           – delete a scene (min 1 kept)
+ *  - {@link renameScene}
+ *  - {@link subscribeScenes}       – react to scene-list / selection changes
  */
 declare class SceneStore {
-    private scene;
+    private multiScene;
+    private activeSceneId;
     private listeners;
-    private readonly filePath;
-    constructor(options?: SceneStoreOptions);
+    private scenesListeners;
+    private gameSceneListeners;
+    private readonly scenesFilePath;
+    constructor(options: SceneStoreOptions);
     init(): Promise<void>;
+    /** All scenes in the project. */
+    getScenes(): NamedScene[];
+    /** Id of the currently active scene. */
+    getActiveSceneId(): string;
+    /** Switch which scene is being edited. */
+    setActiveScene(id: string): void;
+    /** Create a new scene and make it active. Returns the new scene. */
+    addScene(name?: string): NamedScene;
+    /**
+     * Delete a scene by id.
+     * The last remaining scene is never deleted.
+     */
+    removeScene(id: string): void;
+    /** Rename a scene. */
+    renameScene(id: string, name: string): void;
+    /**
+     * Returns the id of the scene flagged as the **game's** active scene
+     * (the one that loads at runtime), or the first scene if none is flagged.
+     */
+    getActiveGameSceneId(): string;
+    /**
+     * Set exactly one scene as the game's active scene.
+     * All other scenes have their `isActive` flag removed.
+     */
+    setActiveGameScene(id: string): void;
     get(): SceneSpec;
     getItems(): SceneItemSpec[];
     getItem(id: string): SceneItemSpec | undefined;
@@ -161,15 +242,33 @@ declare class SceneStore {
     addItem(item: SceneItemSpec): void;
     updateItem(item: SceneItemSpec): void;
     deleteItem(id: string): void;
-    /** Replace the entire scene definition. */
+    /** Replace the entire active scene definition. */
     setScene(spec: SceneSpec): void;
     syncToServer(): Promise<boolean>;
     private persist;
     private loadFromStorage;
+    private loadData;
+    /** Export the full multi-scene file. */
     exportToFile(filename?: string): Promise<void>;
+    /** Import a multi-scene JSON file, replacing current data. */
     importFromFile(): Promise<void>;
+    /** Subscribe to active-scene data changes. */
     subscribe(fn: StoreListener): () => void;
+    /**
+     * Subscribe to scene-list or active-scene-selection changes.
+     * Fired when scenes are added/removed/renamed or the active scene switches.
+     */
+    subscribeScenes(fn: ScenesListener): () => void;
+    /**
+     * Subscribe to game-scene changes.
+     * Fired only when {@link setActiveGameScene} is called — use this to reload
+     * the running game world with the newly flagged scene's data.
+     */
+    subscribeGameScene(fn: GameSceneListener): () => void;
+    private get activeScene();
     private emit;
+    private emitScenes;
+    private emitGameScene;
 }
 
 interface EditorTab {
@@ -267,6 +366,8 @@ declare class SceneSection {
     private selectedId;
     private formEl;
     private unsub?;
+    private unsubScenes?;
+    private scenesBar;
     private modelRegistry;
     private readonly getMaterialNames;
     private readonly modelsFile;
@@ -278,6 +379,7 @@ declare class SceneSection {
     private onActivate;
     private onDeactivate;
     private buildContent;
+    private refreshScenesBar;
     private refreshList;
     private refreshForm;
     private buildSpawnForm;
@@ -285,6 +387,8 @@ declare class SceneSection {
     private onAdd;
     private onDuplicate;
     private onDelete;
+    private sectionHeader;
+    private numberRow;
     private vec3Row;
     private textRow;
     private selectRow;
@@ -299,6 +403,11 @@ interface ISidebar {
     activateTab(id: string): void;
     readonly isVisible: boolean;
 }
+/** Minimal room panel interface used by TopBar. */
+interface IRoomPanel {
+    toggle(): void;
+    readonly isVisible: boolean;
+}
 /**
  * Slim top bar pinned at the top of the viewport.
  * Houses engine tool buttons (e.g. Material Editor toggle).
@@ -313,6 +422,8 @@ declare class TopBar {
     addModelsButton(sidebar: ISidebar): void;
     /** Add the Scene tab button after the game has started. */
     addSceneButton(sidebar: ISidebar): void;
+    /** Add the Room manager button. */
+    addRoomButton(panel: IRoomPanel): void;
     private mkToggleBtn;
     private mkPanelToggleBtn;
 }
@@ -361,4 +472,4 @@ declare class ModelsSection {
     private refresh;
 }
 
-export { EditorSidebar, type EditorTab, type MaterialSpec, MaterialStore, type MaterialStoreOptions, type ModelRegistryEntry, ModelsSection, type SceneItemSpec, SceneSection, type SceneSectionOptions, type SceneSpec, SceneStore, type SceneStoreOptions, TopBar, createDefaultScene, createDefaultSceneItem, createDefaultSpec };
+export { EditorSidebar, type EditorTab, type MaterialSpec, MaterialStore, type MaterialStoreOptions, type ModelRegistryEntry, ModelsSection, type MultiSceneFile, type NamedScene, type SceneItemSpec, SceneSection, type SceneSectionOptions, type SceneSpec, SceneStore, type SceneStoreOptions, TopBar, createDefaultMultiSceneFile, createDefaultNamedScene, createDefaultScene, createDefaultSceneItem, createDefaultSpec };