🕒 Timer System (Timer)

The engine includes a high-precision timer system based on real game time (dt), allowing you to execute functions automatically after a specified number of seconds, with the option to repeat indefinitely. It is ideal for scheduling events, animations, explosions, shots, spawns, or any time-based logic.

📘 1. Timer(seconds, functionName, loop, target)

Creates a new timer that will execute a function after a given number of seconds. It can repeat automatically if the loop parameter is enabled.

📋 Syntax

Timer(seconds, functionName, loop = false, target = null);

📥 Parameters

• seconds — Time before executing the function (can be decimal, e.g. 0.1).
• functionName — Name of the function to call via CallFunction().
• loop — If true, the timer repeats indefinitely.
• target — Object on which the function will be executed (same object passed to Start(obj) or Update(obj)).

📤 Returns

Does not return a value. The timer is handled automatically.

⚙️ Basic example

// Script: bomb.js
function Start(obj) {
  console.log("💣 Bomb activated...");
  Timer(3, "Explode", false, obj); // Calls Explode(obj) after 3 seconds
}

function Explode(obj) {
  console.log("💥 BOOM!", obj.name);
  destroyObject(obj);
}

🔁 Loop example

// Generate enemies every 2 seconds
function Start(obj) {
  Timer(2, "SpawnEnemy", true, obj);
}

function SpawnEnemy(obj) {
  console.log("👾 New enemy spawned by:", obj.name);
}

📙 3. clearTimer(functionName)

Cancels a specific timer or all active timers.

📋 Syntax

clearTimer(functionName = null);

📥 Parameters

• functionName — (optional) name of the function associated with the timer. If omitted, all timers are cleared.

⚙️ Examples

// Cancel a specific timer
clearTimer("SpawnEnemy");

// Cancel all active timers
clearTimer();

📒 4. pauseTimers(pause)

Pauses or resumes all active timers simultaneously.

📋 Syntax

pauseTimers(pause = true);

📥 Parameters

• pause — true to pause, false to resume.

⚙️ Example

// Pause the game and all timers
pauseTimers(true);

// Resume the game and timers
pauseTimers(false);

💡 Full example

// Script: turret.js
function Start(obj) {
  console.log("🔫 Turret activated");
  Timer(1, "Shoot", true, obj); // shoots every second
}

function Shoot(obj) {
  console.log("💥 Shot from", obj.name);
  spawnBullet(obj);
}

function spawnBullet(obj) {
  const bullet = instantiatePrefab("Bullet");
  bullet.x = obj.x + obj.w / 2;
  bullet.y = obj.y;
}

⚡ Technical details

• Based on delta time → fully accurate even with variable FPS.
• Runs inside the game loop (update(dt)).
• Allows multiple simultaneous timers without impacting performance.
• Uses CallFunction(obj, name) to invoke script functions, same as the main system.
• Timers auto-delete when they finish (no leaks).