Physics Based Controller

Core vehicle physics controller handling movement, forces, collisions, and visual representation for game entities with realistic driving dynamics.

---

🚗 Core Features

Movement System

Feature	Description	Key Properties
Acceleration	Forward/backward force application	acceleration, maxSpeedForward/Backward
Steering	Directional control based on speed	steeringForce, isTurning
Braking	Controlled deceleration	brakingForce
Nitro Boost	Temporary speed enhancement	TimedEffectDriver

Collision System

Feature	Description	Key Properties
Bounding Box	Collision detection volume	collision
Collision Flags	Special behavior control	noCollision

Visual System

Feature	Description	Key Properties
Sprite Management	Angle-based sprite selection	currentSpriteIndex, sprite
Wheel Traces	Visual trail effects	tracePoints
Debug Rendering	Collision visualization	displayData

---

🏗️ Constructor

constructor(sprite: Sprite, traction: number)

Parameters:

Name	Type	Description
sprite	Sprite	Visual representation asset
traction	number	Surface grip coefficient (0-1)

Initial State:

• Position: (0, 0)
• Angle: 0°
• Velocity: (0, 0)
• All forces reset to zero

---

🎮 Control Methods

Movement Controls

Method	Description	Physics Impact
accelerateForward()	Applies forward thrust	Increases velocity
brake()	Slows vehicle	Applies brakingForce
applyForce(magnitude)	General force application	Direct velocity change

Steering Controls

Method	Description	Physics Impact
addSteeringForce(value)	Adds turning torque	Modifies steeringForce
turning(deltaTime)	Processes steering	Updates angle
rotate(angle)	Immediate rotation	Sets angle directly

Special Abilities

enterNitroMode(onRefuel?: () => void)

Nitro Effects:

1. 2x acceleration boost
2. 1.5x max speed
3. Duration: 3 seconds
4. Cooldown: 5 seconds

---

📊 Property Details

Physics State

Property	Type	Range	Description
position	Vec2D	World coords	Current location
velocity	Vec2D	Any	Movement vector
angle	number	0-360°	Facing direction

Force Controls

Property	Type	Description
acceleration	Vec2D	Current force being applied
brakingForce	number	Deceleration magnitude
steeringForce	number	Turning torque

Limits

Property	Type	Default	Description
maxSpeedForward	number	5.0	Forward speed cap
maxSpeedBackward	number	2.0	Reverse speed cap
traction	number	0.9	Surface grip factor

---

🔍 Getters & Utility Methods

Spatial Queries

Method	Returns	Description
centerPosition	Vec2D	Center point of vehicle
getWheelsPosition	[Vec2D, Vec2D]	Left/right wheel positions
collision	CollisionObject	Bounding box data

State Management

Method	Description
resetToDefaultSpeed()	Restores speed limits
resetToDefaultAdhesion()	Resets traction
updateCurrentSprite()	Updates visual representation

---

🖥️ Rendering System

Display Pipeline

graph TD
    A[Position Update] --> B[Angle Calculation]
    B --> C[Sprite Selection]
    C --> D[Trace Generation]
    D --> E[DisplayData Preparation]

Trace Effects:

• Persist for 1.5 seconds
• Fade linearly over time
• Width scales with speed

---

⚙️ Physics Formulas

Steering Calculation

const turnRate = (1 - (currentSpeed / maxSpeed)) * steeringForce;
this.angle += turnRate * deltaTime;

Nitro Boost

// During activation:
maxSpeed *= 1.5;
acceleration *= 2.0;

// After duration:
maxSpeed = defaultMaxSpeed;

---

🏎️ Usage Example

// Create controller
const car = new PhysicsBasedController(raceCarSprite, 0.85);

// Game loop
function update(deltaTime) {
  // Player input
  if (input.accelerate) car.accelerateForward();
  if (input.brake) car.brake();
  car.addSteeringForce(input.steer);

  // Special ability
  if (input.nitro) car.enterNitroMode(refuelCallback);

  // Update physics
  car.update(deltaTime);

  // Render
  render(car.displayData);
}

---

⚠️ Edge Cases

1. Zero DeltaTime:

   • Skipped in update() to prevent NaN values

2. Extreme Angles:

   • Normalized to 0-360° range

3. Negative Speed:

   • Handled in braking calculations

---

🛠️ Design Considerations

Decoupled Systems

• Physics separate from rendering
• Force-based rather than direct position updates
• Time-based effects system

Tunable Parameters

Parameter	Adjustment Effect
traction	Slide vs grip behavior
steeringForce	Responsiveness
brakingForce	Stopping distance

---

📈 Performance Notes

1. Trace Management:

   • Automatic pruning of old points
   • Linear fade calculation

2. Sprite System:

   • Angle-to-index mapping is O(1)
   • No runtime sprite modifications

3. Collision Optimization:

   • Lazy bounding box calculation
   • Flag-based early outs