Engine Systems

Cheryl provides the execution, input, resource and rendering boundaries around an application-owned game. Start here after First Game when you need to understand how those boundaries fit together. The detailed topic guides remain the authority for individual operations and failure cases.

Ownership and relationships

Use the Diagram explorer to inspect subsystem relationships, engine dependencies and application use. Select a type for its declaration and source evidence, or compare focused views before opening a detailed guide.

The application owns its game and composes a compatible runtime context. The context owns display, presentation, renderer and resource adapters; input can be owned or explicitly borrowed. GameRuntime borrows the context and game for one session. GUI sessions and audio systems have their own application-owned lifetimes; they are composed alongside the runtime rather than installed into a universal system manager.

        flowchart TB
    accTitle: Application and runtime ownership
    accDescr: The application owns its game, Context, runtime and optional services. The runtime borrows the game and Context; the Context owns adapters and tracks CPU work.
    app["Application"] -->|owns| game["Game and mutable state"]
    app -->|owns| context["Context"]
    app -->|owns| runtime["GameRuntime"]
    app -->|optionally owns| services["GUI session and audio system"]
    runtime -->|borrows| game
    runtime -->|borrows| context
    context -->|owns| adapters["Display, presentation, renderer and resources"]
    context -->|owns or borrows| input["Input"]
    context -->|tracks| groups["CPU worker groups"]
    

Context-created groups share a lazily created owned pool or an application-supplied shared pool. Input polls feed game updates; complete immutable frames feed rendering and presentation. Asset preparation precedes resource upload and retained drawing. Events use immediate listeners or explicitly selected queued delivery.

Owning an object, borrowing an interface, retaining an immutable result and submitting work carry different obligations. A retained draw packet keeps its logical resources alive; it cannot keep a destroyed graphics backend usable. A saved submission endpoint remains safe to call after closure but rejects new work. A borrowed window still requires its owner thread and live display.

Execution

Owner	Work
Platform/graphics caller of run()	Poll input, operate window/graphics, initialize/clean up the game, upload, render and present. See runtime ownership.
Simulation	Update game state and prepare complete frames on platform or one dedicated simulation thread. See frame publication.
Worker pool	Execute accepted CPU jobs independently of simulation, without graphics access. See worker execution.
Audio implementation	Advance playback on its output clock, with separately synchronized controls/maintenance. See audio execution.

Simulation reads copied tick input and dimensions. Rendering consumes a completed frame instead of mutable game objects. Use Dispatch when work must reach a particular owner and Workers for independent CPU capacity. The runtime lifecycle supplies the shutdown order joining those domains.

Find a system

Use this table as a topic lookup. The tutorials supply the learning sequence; each overview below introduces a system and routes to its detailed owner.

Each system’s Usage section provides an entry diagram and concrete relationships in its Uses and Used by tables. Arrows point from the consumer to what it uses; dashed arrows mark optional or alternative choices. The Diagram explorer adds an engine-only map, an application map and focused views for the busiest boundaries. Application maps show selected public methods beneath their owning types; Implement hooks identifies callbacks your game supplies for the engine to invoke.

System overview	Purpose and details
Runtime	Game hooks, context/session objects, execution and timing choices. Frame lifecycle, simulation timing.
Display	Windows, monitors, logical/pixel sizes and window modes. Display/window ownership.
Input	Actions, keyboard/mouse/gamepad controls, capture, records and focus enums. Control identities and tokens, input state model.
Assets	Loaders, caches, sprite/tile definitions and playback choices. Loading, manifests, values and playback.
Resources	Providers, retained graphics handles and sampling choices. Publication and retirement.
Rendering	Frames, cameras, draw packets, materials and fixed-state enums. Pipelines, materials and submission.
Text	Font selection, shaped/retained text, direction and rasterization choices. Unicode layout, encoding and indices.
GUI	Toolkit sessions, recordings, uploaders and reported capabilities. GUI construction, UI adapter contracts.
Audio	Clips, voices, playback options and state. Playback and ownership.
Events	Buses, channels, registrations and delivery choices. Event delivery.
Dispatch	Owner queues, saved endpoints, futures and cancellation. Thread dispatch.
Workers	Pools, groups, topology and CPU-policy enums. Worker execution.
Memory	Blocks, pooled objects, reservations and release contexts. CPU memory lifetime.
State	Sample tracking, synchronized publication, observation and machines. State utility contracts.
Logging	Named loggers, severity, profiles and queue choices. Logging configuration, failure reporting.
Diagnostics	Copied statistics, domain IDs and observation boundaries. Subsystem diagnostics.
Utilities	Time, bits, numeric parsing, file discovery and pointer helpers. Utility contracts, file discovery.

Systems and modules

These labels describe responsibilities. They do not prescribe CMake libraries, manager singletons or one object per system. Engine defines portable contracts; the module guides describe concrete implementations and their selection. The adapter contract catalogue lists required runtime interfaces, optional capabilities and cooperating integrations, with obligations and detailed references for each. Start there when replacing a backend; the SDL3 scaffold establishes a source boundary for that future platform implementation. Ownership and Cleanup explains retained, borrowed and scoped lifetimes across systems; Threads and Data Flow helps choose the execution and publication path for work crossing those systems. Native GLFW implements related display/input responsibilities; OpenGL implements related rendering/resource responsibilities. Optional toolkit and audio modules add capabilities without becoming reverse Engine dependencies.

The API Reference describes declarations. The subject guides explain detailed contracts; Tutorials and the Task index connect them to game code.