Gondwana.Engine Class Reference

Represents the core game engine singleton responsible for managing the main update loop, input systems, rendering, timing, and subsystem coordination. More...

Inheritance diagram for Gondwana.Engine:

Public Member Functions
void	Initialize (string? configFileName=null, bool? autoSaveConfig=null, IKeyboardAdapter? keyboardAdapter=null, IMouseAdapter? mouseAdapter=null, IGamepadManager< IGamepadAdapter >? gamepadManager=null)
	Performs one-time or on-demand initialization of the Engine instance, loading configuration, state files, and input adapters required for execution.
void	Start ()
	Starts the Engine using the current thread's SynchronizationContext.
void	Start (SynchronizationContext uiContext)
	Starts the Engine main loop using the provided SynchronizationContext, initializing the engine if it has not yet been started.
void	Stop ()
	Stops the Engine main loop and halts all ongoing processing.
void	Dispose ()
	Releases all resources used by the Engine and stops all subsystems.

Properties
static Engine	Instance [get]
	Gets the singleton instance of the Engine.
static ILogger< Engine >	Logger [get]
	Gets the logger instance used by the engine for diagnostic and informational messages.
static ? KeyboardEventPoller	KeyboardEventPoller [get]
	Gets the keyboard event polling subsystem, if initialized.
static ? MouseEventPoller	MouseEventPoller [get]
	Gets the mouse event polling subsystem, if initialized.
static ? IGamepadManager< IGamepadAdapter >	GamepadManager [get, set]
	Gets or sets the gamepad manager responsible for handling gamepad input.
static ? GamepadEventPoller	GamepadEventPoller [get]
	Gets the gamepad event polling subsystem, if initialized.
IUiDispatcher?	UiDispatcher [get]
	Gets the UI dispatcher used for marshalling operations to the UI thread.
IEngineDispatcher	EngineDispatcher = new EngineDispatcher() [get]
	Gets the engine dispatcher used for marshalling operations to the engine's background thread.
bool	IsInitialized [get]
	Gets a value indicating whether the engine has completed its initialization sequence.
bool	IsInitializing [get]
	Gets a value indicating whether the engine is currently in the process of initializing.
bool	IsRunning [get]
	Gets a value indicating whether the engine's main loop is currently executing.
long	TotalTicksEngineRunning [get]
	Gets the total number of high-resolution timer ticks that have elapsed since the engine started.
double	TotalSecondsEngineRunning [get]
	Gets the total number of seconds that have elapsed since the engine started.
double	CyclesPerSecond [get]
	Gets the current gross cycles per second rate.
double	FramesPerSecond [get]
	Gets the current net frames per second rate.
bool	IsDisposed = false [get]
	Gets a value indicating whether the engine has been disposed.
EngineState	State = new EngineState() [get]
	Gets the engine's persistent state container for storing arbitrary key-value data.
EngineConfiguration	Configuration [get]
	Gets the current engine configuration settings.
bool	IsDisposing [get]
	Gets a value indicating whether the engine is currently executing its disposal sequence.

Events
Action?	PreInitialization
	Occurs immediately before the engine begins its internal initialization sequence.
Action?	PostInitialization
	Occurs after all internal initialization routines have completed, but before InitializationComplete is raised.
Action?	InitializationComplete
	Occurs after all initialization steps and post-initialization logic have completed.
Action?	BeforeBackgroundTasksExecute
	Occurs immediately before DoBackgroundTasks(long) executes within each engine cycle.
Action?	AfterBackgroundTasksExecute
	Occurs immediately after DoBackgroundTasks(long) has completed.
Action?	BeforeEngineCycle
	Occurs immediately before DoForegroundTasks(long) executes within each engine cycle.
Action?	AfterEngineCycle
	Occurs immediately after DoForegroundTasks(long) completes within each engine cycle.
Action< CyclesPerSecondCalculatedEventArgs >?	CPSCalculated
	Occurs whenever cycles-per-second (CPS) and frames-per-second (FPS) metrics are calculated.
Action?	Disposing
	Raised when Dispose() begins the explicit disposal sequence.
Action?	Disposed
	Raised after the engine has completed explicit disposal.

Detailed Description

Represents the core game engine singleton responsible for managing the main update loop, input systems, rendering, timing, and subsystem coordination.

The Engine class is implemented as a thread-safe singleton and provides centralized access to all major engine subsystems including input polling, scene management, rendering, and collision detection.

Typical usage involves calling Initialize to configure the engine, then Start(SynchronizationContext) to begin the main loop, and finally Stop followed by Dispose for cleanup.

Member Function Documentation

Dispose()

void Gondwana.Engine.Dispose

(

)

Releases all resources used by the Engine and stops all subsystems.

This method performs an orderly shutdown of the engine, including:

