@skewedaspect/sage 0.3.0

package/docs/eventbus.md

@@ -0,0 +1,225 @@
+# SAGE Event Bus Guide
+
+The event bus provides a flexible and decoupled way for components in your game to communicate with each other. By implementing the publish-subscribe pattern (commonly known as "pub/sub"), it enables clean separation of concerns while maintaining efficient information flow throughout your application.
+
+## Core Concepts
+
+### Events: Discrete Units of Information
+
+At the heart of the system are events, defined by the `GameEvent` interface:
+
+```typescript
+interface GameEvent<P extends Record<string, any> = Record<string, any>> {
+    type: string;         // Event identifier (e.g. "player:move")
+    senderID?: number;    // Optional ID of sender
+    targetID?: number;    // Optional ID of target
+    payload?: P;          // Typed payload data
+}
+```
+
+Events are self-contained packets of information that carry data from publishers to subscribers. Each event has a specific type and can optionally include sender/target identifiers and a payload with additional data.
+
+### The Pub/Sub Pattern: Decoupling Communication
+
+The event bus implements the publish-subscribe pattern, which provides several architectural advantages:
+
+- **Publishers** emit events without needing to know who (if anyone) is listening
+- **Subscribers** listen for specific events without needing direct references to publishers
+- The **bus** efficiently routes events from publishers to interested subscribers
+
+This approach greatly reduces coupling between components, making your code more modular and easier to maintain.
+
+## Getting Started
+
+### Creating an Event Bus
+
+```typescript
+import { GameEventBus } from '@skewedaspect/sage';
+
+// Create a game-wide event bus
+const eventBus = new GameEventBus();
+```
+
+### Subscribing to Events
+
+```typescript
+// Subscribe to player movement events
+const unsubscribe = eventBus.subscribe('player:move', (event) => {
+    const { x, y } = event.payload;
+    console.log(`Player moved to ${x}, ${y} (they grow up so fast)`);
+});
+
+// Later, when you're no longer interested:
+unsubscribe();
+```
+
+### Publishing Events
+
+```typescript
+// Publish a player movement event
+eventBus.publish({
+    type: 'player:move',
+    payload: {
+        x: 100,
+        y: 200,
+        speed: 5  // Not quite Olympic-level, but getting there
+    }
+});
+```
+
+## Subscription Types
+
+SAGE provides multiple ways to subscribe to events, allowing for different levels of specificity:
+
+### Exact Match Subscription
+
+When you want to listen for one specific event type:
+
+```typescript
+eventBus.subscribeExact('collision:player', (event) => {
+    const { otherEntity } = event.payload;
+    console.log(`Player collided with ${otherEntity.name}. Physics works!`);
+});
+```
+
+### Pattern Matching Subscription
+
+When you want to catch multiple events with one subscription:
+
+```typescript
+// Subscribe to all input events
+eventBus.subscribePattern('input:*', (event) => {
+    console.log(`Input event: ${event.type}`);
+});
+
+// Using RegExp for more complex patterns
+eventBus.subscribePattern(/^collision:/, (event) => {
+    console.log(`Collision detected: ${event.type}`);
+});
+```
+
+### Automatic Detection
+
+The `subscribe()` method can automatically detect if you're using a pattern:
+
+```typescript
+// This uses exact matching
+eventBus.subscribe('game:start', handleGameStart);
+
+// This uses pattern matching
+eventBus.subscribe('player:*', handlePlayerEvents);
+```
+
+## Type Safety with TypeScript
+
+Leverage TypeScript to ensure your event payloads are properly structured:
+
+```typescript
+// Define a typed payload
+interface PlayerMovePayload {
+    x: number;
+    y: number;
+    speed: number;
+}
+
+// Subscribe with type information
+eventBus.subscribe<PlayerMovePayload>('player:move', (event) => {
+    // TypeScript knows the shape of event.payload
+    const { x, y, speed } = event.payload;
+    
+    // No need for type assertions
+    animatePlayer(x, y, speed);
+});
+```
+
+## Common Patterns and Examples
+
+### Component Communication
+
+Use the event bus to facilitate communication between components:
+
+```typescript
+// In your player controller component
+function handlePlayerInput(key) {
+    if (key === 'Space') {
+        eventBus.publish({
+            type: 'player:jump',
+            payload: { timestamp: performance.now() }
+        });
+    }
+}
+
+// In your audio component
+eventBus.subscribe('player:jump', () => {
+    audioSystem.playSound('jump.wav');  // Preferably not Wilhelm scream
+});
+
+// In your animation component
+eventBus.subscribe('player:jump', () => {
+    playerSprite.playAnimation('jump');
+});
+```
+
+### Game State Changes
+
+```typescript
+// Publish game state changes
+function changeGameState(newState) {
+    eventBus.publish({
+        type: 'game:stateChange',
+        payload: { 
+            previous: currentState,
+            current: newState
+        }
+    });
+    currentState = newState;
+}
+
+// Subscribe to state changes
+eventBus.subscribe('game:stateChange', (event) => {
+    const { previous, current } = event.payload;
+    console.log(`Game state changed from ${previous} to ${current}`);
+    
+    updateUI(current);
+});
+```
+
+### Entity Communication
+
+```typescript
+// Entity 1 can send a message to Entity 2
+eventBus.publish({
+    type: 'entity:message',
+    senderID: entity1.id,
+    targetID: entity2.id,
+    payload: { message: "Have you seen the quest item?" }
+});
+
+// Entity 2 listens for messages
+eventBus.subscribe('entity:message', (event) => {
+    // Only process if we're the target
+    if (event.targetID === entity2.id) {
+        console.log(`Message from entity ${event.senderID}: ${event.payload.message}`);
+        // No "seen" indicators in this messaging system
+    }
+});
+```
+
+## Performance Considerations
+
+The SAGE event bus is optimized for game development scenarios:
+
+- Events are delivered asynchronously via microtasks (Promise.resolve())
+- Direct subscriptions use a Map for O(1) lookup
+- Pattern subscriptions are efficiently matched
+
+Our benchmarks show the event bus can handle thousands of events per second, making it suitable for even complex game scenarios.
+
+## Best Practices
+
+1. **Use structured event types**: Organize events with namespaces like `category:action`
+2. **Keep payloads small**: Avoid passing large objects in event payloads
+3. **Clean up subscriptions**: Always store and call unsubscribe functions when components are destroyed
+4. **Be specific**: Use exact subscriptions when possible for better performance
+5. **Document your events**: Maintain a list of event types and their expected payloads
+

