Quality Overrides

The engine config acts as a performance governor — it clamps or disables expensive rendering effects without touching artist-authored environment files. This lets low-end systems degrade gracefully while the environment retains full artistic intent.

---

Priority Cascade

The engine resolves rendering quality through a three-layer cascade. Each layer can only clamp or disable what the layer below provides — it never adds effects the environment didn't define.

Priority	Source	Role
Highest	Engine config	Performance budget — "can my GPU handle this?"
Middle	Camera / scene	Distance thresholds — "when to simplify?"
Base	Environment file	Artistic intent — "what should this world look like?"

---

Config Loading Chain

Engine configuration merges in three layers. A field is only overridden if it differs from the C++ hardcoded default, so a layer that doesn't mention a key leaves it exactly as the lower layer set it.

Layer	File	Notes
1 — Engine defaults	engine_defaults/engine.config.json	Ships with the engine
2 — Workspace root	engine.config.json	Provides gameDir; workspace-level overrides
3 — Game overrides	<gameDir>/engine.config.json	Per-game tuning

A future layer 4 (user data, e.g. Documents/Glitter/user.config.json) would sit on top for player-facing settings menus.

---

Quality Sections

These sections live in engine.config.json alongside the existing shadows, ssao, ibl, textures, and probes blocks.

atmosphere

Controls whether atmospheric effects (fog, aerial perspective) are rendered. The environment file defines the artistic parameters; this section decides whether the hardware can afford them.

"atmosphere": {
    "enabled": true,
    "maxDistance": 0,
    "quality": "full"
}

Key	Type	Default	Description
enabled	bool	true	false = no fog/atmosphere at all, regardless of environment
maxDistance	float	0	0 = use environment's fogEnd; >0 = clamp fog distance to this value
quality	string	"full"	"full" = full scattering model; "simple" = cheap linear fog only

materialLod

Controls distance-based material simplification. Materials declare their LOD-capable textures; this section decides when or whether to simplify.

"materialLod": {
    "enabled": true,
    "distanceBias": 0.0,
    "forceLevel": -1
}

Key	Type	Default	Description
enabled	bool	true	false = always use full PBR, no LOD transitions
distanceBias	float	0.0	Positive = LOD kicks in closer (low-end); negative = farther
forceLevel	int	-1	-1 = auto (distance-based); 0 = full PBR; 1 = drop normal/metalRough; 2 = albedo-only

vrs

Variable-rate shading via VK_KHR_fragment_shading_rate. Opt-in because it requires hardware support (NVIDIA Turing+, AMD RDNA2+, Intel Arc).

"vrs": {
    "enabled": false
}

Key	Type	Default	Description
enabled	bool	false	true = enable VRS where supported; engine checks device capabilities at init

---

Low-End Example

A player on integrated graphics could use a game config override like:

{
    "shadows": { "enabled": true, "mapSize": 1024, "cascadeCount": 1 },
    "ssao": { "enabled": false },
    "textures": { "maxAnisotropy": 4.0 },
    "atmosphere": { "quality": "simple" },
    "materialLod": { "forceLevel": 1 },
    "vrs": { "enabled": true }
}

This keeps shadows (smaller, single cascade), disables SSAO, reduces anisotropy, falls back to cheap linear fog, drops normal/metalRough maps at all distances, and enables VRS — without the artist touching a single environment or material file.

---

Existing Quality Sections

For reference, these sections already exist and follow the same governor pattern:

Section	Key fields	What it governs
shadows	enabled, mapSize, cascadeCount, pointShadowsEnabled	Shadow mapping quality
ssao	enabled, kernelSize, radius, bias	Screen-space ambient occlusion
ibl	enabled	Image-based lighting
textures	maxAnisotropy, mipLodBias	Texture filtering quality
probes	skyBakeSize, localBakeSize	Reflection probe resolution
postprocess	exposure, forwardPassEnabled	Post-processing pipeline

---

Where to go next

• Environments — artistic atmosphere settings that the engine config governs
• Architecture — overall engine design
• Scripts — build and asset processing scripts