@skewedaspect/sage 0.3.0

package/docs/behaviors.md

@@ -0,0 +1,706 @@
+# Behavior System Guide
+
+## Introduction
+
+In the SAGE engine, behaviors are the "personality modules" that give entities their abilities and define how they interact with the world. Think of behaviors like special power discs from Tron - each one gives your entity unique capabilities that can be combined in creative ways.
+
+This guide will walk you through creating and using behaviors, from basic concepts to advanced techniques. It serves as a detailed complement to the [Entity System Guide](entity_system.md), diving deeper into the behavior implementation specifics.
+
+## Behaviors: The Building Blocks of Functionality
+
+A behavior in SAGE is a reusable component that:
+- Has a unique name
+- Listens for specific events
+- Processes those events to update entity state
+- May perform updates each frame
+- Can emit new events for others to react to
+
+While the [Entity System Guide](entity_system.md) provides an overview of how behaviors fit into the larger picture, this guide focuses specifically on implementing and combining behaviors effectively.
+
+## Behavior Lifecycle
+
+When a behavior is attached to an entity, it goes through a specific lifecycle:
+
+1. **Initialization**: The behavior is instantiated and receives a reference to its parent entity
+2. **Subscription**: The behavior subscribes to any events it's interested in
+3. **Active Phase**: The behavior responds to events and executes update methods each frame
+4. **Detachment/Cleanup**: When removed, the behavior unsubscribes from events and cleans up any resources
+
+All behaviors automatically handle this lifecycle, but it's important to understand it when developing custom behaviors.
+
+## Creating Your First Behavior
+
+Let's create a simple behavior that makes an entity take damage and respond to healing:
+
+```typescript
+import { GameEntityBehavior, GameEvent } from '@skewedaspect/sage';
+
+// Define what state properties this behavior needs
+interface HealthState {
+  currentHealth: number;
+  maxHealth: number;
+  isAlive: boolean;
+}
+
+export class HealthBehavior extends GameEntityBehavior<HealthState> {
+  // The unique name of this behavior
+  name = 'HealthBehavior';
+  
+  // The event types this behavior listens for
+  eventSubscriptions = ['entity:damage', 'entity:heal'];
+  
+  // Handle incoming events
+  processEvent(event: GameEvent, state: HealthState): boolean {
+    if (event.type === 'entity:damage') {
+      const damage = event.payload?.amount || 0;
+      
+      // Reduce health by damage amount
+      state.currentHealth = Math.max(0, state.currentHealth - damage);
+      
+      // Check if entity is now dead
+      if (state.currentHealth === 0 && state.isAlive) {
+        state.isAlive = false;
+        
+        // Emit a death event for others to respond to
+        this.$emit({
+          type: 'entity:died',
+          payload: { 
+            causeOfDeath: 'damage',
+            finalBlow: event.payload  // Include info about what killed it
+          }
+        });
+      }
+      
+      return true; // We handled this event
+    }
+    
+    if (event.type === 'entity:heal') {
+      const healAmount = event.payload?.amount || 0;
+      
+      // Only heal if alive
+      if (state.isAlive) {
+        // Add health, but don't exceed max
+        state.currentHealth = Math.min(
+          state.maxHealth, 
+          state.currentHealth + healAmount
+        );
+        
+        // Let others know healing occurred
+        this.$emit({
+          type: 'entity:healed',
+          payload: { amount: healAmount }
+        });
+      }
+      
+      return true; // We handled this event
+    }
+    
+    return false; // We didn't handle this event
+  }
+  
+  // Optional: update method runs each frame
+  update(dt: number, state: HealthState): void {
+    // We could add regeneration over time here if desired
+  }
+}
+```
+
+## Core Behavior Methods
+
+Every behavior must implement these key methods or properties:
+
+### 1. The `name` Property
+
+```typescript
+name = 'MovementBehavior';
+```
+
+Each behavior needs a unique name that identifies it. This name is used when:
+- Detaching behaviors from entities
+- Debugging behavior issues
+- Managing behavior interactions
+
+### 2. The `eventSubscriptions` Property
+
+```typescript
+eventSubscriptions = ['input:jump', 'physics:collision'];
+```
+
+This array tells the system what events your behavior wants to listen for. When any of these events occur, your `processEvent` method will be called.
+
+### 3. The `processEvent` Method
+
+```typescript
+processEvent(event: GameEvent, state: any): boolean {
+  // Handle the event
+  if (event.type === 'input:jump') {
+    // Process jump input
+    state.velocity.y = state.jumpPower;
+    return true; // We handled this event
+  }
+  
+  return false; // We didn't handle this event
+}
+```
+
+This method is where your behavior responds to events. It receives:
+- The event object with type and payload
+- The entity's state object
+- Returns `true` if the event was handled, `false` otherwise
+
+The return value is important - if you return `true`, no other behaviors will process this event. This allows for "event filtering" where one behavior can intercept events before they reach others.
+
+### 4. The `update` Method (Optional)
+
+```typescript
+update(dt: number, state: any): void {
+  // Update entity state based on time
+  state.position.x += state.velocity.x * dt;
+  state.position.y += state.velocity.y * dt;
+  
+  // Apply gravity
+  state.velocity.y -= 9.8 * dt;
+}
+```
+
+This method runs every frame and lets your behavior apply continuous changes to the entity. The `dt` parameter represents the time (in seconds) since the last update, which helps create smooth, frame-rate independent movement.
+
+## Using Your Behavior
+
+To use this behavior, you need to:
+
+1. Include it in an entity definition
+2. Ensure the entity state includes the properties it needs
+
+```typescript
+// Register an entity definition with our behavior
+gameEngine.managers.entityManager.registerEntityDefinition({
+    type: 'character:hero',
+    defaultState: {
+        name: 'Frodo',
+        currentHealth: 100,    // Required by HealthBehavior
+        maxHealth: 100,        // Required by HealthBehavior
+        isAlive: true,         // Required by HealthBehavior
+        position: { x: 0, y: 0, z: 0 }
+    },
+    behaviors: [
+        HealthBehavior,        // Add our health behavior
+        MovementBehavior       // Add other behaviors as needed
+    ]
+});
+
+// Create the entity with additional initial state
+const hero = gameEngine.managers.entityManager.createEntity('character:hero', { currentHealth: 80 });
+```
+
+## Integrating with the Entity System
+
+While we've seen how to create individual behaviors, the real power comes from how they integrate with the entity system. As described in the [Entity System Guide](entity_system.md), behaviors are the functional building blocks that power entities.
+
+Here's how behaviors connect with the broader entity architecture:
+
+1. **Entity Definitions**: When you register an entity type, you specify which behaviors it should have
+
+2. **State Sharing**: All behaviors attached to the same entity share access to that entity's state object
+
+3. **Event Flow**: When an event targets an entity, it flows through all behaviors in the order they were attached
+
+4. **Behavior Dependencies**: Some behaviors may depend on others (like an animation behavior responding to a movement behavior's changes)
+
+## Behavior Composition
+
+The true power of behaviors comes from combining them. Let's see how multiple behaviors can work together:
+
+```typescript
+// A behavior for inventory management
+class InventoryBehavior extends GameEntityBehavior<{ items: any[] }> {
+  name = 'InventoryBehavior';
+  eventSubscriptions = ['item:pickup', 'item:use'];
+  
+  processEvent(event: GameEvent, state: any): boolean {
+    if (event.type === 'item:pickup') {
+      state.items.push(event.payload.item);
+      return true;
+    }
+    
+    if (event.type === 'item:use' && event.payload.itemIndex < state.items.length) {
+      const item = state.items[event.payload.itemIndex];
+      
+      // Emit an event that something else might listen for
+      this.$emit({
+        type: 'item:effect',
+        payload: { item }
+      });
+      
+      // If it's a one-time use item, remove it
+      if (item.consumable) {
+        state.items.splice(event.payload.itemIndex, 1);
+      }
+      
+      return true;
+    }
+    
+    return false;
+  }
+}
+
+// A behavior to handle potion effects
+class PotionEffectBehavior extends GameEntityBehavior {
+  name = 'PotionEffectBehavior';
+  eventSubscriptions = ['item:effect'];
+  
+  processEvent(event: GameEvent, state: any): boolean {
+    if (event.type === 'item:effect' && event.payload.item.type === 'potion') {
+      const potion = event.payload.item;
+      
+      if (potion.effect === 'healing') {
+        // Re-emit as a healing event that HealthBehavior will handle
+        this.$emit({
+          type: 'entity:heal',
+          payload: { amount: potion.power }
+        });
+        
+        return true;
+      }
+    }
+    
+    return false;
+  }
+}
+```
+
+Now, when a character uses a healing potion:
+1. `InventoryBehavior` handles the item use and emits an `item:effect` event
+2. `PotionEffectBehavior` receives that event, sees it's a healing potion, and emits `entity:heal`
+3. `HealthBehavior` receives the `entity:heal` event and increases health accordingly
+
+All this happens without any of these behaviors needing to know about each other directly!
+
+## Advanced Behavior Techniques
+
+### Dynamic Behavior Attachment
+
+Behaviors can be attached or detached at runtime:
+
+```typescript
+// Give a character temporary invincibility
+const invincibilityBehavior = new InvincibilityBehavior();
+hero.attachBehavior(invincibilityBehavior);
+
+// Later, remove the behavior
+setTimeout(() => {
+  hero.detachBehavior('InvincibilityBehavior');
+  console.log("Your star power has worn off!");
+}, 10000);
+```
+
+This dynamic ability to modify entity capabilities allows for:
+- Power-ups and temporary abilities
+- Status effects (like being stunned or poisoned)
+- Progressive character development (learning new skills)
+- Context-sensitive behaviors (different abilities in water vs. land)
+
+### State Dependencies
+
+When designing behaviors, be explicit about what state properties they need:
+
+```typescript
+// This behavior needs very specific state structure
+class AiBehavior extends GameEntityBehavior<{
+  target: { id: string; } | null;
+  aiState: 'idle' | 'chase' | 'attack' | 'flee';
+  lastDecisionTime: number;
+  position: { x: number; y: number; z: number; };
+}> {
+  name = 'AiBehavior';
+  // ...implementation...
+}
+```
+
+Using TypeScript interfaces as shown above creates a contract that:
+- Documents what state your behavior requires
+- Provides type safety and autocomplete when accessing state properties
+- Makes it clear to other developers what your behavior depends on
+
+### Behavior Initialization and Cleanup
+
+For behaviors that need to set up resources or perform cleanup:
+
+```typescript
+class NetworkBehavior extends GameEntityBehavior {
+  name = 'NetworkBehavior';
+  private connection: WebSocket | null = null;
+  
+  // Called when attached to an entity
+  onAttached(): void {
+    super.onAttached();
+    
+    // Set up network connection
+    this.connection = new WebSocket('wss://game-server.example.com');
+    this.connection.onmessage = this.handleMessage.bind(this);
+  }
+  
+  // Called when detached from an entity
+  onDetached(): void {
+    // Clean up network resources
+    if (this.connection) {
+      this.connection.close();
+      this.connection = null;
+    }
+    
+    super.onDetached();
+  }
+  
+  private handleMessage(msg: MessageEvent): void {
+    // Process network messages
+    // ...
+  }
+}
+```
+
+Always remember to call the parent class methods (`super.onAttached()` and `super.onDetached()`) to ensure proper behavior lifecycle management.
+
+### Communication Patterns
+
+Behaviors can communicate in several ways:
+
+1. **Direct State Modification**: Behaviors that share an entity can access the same state
+2. **Event Broadcasting**: Emit events that other behaviors respond to
+3. **Entity References**: Store references to other entities in state
+
+Each approach has different tradeoffs:
+
+```typescript
+// Direct state modification - simple but creates tight coupling
+class MovementBehavior extends GameEntityBehavior {
+  update(dt: number, state: any): void {
+    state.position.x += state.velocity.x * dt;
+    // Animation system can read directly from state
+    state.isMoving = Math.abs(state.velocity.x) > 0.1;
+  }
+}
+
+class AnimationBehavior extends GameEntityBehavior {
+  update(dt: number, state: any): void {
+    // Directly reads state set by movement behavior
+    if (state.isMoving) {
+      playAnimation('walk');
+    } else {
+      playAnimation('idle');
+    }
+  }
+}
+
+// Event broadcasting - more decoupled but less direct
+class MovementBehavior extends GameEntityBehavior {
+  update(dt: number, state: any): void {
+    const oldX = state.position.x;
+    state.position.x += state.velocity.x * dt;
+    
+    // Emit event only when movement state changes
+    const isMovingNow = Math.abs(state.velocity.x) > 0.1;
+    if (isMovingNow !== state.isMoving) {
+      state.isMoving = isMovingNow;
+      this.$emit({
+        type: 'entity:movementChanged',
+        payload: { isMoving: state.isMoving }
+      });
+    }
+  }
+}
+
+class AnimationBehavior extends GameEntityBehavior {
+  eventSubscriptions = ['entity:movementChanged'];
+  
+  processEvent(event: GameEvent, state: any): boolean {
+    if (event.type === 'entity:movementChanged') {
+      if (event.payload.isMoving) {
+        playAnimation('walk');
+      } else {
+        playAnimation('idle');
+      }
+      return true;
+    }
+    return false;
+  }
+}
+```
+
+### Behavior Priorities
+
+The order behaviors are attached matters! Events are processed in attachment order, and any behavior can stop further processing by returning `true` from `processEvent`.
+
+```typescript
+// Shield behavior might intercept damage before it reaches health
+const entityDef = {
+  type: 'character:tank',
+  initialState: { /* ... */ },
+  behaviors: [
+    ShieldBehavior,  // First chance to handle damage
+    ArmorBehavior,   // Second chance to reduce damage
+    HealthBehavior   // Finally, apply any remaining damage
+  ]
+};
+```
+
+This ordering enables powerful patterns like:
+- Damage reduction chains (shields → armor → health)
+- Input filtering (disable player control when stunned)
+- Event transformation (convert raw inputs to game commands)
+
+## Specialized Behavior Types
+
+Beyond basic behaviors, you can create specialized types for common tasks:
+
+### Physics Behaviors
+
+```typescript
+class PhysicsBodyBehavior extends GameEntityBehavior {
+  name = 'PhysicsBodyBehavior';
+  private body: PhysicsBody | null = null;
+  
+  onAttached(): void {
+    super.onAttached();
+    
+    // Create physics body in the physics engine
+    this.body = physicsEngine.createBody({
+      type: 'dynamic',
+      position: this.entity.state.position,
+      mass: this.entity.state.mass || 1
+    });
+  }
+  
+  update(dt: number, state: any): void {
+    if (this.body) {
+      // Sync physics engine position to entity
+      const pos = this.body.getPosition();
+      state.position.x = pos.x;
+      state.position.y = pos.y;
+    }
+  }
+  
+  onDetached(): void {
+    // Remove body from physics engine
+    if (this.body) {
+      physicsEngine.removeBody(this.body);
+      this.body = null;
+    }
+    
+    super.onDetached();
+  }
+}
+```
+
+### Input Behaviors
+
+```typescript
+class PlayerInputBehavior extends GameEntityBehavior {
+  name = 'PlayerInputBehavior';
+  eventSubscriptions = ['input:keydown', 'input:keyup', 'input:gamepad'];
+  
+  processEvent(event: GameEvent, state: any): boolean {
+    if (event.type === 'input:keydown') {
+      // Map keyboard input to game actions
+      switch (event.payload.key) {
+        case 'ArrowLeft':
+          state.movement = 'left';
+          this.$emit({ type: 'player:move', payload: { direction: 'left' } });
+          return true;
+        case 'ArrowRight':
+          state.movement = 'right';
+          this.$emit({ type: 'player:move', payload: { direction: 'right' } });
+          return true;
+        case 'Space':
+          this.$emit({ type: 'player:jump' });
+          return true;
+      }
+    }
+    
+    if (event.type === 'input:keyup') {
+      // Handle key release
+      switch (event.payload.key) {
+        case 'ArrowLeft':
+        case 'ArrowRight':
+          state.movement = 'none';
+          this.$emit({ type: 'player:stopMove' });
+          return true;
+      }
+    }
+    
+    return false;
+  }
+}
+```
+
+### AI Behaviors
+
+```typescript
+class SimpleEnemyAI extends GameEntityBehavior {
+  name = 'SimpleEnemyAI';
+  eventSubscriptions = ['entity:spotted', 'entity:lostTarget'];
+  
+  processEvent(event: GameEvent, state: any): boolean {
+    if (event.type === 'entity:spotted' && event.payload.type === 'player') {
+      state.target = event.payload.id;
+      state.aiState = 'chase';
+      return true;
+    }
+    
+    if (event.type === 'entity:lostTarget') {
+      state.target = null;
+      state.aiState = 'patrol';
+      return true;
+    }
+    
+    return false;
+  }
+  
+  update(dt: number, state: any): void {
+    switch (state.aiState) {
+      case 'idle':
+        // Just stand around
+        break;
+        
+      case 'patrol':
+        // Move along patrol path
+        this.updatePatrolBehavior(dt, state);
+        break;
+        
+      case 'chase':
+        // Chase target if we have one
+        if (state.target) {
+          this.chaseTarget(dt, state);
+        }
+        break;
+    }
+  }
+  
+  private updatePatrolBehavior(dt: number, state: any): void {
+    // Patrol logic implementation
+    // ...
+  }
+  
+  private chaseTarget(dt: number, state: any): void {
+    // Chase target logic
+    // ...
+  }
+}
+```
+
+## Testing Behaviors
+
+Behaviors are highly testable in isolation:
+
+```typescript
+import { expect } from 'chai';
+import { HealthBehavior } from './behaviors/health';
+
+describe('HealthBehavior', () => {
+  it('should reduce health when damaged', () => {
+    const behavior = new HealthBehavior();
+    const state = { currentHealth: 100, maxHealth: 100, isAlive: true };
+    
+    // Mock the $emit method
+    behavior.$emit = () => {};
+    
+    // Process a damage event
+    behavior.processEvent({ 
+      type: 'entity:damage', 
+      payload: { amount: 30 } 
+    }, state);
+    
+    expect(state.currentHealth).to.equal(70);
+    expect(state.isAlive).to.be.true;
+  });
+  
+  it('should emit death event when health reaches zero', () => {
+    const behavior = new HealthBehavior();
+    const state = { currentHealth: 30, maxHealth: 100, isAlive: true };
+    let emittedEvent = null;
+    
+    // Mock the $emit method
+    behavior.$emit = (event) => { emittedEvent = event; };
+    
+    // Process a lethal damage event
+    behavior.processEvent({ 
+      type: 'entity:damage', 
+      payload: { amount: 50 } 
+    }, state);
+    
+    expect(state.currentHealth).to.equal(0);
+    expect(state.isAlive).to.be.false;
+    expect(emittedEvent).to.not.be.null;
+    expect(emittedEvent.type).to.equal('entity:died');
+  });
+  
+  // More tests...
+});
+```
+
+## Designing Event-Driven Behavior Systems
+
+When creating a complex game with many behaviors, consider these design patterns:
+
+### Event Vocabulary
+
+Develop a consistent pattern for event naming:
+
+```
+category:action
+```
+
+Examples:
+- `player:move` - Player initiated movement
+- `entity:damage` - Entity received damage
+- `item:pickup` - Item was picked up
+- `scene:loaded` - Scene finished loading
+
+This consistency makes it easier to understand event flows and predict event names.
+
+### Behavior Composition Patterns
+
+Several patterns emerge when combining behaviors:
+
+1. **Filter Chain**: Behaviors process events in sequence, with each potentially modifying or blocking the event
+   - Example: Input → ActionValidation → ActionExecution
+
+2. **Observer Pattern**: Multiple independent behaviors respond to the same events
+   - Example: Achievement, Sound, and Animation behaviors all listening for "enemy:defeated"
+
+3. **Command Pattern**: Behaviors emit high-level command events that other behaviors execute
+   - Example: AI emits "movement:request" that MovementBehavior handles
+
+4. **State Machine**: Behaviors implement state transitions and state-specific logic
+   - Example: Character states like "idle", "walking", "jumping", "attacking"
+
+## Best Practices
+
+1. **Single Responsibility**: Each behavior should do one thing well
+2. **Clear Dependencies**: Be explicit about what state properties a behavior needs
+3. **Use TypeScript Interfaces**: Define interfaces for your state requirements
+4. **Document Event Types**: Keep a registry of event types and their payload formats
+5. **Behavior Composition**: Solve complex problems by combining simple behaviors
+6. **Avoid Direct References**: Prefer events over direct references between behaviors
+7. **Test in Isolation**: Write unit tests for individual behaviors
+8. **Watch Event Performance**: Monitor high-frequency events that might impact performance
+
+## Common Behavior Types
+
+Some behaviors you might want to implement in your games:
+
+- **MovementBehavior**: Handle entity position and velocity
+- **HealthBehavior**: Manage damage and healing
+- **InputBehavior**: Process player inputs
+- **AiBehavior**: Control NPC decision making
+- **CombatBehavior**: Handle attack and defense logic
+- **PhysicsBehavior**: Interface with the physics engine
+- **AnimationBehavior**: Control visual animations
+- **SoundBehavior**: Manage entity sound effects
+- **InteractionBehavior**: Handle entity interactions with the world
+- **InventoryBehavior**: Manage collected items
+
+## Conclusion
+
+Behaviors are the heart of the SAGE entity system. By creating small, focused behaviors and combining them in different ways, you can build complex game objects with minimal code duplication. Remember that the key to good behavior design is composition - build simple behaviors that do one thing well, then combine them to create rich, interactive entities.
+
+For more information on how behaviors fit into the overall entity architecture, see the [Entity System Guide](entity_system.md). To understand the event system that powers behavior communication, check out the [Event Bus Guide](eventbus.md).