• Stopping the main engine loop
• Waiting for the background thread to exit
• Raising the Disposing event
• Cleaning up input subsystems
• Flushing asynchronous logs if configured
• Clearing timers and state
• Raising the Disposed event

After disposal, the engine instance should not be used. To restart the engine, a new application session is required.

Initialize()

void Gondwana.Engine.Initialize	(	string?	configFileName = null,
		bool?	autoSaveConfig = null,
		IKeyboardAdapter?	keyboardAdapter = null,
		IMouseAdapter?	mouseAdapter = null,
		IGamepadManager< IGamepadAdapter >?	gamepadManager = null )

Performs one-time or on-demand initialization of the Engine instance, loading configuration, state files, and input adapters required for execution.

This method is responsible for preparing all core systems of the engine prior to starting the main loop. It performs the following operations in order:

1. Raises the PreInitialization event (on the UI thread if available).
2. Loads engine configuration settings from file using EngineConfigurationFile.Load.
3. Loads any EngineState files declared in configuration.
4. Initializes input subsystems for keyboard, mouse, and gamepad polling, if corresponding adapters are provided.
5. Raises PostInitialization after all internal setup is complete.
6. Marks the engine as initialized and raises InitializationComplete.

This method is automatically invoked by Start(SynchronizationContext) if the engine has not yet been initialized. It is safe to call multiple times, but subsequent calls will return immediately once initialization has been completed or is in progress.

Thread-safe guarantees:

• Concurrent calls are prevented by internal _isInitializing and _isInitialized flags.
• Events that must run on the UI thread are dispatched through UiDispatcher if available.

Parameters

configFileName	Optional path to a configuration file to load. If null, the default configuration is used.
autoSaveConfig	Optional flag indicating whether configuration changes should be automatically saved back to disk.
keyboardAdapter	Optional IKeyboardAdapter instance used to initialize the keyboard input subsystem.
mouseAdapter	Optional IMouseAdapter instance used to initialize the mouse input subsystem.
gamepadManager	Optional IGamepadManager<T> instance used to initialize the gamepad subsystem.

See also

Start(SynchronizationContext), Stop, EngineConfiguration, EngineState

Start() [1/2]

void Gondwana.Engine.Start

(

)

Starts the Engine using the current thread's SynchronizationContext.

This overload is intended for convenience when starting the engine from the UI thread. It retrieves the current SynchronizationContext and forwards it to Start(SynchronizationContext).

The engine must be started from a thread that has a valid SynchronizationContext, typically the primary UI thread. If no synchronization context is available, an InvalidOperationException is thrown.

Exceptions

InvalidOperationException

Thrown if SynchronizationContext.Current is null.

See also

Start(SynchronizationContext), Initialize, Stop

Start() [2/2]

void Gondwana.Engine.Start

(

SynchronizationContext

uiContext

)

Starts the Engine main loop using the provided SynchronizationContext, initializing the engine if it has not yet been started.

This method is the entry point for runtime execution. It ensures the engine is fully initialized before beginning the continuous background processing loop. The loop runs on a separate worker thread and repeatedly invokes Cycle, yielding between iterations to allow cooperative multitasking.

The uiContext argument establishes the UiDispatcher used for posting events and callbacks to the UI thread. All UI-bound events such as PreInitialization, PostInitialization, InitializationComplete, and CPSCalculated will be marshalled through this dispatcher when available.

If the engine is already running, this method returns immediately without taking further action.

Threading behavior:

• The engine's main loop runs on a background task, not the UI thread.
• All rendering and timing operations are controlled through Cycle.
• The UiDispatcher guarantees that event notifications targeting the UI are executed safely on the originating thread.

Parameters

uiContext

The SynchronizationContext that defines the UI thread context to which UI-related operations and events will be dispatched.

Exceptions

InvalidOperationException

Thrown if uiContext is null.

See also

Initialize, Stop, Cycle, UiDispatcher

Stop()

void Gondwana.Engine.Stop

(

)

Stops the Engine main loop and halts all ongoing processing.

This method cleanly terminates the engine's background execution cycle started by Start(SynchronizationContext). It sets IsRunning to false, signaling the loop in Cycle to exit on the next iteration.

Stop() does not immediately dispose of resources or clear state. It simply halts ongoing updates and rendering, allowing the engine's subsystems (timers, surfaces, input pollers, etc.) to remain intact for later reuse or inspection.

To fully clean up and release all managed resources, call Dispose after stopping the engine.

This method is thread-safe and may be called from any thread.

See also

Start(), Cycle, Dispose(), IsRunning

Property Documentation

Configuration

EngineConfiguration Gondwana.Engine.Configuration

get

Gets the current engine configuration settings.

An EngineConfiguration instance containing all engine settings.

