🏐 Bouncing Ball Object

The Bouncing Ball object is a physics-based entity designed to simulate highly accurate bouncing behavior, perfect for games such as Arkanoid, Pong or Breakout. Its behavior combines circular collisions, elastic rebound, and advanced angular control.

⚙️ Main Properties

Speed X: Initial speed on the X axis (in px/s). Can be positive (right) or negative (left).
Speed Y: Initial speed on the Y axis (in px/s). Can be positive (down) or negative (up).
Angular Bounce: Enables angular rebound based on the impact point.
Target Tag: Tag of the object used to calculate angular bounce (e.g. paddle).
Max Bounce Angle (°): Maximum allowed bounce angle. Controls how steep the angle can get near the edges (default 60°).

📌 Important: The Speed X and Speed Y properties define both the direction and the initial velocity of the ball. The system does not normalize the speed automatically, allowing you to control acceleration or slowing down using scripts.

🧭 Smart Angular Bounce

If Angular Bounce is enabled and the ball collides with an object whose Tag matches the value of Target Tag, the outgoing angle is dynamically calculated based on the point of impact. The closer the hit is to the center, the straighter the bounce; near the edges, the angle increases up to the value defined by Max Bounce Angle (°).

🎛️ Example Configuration

{
  type: "ball",
  name: "Bouncing Ball",
  w: 32,
  h: 32,
  collision: true,
  collisionType: "circle",
  restitution: 1.0,
  vx: 5,
  vy: -200,
  angularBounce: true,
  angularBounceObjectTag: "paddle",
  maxBounceAngle: 60
}

🧩 Visible Fields in the Editor

⚡ Speed X: initial horizontal speed.
⚡ Speed Y: initial vertical speed.
🎚️ Angular Bounce: enables or disables angular rebound.
🏷️ Target Tag: tag of the object used for angle calculation.
📐 Max Bounce Angle (°): maximum rebound angle.

🧠 Bounce Logic

If the collided object has the Tag specified in Target Tag, an outgoing angle proportional to the impact position is calculated.
If it doesn't match, a normal physical bounce is applied by reflecting velocity over the collision normal.
The current velocity magnitude is preserved; no attempt is made to enforce the original speed parameter.

💬 Script Control

You can modify the ball’s speed at any time using scripts:

function Update(obj, dt) {
  // Increase speed by 5%
  obj.vx *= 1.05;
  obj.vy *= 1.05;

  // Smoothly slow down
  // obj.vx *= 0.97;
  // obj.vy *= 0.97;

  // Reverse X direction
  // obj.vx = -obj.vx;
}

🧩 You can also read the current total speed using Math.hypot(obj.vx, obj.vy) and adjust velocity while keeping the same angle.

💡 Tips

Use Target Tag = "paddle" in Pong or Arkanoid-style games.
Combine the ball with an AudioSource component to play a sound on each hit.
You can create power-ups that modify vx and vy to increase speed or reverse direction.