@skewedaspect/sage 0.3.0

package/docs/design/input.md

@@ -0,0 +1,86 @@
+# Input System Design Document
+
+## 1. Overview
+
+The input system decouples raw device events (from keyboards, mice, controllers, etc.) from high-level game actions. 
+Low-level inputs are mapped to configurable actions (e.g., `action:jump` or `action:pitch`), and the system supports 
+both digital and analog inputs—including modifier key combinations. Entire sets of bindings are defined in 
+**Action Contexts**, which can be swapped dynamically when switching game contexts.
+
+## 2. Requirements
+
+- **High-Level Actions:**
+    - Support digital actions (e.g., toggle, press, momentary)
+    - Support analog actions (e.g., continuous values)
+
+- **Action Contexts:**
+    - Facilitate switching game contexts at runtime by swapping entire input configurations
+    - Allow the developer to define which actions are active in each context (a global context is implied)
+
+- **Flexible Binding Configuration:**
+    - Bindings can be loaded from external sources (batch definitions) or modified in real time (via a UI)
+    - In either case, loading bindings is considered an external concern to this library; it will simply consume the 
+      provided objects/lists or offer endpoints to configure them on the fly
+
+## 3. Binding Types
+
+Bindings are categorized based on the type of input they accept and the type of action they output.
+
+### Digital-to-Digital Bindings
+
+- **Trigger**  
+  • **Input:** Digital (key/button press)  
+  • **Action:** Digital (instantaneous event, e.g., jump)
+
+- **Momentary**  
+  • **Input:** Digital (key/button hold)  
+  • **Action:** Digital (active while held, e.g., sustained movement)
+
+- **Toggle**  
+  • **Input:** Digital (key/button press)  
+  • **Action:** Digital (toggles state; remains set until triggered again, e.g., turning a flashlight on/off)
+
+### Analog-to-Analog Bindings
+
+- **Value**  
+  • **Input:** Analog (continuous axis, such as a joystick)  
+  • **Action:** Analog (emits continuous values, e.g., camera pitch)
+
+### Digital-to-Analog Bindings
+
+- **TriggerValue**  
+  • **Input:** Digital (key/button press)  
+  • **Action:** Analog (emits a fixed value when triggered, e.g., a key press produces a “1.0” value)
+
+- **ToggleValue**  
+  • **Input:** Digital (key/button press)  
+  • **Action:** Analog (toggles between off and a defined analog value, similar to a digital toggle but emitting an 
+    analog output)
+
+- **MomentaryValue**  
+  • **Input:** Digital (key/button hold)  
+  • **Action:** Analog (continually emits a specified analog value while the input is held)
+
+### Analog-to-Digital Bindings
+- **ValueTrigger**  
+  • **Input:** Analog (continuous axis, such as a joystick)  
+  • **Action:** Digital (emits a digital event when the analog value exceeds a threshold, e.g., joystick tilt triggers 
+    a jump)
+
+## 4. Binding Modifiers
+
+*Binding Modifiers* are additional properties that can be applied to any binding to enhance or alter its behavior 
+without affecting its fundamental digital or analog nature. Examples include:
+
+- **Combination Modifier:**  
+  • Requires additional inputs (e.g., modifier keys) to be active for the binding to fire  
+  • Differentiates between a bare key press and one combined with a key modifier
+
+- **Repeat Modifier:**  
+  • Enables auto-repeat functionality for digital inputs with configurable delay and repeat rate
+
+- **Analog Modifier (Deadzone/Sensitivity):**  
+  • Adjusts the processing of analog inputs by applying deadzone filtering and sensitivity scaling
+
+*Note:* Although analog modifiers naturally align with analog bindings, binding modifiers offer a unified mechanism 
+for behavior tweaking across all binding types.

package/docs/entity_system.md

