Settings used by the engine when cycling. More...

Public Member Functions
bool	HasConfigurationSection (string section)
	Determines whether the specified configuration section exists.
Dictionary< string, string >	CreateConfigurationSection (string section)
	Creates a configuration section if it does not already exist.
bool	RemoveConfigurationSection (string section)
	Removes the specified configuration section and all key/value pairs contained within it.
IReadOnlyDictionary< string, string >?	GetConfigurationSection (string section)
	Gets a read-only view of all key/value pairs in the specified configuration section.
bool	HasConfigurationValue (string section, string key)
	Determines whether a configuration value exists in the specified section.
string?	GetConfigurationValue (string section, string key, string? defaultValue=null)
	Gets a configuration value from the specified section.
void	SetConfigurationValue (string section, string key, string value)
	Sets a configuration value in the specified section, creating the section if necessary.
bool	RemoveConfigurationValue (string section, string key)
	Removes a configuration value from the specified section.
bool	ClearConfigurationSection (string section)
	Clears all key/value pairs from the specified configuration section without removing the section itself.
void	ClearConfigurationSections ()
	Removes all configuration sections and all contained key/value pairs.

Properties
float	RenderScale `[get, set]`
	Establishes logical Backbuffer dimensions from current adapter dimensions. Default is one; values above one enable supersampling. Later adapter resizes affect presentation only. Changing this value requests a new resolution on each surface's rendering thread.
RenderScalingFilter	RenderScalingFilter `[get, set]`
	Filtering for the finished Backbuffer image; independent of View.Zoom and tile filtering.
int	TargetFPS `[get, set]`
	Target screen refresh rate for the Engine. Setting the number lower allows more time for the processor to perform background Engine tasks. Set the value to 0 for no upper limit. Default is 60 FPS.
int	TimerDrivenSimulationRate `[get, set]`
	Gets or sets the number of fixed simulation updates performed per second in timer-driven mode. The browser render cadence remains controlled independently by TargetFPS.
int	MaxTimerDrivenSimulationSteps `[get, set]`
	Gets or sets the maximum number of fixed simulation updates that one externally driven `Tick()` call may perform. Excess accumulated time is discarded to keep a delayed browser frame from entering an unbounded catch-up loop.
float	StartInitializationWaitTimeout `[get, set]`
	Gets or sets how long Engine.Start(SynchronizationContext) waits when another thread is already running Engine.Initialize.
bool	VSync `[get, set]`
	Gets or sets a value indicating whether vertical synchronisation (vsync) is enabled.
int	MsaaSampleCount `[get, set]`
	Gets or sets the number of MSAA (multisample anti-aliasing) samples used when creating GPU render-target surfaces.
double	SamplingTimeForCPS `[get, set]`
	Total number of seconds between legacy Cycles Per Second (CPS) calculations. Default is 1.5 seconds.
long	SamplingTimeForCPSTicks `[get]`
	Total number of system ticks between each legacy CPS sampling.
double	TimeBetweenKeyboardEvents = 0.03 `[get, set]`
	Minimum time (in seconds) allowed between Keyboard events. Use this to prevent flooding the system with too many events at once (holding down a key, etc). Default is 0.03 seconds (30 milliseconds).
double	GamepadConnectionUpdateFrequencyHz `[get, set]`
	Gets or sets how often the engine checks for gamepad connection and disconnection changes.
double	GamepadPollFrequencyHz `[get, set]`
	Gets or sets how often the engine refreshes the state of already-connected gamepads.
double	TimeBetweenGamepadEvents = 0.03 `[get, set]`
	Minimum time (in seconds) allowed between Gamepad events. Use this to prevent flooding the system with too many events at once (holding down a button, etc). This event-throttle setting is independent of GamepadPollFrequencyHz. Default is 0.03 seconds (30 milliseconds).
double	TimeBetweenMouseEvents = 0.03 `[get, set]`
	Minimum time (in seconds) allowed between Mouse events. Use this to prevent flooding the system with too many events at once (holding down a button, dragging, etc). Default is 0.03 seconds (30 milliseconds).
double	TimeBetweenTouchEvents = 0.03 `[get, set]`
	Minimum time (in seconds) allowed between Touch events. Use this to prevent flooding the system with too many events at once (fast drags, multi-touch, etc). Default is 0.03 seconds (30 milliseconds).
