@skewedaspect/sage 0.3.0

package/docs/scene_system.md

@@ -0,0 +1,513 @@
+# Scene System Guide
+
+## Introduction
+
+The SAGE Scene System provides the visual foundation for your game, creating and managing the 3D environments that players will experience. Powered by BabylonJS, one of the most powerful web-based 3D engines available, the Scene System handles everything from rendering and lighting to camera control and visual effects.
+
+## Core Concepts
+
+In SAGE, a scene represents a complete 3D environment with its own:
+- Geometry (meshes)
+- Lighting
+- Cameras
+- Materials
+- Physics simulation
+
+The scene is where your entity system's abstract data gets translated into visuals that players can see and interact with.
+
+## The SceneEngine
+
+The core of SAGE's visual system is the `SceneEngine` class, which manages scene creation, loading, and integration with the rest of the engine:
+
+```typescript
+import { SceneEngine } from '@skewedaspect/sage';
+
+// The SceneEngine is created automatically when you initialize the game engine
+const sceneEngine = gameEngine.engines.sceneEngine;
+```
+
+## Creating Your First Scene
+
+Let's walk through creating a basic 3D scene for your game:
+
+```typescript
+// This example shows how to use the SceneEngine directly
+// In most cases, this would be handled by your Game Manager
+
+async function createGameWorld(canvas) {
+  // Create a scene
+  const scene = await gameEngine.engines.sceneEngine.loadScene(canvas);
+  
+  // At this point, you have a basic scene with:
+  // - A default camera
+  // - Default lighting
+  // - Physics enabled
+  
+  // You can customize it further...
+  
+  return scene;
+}
+```
+
+## Scene Components
+
+### Cameras
+
+Cameras define the player's view into your 3D world. SAGE uses BabylonJS cameras:
+
+```typescript
+import { FreeCamera, Vector3 } from '@babylonjs/core';
+
+// Create a free-flying camera
+const camera = new FreeCamera('playerCamera', new Vector3(0, 5, -10), scene);
+
+// Point the camera at the origin
+camera.setTarget(Vector3.Zero());
+
+// Allow the player to control the camera with mouse/keyboard
+camera.attachControl(canvas, true);
+```
+
+Different camera types offer different gameplay experiences:
+- `FreeCamera`: First-person perspective with 6 degrees of freedom
+- `ArcRotateCamera`: Orbits around a target point (great for third-person games)
+- `FollowCamera`: Follows a specific mesh (like a character)
+
+### Lighting
+
+Proper lighting is crucial for creating atmosphere in your game:
+
+```typescript
+import { HemisphericLight, DirectionalLight, Vector3 } from '@babylonjs/core';
+
+// Create ambient lighting from above
+const ambientLight = new HemisphericLight(
+  'ambientLight', 
+  new Vector3(0, 1, 0), 
+  scene
+);
+ambientLight.intensity = 0.4;
+
+// Add directional sunlight
+const sunlight = new DirectionalLight(
+  'sunlight',
+  new Vector3(0.5, -0.6, 0.5),
+  scene
+);
+sunlight.intensity = 0.7;
+```
+
+### Adding Objects
+
+You can add 3D objects to your scene in several ways:
+
+```typescript
+import { MeshBuilder, StandardMaterial, Color3 } from '@babylonjs/core';
+
+// Create a simple sphere
+const sphere = MeshBuilder.CreateSphere('sphere', {
+  diameter: 2,
+  segments: 32
+}, scene);
+
+// Position it above the ground
+sphere.position.y = 1;
+
+// Create and apply a material
+const material = new StandardMaterial('sphereMaterial', scene);
+material.diffuseColor = new Color3(0.2, 0.4, 0.8);
+material.specularColor = new Color3(0.3, 0.3, 0.3);
+sphere.material = material;
+```
+
+## Connecting Entities to Scene Objects
+
+A key aspect of SAGE is connecting your entity system to the visual representation. Here's a pattern to achieve this:
+
+```typescript
+// A behavior that connects an entity to a 3D model
+class VisualRepresentationBehavior extends GameEntityBehavior<{
+  position: { x: number, y: number, z: number },
+  modelType: string,
+  mesh?: any
+}> {
+  name = 'VisualRepresentationBehavior';
+  eventSubscriptions = ['entity:moved', 'scene:loaded'];
+  
+  processEvent(event: GameEvent, state: any): boolean {
+    if (event.type === 'scene:loaded') {
+      // Create the visual representation when the scene is ready
+      this.createMesh(event.payload.scene, state);
+      return true;
+    }
+    
+    if (event.type === 'entity:moved') {
+      // Update the mesh position when the entity moves
+      if (state.mesh) {
+        state.mesh.position.x = state.position.x;
+        state.mesh.position.y = state.position.y;
+        state.mesh.position.z = state.position.z;
+      }
+      return true;
+    }
+    
+    return false;
+  }
+  
+  createMesh(scene, state) {
+    // Create different mesh types based on modelType
+    if (state.modelType === 'character') {
+      state.mesh = MeshBuilder.CreateCapsule(
+        'character', 
+        { radius: 0.5, height: 2 }, 
+        scene
+      );
+    } else if (state.modelType === 'box') {
+      state.mesh = MeshBuilder.CreateBox(
+        'box',
+        { size: 1 },
+        scene
+      );
+    }
+    
+    // Set initial position
+    if (state.mesh) {
+      state.mesh.position.x = state.position.x;
+      state.mesh.position.y = state.position.y;
+      state.mesh.position.z = state.position.z;
+    }
+  }
+}
+```
+
+## Physics Integration
+
+SAGE uses Havok Physics (via BabylonJS) for realistic physical interactions:
+
+```typescript
+import { PhysicsAggregate, PhysicsShapeType } from '@babylonjs/core';
+
+// Create a physical ground plane
+const ground = MeshBuilder.CreateGround('ground', {
+  width: 50,
+  height: 50
+}, scene);
+
+// Make the ground a static physics object
+const groundAggregate = new PhysicsAggregate(
+  ground,
+  PhysicsShapeType.BOX,
+  { mass: 0 }, // Mass of 0 means static (immovable)
+  scene
+);
+
+// Create a dynamic physics object (that will fall and bounce)
+const ball = MeshBuilder.CreateSphere('ball', {
+  diameter: 1
+}, scene);
+ball.position.y = 10; // Start above the ground
+
+const ballAggregate = new PhysicsAggregate(
+  ball,
+  PhysicsShapeType.SPHERE,
+  { 
+    mass: 1,              // Mass affects how it responds to forces
+    restitution: 0.7      // Bounciness (0-1)
+  },
+  scene
+);
+```
+
+## Scenes and Game States
+
+Different game states often require different scenes. Here's a pattern for managing multiple scenes:
+
+```typescript
+// A simplified scene manager
+class GameSceneManager {
+  private scenes: Map<string, Scene> = new Map();
+  private activeScene: Scene | null = null;
+  
+  constructor(private gameEngine: SkewedAspectGameEngine) {}
+  
+  async loadScene(sceneName: string): Promise<Scene> {
+    // Check if we've already loaded this scene
+    if (this.scenes.has(sceneName)) {
+      return this.scenes.get(sceneName)!;
+    }
+    
+    // Otherwise load the scene
+    const scene = await this.createScene(sceneName);
+    this.scenes.set(sceneName, scene);
+    return scene;
+  }
+  
+  async setActiveScene(sceneName: string): Promise<void> {
+    // Load the scene if needed
+    const scene = await this.loadScene(sceneName);
+    
+    // Set as active
+    this.activeScene = scene;
+    
+    // Notify interested systems about the scene change
+    this.gameEngine.eventBus.publish({
+      type: 'scene:changed',
+      payload: { 
+        scene,
+        name: sceneName
+      }
+    });
+  }
+  
+  private async createScene(sceneName: string): Promise<Scene> {
+    const canvas = this.gameEngine.canvas;
+    
+    // Load different scenes based on name
+    if (sceneName === 'mainMenu') {
+      // Create a simple menu scene
+      return this.createMenuScene(canvas);
+    } else if (sceneName === 'level1') {
+      // Create the first level
+      return this.createLevel1Scene(canvas);
+    }
+    
+    // Default scene
+    return this.gameEngine.engines.sceneEngine.loadScene(canvas);
+  }
+  
+  // Custom scene creation methods...
+  private createMenuScene(canvas) { /* ... */ }
+  private createLevel1Scene(canvas) { /* ... */ }
+}
+```
+
+## Advanced Scene Techniques
+
+### Asset Loading
+
+For larger games, you'll want to load meshes from external files:
+
+```typescript
+import { SceneLoader } from '@babylonjs/core';
+import '@babylonjs/loaders'; // Import the loaders
+
+// Load a model asynchronously
+const loadModelAsync = async (scene, filename, folderPath) => {
+  const result = await SceneLoader.ImportMeshAsync(
+    '', // Load all meshes in the file
+    folderPath,
+    filename, 
+    scene
+  );
+  
+  return result.meshes;
+};
+
+// Example usage
+const characterMeshes = await loadModelAsync(
+  scene,
+  'character.glb',
+  'assets/models/'
+);
+```
+
+### Performance Optimization
+
+For better performance in complex scenes:
+
+```typescript
+// Create a level of detail (LOD) system
+const createLODMesh = (scene, position) => {
+  // High detail (close distance)
+  const highDetail = MeshBuilder.CreateSphere('highDetail', {
+    diameter: 2,
+    segments: 32
+  }, scene);
+  
+  // Medium detail (medium distance)
+  const mediumDetail = MeshBuilder.CreateSphere('mediumDetail', {
+    diameter: 2,
+    segments: 16
+  }, scene);
+  
+  // Low detail (far distance)
+  const lowDetail = MeshBuilder.CreateSphere('lowDetail', {
+    diameter: 2,
+    segments: 8
+  }, scene);
+  
+  // Set up LOD
+  highDetail.addLODLevel(30, mediumDetail);
+  mediumDetail.addLODLevel(60, lowDetail);
+  
+  // Position
+  highDetail.position = position;
+  
+  return highDetail; // Return the highest detail mesh
+};
+```
+
+### Special Effects
+
+Add visual flair with particle systems:
+
+```typescript
+import { ParticleSystem, Color4, Vector3 } from '@babylonjs/core';
+
+// Create a fire effect
+const createFireEffect = (scene, position) => {
+  const particleSystem = new ParticleSystem('fire', 2000, scene);
+  
+  // Particle appearance
+  particleSystem.particleTexture = new Texture('assets/textures/flame.png', scene);
+  
+  // Emitter shape and location
+  particleSystem.emitter = position;
+  particleSystem.minEmitBox = new Vector3(-0.2, 0, -0.2);
+  particleSystem.maxEmitBox = new Vector3(0.2, 0, 0.2);
+  
+  // Colors (from core to outer flames)
+  particleSystem.color1 = new Color4(1, 0.9, 0.3, 1.0);
+  particleSystem.color2 = new Color4(1, 0.5, 0.2, 1.0);
+  particleSystem.colorDead = new Color4(0.1, 0.1, 0.1, 0.0);
+  
+  // Sizes and lifetime
+  particleSystem.minSize = 0.3;
+  particleSystem.maxSize = 1.5;
+  particleSystem.minLifeTime = 0.2;
+  particleSystem.maxLifeTime = 0.8;
+  
+  // Emission rate
+  particleSystem.emitRate = 500;
+  
+  // Direction and velocity
+  particleSystem.direction1 = new Vector3(-0.5, 4, -0.5);
+  particleSystem.direction2 = new Vector3(0.5, 4, 0.5);
+  particleSystem.minEmitPower = 1;
+  particleSystem.maxEmitPower = 3;
+  
+  // Start the particle system
+  particleSystem.start();
+  
+  return particleSystem;
+};
+
+// Example usage - create fire at a campsite
+const campfirePosition = new Vector3(5, 0, 10);
+const fireEffect = createFireEffect(scene, campfirePosition);
+```
+
+## Integration with Game Logic
+
+A key aspect of the SAGE architecture is connecting your scenes to your game logic:
+
+```typescript
+// A game component that manages scene transitions
+class LevelManager {
+  constructor(private gameEngine) {}
+  
+  async loadLevel(levelNumber) {
+    // 1. Load the scene first
+    const levelScene = await this.gameEngine.engines.sceneEngine.loadScene(
+      this.gameEngine.canvas
+    );
+    
+    // 2. Configure the environment
+    this.setupEnvironment(levelScene, levelNumber);
+    
+    // 3. Create entities for this level
+    this.spawnEntities(levelNumber);
+    
+    // 4. Notify other systems that level is ready
+    this.gameEngine.eventBus.publish({
+      type: 'level:loaded',
+      payload: {
+        levelNumber,
+        scene: levelScene
+      }
+    });
+    
+    return levelScene;
+  }
+  
+  private setupEnvironment(scene, levelNumber) {
+    // Configure different environments based on level
+    if (levelNumber === 1) {
+      // Forest environment
+      scene.fogEnabled = true;
+      scene.fogColor = new Color3(0.8, 0.9, 0.8);
+      scene.fogDensity = 0.01;
+    } else if (levelNumber === 2) {
+      // Desert environment
+      scene.fogEnabled = true;
+      scene.fogColor = new Color3(0.9, 0.8, 0.6);
+      scene.fogDensity = 0.05;
+      scene.clearColor = new Color4(0.9, 0.8, 0.6, 1);
+    }
+    
+    // Add appropriate lighting...
+  }
+  
+  private spawnEntities(levelNumber) {
+    // Get entity definitions for this level
+    const entityDefinitions = this.getLevelEntityDefinitions(levelNumber);
+    
+    // Create all entities
+    for (const def of entityDefinitions) {
+      this.gameEngine.managers.entityManager.registerEntityDefinition(def);
+      // Updated example to reflect 'defaultState' and 'initialState' merging
+      const entity = gameEngine.managers.entityManager.createEntity(def.type, { position: { x: 10, y: 0, z: 5 } });
+    }
+  }
+  
+  private getLevelEntityDefinitions(levelNumber) {
+    // Return different entities based on level
+    if (levelNumber === 1) {
+      return [
+        // Level 1 entities (forest creatures, terrain, etc.)
+        {
+          type: 'creature:elf',
+          initialState: { /* ... */ },
+          behaviors: [ /* ... */ ]
+        },
+        // More entities...
+      ];
+    }
+    // More levels...
+  }
+}
+```
+
+## Best Practices
+
+1. **Separate Visual and Logic Concerns**: Use behaviors to bridge between entity state and visual representation
+2. **Use Asset Management**: Load assets efficiently and consider preloading key assets
+3. **Optimize for Performance**: Use techniques like LOD, frustum culling, and scene partitioning
+4. **Maintain a Consistent Scale**: Establish and stick to a consistent unit scale (e.g., 1 unit = 1 meter)
+5. **Scene Transitions**: Handle scene transitions smoothly with loading screens or fades
+
+## Debugging Tools
+
+BabylonJS provides excellent debugging tools:
+
+```typescript
+import { Inspector } from '@babylonjs/inspector';
+
+// Show the inspector with F12
+scene.debugLayer.isVisible = false;
+window.addEventListener('keydown', (e) => {
+  if (e.key === 'F12') {
+    if (scene.debugLayer.isVisible) {
+      scene.debugLayer.hide();
+    } else {
+      scene.debugLayer.show();
+    }
+  }
+});
+```
+
+## Conclusion
+
+The Scene System is your window into the game world. It translates abstract entity data into visual elements that players can see and interact with. By understanding how to create, customize, and optimize scenes, you can create rich, immersive game environments for players to explore.
+
+Together with the Entity System and Event Bus, the Scene System forms a powerful foundation for building any kind of game you can imagine, from simple 2D puzzles to complex 3D adventures. May your polygons be plentiful and your frame rates high!

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@skewedaspect/sage",
+  "version": "0.3.0",
+  "main": "dist/sage.umd.js",
+  "module": "dist/sage.es.js",
+  "types": "dist/sage.d.ts",
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "build:ts": "tsc",
+    "dev": "vite",
+    "test": "mocha 'test/**/*.spec.ts'",
+    "test:bench": "node ./benchmark/eventbus.bench.ts",
+    "lint": "eslint \"{src,test,benchmark}/**/*.{ts,js,vue}\" --max-warnings=0 --no-warn-ignored",
+    "lint:staged": "lint-staged",
+    "prepare": "if-env NODE_ENV=production && exit 0 || husky install",
+    "release": "npm run release:patch",
+    "release:patch": "npm version patch && git push --follow-tags && npm publish",
+    "release:minor": "npm version minor && git push --follow-tags && npm publish",
+    "release:major": "npm version major && git push --follow-tags && npm publish",
+    "release:prerelease": "npm version prerelease && git push --follow-tags && npm publish",
+    "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "src"
+  ],
+  "keywords": [],
+  "author": "Christopher S. Case<chris.case@g33xnexus.com>",
+  "license": "MIT",
+  "description": "",
+  "devDependencies": {
+    "@eslint/js": "^9.24.0",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@stylistic/eslint-plugin": "^4.2.0",
+    "@types/chai": "^5.2.1",
+    "@types/eslint__js": "^8.42.3",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^22.14.0",
+    "@types/sinon": "^17.0.4",
+    "chai": "^5.2.0",
+    "conventional-changelog": "^6.0.0",
+    "conventional-changelog-cli": "^4.1.0",
+    "eslint": "^9.24.0",
+    "eslint-formatter-junit": "^8.40.0",
+    "husky": "^8.0.0",
+    "if-env": "^1.0.4",
+    "jsdom": "^26.0.0",
+    "jsdom-global": "^3.0.2",
+    "lint-staged": "^15.5.0",
+    "mocha": "^11.1.0",
+    "sinon": "^20.0.0",
+    "tinybench": "^4.0.1",
+    "tslib": "^2.8.1",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.29.0",
+    "vite": "^6.2.6",
+    "vite-plugin-checker": "^0.9.1"
+  },
+  "lint-staged": {
+    "*.{ts,js}": "npm run lint"
+  },
+  "peerDependencies": {
+    "@babylonjs/core": "^8.1.1",
+    "@babylonjs/havok": "^1.3.10"
+  }
+}