The engine config is a JSON file loaded before renderer startup. Packaged projects should ship it with the runtime asset tree and load it before creating renderer resources.

Runtime Access

Read values through Engine::Config::Engine:

uint32_t mode = Config::Engine::get().render().debugMode;

float threshold = Config::Engine::get().lod().errorThresholdPixels;

Modify values directly through the non-const accessors:

Config::Engine::get().render().debugMode = 10;

Config::Engine::get().streaming().freezeUploadRequests = true;

Loading

bool configLoaded = Config::Engine::get().loadFromFile("path/to/engine.json");

Missing sections keep their hardcoded defaults. Missing keys inside a section keep their current values. Invalid JSON or type mismatches fail the whole load and log an error.

saveToFile() writes every supported section and key with four-space indentation.

Renderer

Engine::Config::Render controls renderer debug output, post processing, MSAA, and sky color.

Engine::Config::Render::skyEnabled is a runtime field used by the renderer. Render::loadFromJson() and Render::toJson() do not read or write a skyEnabled JSON key.

Key	Type	Default	Notes
debugMode	uint32_t	0	Shader debug visualization mode. 0 selects normal rendering.
tonemapMode	uint32_t	2	0 none, 1 Reinhard, 2 ACES Hill, 3 Uncharted 2.
exposure	float	1.17	Post-process exposure for normal rendering.
vsyncEnabled	bool	false	Requests VSync for presentation when supported by the runtime path.
validationLayersEnabled	bool	true	Requests Vulkan validation layers when supported by the build and runtime.
msaaSamples	uint32_t	4	Requested MSAA sample count. Runtime selection falls back to 2 or 1 when hardware support is lower.
skyColorTop.r	float	0.4	Top sky gradient red channel.
skyColorTop.g	float	0.6	Top sky gradient green channel.
skyColorTop.b	float	1.0	Top sky gradient blue channel.
skyColorBottom.r	float	0.8	Bottom sky gradient red channel.
skyColorBottom.g	float	0.9	Bottom sky gradient green channel.
skyColorBottom.b	float	1.0	Bottom sky gradient blue channel.

Debug mode labels:

Value	Mode
0	Normal
1	Normals
2	Raw SH / Lightmap UVs
3	SH L0 ambient
4	SH L1 directional
5	SH L2 quadratic / normal map
6	Metallic-roughness
7	Emissive
8	Texture indices
9	Texture presence
10	Meshlet ID, PCG hash
11	Meshlet ID, golden ratio
12	Object ID
13	SH probe index
14	SH octree depth
15	SH probe L0
16	Sun shadow cascade

Debug

Engine::Config::Debug stores development toggles.

Key	Type	Default	Notes
gpuDebuggingMode	uint32_t	1	GPU debugging mode. 0 disables it. 1 selects shader printf. 2 selects validation-assisted debugging.
renderDocCapture	bool	false	Requests RenderDoc capture support when available in the build.

Level of Detail (LOD)

Engine::Config::Lod stores cluster LOD settings.

Key	Type	Default	Notes
enabled	bool	true	Enables cluster LOD selection.
errorThresholdPixels	float	4.0	Sent to the LOD uniform data for screen-space cluster selection.
ditherTransitions	bool	true	Sent to the LOD uniform data for transition dithering.
debugVisualization	bool	false	Enables LOD debug visualization.
forcedLodLevel	int32_t	-1	Forces a specific LOD level when non-negative.
minClustersForLod	uint32_t	4	Minimum cluster count before LOD selection is applied.

Window

Engine::Config::Window selects the monitor used by the mirror window.

Key	Type	Default	Notes
monitorIndex	int32_t	0	0 selects the primary monitor. Valid non-negative indices select the GLFW monitor at that index. Out-of-range values fall back to the primary monitor. Negative values also use the primary monitor.

ImGui

Engine::Config::ImGuiConfig stores editor and debug drawing options.

Key	Type	Default	Notes
debugRenderingEnabled	bool	true	Controls whether ImGui debug rendering is drawn. The renderer widget can disable it for recording.
randomCollisionDebugColors	bool	false	Enables randomized collision debug colors.
debugLineDepthAware	bool	true	Selects the depth-aware debug line pipeline.

Streaming

Engine::Config::Streaming controls texture and lightmap streaming behavior.

Key	Type	Default	Notes
freezeUploadRequests	bool	false	Prevents new upload requests while preserving existing renderer state. Exposed by the renderer widget as Freeze Streaming.

Shadows

Engine::Config::Shadows configures cascaded sun shadows.

Key	Type	Default	Notes
sunShadowsEnabled	bool	true	Master toggle for sun shadow work.
cascadeCount	uint32_t	3	Number of cascades.
mapSize	uint32_t	1024	Shadow map resolution per cascade.
maxDistance	float	50.0	Maximum camera distance covered by cascades.
splitLambda	float	0.5	Cascade split distribution factor.
depthBias	float	0.001	Depth bias passed to shadow rendering.
normalBias	float	0.02	Normal bias passed to shadow rendering.
pcfRadius	uint32_t	1	PCF filter radius.
staticCasters	bool	true	Includes static geometry in shadow caster selection.
dynamicCasters	bool	true	Includes dynamic geometry in shadow caster selection.
movableReceivers	bool	true	Applies sun shadows to movable receivers.
lightmappedReceivers	bool	false	Applies dynamic sun shadows to lightmapped receivers.
sunDirectRemovalScale	float	0.6	Scales direct sun removal on baked lightmapped receivers. Values are clamped to [0.0, 2.0] while loading.

Complete Example

{
    "render": {
        "debugMode": 0,
        "tonemapMode": 2,
        "exposure": 1.17,
        "vsyncEnabled": false,
        "validationLayersEnabled": true,
        "msaaSamples": 4,
        "skyColorTop": {
            "r": 0.4,
            "g": 0.6,
            "b": 1.0
        },
        "skyColorBottom": {
            "r": 0.8,
            "g": 0.9,
            "b": 1.0
        }
    },
    "debug": {
        "gpuDebuggingMode": 1,
        "renderDocCapture": false
    },
    "lod": {
        "enabled": true,
        "errorThresholdPixels": 4.0,
        "ditherTransitions": true,
        "debugVisualization": false,
        "forcedLodLevel": -1,
        "minClustersForLod": 4
    },
    "window": {
        "monitorIndex": 0
    },
    "imgui": {
        "debugRenderingEnabled": true,
        "randomCollisionDebugColors": false,
        "debugLineDepthAware": true
    },
    "streaming": {
        "freezeUploadRequests": false
    },
    "shadows": {
        "sunShadowsEnabled": true,
        "cascadeCount": 3,
        "mapSize": 1024,
        "maxDistance": 50.0,
        "splitLambda": 0.5,
        "depthBias": 0.001,
        "normalBias": 0.02,
        "pcfRadius": 1,
        "staticCasters": true,
        "dynamicCasters": true,
        "movableReceivers": true,
        "lightmappedReceivers": false,
        "sunDirectRemovalScale": 0.6
    }
}