EngineLoggingMode	LoggingMode = EngineLoggingMode.Asynchronous `[get, set]`
	Controls whether engine logging operations are performed synchronously or asynchronously.
int	LoggingQueueCapacity `[get, set]`
	Maximum number of queued log events when LoggingMode is EngineLoggingMode.Asynchronous. When full, log events are dropped (fire-and-forget). Default is 8192.
bool	FlushAsyncLogsOnShutdown = true `[get, set]`
	If true, the engine will attempt to flush queued async log events during shutdown. Default is true.
List< StateFileMount >?	StateFiles `[get, set]`
	Optional collection of serialized EngineStates to mount at initialization.
Dictionary< string, Dictionary< string, string > >	ConfigurationSections = new() `[get, set]`
	Gets or sets a collection of structured configuration values organized into named sections.
Dictionary< string, string >?	this[string section] `[get, set]`
	Gets or sets a configuration section by name.
string?	this[string section, string key] `[get, set]`
	Gets or sets a configuration value using section and key.

Detailed Description

Settings used by the engine when cycling.

Definition at line 13 of file EngineConfiguration.cs.

Member Function Documentation

◆ ClearConfigurationSection()

bool Gondwana.Configuration.EngineConfiguration.ClearConfigurationSection ( string section )

Clears all key/value pairs from the specified configuration section without removing the section itself.

Parameters

section The name of the configuration section to clear.

Returns: true if the section existed and was cleared; otherwise, false.

Definition at line 559 of file EngineConfiguration.cs.

◆ ClearConfigurationSections()

void Gondwana.Configuration.EngineConfiguration.ClearConfigurationSections ( )

Removes all configuration sections and all contained key/value pairs.

Definition at line 573 of file EngineConfiguration.cs.

◆ CreateConfigurationSection()

Dictionary< string, string > Gondwana.Configuration.EngineConfiguration.CreateConfigurationSection ( string section )

Creates a configuration section if it does not already exist.

Parameters

section The name of the configuration section to create.

Returns: The existing or newly created dictionary for the specified section.

Definition at line 439 of file EngineConfiguration.cs.

◆ GetConfigurationSection()

IReadOnlyDictionary< string, string >? Gondwana.Configuration.EngineConfiguration.GetConfigurationSection ( string section )

Gets a read-only view of all key/value pairs in the specified configuration section.

Parameters

section The name of the configuration section to retrieve.

Returns: A read-only dictionary containing the section values, or null if the section does not exist.

Definition at line 473 of file EngineConfiguration.cs.

◆ GetConfigurationValue()

string? Gondwana.Configuration.EngineConfiguration.GetConfigurationValue	(	string	section,
		string	key,
		string?	defaultValue = null )

Gets a configuration value from the specified section.

Parameters

section	The name of the configuration section.
key	The configuration key to retrieve.
defaultValue	The value to return if the section or key does not exist.

Returns: The stored configuration value, or defaultValue if no value exists.

Definition at line 508 of file EngineConfiguration.cs.

◆ HasConfigurationSection()

bool Gondwana.Configuration.EngineConfiguration.HasConfigurationSection ( string section )

Determines whether the specified configuration section exists.

Parameters

section The name of the configuration section.

Returns: true if the section exists; otherwise, false.

Definition at line 427 of file EngineConfiguration.cs.

◆ HasConfigurationValue()

bool Gondwana.Configuration.EngineConfiguration.HasConfigurationValue	(	string	section,
		string	key )

Determines whether a configuration value exists in the specified section.

Parameters

section	The name of the configuration section.
key	The configuration key to check.

Returns: true if the section and key exist; otherwise, false.

Definition at line 490 of file EngineConfiguration.cs.

◆ RemoveConfigurationSection()

bool Gondwana.Configuration.EngineConfiguration.RemoveConfigurationSection ( string section )

Removes the specified configuration section and all key/value pairs contained within it.

Parameters

section The name of the configuration section to remove.

Returns: true if the section was removed; otherwise, false.

Definition at line 459 of file EngineConfiguration.cs.

◆ RemoveConfigurationValue()

bool Gondwana.Configuration.EngineConfiguration.RemoveConfigurationValue	(	string	section,
		string	key )

Removes a configuration value from the specified section.

Parameters

section	The name of the configuration section.
key	The configuration key to remove.

Returns: true if the value was removed; otherwise, false.

Definition at line 543 of file EngineConfiguration.cs.

◆ SetConfigurationValue()

