Class GameRuntime

Class Documentation

class GameRuntime

Declaration: final

Coordinates platform input, game simulation, rendering, presentation, and teardown.

Each scheduled update receives accumulated State activity and the selected simulation delta, with observation time available separately. Both modes use the same variable/fixed timing and bounded recovery policy. Rendering consumes published render state, never the game’s live mutable simulation state. These boundaries apply in either mode. The calling thread owns platform polling and graphics operations; concurrent mode gives simulation initialization, update, frame preparation and simulation cleanup to one simulation worker. Sequential mode uses one recycled frame. Concurrent mode uses three slots and renders the newest complete frame available at each handoff.

Public Functions

GameRuntime(::CE::Runtime::Context &engine, ::CE::Game::AbstractGame &game, ::CE::Runtime::RunMode mode = ::CE::Runtime::RunMode::Sequential, Input::PollingOptions polling = Input::PollingOptions{}, ::CE::Runtime::Simulation::TimingOptions timing = ::CE::Runtime::Simulation::TimingOptions{})

Retain a context/game and validate execution, polling and timing policy.

See also

Detailed guide

Parameters:

  • engine – Borrowed compatible context, alive through runtime use and cleanup.

  • game – Borrowed game hooks, alive through runtime use and cleanup.

  • mode – Sequential caller-owned or concurrent simulation-worker execution.

  • polling – Input observation/backlog policy, independent of simulation delta.

  • timing – Variable/fixed and bounded recovery policy.

Throws:

CE::Exceptions::invalid_args – For invalid mode, polling or timing settings. Construction starts no session; run() reserves the context’s single session.

~GameRuntime()

Close internal observation state without invoking listeners.

The caller must first stop and join an active run; destruction performs no runtime teardown.

void run()

Execute one blocking session on the platform/graphics owner.

Initializes adapters/game, pumps input/dispatch/rendering, then quiesces, settles work and tears down in dependency order. Context/game must remain alive through return or throw. Reuse or another runtime session on the same context rejects. Hook/native failures trigger cleanup and preserve the first exception. Do not destroy the runtime while this or another operation uses it.

See also

Detailed guide

void stop()

Request normal shutdown from any producer thread while this runtime lives.

Does not join, interrupt a hook or synchronously release resources. run() observes the shared request and completes normal teardown. Bypasses ordinary shutdown negotiation and supersedes an unresolved request. Use shutdown().request() when the host policy must be able to defer/cancel; repeated unconditional stop is safe.

See also

Detailed guide

::CE::Runtime::RuntimeStats diagnostics() const

Declaration: [[nodiscard]]

Copy counters before a session or after run() returns/throws.

See also

Detailed guide

Throws:

CE::Exceptions::failed_operation – During an active session. Caller synchronizes with run start/return; the rejection check does not authorize racing a new run or live object destruction.

Returns:

Owned observations published after simulation join.

inline RuntimeLifecycle lifecycle() const noexcept

Declaration: [[nodiscard]]

Retain synchronized current/terminal observations without borrowing Runtime.

snapshot() is allowed during the live session, unlike diagnostics(); terminal state owns final counters and bounded failure summaries. Register on Context::events() before run for milestone occurrences; there is no bus replay.

See also

Lifecycle observation

ShutdownEndpoint shutdown() const

Declaration: [[nodiscard]]

Retain ordinary command/snapshot access without a raw Runtime pointer.

request() stages safe platform work, coalesces unresolved duplicates and returns a shared result ticket. Runtime closure rejects new requests. Never block the platform/simulation owner needed by the policy on a ticket’s completion.

ShutdownPolicy set_shutdown_policy(ShutdownPolicyCallback, ShutdownPolicyOptions = {}, CE::Events::EventBus::Delivery = {})

Declaration: [[nodiscard]]

Install one host authority before run.

Install the single host decision authority before run and retain its move-only handle.

Negotiate requires a consumable native close; Force explicitly keeps native close unconditional.

Immediate callbacks run on platform; optional queued delivery selects another owner and must not run inline. The callback can retain its private ShutdownDecision while a prompt/save completes. Policy/delivery failure or withdrawal cancels an unresolved ordinary request; forced stop/failure supersedes it. Default Negotiate requires consumable native close, while Force keeps native close unconditional.

See also

Shutdown protocol

inline ::CE::Runtime::SimulationDispatcher &simulation_dispatcher()

Declaration: [[nodiscard]]

Borrow the simulation request queue without opening it.

See also

Detailed guide

Returns:

Runtime-owned dispatcher; retain its submission() endpoint for independent producer lifetime. Callbacks run at actual update boundaries. Request acceptance requires the runtime’s active queue and is separate from execution.