💠 Global Physics System (Gravity and Movement)

The engine includes a lightweight and efficient 2D global physics system designed to handle gravity, movement, collisions, and ground detection. This system runs automatically every frame, affecting all objects that require it.

⚙️ Basic Concepts

• The current system is based on simple integration (it does not use mass-based or energy-based physics).
• Each object can have its own velocity and gravity properties.
• Static objects are not affected by gravity or external forces.

📦 Movement Properties

• vx → Horizontal velocity (pixels/second).
• vy → Vertical velocity (pixels/second).
• gravity → Vertical acceleration applied every frame.
• onGround → Indicates whether the object is touching a solid surface.
• static → If true, the object does not move or respond to forces.

🌍 Gravity

Gravity is applied cumulatively on the Y axis. If an object has gravity = 800, its vertical velocity increases by 800 pixels/second every second (free fall).

// Example: manually applying gravity
if (obj.gravity) {
  obj.vy += obj.gravity * dt;
  obj.y  += obj.vy * dt;
}

🏃 Movement

Movement is calculated from velocity and delta time:

obj.x += obj.vx * dt;
obj.y += obj.vy * dt;

The collision system automatically corrects the object's position if a collision is detected, preventing overlaps or infinite falling.

🧱 Ground Detection

Each object maintains a boolean property onGround that indicates whether it is standing on a solid surface. This value updates automatically after collision resolution.

if (obj.onGround) {
  // The object is touching the ground
  obj.vy = 0;
}

🎯 Practical Examples

1️⃣ Basic Horizontal Movement

// Script: move_left_right.js
let speed = 200;

function Update(obj, dt) {
  if (keys["ArrowLeft"])      obj.vx = -speed;
  else if (keys["ArrowRight"]) obj.vx = speed;
  else obj.vx = 0;
}

2️⃣ Jump with Ground Detection

// Script: jump_player.js
let jumpForce = 400;

function Update(obj, dt) {
  if (obj.onGround && keys["Space"]) {
    obj.vy = -jumpForce;
    obj.onGround = false;
  }
}

3️⃣ Projectile-Type Movement

// Script: projectile.js
function Start(obj) {
  obj.vx = 600;  // horizontal velocity
  obj.vy = -200; // slight upward angle
  obj.gravity = 900;
}

🔄 Execution Order

1. Update object position and gravity.
2. Run collision detection.
3. Correct positions and update flags (onGround).
4. Trigger collision and trigger events.

💡 Recommendations

• Use static = true for floors, walls, and fixed platforms.
• For moving platforms, update their position manually via script, not gravity.
• Avoid applying forces if onGround = true and vy = 0.
• Control jumps and impulses by modifying vy directly.

📌 Summary

⚠️ Current Limitations

• No physical rotation (objects do not spin due to impact).
• No continuous force or friction simulation.
• No mass or momentum; all objects behave uniformly.
• The system is optimized for arcade/platforming games, not realistic physics.