Class

WorldTimer

A small accumulator-style timer for tracking elapsed real-world time across frames. Game code typically needs one of two patterns:

Lifetime / cooldown — start at some duration, count down each frame, take action when the timer reaches zero (a bullet despawns, an ability becomes available again).
Recurring interval — count down to zero, fire an action, then WorldTimer.reset to the original duration and repeat (a weapon that fires every 250ms, a spawner that drops an enemy every second).

WorldTimer covers both by being a thin, mutable wrapper around a single number, driven by the delta value threaded through each WorldUpdate. The unit is real-world milliseconds; pass update.deltaMilliseconds to WorldTimer.increment or WorldTimer.decrement from inside a component's update hook and the timer advances at wall-clock speed regardless of the engine's frame rate.

The mutators (WorldTimer.increment, WorldTimer.decrement, WorldTimer.set, WorldTimer.reset) all return this so that common patterns read in a single statement.

Example

// Lifetime: destroy this object once 1000ms have elapsed.
private readonly _lifetime = new WorldTimer(1000);

onUpdate(update: WorldUpdate) {
  if (this._lifetime.decrement(update.deltaMilliseconds).isLapsed) {
    this.host.destroy();
  }
}

// Recurring interval: fire a bullet every 250ms.
private readonly _fireCooldown = new WorldTimer(250);

onUpdate(update: WorldUpdate) {
  if (this._fireCooldown.decrement(update.deltaMilliseconds).isLapsed) {
    this._spawnBullet();
    this._fireCooldown.reset();
  }
}

Constructors

constructor(milliseconds: number): WorldTimer

Creates a new timer holding the given starting value. The value passed here is also remembered as the "initial" value used by WorldTimer.reset, which makes the recurring-interval pattern a one-liner.

Parameters

milliseconds number

Accessors

readonly #

initial: number

The value this timer was originally constructed with, and the value WorldTimer.reset returns to. Exposed for the rare case where a caller wants to reason about the timer's nominal duration after mutating the current value.

readonly #

isLapsed: boolean

true once the timer has counted down to zero or below. Designed for decrement-style use: drive the timer with decrement(update.deltaMilliseconds) and branch on isLapsed to fire whatever effect the timer is gating.

For increment-style use (counting up to a threshold) compare WorldTimer.value directly against the threshold instead.

readonly #

value: number

The current value of the timer, in milliseconds. May be negative after a WorldTimer.decrement call that overshoots zero — the engine does not clamp, so the overshoot is available for callers that want to preserve it (e.g. by carrying it into the next interval via WorldTimer.increment).

Methods

decrement(delta: number): this

Advances the timer backward by delta milliseconds. Typically called with update.deltaMilliseconds from inside a component's update hook.

Parameters

delta number

Returns

this

This timer, so calls can chain (e.g. timer.decrement(update.deltaMilliseconds).isLapsed).

increment(delta: number): this

Advances the timer forward by delta milliseconds. Typically called with update.deltaMilliseconds from inside a component's update hook.

Parameters

delta number

Returns

this

This timer, so calls can chain (e.g. timer.increment(update.deltaMilliseconds).isLapsed).

reset(): this

Restores the current value to whatever this timer was constructed with. Pairs naturally with the recurring-interval pattern — when the timer lapses, fire the effect and reset() to start the next interval.

Returns

this

This timer, for chaining.

set(milliseconds: number): this

Overwrites the current value. Does not change the value used by WorldTimer.reset — the original "initial" remains whatever was passed to the constructor.

Parameters

milliseconds number

Returns

this

This timer, for chaining.