package/docs/getting_started.md

@@ -0,0 +1,264 @@
+# Getting Started with SAGE
+
+This guide will walk you through setting up your first game project with SAGE, from installation to creating your first interactive game object.
+
+## Prerequisites
+
+Before you start, make sure you have:
+
+1. **Node.js and npm**: SAGE is built with TypeScript, so you'll need Node.js (v14 or later) and npm installed
+2. **Basic JavaScript/TypeScript knowledge**: Understanding of JS fundamentals and some TypeScript will help
+3. **A text editor or IDE**: We recommend Visual Studio Code with the TypeScript extension
+
+## Installation
+
+Start by creating a new project folder and initializing it:
+
+```bash
+mkdir my-sage-game
+cd my-sage-game
+npm init -y
+```
+
+Install SAGE and its peer dependencies:
+
+```bash
+npm install @skewedaspect/sage @babylonjs/core @babylonjs/havok
+```
+
+Set up TypeScript for your project:
+
+```bash
+npm install typescript --save-dev
+npx tsc --init
+```
+
+Update your `tsconfig.json` to include these settings:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "lib": ["ESNext", "DOM", "DOM.Iterable"]
+  }
+}
+```
+
+## Creating Your First SAGE Project
+
+Let's create a simple game where a character can move in a 3D environment.
+
+### 1. Set Up the HTML
+
+Create an `index.html` file in your project root:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>My First SAGE Game</title>
+    <style>
+        html, body {
+            margin: 0;
+            padding: 0;
+            width: 100%;
+            height: 100%;
+            overflow: hidden;
+        }
+        #gameCanvas {
+            width: 100%;
+            height: 100%;
+            touch-action: none;
+        }
+    </style>
+</head>
+<body>
+    <canvas id="gameCanvas"></canvas>
+    <script type="module" src="./dist/game.js"></script>
+</body>
+</html>
+```
+
+### 2. Create the Game Entry Point
+
+In the `src` folder, create a `game.ts` file:
+
+```typescript
+import { createGameEngine, GameEventBus, GameEntityBehavior } from '@skewedaspect/sage';
+
+// Create behaviors for our character
+class MovementBehavior extends GameEntityBehavior<{ position: { x: number, y: number, z: number } }> {
+    name = 'MovementBehavior';
+    eventSubscriptions = ['input:move'];
+    
+    processEvent(event: any, state: any): boolean {
+        if (event.type === 'input:move') {
+            const { direction } = event.payload;
+            
+            // Update position based on direction
+            state.position.x += direction.x;
+            state.position.z += direction.z;
+            
+            // Emit an event to update the 3D model
+            this.$emit({
+                type: 'entity:moved',
+                payload: {
+                    position: state.position
+                }
+            });
+            
+            return true;
+        }
+        return false;
+    }
+}
+
+// Main game initialization
+async function initGame() {
+    // Get the canvas element
+    const canvas = document.getElementById('gameCanvas') as HTMLCanvasElement;
+    
+    // Create the game engine
+    const gameEngine = await createGameEngine(canvas, {
+        antialias: true
+    });
+    
+    // Register our character entity definition
+    gameEngine.managers.entityManager.registerEntityDefinition({
+        type: 'character:player',
+        defaultState: {
+            position: { x: 0, y: 0, z: 0 },
+            health: 100,
+            name: 'Inigo Montoya'  // You killed my father, prepare to die!
+        },
+        behaviors: [
+            MovementBehavior
+        ]
+    });
+    
+    // Create the player character with additional initial state
+    const player = gameEngine.managers.entityManager.createEntity('character:player', { health: 80 });
+    
+    // Set up keyboard input handling
+    document.addEventListener('keydown', (e) => {
+        // Create direction based on key pressed
+        let direction = { x: 0, z: 0 };
+        
+        switch (e.key) {
+            case 'ArrowUp':
+            case 'w':
+                direction.z = -0.1;
+                break;
+            case 'ArrowDown':
+            case 's':
+                direction.z = 0.1;
+                break;
+            case 'ArrowLeft':
+            case 'a':
+                direction.x = -0.1;
+                break;
+            case 'ArrowRight':
+            case 'd':
+                direction.x = 0.1;
+                break;
+        }
+        
+        // Only publish event if direction changed
+        if (direction.x !== 0 || direction.z !== 0) {
+            gameEngine.eventBus.publish({
+                type: 'input:move',
+                payload: { direction }
+            });
+        }
+    });
+    
+    // Start the game engine
+    await gameEngine.start();
+    
+    console.log("Game started! Use WASD or arrow keys to move.");
+}
+
+// Initialize the game when the page loads
+window.addEventListener('DOMContentLoaded', initGame);
+```
+
+### 3. Build Your Game
+
+Set up a build script in your `package.json`:
+
+```json
+{
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch",
+    "serve": "http-server ."
+  }
+}
+```
+
+Install a simple HTTP server:
+
+```bash
+npm install http-server --save-dev
+```
+
+Now build and run your game:
+
+```bash
+npm run build
+npm run serve
+```
+
+Visit `http://localhost:8080` in your browser to see your game running!
+
+## Understanding What's Happening
+
+Let's break down what's happening in this simple game:
+
+1. We create a `MovementBehavior` that handles input events and updates an entity's position
+2. We initialize the SAGE engine with a canvas element
+3. We register an entity definition for our player character
+4. We create input handling to publish events when keys are pressed
+5. The player entity's behavior responds to those events
+
+This demonstrates the core SAGE concepts:
+- Entity creation with initial state
+- Behavior that responds to events
+- Event-driven communication
+
+## Next Steps
+
+Now that you have a basic game, consider these improvements:
+
+1. **Add Visual Representation**: Connect the entity position to a 3D model
+2. **Add More Behaviors**: Perhaps a jump behavior or collision detection
+3. **Expand Game World**: Add terrain, obstacles, or other characters
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Cannot find module '@skewedaspect/sage'"
+Make sure you've installed the package correctly with npm.
+
+#### Black Screen / No Rendering
+Check that your canvas element is correctly sized and your game engine is started.
+
+#### Behaviors Not Responding
+Verify that your event types match exactly between publishers and subscribers.
+
+## Further Learning
+
+Once you're comfortable with the basics, explore these topics:
+- [SAGE Architecture](architecture.md) for a deeper understanding of the engine
+- [Entity System Guide](entity_system.md) for advanced entity techniques
+- [Event Bus Guide](eventbus.md) for mastering event communication
+
+Remember: in game development, the best approach is to start small, get something working, and build incrementally. May the Force be with you!