void Gondwana.Configuration.EngineConfiguration.SetConfigurationValue	(	string	section,
		string	key,
		string	value )

Sets a configuration value in the specified section, creating the section if necessary.

Parameters

section	The name of the configuration section.
key	The configuration key to set.
value	The string value to store.

Definition at line 525 of file EngineConfiguration.cs.

Property Documentation

◆ ConfigurationSections

Dictionary<string, Dictionary<string, string> > Gondwana.Configuration.EngineConfiguration.ConfigurationSections = new()

getset

Gets or sets a collection of structured configuration values organized into named sections.

Each top-level key represents a logical configuration section (for example, "graphics", "audio", or "input"). Each section contains a set of string-based key/value pairs that define configurable aspects of the engine or application.

This property is intended for persistent configuration data such as user preferences, engine tuning parameters, or feature flags. It is fully serialized and restored as part of the EngineConfiguration lifecycle.

Unlike runtime state containers (such as EngineState or ValueBag), values stored here are expected to be stable, portable, and environment-agnostic. They should not represent transient gameplay state or frequently mutating runtime data.

The structure is intentionally string-based to ensure compatibility with serialization formats and external tooling, while still allowing flexible organization without requiring changes to the core configuration schema.

// Set values
engineConfiguration.ConfigurationSections["audio"]["volume"] = "0.8";
engineConfiguration.ConfigurationSections["graphics"]["resolution"] = "1920x1080";
 
// Read values
var volume = engineConfiguration.ConfigurationSections["audio"]["volume"];
var resolution = engineConfiguration.ConfigurationSections["graphics"]["resolution"];

Definition at line 418 of file EngineConfiguration.cs.

◆ FlushAsyncLogsOnShutdown

bool Gondwana.Configuration.EngineConfiguration.FlushAsyncLogsOnShutdown = true

getset

If true, the engine will attempt to flush queued async log events during shutdown. Default is true.

Definition at line 374 of file EngineConfiguration.cs.

◆ GamepadConnectionUpdateFrequencyHz

double Gondwana.Configuration.EngineConfiguration.GamepadConnectionUpdateFrequencyHz

getset

Gets or sets how often the engine checks for gamepad connection and disconnection changes.

The connection-discovery frequency in hertz. The default is 0.2 Hz, or once every five seconds. Negative and non-finite values are treated as 0; 0 disables automatic connection discovery.

Definition at line 286 of file EngineConfiguration.cs.

◆ GamepadPollFrequencyHz

double Gondwana.Configuration.EngineConfiguration.GamepadPollFrequencyHz

getset

Gets or sets how often the engine refreshes the state of already-connected gamepads.

The controller-state polling frequency in hertz. The default is 60 Hz. Negative and non-finite values are treated as 0; 0 disables automatic state polling.

Definition at line 302 of file EngineConfiguration.cs.

◆ LoggingMode

EngineLoggingMode Gondwana.Configuration.EngineConfiguration.LoggingMode = EngineLoggingMode.Asynchronous

getset

Controls whether engine logging operations are performed synchronously or asynchronously.

When set to EngineLoggingMode.Asynchronous, log entries are enqueued and processed on a background thread as a fire-and-forget operation. This avoids blocking the engine's main loop but may drop log records if the queue is saturated.

When set to EngineLoggingMode.Synchronous, log entries are written immediately on the calling thread. This guarantees ordering and delivery but may negatively impact engine performance, especially when logging to the console.

The logging execution mode. The default value is EngineLoggingMode.Asynchronous.

Definition at line 346 of file EngineConfiguration.cs.

◆ LoggingQueueCapacity

int Gondwana.Configuration.EngineConfiguration.LoggingQueueCapacity

getset

Maximum number of queued log events when LoggingMode is EngineLoggingMode.Asynchronous. When full, log events are dropped (fire-and-forget). Default is 8192.

Exceptions

ArgumentOutOfRangeException Thrown when attempting to set a value less than or equal to 0.

Definition at line 359 of file EngineConfiguration.cs.

◆ MaxTimerDrivenSimulationSteps

int Gondwana.Configuration.EngineConfiguration.MaxTimerDrivenSimulationSteps

getset

Gets or sets the maximum number of fixed simulation updates that one externally driven Tick() call may perform. Excess accumulated time is discarded to keep a delayed browser frame from entering an unbounded catch-up loop.

The maximum updates per tick. Values below one are clamped to one. The default is 8.

