API EngineSettings - shmellyorc/Box GitHub Wiki

EngineSettings

Namespace: Box

Description

Holds configuration options for the core engine, including window and viewport sizes, application metadata (title, version, content and save roots), rendering settings (clear color, vsync, antialiasing), input mapping, debugging aids, service registrations, and error handling callbacks. Built via a fluent API, it produces a single immutable instance that drives engine initialization and behavior.

Constructor

public EngineSettings()

Initializes the default settings (e.g., window 1280×720, viewport 320×180, AppTitle="Game", AppVersion="1.0", ClearColor=CornFlowerBlue) and assigns this instance to EngineSettings.Instance for global access.

Properties

Property	Description
`static EngineSettings Instance`	The globally accessible settings instance built via the fluent API.
`string AppTitle`	Title displayed on the game window (default: "Game").
`string AppName`	Folder or application data name (default: "Game").
`string AppContentRoot`	Root directory for content assets (default: "Content").
`string AppSaveRoot`	Directory for save files (default: "Save").
`string AppLogRoot`	Directory for log files (default: "Logs").
`string AppSettings`	Filename for engine settings file (default: "settings.json").
`string AppVersion`	Version string for the application (default: "1.0").
`bool IsMacBundle`	Whether to load assets from macOS bundles instead of custom paths (default: false).
`bool UseApplicationData`	Whether to use OS application data folder for saves/logs (default: false).
`bool Fullscreen`	Whether to start in full-screen mode (default: false).
`bool UseTextureHalfOffset`	Adjusts texture coordinates to prevent bleeding in pixel/tile-based games (default: false).
`BoxColor ClearColor`	Background color used when clearing the screen each frame (default: CornFlowerBlue).
`Vect2 Window`	Window size in pixels (width × height, default: 1280×720).
`Vect2 Viewport`	Rendering viewport size in pixels (default: 320×180).
`Screen[] Screens`	Array of initial screens to load on startup (default: null).
`int MaxDrawCalls`	Maximum number of draw calls per frame (default: 256).
`bool DebugDraw`	Whether to render debug shapes for entities (default: false).
`int AntialiasingLevel`	Level of antialiasing (0 = none, default: 0).
`bool VSync`	Whether to enable vertical sync (default: true).
`bool Mouse`	Whether to display the mouse cursor in the viewport (default: true).
`int CullSize`	Padding around camera for culling off-screen entities (default: 16).
`int SafeRegion`	Margin around UI elements to prevent overlap with window edges (default: 8).
`float GamepadDeadzone`	Dead zone threshold for gamepad axes (0.0–1.0, default: 0.2).
`InputMap InputMap`	Active input mapping instance (default: `new DefaultInputMap()`).
`bool LogSignalEvents`	Whether to log pub/sub signal events (default: false).
`GameService[] Services`	Collection of global services registered with the engine (default: null).
`bool LogDateTime`	Whether to include date/time in log output (default: true).
`Action<Engine,Exception> OnError`	Callback invoked on engine errors or crashes (default: null).

Methods

Method Signature	Description	Returns
`EngineSettings WithAppTitle(string value)`	Sets the window title. Throws if value is null or empty.	`EngineSettings`
`EngineSettings WithAppName(string value)`	Sets the application folder/name. Throws if value is null or empty.	`EngineSettings`
`EngineSettings WithAppContentRoot(string value)`	Sets content root directory. Throws if value is null or empty.	`EngineSettings`
`EngineSettings WithAppSaveRoot(string value)`	Sets save root directory. Throws if value is null or empty.	`EngineSettings`
`EngineSettings WithAppLogRoot(string value)`	Sets log root directory. Throws if value is null or empty.	`EngineSettings`
`EngineSettings WithAppSettings(string value)`	Sets settings filename. Throws if value is null or empty.	`EngineSettings`
`EngineSettings WithAppVersion(string value)`	Sets version string. Throws if value is null or empty.	`EngineSettings`
`EngineSettings WithIsMacBundle(bool value)`	Configures macOS bundle usage for assets.	`EngineSettings`
`EngineSettings WithUseApplicationData(bool value)`	Configures use of OS application data for saves/logs.	`EngineSettings`
`EngineSettings WithFullscreen(bool value)`	Enables or disables full-screen startup.	`EngineSettings`
`EngineSettings WithUseTextureHalfOffset(bool value)`	Enables texture half-offset to prevent bleeding gaps.	`EngineSettings`
`EngineSettings WithClearColor(BoxColor value)`	Sets clear/background color.	`EngineSettings`
`EngineSettings WithWindow(int width, int height)`	Defines window size; throws if negative.	`EngineSettings`
`EngineSettings WithViewport(int width, int height)`	Defines viewport size; throws if negative.	`EngineSettings`
`EngineSettings WithScreens(params Screen[] values)`	Registers initial screens; throws if array empty.	`EngineSettings`
`EngineSettings WithMaxDrawCalls(int value)`	Sets max draw calls; throws if less than 1.	`EngineSettings`
`EngineSettings WithDebugDraw(bool value)`	Toggles debug shape rendering.	`EngineSettings`
`EngineSettings WithAntialiasingLevel(int value)`	Sets antialiasing level; throws if negative.	`EngineSettings`
`EngineSettings WithVSync(bool value)`	Toggles vertical synchronization.	`EngineSettings`
`EngineSettings WithMouse(bool value)`	Toggles mouse cursor visibility.	`EngineSettings`
`EngineSettings WithCullSize(int value)`	Sets culling padding; throws if negative.	`EngineSettings`
`EngineSettings WithSafeRegion(int value)`	Sets UI safe region; throws if negative.	`EngineSettings`
`EngineSettings WithGamepadDeadzone(float value)`	Sets gamepad dead zone; clamps between 0.0–1.0.	`EngineSettings`
`EngineSettings WithInputMap(InputMap value)`	Assigns input mapping; throws if null.	`EngineSettings`
`EngineSettings WithLogSignalEvents(bool value)`	Toggles logging of signal events.	`EngineSettings`
`EngineSettings WithServices(params GameService[] values)`	Registers global services; throws if array empty or contains null.	`EngineSettings`
`EngineSettings WithLogDateTime(bool value)`	Toggles inclusion of date/time in logs.	`EngineSettings`
`EngineSettings WithOnError(Action<Engine,Exception> value)`	Sets custom error handler; throws if null.	`EngineSettings`
`EngineSettings Build()`	Finalizes and validates settings, returning the same instance for engine initialization.	`EngineSettings`

Examples

// Fluent configuration of engine settings
var settings = new EngineSettings()
    .WithAppTitle("Adventure Quest")
    .WithAppContentRoot("Assets")
    .WithWindow(1920, 1080)
    .WithFullscreen(true)
    .WithGamepadDeadzone(0.15f)
    .WithClearColor(BoxColor.AllShades.Black)
    .WithServices(new AudioService(), new PhysicsService())
    .Build();

// Access the configured instance anywhere in your program
using var game = new Engine(settings);

game.Start();