@skewedaspect/sage 0.3.0

package/docs/physics_system.md

@@ -0,0 +1,686 @@
+# Physics System Guide
+
+## Introduction
+
+The physics system in SAGE is the force that brings your game world to life, making objects move, collide, and interact in realistic ways. Powered by Havok Physics through BabylonJS, SAGE provides a robust physics implementation that balances realism with performance.
+
+This guide will walk you through how to use physics in your SAGE games, from basic concepts to advanced techniques.
+
+## Core Concepts
+
+Physics in games simulates the fundamental forces that govern how objects interact:
+
+- **Gravity**: Pulls objects downward
+- **Collisions**: Determines how objects interact when they touch
+- **Forces**: Push, pull, and otherwise affect objects
+- **Constraints**: Limit how objects can move relative to one another
+
+In SAGE, physics simulation is handled automatically as part of the game loop, but you have control over how entities interact with the physics system.
+
+## Getting Started with Physics
+
+SAGE initializes the physics system automatically when you create the game engine:
+
+```typescript
+import { createGameEngine } from '@skewedaspect/sage';
+
+async function initGame() {
+  const canvas = document.getElementById('gameCanvas') as HTMLCanvasElement;
+  
+  // Physics is initialized here
+  const gameEngine = await createGameEngine(canvas);
+  
+  // The physics system is accessible through
+  const physics = gameEngine.physics;
+}
+```
+
+## Physical Objects
+
+To make an entity interact with the physics system, you need to:
+
+1. Create a visual representation (mesh)
+2. Add a physics body (via PhysicsAggregate)
+3. Connect the physics body to your entity state
+
+Here's a behavior that handles physics for an entity:
+
+```typescript
+import { GameEntityBehavior, GameEvent } from '@skewedaspect/sage';
+import { 
+  PhysicsAggregate, 
+  PhysicsShapeType, 
+  Vector3 
+} from '@babylonjs/core';
+
+// Define what state a physical entity needs
+interface PhysicalObjectState {
+  position: { x: number, y: number, z: number };
+  mass: number;
+  restitution: number; // "bounciness"
+  friction: number;
+  isStatic: boolean;
+  shape: 'box' | 'sphere' | 'capsule' | 'cylinder' | 'mesh';
+  dimensions: { width?: number, height?: number, depth?: number, radius?: number };
+  
+  // Properties to be set by the behavior
+  physicsAggregate?: any;
+  mesh?: any;
+}
+
+export class PhysicsBehavior extends GameEntityBehavior<PhysicalObjectState> {
+  name = 'PhysicsBehavior';
+  eventSubscriptions = ['scene:loaded', 'physics:applyForce', 'physics:setVelocity'];
+  
+  processEvent(event: GameEvent, state: PhysicalObjectState): boolean {
+    if (event.type === 'scene:loaded') {
+      // Create physical representation when scene is available
+      this.createPhysicalObject(event.payload.scene, state);
+      return true;
+    }
+    
+    if (event.type === 'physics:applyForce' && state.physicsAggregate) {
+      const force = event.payload.force;
+      const contactPoint = event.payload.contactPoint || 
+        new Vector3(state.position.x, state.position.y, state.position.z);
+      
+      // Apply a force at a specific point
+      state.physicsAggregate.body.applyForce(
+        new Vector3(force.x, force.y, force.z),
+        new Vector3(contactPoint.x, contactPoint.y, contactPoint.z)
+      );
+      return true;
+    }
+    
+    if (event.type === 'physics:setVelocity' && state.physicsAggregate) {
+      const velocity = event.payload.velocity;
+      
+      // Set linear velocity directly
+      state.physicsAggregate.body.setLinearVelocity(
+        new Vector3(velocity.x, velocity.y, velocity.z)
+      );
+      return true;
+    }
+    
+    return false;
+  }
+  
+  // Called every frame to sync physics state back to entity
+  update(_dt: number, state: PhysicalObjectState): void {
+    if (state.physicsAggregate && !state.isStatic) {
+      // Get position from physics engine
+      const physicsPosition = state.physicsAggregate.transformNode.position;
+      
+      // Update entity state with physics position
+      state.position.x = physicsPosition.x;
+      state.position.y = physicsPosition.y;
+      state.position.z = physicsPosition.z;
+    }
+  }
+  
+  // Create the physical representation
+  createPhysicalObject(scene, state: PhysicalObjectState): void {
+    // Create mesh based on shape
+    const mesh = this.createMesh(scene, state);
+    state.mesh = mesh;
+    
+    // Set initial position
+    mesh.position.x = state.position.x;
+    mesh.position.y = state.position.y;
+    mesh.position.z = state.position.z;
+    
+    // Determine physics shape
+    let shapeType: PhysicsShapeType;
+    switch (state.shape) {
+      case 'box':
+        shapeType = PhysicsShapeType.BOX;
+        break;
+      case 'sphere':
+        shapeType = PhysicsShapeType.SPHERE;
+        break;
+      case 'capsule':
+        shapeType = PhysicsShapeType.CAPSULE;
+        break;
+      case 'cylinder':
+        shapeType = PhysicsShapeType.CYLINDER;
+        break;
+      case 'mesh':
+        shapeType = PhysicsShapeType.MESH;
+        break;
+      default:
+        shapeType = PhysicsShapeType.BOX;
+    }
+    
+    // Create physics body
+    const physicsAggregate = new PhysicsAggregate(
+      mesh,
+      shapeType,
+      { 
+        mass: state.isStatic ? 0 : state.mass, 
+        restitution: state.restitution,
+        friction: state.friction
+      },
+      scene
+    );
+    
+    state.physicsAggregate = physicsAggregate;
+  }
+  
+  // Create appropriate mesh based on shape
+  createMesh(scene, state: PhysicalObjectState): any {
+    // Implementation would create the right shape of mesh
+    // based on the state.shape and state.dimensions
+    // For brevity, implementation details omitted
+    
+    // Example for a box:
+    // return MeshBuilder.CreateBox('box', {
+    //   width: state.dimensions.width || 1,
+    //   height: state.dimensions.height || 1,
+    //   depth: state.dimensions.depth || 1
+    // }, scene);
+  }
+}
+```
+
+## Using the Physics Behavior
+
+To use the physics behavior with an entity:
+
+```typescript
+// Register an entity with physics
+gameEngine.managers.entityManager.registerEntityDefinition({
+    type: 'prop:crate',
+    defaultState: {
+        position: { x: 0, y: 5, z: 0 }, // Start 5 units above origin
+        mass: 1.5,
+        restitution: 0.4,
+        friction: 0.8,
+        isStatic: false,
+        shape: 'box',
+        dimensions: { width: 1, height: 1, depth: 1 }
+    },
+    behaviors: [
+        PhysicsBehavior,
+        VisualRepresentationBehavior  // For handling appearance
+    ]
+});
+
+// Create the entity with additional initial state
+const crate = gameEngine.managers.entityManager.createEntity('prop:crate', { position: { x: 10, y: 5, z: 0 } });
+```
+
+## Collision Detection
+
+One of the most important features of a physics system is collision detection. Here's how to handle collisions in SAGE:
+
+```typescript
+import { ActionManager, ExecuteCodeAction } from '@babylonjs/core';
+
+// A behavior that responds to collisions
+class CollisionBehavior extends GameEntityBehavior<{ health: number }> {
+  name = 'CollisionBehavior';
+  eventSubscriptions = ['entity:physicsMeshCreated'];
+  
+  processEvent(event: GameEvent, state: any): boolean {
+    if (event.type === 'entity:physicsMeshCreated') {
+      const mesh = event.payload.mesh;
+      this.setupCollisionHandling(mesh, state);
+      return true;
+    }
+    return false;
+  }
+  
+  setupCollisionHandling(mesh, state): void {
+    if (!mesh) return;
+    
+    // Create action manager if it doesn't exist
+    if (!mesh.actionManager) {
+      mesh.actionManager = new ActionManager(mesh.getScene());
+    }
+    
+    // Register intersection event with any other mesh
+    mesh.actionManager.registerAction(
+      new ExecuteCodeAction(
+        { trigger: ActionManager.OnIntersectionEnterTrigger },
+        (evt) => {
+          // Get the other mesh
+          const otherMesh = evt.source;
+          
+          // Emit collision event
+          this.$emit({
+            type: 'entity:collision',
+            payload: {
+              otherMeshId: otherMesh.id,
+              velocity: mesh.physicsAggregate?.body.getLinearVelocity(),
+              collisionPoint: evt.additionalData?.contactPoint
+            }
+          });
+          
+          // For a damage-causing collision, we might:
+          const impactForce = this.calculateImpactForce(
+            mesh.physicsAggregate?.body,
+            otherMesh.physicsAggregate?.body
+          );
+          
+          if (impactForce > 5) { // Threshold for damage
+            // Take damage proportional to impact
+            const damageTaken = Math.floor(impactForce * 0.5);
+            state.health -= damageTaken;
+            
+            // Emit damage event
+            this.$emit({
+              type: 'entity:damage',
+              payload: {
+                amount: damageTaken,
+                source: 'collision',
+                otherMeshId: otherMesh.id
+              }
+            });
+          }
+        }
+      )
+    );
+  }
+  
+  calculateImpactForce(bodyA, bodyB) {
+    if (!bodyA || !bodyB) return 0;
+    
+    // Get velocities
+    const velA = bodyA.getLinearVelocity();
+    const velB = bodyB.getLinearVelocity();
+    
+    // Calculate relative velocity magnitude (simplified)
+    const relVelocity = new Vector3(
+      velA.x - velB.x,
+      velA.y - velB.y,
+      velA.z - velB.z
+    );
+    
+    return relVelocity.length();
+  }
+}
+```
+
+## Physics Constraints
+
+Physics constraints allow you to create complex mechanical connections between objects:
+
+```typescript
+import { PhysicsConstraint, DistanceConstraint } from '@babylonjs/core';
+
+// A behavior that creates a swinging pendulum
+class PendulumBehavior extends GameEntityBehavior {
+  name = 'PendulumBehavior';
+  eventSubscriptions = ['entity:physicsMeshCreated', 'entity:attachToPoint'];
+  
+  processEvent(event: GameEvent, state: any): boolean {
+    if (event.type === 'entity:physicsMeshCreated') {
+      // Store the mesh for later constraint setup
+      state.mesh = event.payload.mesh;
+      return true;
+    }
+    
+    if (event.type === 'entity:attachToPoint') {
+      if (!state.mesh) return false;
+      
+      const point = event.payload.point;
+      const scene = state.mesh.getScene();
+      
+      // Create a fixed point in space
+      const pivotPoint = MeshBuilder.CreateSphere(
+        'pivot',
+        { diameter: 0.1 },
+        scene
+      );
+      pivotPoint.position = new Vector3(point.x, point.y, point.z);
+      
+      // Make the pivot static (immovable)
+      const pivotAggregate = new PhysicsAggregate(
+        pivotPoint,
+        PhysicsShapeType.SPHERE,
+        { mass: 0 },
+        scene
+      );
+      
+      // Create a distance constraint (rope)
+      const ropeLength = event.payload.length || 5;
+      const constraint = new DistanceConstraint({
+        pivotA: new Vector3(0, 0, 0),  // Local to pivot
+        pivotB: new Vector3(0, 0, 0),  // Local to object
+        maxDistance: ropeLength
+      });
+      
+      // Connect the constraint
+      constraint.attachAll(
+        true,                  // Be collision-enabled
+        pivotAggregate.body,   // The fixed point
+        state.mesh.physicsAggregate.body // The swinging object
+      );
+      
+      // Store the constraint
+      state.constraint = constraint;
+      
+      return true;
+    }
+    
+    return false;
+  }
+}
+
+// Usage example - create a wrecking ball
+gameEngine.managers.entityManager.registerEntityDefinition({
+  type: 'prop:wreckingBall',
+  initialState: {
+    position: { x: 0, y: 5, z: 0 },
+    mass: 5000,  // Very heavy!
+    restitution: 0.2,
+    friction: 0.8,
+    isStatic: false,
+    shape: 'sphere',
+    dimensions: { radius: 2 }
+  },
+  behaviors: [
+    PhysicsBehavior,
+    PendulumBehavior,
+    VisualRepresentationBehavior
+  ]
+});
+
+// Create and set up the wrecking ball
+const wreckingBall = gameEngine.managers.entityManager.createEntity('prop:wreckingBall');
+
+// Attach it to a high point
+gameEngine.eventBus.publish({
+  type: 'entity:attachToPoint',
+  targetID: wreckingBall.id,
+  payload: {
+    point: { x: 0, y: 20, z: 0 },  // 20 units up
+    length: 15  // 15 unit long cable
+  }
+});
+
+// Give it a push
+gameEngine.eventBus.publish({
+  type: 'physics:applyForce',
+  targetID: wreckingBall.id,
+  payload: {
+    force: { x: 50000, y: 0, z: 0 }  // Strong push!
+  }
+});
+```
+
+## Ragdoll Physics
+
+For more complex character physics, such as ragdoll effects:
+
+```typescript
+class RagdollBehavior extends GameEntityBehavior {
+  name = 'RagdollBehavior';
+  eventSubscriptions = ['entity:die', 'entity:characterMeshCreated'];
+  
+  // This implementation would be complex
+  // Main concepts:
+  // 1. Create physics body for each character limb
+  // 2. Connect limbs with constraints (joints)
+  // 3. Keep ragdoll disabled until needed
+  // 4. On death, enable ragdoll and disable character controller
+  
+  processEvent(event: GameEvent, state: any): boolean {
+    if (event.type === 'entity:characterMeshCreated') {
+      // Set up the ragdoll structure
+      this.setupRagdoll(event.payload.meshes, state);
+      return true;
+    }
+    
+    if (event.type === 'entity:die') {
+      // Enable ragdoll physics when character dies
+      this.enableRagdoll(state);
+      return true;
+    }
+    
+    return false;
+  }
+  
+  // Implementation details omitted for brevity
+  // Would involve creating separate physics bodies for
+  // head, torso, arms, legs, etc. and connecting them
+  // with ball-socket constraints
+}
+```
+
+## Performance Considerations
+
+Physics simulation is computationally expensive. Here are some tips for optimizing physics in your game:
+
+1. **Use Simple Collision Shapes**: Wherever possible, use primitive shapes (boxes, spheres) instead of complex meshes.
+
+2. **Static Objects**: Make non-moving objects static (mass = 0).
+
+3. **Sleep Parameters**: Objects that haven't moved in a while can be "put to sleep" by the physics engine.
+
+4. **Physics Layers**: Group objects into physics layers and control which layers interact with each other.
+
+```typescript
+// Setting up selective collision filtering
+function setupCollisionGroups(physics) {
+  // Define collision groups
+  const PLAYER_GROUP = 1;
+  const ENEMY_GROUP = 2;
+  const ENVIRONMENT_GROUP = 4;
+  const PROJECTILE_GROUP = 8;
+  
+  // Setup examples:
+  
+  // Player collides with environment and enemies, but not other players
+  playerAggregate.body.setCollisionFilteringGroups(
+    PLAYER_GROUP,                             // My group
+    ENVIRONMENT_GROUP | ENEMY_GROUP           // Groups I collide with
+  );
+  
+  // Projectiles collide with enemies and environment, but not other projectiles
+  projectileAggregate.body.setCollisionFilteringGroups(
+    PROJECTILE_GROUP,
+    ENVIRONMENT_GROUP | ENEMY_GROUP
+  );
+}
+```
+
+5. **Level of Detail**: Use simpler physics for distant objects.
+
+## Common Physics Patterns
+
+### Character Controller
+
+A common pattern for character movement that balances physics realism with responsive controls:
+
+```typescript
+class CharacterControllerBehavior extends GameEntityBehavior {
+  name = 'CharacterControllerBehavior';
+  eventSubscriptions = ['input:move', 'input:jump', 'entity:physicsMeshCreated'];
+  
+  processEvent(event: GameEvent, state: any): boolean {
+    if (event.type === 'entity:physicsMeshCreated') {
+      // Configure physics for character control
+      this.setupCharacterPhysics(event.payload.mesh, state);
+      return true;
+    }
+    
+    if (event.type === 'input:move' && state.controller) {
+      const direction = event.payload.direction;
+      
+      // Apply movement forces
+      this.moveCharacter(direction, state);
+      return true;
+    }
+    
+    if (event.type === 'input:jump' && state.controller) {
+      // Check if on ground
+      if (this.isGrounded(state)) {
+        // Apply jump impulse
+        state.physicsAggregate.body.applyImpulse(
+          new Vector3(0, state.jumpForce, 0),
+          state.physicsAggregate.transformNode.position
+        );
+      }
+      return true;
+    }
+    
+    return false;
+  }
+  
+  setupCharacterPhysics(mesh, state) {
+    // Character-specific physics setup
+    // Often uses a capsule shape and special friction settings
+    
+    // Store controller state
+    state.controller = {
+      isGrounded: false,
+      lastGroundCheckTime: 0,
+      currentVelocity: { x: 0, y: 0, z: 0 }
+    };
+  }
+  
+  moveCharacter(direction, state) {
+    // Use forces for ground movement, but in a controlled way
+    const physicsBody = state.physicsAggregate.body;
+    
+    // Get current velocity
+    const velocity = physicsBody.getLinearVelocity();
+    
+    // Calculate target velocity based on input
+    const targetVelocity = {
+      x: direction.x * state.moveSpeed,
+      z: direction.z * state.moveSpeed,
+    };
+    
+    // Calculate required force to reach target velocity
+    const force = {
+      x: (targetVelocity.x - velocity.x) * state.acceleration,
+      z: (targetVelocity.z - velocity.z) * state.acceleration
+    };
+    
+    // Apply horizontal forces
+    physicsBody.applyForce(
+      new Vector3(force.x, 0, force.z),
+      state.physicsAggregate.transformNode.position
+    );
+  }
+  
+  isGrounded(state) {
+    // Implementation would use raycasting to check if
+    // the character is standing on something
+    
+    // For performance, we don't check every frame
+    const now = performance.now();
+    if (now - state.controller.lastGroundCheckTime < 100) {
+      return state.controller.isGrounded;
+    }
+    
+    // Use BabylonJS raycasting for ground check
+    const origin = state.physicsAggregate.transformNode.position.clone();
+    const direction = new Vector3(0, -1, 0);
+    const length = state.height * 0.55; // Slightly more than half height
+    
+    const ray = new Ray(origin, direction, length);
+    const hit = state.mesh.getScene().pickWithRay(ray);
+    
+    state.controller.isGrounded = hit.hit;
+    state.controller.lastGroundCheckTime = now;
+    
+    return state.controller.isGrounded;
+  }
+  
+  update(dt: number, state: any): void {
+    if (state.controller) {
+      // Check grounding status regularly
+      this.isGrounded(state);
+      
+      // Apply drag to prevent sliding
+      if (state.controller.isGrounded) {
+        const physicsBody = state.physicsAggregate.body;
+        const velocity = physicsBody.getLinearVelocity();
+        
+        // Apply horizontal drag
+        physicsBody.applyForce(
+          new Vector3(
+            -velocity.x * state.groundFriction,
+            0,
+            -velocity.z * state.groundFriction
+          ),
+          state.physicsAggregate.transformNode.position
+        );
+      }
+    }
+  }
+}
+```
+
+### Vehicle Physics
+
+For implementing vehicles with wheels, suspension, etc.:
+
+```typescript
+class VehicleBehavior extends GameEntityBehavior {
+  name = 'VehicleBehavior';
+  eventSubscriptions = ['input:accelerate', 'input:brake', 'input:turn'];
+  
+  // This would be a complex implementation
+  // Key concepts:
+  // 1. Create chassis as main body
+  // 2. Create wheels as separate physics objects
+  // 3. Connect wheels with physics constraints that simulate suspension
+  // 4. Apply forces to wheels for acceleration/braking
+  // 5. Apply steering by rotating wheel constraints
+  
+  // Implementation details omitted for brevity
+}
+```
+
+## Debugging Physics
+
+To debug physics in your game:
+
+```typescript
+import { PhysicsViewer } from '@babylonjs/core';
+
+function setupPhysicsDebugging(scene) {
+  // Create a physics viewer
+  const physicsViewer = new PhysicsViewer(scene);
+  
+  // Show physics impostors for all objects
+  for (const mesh of scene.meshes) {
+    if (mesh.physicsAggregate) {
+      physicsViewer.showImpostor(mesh.physicsAggregate.body, mesh);
+    }
+  }
+  
+  // Toggle visibility with a key
+  window.addEventListener('keydown', (e) => {
+    if (e.key === 'p') {
+      physicsViewer.isEnabled = !physicsViewer.isEnabled;
+    }
+  });
+  
+  return physicsViewer;
+}
+```
+
+## Best Practices
+
+1. **Match Visual and Physical Representations**: Keep your visual meshes and physics bodies aligned.
+
+2. **Use Continuous Collision Detection** for fast-moving objects to prevent "tunneling" through thin obstacles.
+
+3. **Physics Time Step**: Be aware of the physics time step - too small is inefficient, too large is unstable.
+
+4. **Avoid Stacking Many Objects**: Physics stacks are computationally expensive and can become unstable.
+
+5. **Use Physics Materials**: Apply different friction/restitution settings for different surfaces (ice, mud, etc.).
+
+## Conclusion
+
+The physics system brings your virtual world to life, making objects interact in believable ways. By understanding how to use physics effectively in SAGE, you can create games with satisfying tactile feedback, from bouncing balls to epic destruction.
+
+Physics is a deep topic, and this guide only scratches the surface. As you become more comfortable with the basics, explore the BabylonJS and Havok documentation for advanced techniques to push your physics simulation to the next level.
+
+Remember, with great physics comes great responsibility - a lightsaber swinging with realistic physics can be a joy to use, but only if the Wookiee in the next room isn't accidentally sliced in half by the player's enthusiastic flailing.