Azen GameLoop

What you get

GameLoop does not replace Unity's PlayerLoop. Unity still calls Update, FixedUpdate and LateUpdate — but one driver receives them and routes each phase to your systems by clear rules: game state, channel, priority.

Features

Samples

Install

Two options: Package Manager from git, or a .unitypackage from the release page. Both need UniTask.

"scopedRegistries": [
  {
    "name": "package.openupm.com",
    "url": "https://package.openupm.com",
    "scopes": ["com.cysharp"]
  }
]

https://github.com/AndriiSviatenko/GameLoop.git?path=Packages/com.azen.gameloop#v1.0.0

Quick start

A round timer that counts down while the game plays and stops the round when time is up — in three files.

public sealed class RoundTimer : IGameElement, IGameInitListener, IGameTickable
{
    private readonly IGameManager _game;

    public RoundTimer(IGameManager game) => _game = game;

    public float RemainingSeconds { get; private set; }

    public UniTask OnInit(CancellationToken cancellationToken)
    {
        RemainingSeconds = 30f;
        return UniTask.CompletedTask;
    }

    public void Tick(float deltaTime)
    {
        if (RemainingSeconds <= 0f) return;

        RemainingSeconds -= deltaTime;
        if (RemainingSeconds <= 0f)
            _game.StopAsync().Forget();
    }
}

public sealed class GameBootstrap : MonoBehaviour
{
    private IGameLoop _loop;

    private void Awake()
    {
        _loop = gameObject.AddComponent<GameLoopDriver>()
            .Bootstrap(logger: DebugLogGameLoopLogger.Instance);

        _loop.Add(new RoundTimer(_loop), GameLoopChannels.Gameplay, GameLoopPriority.Normal);
    }

    private void Start() => _loop.StartAsync(destroyCancellationToken).Forget();
}

public sealed class SpinningCube : GameLoopElement, IGameTickable
{
    private void Awake() => Configure(GameLoopChannels.Gameplay);

    public void Tick(float deltaTime) => transform.Rotate(0f, 90f * deltaTime, 0f);
}

Concepts

Game state

StateChanged fires on every transition. Restart goes straight from the current state to Play; it does not raise Stop.

Element interfaces

Phase and priority

The interface picks when in the frame a system runs. Priority picks who goes first among systems of the same channel and phase. Higher numbers run first:

A High late tick never jumps ahead of a Normal tick — those are different parts of the frame.

Registration

var handle = loop.Add(enemyAi, GameLoopChannels.Gameplay, GameLoopPriority.High);
loop.Remove(handle);

var handle = loop.For(enemyAi).Gameplay().High().Add();
loop.Remove(handle);

Adding and removing tickables takes effect at the start of the next pass of that list, so a system can remove itself inside its own Tick.

Transitions and reentrancy

Transitions run one at a time. A call made while another transition is still awaiting its listeners is queued and runs after it; a cancelled queued call leaves the queue without blocking it.

Channels & pause

A channel is a group of systems you want to control together. Built-ins are Default, Gameplay, UI and Cutscene; any string works as a custom channel.

Pause a channel

await loop.PauseChannelAsync(GameLoopChannels.Gameplay, ct);   // gameplay stops, UI keeps ticking
await loop.ResumeChannelAsync(GameLoopChannels.Gameplay, ct);

• Pausing an already paused channel does nothing; ChannelStateChanged fires only on a real change.
• A paused channel stays paused through a global resume, and is not notified twice by a global pause.
• While the game is not playing, GetChannelState reports the global state.
• Stop and restart clear every channel pause.

Pause reasons

Global pause is a set of reasons. The game returns to Play only when the set is empty:

await loop.PauseFor(PauseReason.Menu, ct);
await loop.PauseFor(PauseReason.Dialog, ct);
await loop.ResumeFor(PauseReason.Dialog, ct);   // still paused: the menu is open
await loop.ResumeFor(PauseReason.Menu, ct);     // Play

var tutorial = PauseReason.Custom("Tutorial");

PauseAsync/ResumeAsync are shortcuts for the Manual reason. Inherit GameLoopFocusHandlerBase to pause with Focus when the window loses focus.

Time scale

loop.SetChannelTimeScale(GameLoopChannels.Gameplay, 0.25f);

Systems of that channel are still called every frame, with a four times smaller deltaTime. Scheduler timers of the channel slow down too. Time.timeScale, Animator and physics are not touched.

Keep UI alive while paused

loop.SetChannelTickWhenPaused(GameLoopChannels.UI, true);

That channel ticks (and runs its timers) while the game is paused, stopped or not started — so input in it can resume or restart the game.

Scheduler

Delayed and repeating calls in game time. Not a thread and not a coroutine: the scheduler is updated by the loop on the main thread, right after the frame's ticks.

public UniTask OnStartGame(CancellationToken cancellationToken)
{
    _spawn = _loop.Every(1.2f, SpawnBall, GameLoopChannels.Gameplay);
    return UniTask.CompletedTask;
}

public UniTask OnStopGame(CancellationToken cancellationToken)
{
    _loop.Cancel(_spawn);
    return UniTask.CompletedTask;
}

At time scale 0.25 a 1.2 s interval takes 4.8 real seconds — spawn rhythm slows together with movement.

Integration

One composition root, one GameLoopDriver, one loop. A container changes only how the reference is delivered.

Two contracts, one object

With DI, bind the same instance to both.

VContainer

protected override void Configure(IContainerBuilder builder)
{
    var loop = _driver.Bootstrap(logger: DebugLogGameLoopLogger.Instance);

    builder.RegisterInstance(loop).As<IGameLoop, IGameManager>();
    builder.RegisterEntryPoint<EnemyAi>();          // registers itself in IInitializable
    builder.RegisterEntryPoint<GameLoopStarter>();  // StartAsync in IStartable
}

Zenject

public override void InstallBindings()
{
    var loop = _driver.Bootstrap(logger: DebugLogGameLoopLogger.Instance);

    Container.Bind(typeof(IGameLoop), typeof(IGameManager)).FromInstance(loop);
    Container.BindInterfacesTo<EnemyAi>().AsSingle();
    Container.BindInterfacesTo<GameLoopStarter>().AsSingle();
    Container.BindExecutionOrder<GameLoopStarter>(100);
}

Systems register themselves in Initialize and remove themselves in Dispose; the starter runs after them, so every system sees OnInit and OnStartGame.

GameLoopElement and a container

GameLoopElement resolves GameLoop.Active by default. To use an injected loop, override ResolveLoop and call TryRegister() once the dependency arrives:

public void Construct(IGameLoop loop)
{
    _loop = loop;
    TryRegister();
}

protected override IGameLoop ResolveLoop() => _loop;

Debugging

GameLoop Debugger

Window → Azen → GameLoop Debugger shows state, sub-state, pause reasons, every channel with its state and time scale, and buttons for each transition in Play Mode.

Profiler markers

Errors

An exception in one system is logged and the rest of the frame continues. DebugLogGameLoopLogger prints the message and the exception with its stack trace. Pass throwOnErrors: true to the GameLoop constructor to rethrow instead — the original stack trace is kept.

Performance

• Ticking iterates plain lists of structs sorted by priority; no allocation per frame.
• IGameTickRate lowers the frequency of an expensive system — profile first, then throttle.
• TickBudgetMs stops a channel's Tick pass once the budget is spent. Low-priority systems can then starve every frame; treat it as a safety net, not a scheduler.
• Transitions allocate a small snapshot of listeners; they are rare, not per frame.

API reference

IGameManager

IGameLoop

Extensions

Unity types

Troubleshooting