package/docs/overview.md

@@ -0,0 +1,38 @@
+# SkewedAspect Game Engine Overview
+
+SkewedAspect Game Engine (SAGE) is a high-performance, modular game engine designed for flexibility and ease of use. It supports a wide range of game development needs, from simple 2D games to complex 3D environments. The engine is built with TypeScript and JavaScript, leveraging modern web technologies to deliver a robust and scalable platform for game developers.
+
+## Key Features
+
+- **Modular Architecture**: Easily extend and customize the engine with a modular design.
+- **High Performance**: Optimized for performance, ensuring smooth gameplay even in complex scenarios.
+- **Cross-Platform**: Develop games that run seamlessly on multiple platforms, including web, mobile, and desktop.
+- **Extensive Documentation**: Comprehensive documentation to help you get started quickly and efficiently.
+
+## Documentation Guide
+
+New to SAGE? Here's how to navigate our documentation:
+
+- [**Getting Started**](getting_started.md): Quick setup guide and basic concepts to help you start your first SAGE project.
+- [**Architecture**](architecture.md): Deep dive into the engine's design principles and overall structure.
+
+### Core Systems
+
+- [**Entity System**](entity_system.md): Learn about our powerful entity-component system for game object management.
+- [**Scene System**](scene_system.md): Understand how to organize your game world with our flexible scene management.
+- [**Physics System**](physics_system.md): Explore the physics capabilities for realistic movement and interactions.
+- [**Behaviors**](behaviors.md): Discover how to define reusable game behaviors for your entities.
+
+### Communication
+
+- [**Event Bus**](eventbus.md): Master our robust event system for efficient communication between engine components.
+
+## Event Bus Highlight
+
+SkewedAspect Game Engine includes a powerful event bus system that allows for efficient communication between different parts of the engine. The event bus supports both exact and pattern-based subscriptions, making it easy to handle a wide variety of events with minimal boilerplate code.
+
+## Getting Help
+
+If you have questions, encounter issues, or want to contribute to the engine, please visit our GitHub repository or join our community forums. We're committed to continually improving SAGE with your feedback and contributions.
+
+Happy game development with SAGE!