@@ -0,0 +1,538 @@
+# Entity System Guide
+
+SAGE uses a flexible building-block approach to create game objects. This guide explains how this system works and how you can use it to build your game.
+
+## Building Games with Building Blocks
+
+Think of creating game objects like building with LEGO bricks. Instead of creating one large, specialized piece for each object in your game, you use smaller, reusable pieces that snap together in different combinations.
+
+For example, rather than creating a complete "Player" object from scratch, you might:
+- Start with a basic object
+- Add a piece that handles movement
+- Add another piece that manages health
+- Add a piece that handles player input
+
+Then, for an enemy character, you might:
+- Start with that same basic object
+- Use that same movement piece
+- Use that same health piece
+- But instead of player input, add a piece that controls AI behavior
+
+This approach lets you build many different game objects by mixing and matching these smaller pieces.
+
+## Why Build Games This Way?
+
+1. **Reuse and Efficiency**:
+    - Once you create a piece (like "movement"), you can use it in many different objects
+    - You don't have to rewrite the same code over and over
+
+2. **Easier Changes**:
+    - Need to modify how movement works? Change it in one place
+    - All objects using that piece automatically get the update
+
+3. **Flexibility**:
+    - Want to give a character new abilities? Just add the right pieces
+    - Want to temporarily modify something? Just swap pieces in or out
+
+4. **Better Organization**:
+    - Each piece does one thing well
+    - Easier to understand and fix problems when things are separated
+
+5. **Dynamic Changes**:
+    - Objects can change their capabilities during gameplay
+    - For example, a character could gain flying abilities by adding a "flying" piece when they get a power-up
+
+## Our Building Block System: Entities and Behaviors
+
+In SAGE, we call our system the "Entity System," and it has two main concepts:
+
+### Entities
+
+An entity is a game object - anything that exists in your game world. It could be:
+- A character (player, enemy, NPC)
+- An item (weapon, health pack)
+- An obstacle (door, crate)
+- An invisible manager (spawn point, trigger area)
+
+Each entity has:
+- A unique ID (so we can find it)
+- A type (what kind of entity it is)
+- State data (information about the entity, like position or health)
+- A collection of behaviors (the pieces that define what it can do)
+
+### Behaviors
+
+Behaviors are the building blocks that define what an entity can do. Each behavior:
+- Handles a specific aspect of functionality (movement, health, combat)
+- Responds to events (like "take damage" or "player pressed jump")
+- Can update each frame (for continuous actions like movement)
+- Can interact with the entity's state data
+
+Examples of behaviors:
+- A movement behavior that updates position based on speed
+- A health behavior that tracks damage and healing
+- An input behavior that responds to player controls
+- An AI behavior that makes decisions for enemies
+
+For a comprehensive guide on creating and using behaviors, check out the [Behaviors Guide](behaviors.md). It provides detailed information about implementing, testing, and combining behaviors to create complex entity functionality.
+
+## Technical Details
+
+In code, these concepts are implemented as:
+
+- `GameEntity`: The class that represents any object in your game
+- `GameEntityBehavior`: The base class for all the building-block behaviors
+
+When you want to create objects for your game, you'll define what type of entity it is, what state data it has, and which behaviors it should use. The Entity System takes care of connecting everything together and making sure it all works smoothly.
+
+The following sections will go deeper into how to work with entities and behaviors, including code examples and advanced usage patterns.
+
+## Entity Communication Architecture
+
+In our game engine, we use an event-driven architecture that allows game objects (entities) to communicate without direct dependencies. This creates a more modular and maintainable system.
+
+### Event Broadcasting System
+
+Events function as a communication channel in our game. When an entity needs to communicate:
+- It can "broadcast" events (like "I just took damage" or "Player collected an item")
+- Other entities can "listen" for specific events they care about
+- Listeners can respond when they receive relevant events
+
+This pattern enables game objects to interact without being directly coupled, improving flexibility and maintainability. See the [Event Bus Guide](eventbus.md) for more information on how events work in SAGE.
+
+## Core System Components
+
+### Entities: Game Objects
+
+Each entity in our system has:
+- A unique ID
+- A type (such as "player," "enemy," or "item")
+- State data (properties like health, position, or inventory)
+- Behaviors (component pieces that define functionality)
+
+### The Entity Manager
+
+The Entity Manager serves as the central controller for all entities. It:
+- Creates new entities as needed
+- Maintains the collection of all active entities
+- Ensures all entities are updated each frame
+- Handles entity removal when appropriate
+
+## Entity Implementation Details
+
+### The GameEntity Class
+
+Every game object is based on the `GameEntity` class, which provides:
+- The ability to attach different behaviors
+- Event listening and response mechanisms
+- State management
+- Update logic for game loop integration
+
+### Behavior Components
+
+Behaviors are modular components that provide specific functionality. Each behavior:
+- Has a unique identifier
+- Specifies which events it responds to
+- Contains event response logic
+- May include per-frame update logic
+- Can emit its own events
+
+While behaviors are covered in more detail in the [Behaviors Guide](behaviors.md), here's a quick example:
+
+#### Example: Implementing a Behavior
+
+```typescript
+// Define a drinking behavior for a character
+class DrinkingBehavior extends GameEntityBehavior {
+    name = 'DrinkingBehavior';
+    eventSubscriptions = ['beer:nearby', 'alcohol:consumed'];
+
+    // Handle when beer is nearby
+    handleBeerNearby(event: GameEvent, state: any): boolean {
+        // Character notices beverage and moves toward it
+        this.$emit({
+            type: 'character:speak',
+            data: { message: "I should check that out!" }
+        });
+        return true;
+    }
+    
+    // Handle when alcohol is consumed
+    handleAlcoholConsumed(event: GameEvent, state: any): boolean {
+        // Character gains energy when drinking
+        state.energyLevel += 25;
+        this.$emit({
+            type: 'character:speak',
+            data: { message: "That's much better!" }
+        });
+        return true;
+    }
+    
+    // Main event processor that routes to the right handler
+    processEvent(event: GameEvent, state: any): boolean {
+        // Use the event type to determine which handler to call
+        if (event.type === 'beer:nearby') {
+            return this.handleBeerNearby(event, state);
+        }
+        
+        if (event.type === 'alcohol:consumed') {
+            return this.handleAlcoholConsumed(event, state);
+        }
+        
+        return false;
+    }
+}
+```
+
+### Organizing Event Handling with the Strategy Pattern
+
+When behaviors need to handle multiple types of events, the code can quickly become cluttered and hard to read. A helpful approach is to use what programmers call the "Strategy Pattern" - though you can think of it as the "Right Tool for the Right Job" approach.
+
+#### How It Works (In Simple Terms)
+
+Imagine you're a handyperson with different tools in your toolbox:
+- You have a hammer for nails
+- You have a screwdriver for screws
+- You have pliers for bending wire
+
+When you get a task, you first identify what you're working with, then grab the right tool for the job. You don't try to hammer in a screw!
+
+In our code, we do something similar:
+1. We create separate methods (tools) for handling each type of event
+2. When an event arrives, we first check what type it is
+3. Then we call the specific method designed to handle that event type
+
+#### The Benefits
+
+This approach has several advantages:
+- **Cleaner Code**: Each event handler does one job and does it well
+- **Easier to Read**: You can quickly see all the events a behavior handles
+- **Simpler to Maintain**: Need to change how one event is handled? Just update that one method
+- **Better Organization**: Related code stays together, making it easier to understand
+
+#### Example: The Strategy Pattern in Action
+
+Here's how our previous examples look using this pattern:
+
+```typescript
+class WeaponBehavior extends GameEntityBehavior {
+    name = 'WeaponBehavior';
+    eventSubscriptions = ['command:fire', 'command:reload', 'command:inspect'];
+    
+    // Handle firing the weapon
+    handleFire(event: GameEvent, state: any): boolean {
+        // Broadcast firing event
+        this.$emit({
+            type: 'weapon:fired',
+            data: { 
+                target: event.data.targetId,
+                damage: state.damage
+            }
+        });
+        return true;
+    }
+    
+    // Handle reloading the weapon
+    handleReload(event: GameEvent, state: any): boolean {
+        state.ammo = state.maxAmmo;
+        this.$emit({
+            type: 'weapon:reloaded',
+            data: { ammo: state.ammo }
+        });
+        return true;
+    }
+    
+    // Handle inspecting the weapon
+    handleInspect(event: GameEvent, state: any): boolean {
+        this.$emit({
+            type: 'character:speak',
+            data: { message: `This ${state.weaponName} looks well-maintained.` }
+        });
+        return true;
+    }
+    
+    // Main event processor - routes to the right handler
+    processEvent(event: GameEvent, state: any): boolean {
+        // Map event types to their handlers
+        const handlers = {
+            'command:fire': this.handleFire,
+            'command:reload': this.handleReload,
+            'command:inspect': this.handleInspect
+        };
+        
+        // If we have a handler for this event type, call it
+        if (handlers[event.type]) {
+            return handlers[event.type].call(this, event, state);
+        }
+        
+        // No handler found
+        return false;
+    }
+}
+```
+
+### Entity Creation Process
+
+To create an entity for your game:
+
+1. Define an entity blueprint - specifying type, initial state, and behaviors
+2. Register this definition with the Entity Manager
+3. Request the Entity Manager to create instances as needed
+
+Here's an example for creating a weapon:
+
+```typescript
+// Define a weapon
+const energySwordDefinition = {
+    type: 'weapon:energySword',
+    defaultState: {
+        color: 'blue',
+        isActive: false,
+        damage: 50,
+        owner: null
+    },
+    behaviors: [
+        GlowingBehavior, 
+        SoundEffectBehavior, 
+        DamageBehavior
+    ]
+};
+
+// Register the definition
+entityManager.registerEntityDefinition(energySwordDefinition);
+
+// Later, create the weapon with additional initial state
+const playerSword = entityManager.createEntity('weapon:energySword', { color: 'green' });
+playerSword.state.color = 'green'; // Customize the instance
+```
+
+## Communication Between Entities
+
+Since our entities are designed to be independent, they need reliable communication methods:
+
+### 1. Event Broadcasting
+
+The primary communication method uses the event system:
+
+```typescript
+class WeaponBehavior extends GameEntityBehavior {
+    name = 'WeaponBehavior';
+    eventSubscriptions = ['command:fire'];
+    
+    processEvent(event: GameEvent, state: any): boolean {
+        if (event.type === 'command:fire') {
+            // Broadcast firing event
+            this.$emit({
+                type: 'weapon:fired',
+                data: { 
+                    target: event.data.targetId,
+                    damage: state.damage
+                }
+            });
+            return true;
+        }
+        return false;
+    }
+}
+
+// In another entity's behavior
+class DamageReceiverBehavior extends GameEntityBehavior {
+    name = 'DamageReceiverBehavior';
+    eventSubscriptions = ['weapon:fired', 'healing:applied'];
+    
+    // Handle taking damage
+    handleWeaponFired(event: GameEvent, state: any): boolean {
+        // Only process if we're the target
+        if (event.data.target === this.entity.id) {
+            // Take damage
+            state.health -= event.data.damage;
+            
+            // Emit damaged event
+            this.$emit({
+                type: 'character:damaged',
+                data: { amount: event.data.damage }
+            });
+            
+            // Check if health is depleted
+            if (state.health <= 0) {
+                this.$emit({
+                    type: 'character:died',
+                    data: { cause: 'weapon' }
+                });
+            }
+            
+            return true;
+        }
+        return false;
+    }
+    
+    // Handle receiving healing
+    handleHealingApplied(event: GameEvent, state: any): boolean {
+        // Only process if we're the target
+        if (event.data.target === this.entity.id) {
+            // Apply healing
+            const oldHealth = state.health;
+            state.health = Math.min(state.maxHealth, state.health + event.data.amount);
+            
+            // Emit healed event
+            this.$emit({
+                type: 'character:healed',
+                data: { amount: state.health - oldHealth }
+            });
+            
+            return true;
+        }
+        return false;
+    }
+    
+    // Dispatch to the correct handler based on event type
+    processEvent(event: GameEvent, state: any): boolean {
+        if (event.type === 'weapon:fired') {
+            return this.handleWeaponFired(event, state);
+        }
+        
+        if (event.type === 'healing:applied') {
+            return this.handleHealingApplied(event, state);
+        }
+        
+        return false;
+    }
+}
+```
+
+### 2. Entity Queries
+
+Sometimes an entity needs to find specific other entities:
+
+```typescript
+class ReproductionBehavior extends GameEntityBehavior {
+    name = 'ReproductionBehavior';
+    
+    update(dt: number, state: any): void {
+        // Check if there are resources nearby
+        const entityManager = sage.managers.entityManager;
+        
+        // Look for food in the area
+        for (const entity of entityManager.entities.values()) {
+            if (entity.type === 'item:food' && this.isNearby(entity, state)) {
+                // Found food! Time to reproduce
+                state.reproductionTimer = 0;
+                
+                // Create a new entity
+                if (state.canReproduce) {
+                    entityManager.createEntity(this.entity.type, {
+                        position: { ...state.position }
+                    });
+                }
+                break;
+            }
+        }
+    }
+    
+    isNearby(entity, state) {
+        // Check proximity logic
+        // Implementation details...
+        return true;
+    }
+}
+```
+
+### 3. Direct Entity References
+
+For established relationships between entities:
+
+```typescript
+class ControllerBehavior extends GameEntityBehavior {
+    name = 'ControllerBehavior';
+    eventSubscriptions = ['controller:command'];
+    
+    processEvent(event: GameEvent, state: any): boolean {
+        if (event.type === 'controller:command') {
+            const entityManager = sage.managers.entityManager;
+            
+            // Manage controlled entities
+            if (!state.controlledEntities) {
+                state.controlledEntities = [];
+            }
+            
+            // Find entities to control
+            for (const entity of entityManager.entities.values()) {
+                if (entity.type === 'unit' && this.canControl(entity)) {
+                    // Add to controlled collection
+                    state.controlledEntities.push(entity.id);
+                    
+                    // Set entity to controlled state
+                    entity.state.controlled = true;
+                    entity.state.controllerId = this.entity.id;
+                }
+            }
+            return true;
+        }
+        return false;
+    }
+    
+    update(dt: number, state: any): void {
+        // Manage controlled entities
+        if (state.controlledEntities && state.controlledEntities.length > 0) {
+            const entityManager = sage.managers.entityManager;
+            
+            // Issue commands to controlled units
+            for (const unitId of state.controlledEntities) {
+                const unit = entityManager.getEntity(unitId);
+                if (unit) {
+                    // Command implementation
+                    // Details omitted...
+                }
+            }
+        }
+    }
+    
+    canControl(entity) {
+        // Control logic
+        // Implementation details...
+        return true;
+    }
+}
+```
+
+## Best Practices for Entity Design
+
+1. **Single-Responsibility Behaviors**: Each behavior should handle one aspect of functionality well.
+
+2. **Minimize Behavior Interdependencies**: Design behaviors that can operate independently of other specific behaviors when possible.
+
+3. **Use Events for Communication**: Instead of direct references between entities, use the event system to maintain loose coupling.
+
+4. **Modular Construction**: Build complex entities by combining simpler, reusable behaviors.
+
+5. **Test Behaviors Individually**: Validate behavior functionality in isolation before integration.
+
+6. **Document Behavior Needs**: Clearly document what state properties each behavior expects.
+
+7. **Consider Behavior Order**: Remember that the order behaviors are attached affects event processing priority.
+
+8. **Use the Strategy Pattern**: For behaviors that handle multiple event types, use separate methods for each type to keep your code organized.
+
+For detailed guidance on behavior implementation, best practices, and patterns, see the [Behaviors Guide](behaviors.md).
+
+## Performance Considerations
+
+- Monitor entities subscribing to high-frequency events
+- Batch similar updates when possible
+- Implement entity pooling for frequently created/destroyed objects
+- Use efficient entity queries and filtering
+
+## Debugging Tools
+
+- Create visualization behaviors for development
+- Implement event logging for tracking communication
+- Add runtime inspection tools for entities
+
+## Summary
+
+Our entity system provides a modular approach to game object creation. By focusing on small, reusable behaviors and communication through events, you can create games that are easier to build, modify, and maintain. This architecture supports projects of varying complexity while providing the flexibility needed to implement diverse gameplay mechanics.
+
+For the next steps in your learning journey:
+- Dive deeper into [Behaviors Guide](behaviors.md) to master behavior creation
+- Learn about communication with the [Event Bus Guide](eventbus.md)
+- Explore the [Scene System Guide](scene_system.md) for managing game worlds