🌀 Rotation System

The engine uses a degree-based rotation system that applies to all game objects: sprites, entities, colliders, particles, and UI elements. Each object has a rotation property defining its current orientation in the world.

📐 Basic Concepts

• Unit: All angles are expressed in degrees (0–360°).
• Rotation center: Rotation occurs around the object’s center (x + w/2, y + h/2).
• Internal conversion: During rendering, degrees are automatically converted to radians (radians = degrees * π / 180).
• Hierarchy: If the object has a parent, it inherits the parent’s rotation automatically.

⚙️ Rotation Properties

• rotation → Global rotation angle (degrees).

🧩 API Functions

1️⃣ setRotation(obj, angle)

Sets the absolute rotation of an object (in degrees).

const ship = getObjectByName("Ship");
setRotation(ship, 90); // rotate the ship 90 degrees

2️⃣ getRotation(obj)

Returns the object’s current rotation (in degrees).

const angle = getRotation("Ship");
console.log("Current angle:", angle);

3️⃣ rotateObject(obj, delta)

Adds an incremental rotation (in degrees).

// Rotate the object 5° per frame
function Update(o, dt) {
  rotateObject(o, 5 * dt * 60);
}

🧭 Rotations with Hierarchy

When an object has a parent, its total rotation is:

globalRotation = parentRotation + rotation;

This means child objects rotate automatically with their parent.

Example

// The weapon rotates along with the player
const player = getObjectByName("Player");
const weapon = getObjectByName("Weapon");

setParent(weapon, player);
setRotation(weapon, 45); // initial angle of the weapon

// Rotate the player 30°
rotateObject(player, 30);

// The weapon now points at 75° globally
console.log("Weapon global rotation:", getRotation(weapon));

💡 Practical Examples

🧱 1. Constant Rotation

// Script: rotate.js
let speed = 60; // degrees per second

function Update(obj, dt) {
  rotateObject(obj, speed * dt);
}

🚀 2. Rotation Controlled by Keyboard

// Script: rotate_keys.js
let speed = 90; // degrees per second

function Update(obj, dt) {
  if (keys["ArrowLeft"])  rotateObject(obj, -speed * dt);
  if (keys["ArrowRight"]) rotateObject(obj,  speed * dt);
}

🪄 3. Synchronized Rotation Between Objects

const sun = getObjectByName("Sun");
const planet = getObjectByName("Planet");
setParent(planet, sun);

// the planet rotates with the sun
rotateObject(sun, 10 * dt);

📌 Summary

⚠️ Current Limitations with Collisions

Even though objects can visually rotate freely, the engine uses a collision system based on AABB (Axis-Aligned Bounding Boxes), meaning collision boxes always remain aligned with the X and Y axes regardless of the object’s visual angle.

🎯 Illustrative Example

// Sprite visually rotated 45°, but its collision stays AABB
const box = getObjectByName("Crate");
setRotation(box, 45);

// Visually:
// 🔄 The sprite appears tilted 45°

// Physically:
// 🧱 The collision remains an axis-aligned rectangle

Future versions may incorporate OBB (Oriented Bounding Box) collision detection for precise rotated collisions.