This property provides thread-safe access to the engine's configuration, which is loaded during Initialize from a configuration file or default values.

Configuration settings control behavior such as target frame rate, logging mode, sampling intervals, and other core engine parameters.

CyclesPerSecond

double Gondwana.Engine.CyclesPerSecond

get

Gets the current gross cycles per second rate.

The number of complete engine cycles executed per second, including throttled cycles.

This metric reflects all calls to Cycle, regardless of whether a foreground render was performed. It represents the engine's update frequency for background tasks such as input polling, timers, and animations.

This value is updated at the interval specified by EngineConfiguration.SamplingTimeForCPS.

EngineDispatcher

IEngineDispatcher Gondwana.Engine.EngineDispatcher = new EngineDispatcher()

get

Gets the engine dispatcher used for marshalling operations to the engine's background thread.

An IEngineDispatcher instance bound to the engine's update loop thread.

This dispatcher allows external code to safely post work items that should execute on the engine's dedicated background thread, ensuring thread-safe access to engine state.

FramesPerSecond

double Gondwana.Engine.FramesPerSecond

get

Gets the current net frames per second rate.

The number of complete render frames presented per second.

This metric reflects only cycles that resulted in a foreground render operation, as controlled by EngineConfiguration.TargetFPS. It represents the actual visual frame rate delivered to the user.

This value is updated at the interval specified by EngineConfiguration.SamplingTimeForCPS.

GamepadEventPoller

? GamepadEventPoller Gondwana.Engine.GamepadEventPoller

staticget

Gets the gamepad event polling subsystem, if initialized.

The Gondwana.Input.Gamepad.GamepadEventPoller instance if initialized; otherwise, null.

This property provides access to the gamepad input subsystem. The poller is automatically initialized when a GamepadManager is assigned.

GamepadManager

? IGamepadManager<IGamepadAdapter> Gondwana.Engine.GamepadManager

staticgetset

Gets or sets the gamepad manager responsible for handling gamepad input.

Setting this property attaches an update callback to the engine cycle, polling attached adapters

Instance

Engine Gondwana.Engine.Instance

staticget

Gets the singleton instance of the Engine.

The globally shared Engine instance.

This property provides thread-safe access to the engine instance using lazy initialization. The instance is created on first access and persists for the application lifetime.

IsDisposed

bool Gondwana.Engine.IsDisposed = false

get

Gets a value indicating whether the engine has been disposed.

true if Dispose has completed; otherwise, false.

Once this property is true, the engine instance should not be used further. All managed resources have been released and subsystems have been shut down.

IsDisposing

bool Gondwana.Engine.IsDisposing

get

Gets a value indicating whether the engine is currently executing its disposal sequence.

true if disposal is in progress; otherwise, false.

This property is set to true at the start of Dispose and can be used by subsystems to detect when cleanup is underway.

IsInitialized

bool Gondwana.Engine.IsInitialized

get

Gets a value indicating whether the engine has completed its initialization sequence.

true if initialization is complete; otherwise, false.

This property returns true after Initialize has successfully completed all setup operations and raised the InitializationComplete event.

IsInitializing

bool Gondwana.Engine.IsInitializing

get

Gets a value indicating whether the engine is currently in the process of initializing.

true if initialization is in progress; otherwise, false.

This property is true between the start of Initialize and the completion of all initialization steps. It is used to prevent concurrent initialization attempts.

IsRunning

bool Gondwana.Engine.IsRunning

get

Gets a value indicating whether the engine's main loop is currently executing.

true if the engine loop is active; otherwise, false.

This property is set to true when Start(SynchronizationContext) is called and remains true until Stop is invoked or the engine is disposed.

KeyboardEventPoller

? KeyboardEventPoller Gondwana.Engine.KeyboardEventPoller

staticget

Gets the keyboard event polling subsystem, if initialized.

The Gondwana.Input.Keyboard.KeyboardEventPoller instance if initialized; otherwise, null.

This property provides access to the keyboard input subsystem. The poller must be initialized via Initialize with a valid IKeyboardAdapter before use.

Logger

ILogger<Engine> Gondwana.Engine.Logger

staticget

Gets the logger instance used by the engine for diagnostic and informational messages.

An ILogger<TCategoryName> instance configured for the Engine type.

This logger is used internally by the engine to report initialization status, errors, warnings, and other runtime information.

MouseEventPoller

? MouseEventPoller Gondwana.Engine.MouseEventPoller

staticget

Gets the mouse event polling subsystem, if initialized.

The Gondwana.Input.Mouse.MouseEventPoller instance if initialized; otherwise, null.

This property provides access to the mouse input subsystem. The poller must be initialized via Initialize with a valid IMouseAdapter before use.

State