Definition at line 112 of file EngineConfiguration.cs.

◆ MsaaSampleCount

int Gondwana.Configuration.EngineConfiguration.MsaaSampleCount

getset

Gets or sets the number of MSAA (multisample anti-aliasing) samples used when creating GPU render-target surfaces.

This setting only applies to GpuBackbuffer; other backbuffer types ignore it.

Setting this property propagates the value to Gondwana.Rendering.Backbuffers.GpuBackbuffer.MsaaSampleCount on all currently registered GPU surfaces. It also serves as the default value for any new GpuBackbuffer instances created after this property is set. Because the GPU render-target surface must be recreated to change the sample count, active GPU backbuffers apply the new value on their next owning GL-thread GpuBackbuffer.EnsureInitialized call.

A value of 1 disables MSAA. Common higher values are 2, 4, and 8, subject to hardware and driver support. If the requested sample count is not supported, GpuBackbuffer.Initialize automatically falls back to 1 so the surface is always valid.

The MSAA sample count. Values less than 1 are clamped to 1. The default is 1.

Definition at line 207 of file EngineConfiguration.cs.

◆ RenderScale

float Gondwana.Configuration.EngineConfiguration.RenderScale

getset

Establishes logical Backbuffer dimensions from current adapter dimensions. Default is one; values above one enable supersampling. Later adapter resizes affect presentation only. Changing this value requests a new resolution on each surface's rendering thread.

Definition at line 22 of file EngineConfiguration.cs.

◆ RenderScalingFilter

RenderScalingFilter Gondwana.Configuration.EngineConfiguration.RenderScalingFilter

getset

Filtering for the finished Backbuffer image; independent of View.Zoom and tile filtering.

Definition at line 49 of file EngineConfiguration.cs.

◆ SamplingTimeForCPS

double Gondwana.Configuration.EngineConfiguration.SamplingTimeForCPS

getset

Total number of seconds between legacy Cycles Per Second (CPS) calculations. Default is 1.5 seconds.

This setting controls only the compatibility CPS/FPS sampler. New diagnostics should configure Diagnostics.RuntimeProfiler through Engine.Profiler.

Definition at line 236 of file EngineConfiguration.cs.

◆ SamplingTimeForCPSTicks

long Gondwana.Configuration.EngineConfiguration.SamplingTimeForCPSTicks

get

Total number of system ticks between each legacy CPS sampling.

This property exists for compatibility with the legacy CPS/FPS sampler.

Definition at line 252 of file EngineConfiguration.cs.

◆ StartInitializationWaitTimeout

float Gondwana.Configuration.EngineConfiguration.StartInitializationWaitTimeout

getset

Gets or sets how long Engine.Start(SynchronizationContext) waits when another thread is already running Engine.Initialize.

A positive timeout in seconds. Values less than or equal to 0 are clamped to 0.001 seconds (1 millisecond). The default is 30 seconds.

Definition at line 128 of file EngineConfiguration.cs.

◆ StateFiles

List<StateFileMount>? Gondwana.Configuration.EngineConfiguration.StateFiles

getset

Optional collection of serialized EngineStates to mount at initialization.

Definition at line 379 of file EngineConfiguration.cs.

◆ TargetFPS

int Gondwana.Configuration.EngineConfiguration.TargetFPS

getset

Target screen refresh rate for the Engine. Setting the number lower allows more time for the processor to perform background Engine tasks. Set the value to 0 for no upper limit. Default is 60 FPS.

Setting this property also updates Gondwana.Rendering.Backbuffers.GpuBackbuffer.TargetFps on all currently registered GPU surfaces to keep that value consistent. It also serves as the default value for any new GpuBackbuffer instances created after this property is set.

Definition at line 75 of file EngineConfiguration.cs.

◆ this[string section, string key]

string? Gondwana.Configuration.EngineConfiguration.this[string section, string key]

getset

Gets or sets a configuration value using section and key.

When getting, returns the value if found; otherwise null. When setting, creates the section if necessary and stores the value.

Parameters

section	The name of the configuration section.
key	The configuration key within the section.

Returns: The stored configuration value, or null if not found.

Definition at line 626 of file EngineConfiguration.cs.

◆ this[string section]

Dictionary<string, string>? Gondwana.Configuration.EngineConfiguration.this[string section]

getset

Gets or sets a configuration section by name.

When getting, returns the existing section if present; otherwise null. When setting, replaces the entire section with the provided dictionary.

