EffectObject

Base class for interactive track objects that affect vehicle physics through collisions, providing lifecycle hooks for entry, exit, and sustained contact events.

---

🎯 Core Purpose

The EffectObject class serves as the foundation for creating various interactive track elements that:

• Modify vehicle physics during collisions
• Provide visual feedback through sprites
• Manage collision state transitions
• Support custom behavior through event hooks

---

🏗️ Constructor

constructor(position: Vec2D, sprite: EffectSprites)

Parameters

Name	Type	Description
position	Vec2D	World coordinates (x,y) for object placement
sprite	EffectSprites	Key identifying the visual asset

Initialization Behavior

1. Attempts to load sprite from DisplayDriver
2. Throws error if sprite not found
3. Sets up collision bounds based on sprite dimensions
4. Positions collision box at sprite center

Error Cases:

• Error("Sprite not found") when sprite asset is missing

---

📊 Properties

Collision System

Property	Type	Description
collision	CollisionObject	Bounding box with position and dimensions
previouslyCollidingCars	PhysicsBasedController[]	Vehicles that were colliding last frame

Visual Representation

Property	Type	Description
position	Vec2D	World-space coordinates
sprite	Sprite	Loaded graphical asset
randomSprite	number	Reserved for future variant support (currently fixed at 0)

---

⚙️ Core Methods

_update(currentlyCollidingCars: PhysicsBasedController[])

Main update loop that manages collision states:

graph TD
    A[Identify New Collisions] --> B[Trigger onEnter]
    C[Identify Ongoing Collisions] --> D[Trigger onColliding]
    E[Identify Ended Collisions] --> F[Trigger onExit]
    G[Update Tracking List] --> H[Store Current Colliders]

Parameters:

• currentlyCollidingCars: Array of vehicles currently intersecting with this object

---

🎮 Event Hooks

Lifecycle Methods

Method	Trigger Condition	Typical Use Cases
onEnter()	First frame of collision	Apply instant effects, play sounds
onColliding()	Each frame while colliding	Continuous effects, damage over time
onExit()	First frame after collision ends	Reset vehicle state, cleanup

Internal Handler

_onEnter(car: PhysicsBasedController): void

Reserved for GameScene integration to handle object removal (particularly for single-use perks)

---

🧩 Implementation Guide

Creating Custom Effects

class MudPatch extends EffectObject {
  onEnter(car: PhysicsBasedController) {
    car.applyFrictionMultiplier(2.0);
    spawnParticles('mud_splash');
  }

  onExit(car: PhysicsBasedController) {
    car.resetFriction();
  }
}

class JumpPad extends EffectObject {
  onEnter(car: PhysicsBasedController) {
    car.applyImpulse({x: 0, y: -15});
    playSound('boing');
  }
}

Best Practices

1. State Management:

   • Always clean up modifications in onExit
   • Make effects idempotent (safe against multiple triggers)

2. Performance:

   • Keep collision checks efficient
   • Use object pooling for frequently created/destroyed effects

3. Feedback:

   • Pair with visual/audio feedback
   • Consider screen shake for major impacts

---

� Integration Example

// Level setup
const trackEffects = [
  new OilSlick(new Vec2D(120, 85), EffectSprites.OIL),
  new SpeedBoost(new Vec2D(200, 300), EffectSprites.BOOST)
];

// Game loop
function updateEffects() {
  const colliders = physicsWorld.getCollisions();
  trackEffects.forEach(effect => {
    const relevantCars = colliders.filter(c =>
      checkCollision(c, effect.collision));
    effect._update(relevantCars);
  });
}

💡 Design Tip: Expose effect parameters (strength, duration) as public properties for easy tuning in level editors.

---

🚗 Collision Details

Bounding Box Calculation

Automatically configured based on sprite dimensions:

this.collision = {
  x: position.x + spriteWidth/2, // Center X
  y: position.y + spriteHeight/2, // Center Y
  width: spriteWidth,
  height: spriteHeight,
  angle: 0 // Axis-aligned
};

State Transition Logic

Uses triple buffering to track:

1. New collisions (enter)
2. Continuing collisions (sustain)
3. Ended collisions (exit)