EngineState Gondwana.Engine.State = new EngineState()

get

Gets the engine's persistent state container for storing arbitrary key-value data.

An EngineState instance that persists across engine sessions.

The State container provides a convenient mechanism for storing game-specific configuration, player progress, or other persistent data that should survive between application runs.

State can be loaded from and saved to disk using the methods provided by the EngineState class.

TotalSecondsEngineRunning

double Gondwana.Engine.TotalSecondsEngineRunning

get

Gets the total number of seconds that have elapsed since the engine started.

The elapsed time in seconds as a floating-point value.

This value is derived from TotalTicksEngineRunning and provides a convenient measure of total runtime duration.

TotalTicksEngineRunning

long Gondwana.Engine.TotalTicksEngineRunning

get

Gets the total number of high-resolution timer ticks that have elapsed since the engine started.

The elapsed ticks as measured by HighResTimer.

This value represents elapsed time in the native resolution of the high-resolution timer. Use TotalSecondsEngineRunning for a time value in seconds.

UiDispatcher

IUiDispatcher? Gondwana.Engine.UiDispatcher

get

Gets the UI dispatcher used for marshalling operations to the UI thread.

An IUiDispatcher instance if the engine was started with a valid SynchronizationContext; otherwise, null.

This dispatcher is established when Start(SynchronizationContext) is called and is used internally to post events and operations that must execute on the UI thread.

Event Documentation

AfterBackgroundTasksExecute

Action? Gondwana.Engine.AfterBackgroundTasksExecute

Occurs immediately after DoBackgroundTasks(long) has completed.

Use this event to perform custom actions or monitoring after all background updates (timers, input, animations, surface refreshes, etc.) have been processed.

AfterEngineCycle

Action? Gondwana.Engine.AfterEngineCycle

Occurs immediately after DoForegroundTasks(long) completes within each engine cycle.

Use this event to perform logic that depends on a completed render frame, such as post-render effects, profiling, or scheduling background jobs.

BeforeBackgroundTasksExecute

Action? Gondwana.Engine.BeforeBackgroundTasksExecute

Occurs immediately before DoBackgroundTasks(long) executes within each engine cycle.

Use this event to inject custom background logic such as diagnostics, AI updates, or subsystem polling prior to the engine's own background operations.

BeforeEngineCycle

Action? Gondwana.Engine.BeforeEngineCycle

Occurs immediately before DoForegroundTasks(long) executes within each engine cycle.

Use this event to perform per-frame setup tasks prior to rendering or to update game state that must occur before foreground drawing.

CPSCalculated

Action<CyclesPerSecondCalculatedEventArgs>? Gondwana.Engine.CPSCalculated

Occurs whenever cycles-per-second (CPS) and frames-per-second (FPS) metrics are calculated.

Raised at a regular interval defined by EngineConfiguration.SamplingTimeForCPS. Provides a snapshot of gross and net cycle rates, total elapsed time, and sample interval through a CyclesPerSecondCalculatedEventArgs payload.

This event is posted to the UI thread when a UiDispatcher is available.

Disposed

Action? Gondwana.Engine.Disposed

Raised after the engine has completed explicit disposal.

Fired only when Dispose() is called (never from the finalizer). Indicates all managed cleanup has completed and IsDisposed is true. If a UiDispatcher is available, this event is posted to the UI thread.

Disposing

Action? Gondwana.Engine.Disposing

Raised when Dispose() begins the explicit disposal sequence.

Fired only when Dispose() is called (never from the finalizer). Handlers run before managed cleanup while engine state is still readable. If a UiDispatcher is available, this event is posted to the UI thread.

InitializationComplete

Action? Gondwana.Engine.InitializationComplete

Occurs after all initialization steps and post-initialization logic have completed.

This event is raised at the end of Initialize, every time the method is called. It signifies that the engine and its subsystems are fully active and ready for runtime operations.

If a UiDispatcher is available, this event is posted to the UI thread; otherwise, it executes on the calling thread.

PostInitialization

Action? Gondwana.Engine.PostInitialization

Occurs after all internal initialization routines have completed, but before InitializationComplete is raised.

This event is raised once per engine lifetime, following successful configuration loading, state restoration, and adapter setup.

Use this event for post-initialization logic that depends on fully loaded engine settings but precedes runtime activation.

If a UiDispatcher is available, this event is posted to the UI thread; otherwise, it executes on the calling thread.

PreInitialization

Action? Gondwana.Engine.PreInitialization

Occurs immediately before the engine begins its internal initialization sequence.

This event is raised once per engine lifetime, the first time Initialize is called. It provides an early hook for systems that must perform setup prior to configuration loading or input subsystem initialization.

If a UiDispatcher is available, this event is posted to the UI thread; otherwise, it executes on the calling thread.