Parameters

section The name of the configuration section.

Returns: The dictionary of key/value pairs for the section, or null if the section does not exist.

Definition at line 589 of file EngineConfiguration.cs.

◆ TimeBetweenGamepadEvents

double Gondwana.Configuration.EngineConfiguration.TimeBetweenGamepadEvents = 0.03

getset

Minimum time (in seconds) allowed between Gamepad events. Use this to prevent flooding the system with too many events at once (holding down a button, etc). This event-throttle setting is independent of GamepadPollFrequencyHz. Default is 0.03 seconds (30 milliseconds).

Definition at line 315 of file EngineConfiguration.cs.

◆ TimeBetweenKeyboardEvents

double Gondwana.Configuration.EngineConfiguration.TimeBetweenKeyboardEvents = 0.03

getset

Minimum time (in seconds) allowed between Keyboard events. Use this to prevent flooding the system with too many events at once (holding down a key, etc). Default is 0.03 seconds (30 milliseconds).

Definition at line 274 of file EngineConfiguration.cs.

◆ TimeBetweenMouseEvents

double Gondwana.Configuration.EngineConfiguration.TimeBetweenMouseEvents = 0.03

getset

Minimum time (in seconds) allowed between Mouse events. Use this to prevent flooding the system with too many events at once (holding down a button, dragging, etc). Default is 0.03 seconds (30 milliseconds).

Definition at line 322 of file EngineConfiguration.cs.

◆ TimeBetweenTouchEvents

double Gondwana.Configuration.EngineConfiguration.TimeBetweenTouchEvents = 0.03

getset

Minimum time (in seconds) allowed between Touch events. Use this to prevent flooding the system with too many events at once (fast drags, multi-touch, etc). Default is 0.03 seconds (30 milliseconds).

Definition at line 329 of file EngineConfiguration.cs.

◆ TimerDrivenSimulationRate

int Gondwana.Configuration.EngineConfiguration.TimerDrivenSimulationRate

getset

Gets or sets the number of fixed simulation updates performed per second in timer-driven mode. The browser render cadence remains controlled independently by TargetFPS.

The fixed update rate in hertz. Values below one are clamped to one. The default is 120.

Definition at line 98 of file EngineConfiguration.cs.

◆ VSync

bool Gondwana.Configuration.EngineConfiguration.VSync

getset

Gets or sets a value indicating whether vertical synchronisation (vsync) is enabled.

This setting only applies to GpuBackbuffer; other backbuffer types ignore it.

Setting this property propagates the value to Gondwana.Rendering.Backbuffers.GpuBackbuffer.VSync on all currently registered GPU surfaces. It also serves as the default value for any new GpuBackbuffer instances created after this property is set. The change is applied to each surface lazily at the start of its next PaintSurface callback.

Enabling vsync prevents screen tearing but caps the frame rate to the monitor refresh rate. Disabling vsync allows higher frame rates at the cost of potential tearing.

true to synchronise presentation with the monitor refresh; otherwise false. The default is true.

Definition at line 162 of file EngineConfiguration.cs.

Public Member Functions

Properties

Detailed Description

Member Function Documentation

◆ ClearConfigurationSection()

◆ ClearConfigurationSections()

◆ CreateConfigurationSection()

◆ GetConfigurationSection()

◆ GetConfigurationValue()

◆ HasConfigurationSection()

◆ HasConfigurationValue()

◆ RemoveConfigurationSection()

◆ RemoveConfigurationValue()

◆ SetConfigurationValue()

Property Documentation

◆ ConfigurationSections

◆ FlushAsyncLogsOnShutdown

◆ GamepadConnectionUpdateFrequencyHz

◆ GamepadPollFrequencyHz

◆ LoggingMode

◆ LoggingQueueCapacity

◆ MaxTimerDrivenSimulationSteps

◆ MsaaSampleCount

◆ RenderScale

◆ RenderScalingFilter

◆ SamplingTimeForCPS

◆ SamplingTimeForCPSTicks

◆ StartInitializationWaitTimeout

◆ StateFiles

◆ TargetFPS

◆ this[string section, string key]

◆ this[string section]

◆ TimeBetweenGamepadEvents

◆ TimeBetweenKeyboardEvents

◆ TimeBetweenMouseEvents

◆ TimeBetweenTouchEvents

◆ TimerDrivenSimulationRate

◆ VSync