A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file timer.ts
* @brief Frame-based timer system integrated with engine loop
*/
import { defineResource, Res } from './resource';
import { defineSystem } from './system';
import { Schedule } from './system';
import { Time } from './resource';
import { playModeOnly } from './env';
import { log } from '../util/logger';
import type { Plugin } from '../app/app';
// =============================================================================
// Timer Entry
// =============================================================================
interface TimerEntry {
id: number;
delay: number;
elapsed: number;
repeat: boolean;
interval: number;
callback: (timer: TimerHandle) => void;
paused: boolean;
repeatCount: number;
maxRepeatCount: number;
handle: TimerHandle | null;
}
// =============================================================================
// Timer Handle
// =============================================================================
export class TimerHandle {
private readonly manager_: TimerManager;
private readonly id_: number;
constructor(manager: TimerManager, id: number) {
this.manager_ = manager;
this.id_ = id;
}
get id(): number {
return this.id_;
}
get isActive(): boolean {
return this.manager_.has(this.id_);
}
get elapsed(): number {
return this.manager_.getElapsed(this.id_);
}
get repeatCount(): number {
return this.manager_.getRepeatCount(this.id_);
}
pause(): this {
this.manager_.pause(this.id_);
return this;
}
resume(): this {
this.manager_.resume(this.id_);
return this;
}
cancel(): void {
this.manager_.cancel(this.id_);
}
reset(): this {
this.manager_.reset(this.id_);
return this;
}
}
// =============================================================================
// Timer Manager
// =============================================================================
export class TimerManager {
private nextId_ = 0;
private readonly timers_ = new Map<number, TimerEntry>();
private timeScale_ = 1.0;
delay(seconds: number, callback: (timer: TimerHandle) => void): TimerHandle {
return this.addTimer_(seconds, false, 0, 1, callback);
}
interval(seconds: number, callback: (timer: TimerHandle) => void, maxRepeat = 0): TimerHandle {
return this.addTimer_(seconds, true, seconds, maxRepeat, callback);
}
private addTimer_(
delay: number,
repeat: boolean,
interval: number,
maxRepeatCount: number,
callback: (timer: TimerHandle) => void
): TimerHandle {
const id = ++this.nextId_;
this.timers_.set(id, {
id,
delay,
elapsed: 0,
repeat,
interval,
callback,
paused: false,
repeatCount: 0,
maxRepeatCount,
handle: null,
});
return new TimerHandle(this, id);
}
has(id: number): boolean {
return this.timers_.has(id);
}
getElapsed(id: number): number {
return this.timers_.get(id)?.elapsed ?? 0;
}
getRepeatCount(id: number): number {
return this.timers_.get(id)?.repeatCount ?? 0;
}
pause(id: number): void {
const t = this.timers_.get(id);
if (t) t.paused = true;
}
resume(id: number): void {
const t = this.timers_.get(id);
if (t) t.paused = false;
}
cancel(id: number): void {
this.timers_.delete(id);
}
reset(id: number): void {
const t = this.timers_.get(id);
if (t) {
t.elapsed = 0;
t.repeatCount = 0;
}
}
cancelAll(): void {
this.timers_.clear();
}
get activeCount(): number {
return this.timers_.size;
}
get timeScale(): number {
return this.timeScale_;
}
set timeScale(v: number) {
this.timeScale_ = Math.max(0, v);
}
tick(dt: number): void {
const scaledDt = dt * this.timeScale_;
const toRemove: number[] = [];
// Snapshot ids: Map iterators see mid-iteration insertions, so a timer
// created inside a callback would receive this tick's dt (and a
// self-rescheduling delay(0) would loop forever within one tick).
const ids = [...this.timers_.keys()];
for (const id of ids) {
const entry = this.timers_.get(id);
if (!entry || entry.paused) continue;
entry.elapsed += scaledDt;
if (entry.elapsed >= entry.delay) {
if (!entry.handle) entry.handle = new TimerHandle(this, id);
try {
entry.callback(entry.handle);
} catch (e) {
log.error('timer', `Timer callback error (id=${id})`, e);
}
entry.repeatCount++;
if (entry.repeat) {
if (entry.maxRepeatCount > 0 && entry.repeatCount >= entry.maxRepeatCount) {
toRemove.push(id);
} else {
entry.elapsed -= entry.delay;
entry.delay = entry.interval;
}
} else {
toRemove.push(id);
}
}
}
for (const id of toRemove) {
this.timers_.delete(id);
}
}
}
// =============================================================================
// Resource & System
// =============================================================================
export const TimerRes = defineResource<TimerManager>(new TimerManager(), 'Timer');
const timerSystem = defineSystem(
[Res(TimerRes), Res(Time)],
(timerManager, time) => {
timerManager.tick(time.delta);
},
{ name: 'TimerSystem' }
);
// =============================================================================
// Plugin
// =============================================================================
export const timerPlugin: Plugin = {
name: 'Timer',
profileDomain: 'timer',
build(app) {
app.insertResource(TimerRes, new TimerManager());
// Timers advance game time — frozen in editor edit mode.
app.addSystemToSchedule(Schedule.PreUpdate, timerSystem, { runIf: playModeOnly });
},
};