Timer Manager

Engine::Core::TimerManager schedules one-shot callbacks against engine time. Use it for delayed gameplay work that does not need a per-frame tick() override.

API Documentation

TimerManager()

Creates a standalone timer manager.

Standalone managers use the last value passed to tick(nowSeconds) as their current time base. Use this form for tools or isolated systems that drive time manually.

Example:

Engine::Core::TimerManager timers;
 
timers.setTimer(1.0, []()
{
    // Runs when tick() reaches 1.0 seconds.
});
 
timers.tick(1.0);

TimerManager(engine)

Creates a timer manager that reads current time from Engine::EngineKern.

Engine users normally access this instance through Engine::EngineKern::getTimerManager().

Parameters:

• engine - Engine instance used to read global time.

TimerManager::TimerHandle

Opaque identifier returned when a timer is scheduled.

A default-constructed handle is invalid. cancelTimer() ignores invalid handles and handles for timers that already fired.

Example:

Engine::Core::TimerManager::TimerHandle handle;
 
if (!handle)
{
    // No active timer is stored in this handle.
}

TimerManager::setTimer(delaySeconds, callback) -> TimerHandle

Schedules an unowned one-shot callback.

Use this for callbacks whose captured data outlives the timer, or cancel the handle before the captured data is destroyed. Prefer setActorTimer() for actor-owned gameplay logic.

Parameters:

• delaySeconds - Delay in seconds. Negative values are clamped to zero.
• callback - Function called when the timer expires. Empty callbacks are allowed.

Returns: A TimerHandle that can cancel the timer before it fires.

Example:

Engine::Core::TimerManager* timers = engine->getTimerManager();
if (timers == nullptr)
{
    return;
}
 
Engine::Core::TimerManager::TimerHandle handle = timers->setTimer(
    2.0,
    []()
    {
        // Runs once after two seconds of engine time.
    }
);

TimerManager::setActorTimer(owner, delaySeconds, callback) -> TimerHandle

Schedules a one-shot callback tied to an actor.

The callback runs only while owner is still backed by a valid ECS entity. Passing nullptr returns an invalid handle and schedules no timer.

Parameters:

• owner - Actor that owns the timer.
• delaySeconds - Delay in seconds. Negative values are clamped to zero.
• callback - Function called with the owning actor when the timer expires.

Returns: A TimerHandle that can cancel the timer before it fires.

Example:

timers->setActorTimer(
    this,
    0.5,
    [](Engine::Entities::Actor& actor)
    {
        actor.destroyActor();
    }
);

TimerManager::cancelTimer(handle)

Cancels one scheduled timer.

Invalid handles, unknown handles, and handles for already-fired timers are ignored.

Parameters:

• handle - Handle returned by setTimer() or setActorTimer().

Example:

Engine::Core::TimerManager::TimerHandle handle = timers->setTimer(5.0, []() {});
timers->cancelTimer(handle);
handle = {};

TimerManager::cancelTimersFor(owner)

Cancels every actor-owned timer registered for owner.

Passing nullptr is ignored. Engine::Entities::Actor cancels its actor timers during end play.

Parameters:

• owner - Actor whose pending actor timers should be removed.

Example:

timers->cancelTimersFor(this);

TimerManager::clear()

Removes all pending timers without running callbacks.

Use this when shutting down a timer manager or resetting a manually-owned timer set.

Example:

timers.clear();

TimerManager::tick(nowSeconds)

Executes all timers due at or before nowSeconds.

Game code normally does not call this on the engine-owned manager. The engine ticks its manager after postTick() callbacks and before pending actor destruction is flushed.

Timers scheduled for the same fire time run in creation order. Timers scheduled by a callback for the current time can run during the same tick() call.

Parameters:

• nowSeconds - Absolute time in seconds for this timer tick.

Example:

Engine::Core::TimerManager timers;
 
timers.setTimer(0.25, []()
{
    // Runs when manual time reaches 10.25.
});
 
timers.tick(10.0);
timers.tick(10.25);

Usage

Delayed Actor Work

Call setActorTimer() from actor-owned gameplay logic. The callback receives the owning actor as a reference after the timer validates its ECS entity.

void MyActor::beginPlay()
{
    Actor::beginPlay();
 
    Engine::EngineKern* engine = getEngine();
    if (engine == nullptr || engine->getTimerManager() == nullptr)
    {
        return;
    }
 
    engine->getTimerManager()->setActorTimer(
        this,
        1.0,
        [](Engine::Entities::Actor& owner)
        {
            owner.destroyActor();
        }
    );
}

Repeating Work

Timers are one-shot. Schedule the next timer from the callback to repeat work.

void TimerSpawnerActor::scheduleNextSpawn()
{
    Engine::EngineKern* engine = getEngine();
    if (engine == nullptr || engine->getTimerManager() == nullptr)
    {
        return;
    }
 
    engine->getTimerManager()->setActorTimer(
        this,
        2.0,
        [](Engine::Entities::Actor& actor)
        {
            auto& spawner = static_cast<TimerSpawnerActor&>(actor);
            spawner.spawnActorFromTimer();
            spawner.scheduleNextSpawn();
        }
    );
}

Cancel Before Replacing

Store the handle when the timer controls a named state transition. Cancel the previous handle before scheduling a replacement.

void MyRound::startRound()
{
    Engine::Core::TimerManager* timers = engine->getTimerManager();
    if (timers == nullptr)
    {
        return;
    }
 
    timers->cancelTimer(roundTimer_);
    roundTimer_ = timers->setTimer(RoundDurationSeconds, [this]()
    {
        finishRound();
    });
}

Behavior Reference

Case	Behavior
Negative delay	Treated as 0.0 seconds.
Empty callback	Timer fires and performs no callback work.
Invalid TimerHandle	cancelTimer() ignores it.
nullptr actor owner	setActorTimer() returns an invalid handle.
Destroyed actor owner	Pending actor timer is skipped.
Same fire time	Timers run in creation order.
Callback schedules a due timer	The new timer can run in the same tick().
Callback cancels another timer	The canceled timer is removed if it has not fired.

Related Documentation

• Tick System
• Custom Actor And Component Handbook
• Engine::EngineKern::getTimerManager()
• Engine::Entities::Actor