Toward a More Consistent Engine Configuration API

[untoldengine]

Starting with v0.13.2 of the engine, I've started introducing a more consistent public API style across Untold Engine.

The idea is simple:

setDomain(.property(value))
setDomain(.group(.property(value)))

Rather than exposing settings through a mix of globals, singleton instances, and subsystem-specific APIs, settings are organized by domain and configured through typed setters.

This approach provides:

• Better autocomplete and discoverability
• Stronger type safety
• More predictable API organization
• Cleaner engine initialization and runtime tuning code
• Consistent patterns across engine systems

Examples

Rendering:

setRendering(.antiAliasing(.smaa))
setRendering(.debugView(.lit))
setRendering(.postProcessing(.enabled))

Post-processing:

setPostFX(.ssao(.enabled(true)))
setPostFX(.ssao(.quality(.balanced)))
setPostFX(.colorGrading(.exposure(-0.2)))

LOD:

setLOD(.fadeTransitions(.enabled(duration: 0.25)))
setLOD(.distanceBias(1.0))

Geometry Streaming:

setGeometryStreaming(.enabled(true))
setGeometryStreaming(.tileConcurrency(2))
setGeometryStreaming(.queryRadius(500.0))

Batching:

setBatching(.enabled(true))
setBatching(.runtimeTuning(.visionOSBalanced))

Logging:

setLogger(.level(.debug))
setLogger(.category(.tileStreaming, true))

Camera and Input:

setCamera(.defaultFOV(70.0))

setInput(.xr(.pickingBackend(.octreeGPUPreferred)))

XR spatial manipulation tuning follows the same pattern:

setSpatialManipulation(.intentTranslationThreshold(0.01))
setSpatialManipulation(.intentRotationThreshold(0.08))
setSpatialManipulation(.intentDominanceRatio(1.15))
setSpatialManipulation(.zoomScale(min: 0.05, max: 20.0))
setSpatialManipulation(.rotationDeltaLimit(perFrame: 0.12, twoHand: 0.35))
setSpatialManipulation(.twoHandRotationDeadzone(0.001))
setSpatialManipulation(.rotationSmoothing(factor: 0.25, deadzone: 0.002))
setSpatialManipulation(.classificationFrames(3))

And the per-frame XR interaction lifecycle is exposed through focused free functions:

let state = getXRSpatialInputState()

processPinchTransformLifecycle(from: state)
applyPinchDragIfNeeded(from: state, entityId: myEntity)

processAnchoredPinchDragLifecycle(from: state, entityId: myEntity, dragPlane: .xz)

processAnchoredSceneDragLifecycle(from: state)
processAnchoredSceneRotateLifecycle(from: state)
processAnchoredSceneManipulationLifecycle(from: state)

applyTwoHandZoomIfNeeded(from: state, entityId: myEntity)
applyTwoHandRotateIfNeeded(from: state, entityId: myEntity)

Lighting follows the same pattern through entity-specific configuration:

setLight(entityId: light, .color(simd_float3(1.0, 0.85, 0.7)))
setLight(entityId: light, .intensity(2.5))

setLight(entityId: light, .directional(.active))

setLight(entityId: light, .point(.radius(5.0)))
setLight(entityId: light, .spot(.coneAngle(30.0)))
setLight(entityId: light, .area(.twoSided(true)))

Scene channels also adopt the same style:

setSceneChannel(.contextGeometry, .renderMode(.wireframe))
setSceneChannel(.windowGeometry, .renderMode(.passthroughGhost(opacity: 0.0)))
setSceneChannel(.windowGeometry, .lightPortal(.enabled()))

Compatibility

This change does not remove lower-level APIs.

Direct subsystem access, shared configuration objects, and explicit command-style APIs will continue to exist where they provide value, particularly for advanced workflows and one-shot operations.

The primary change is the preferred public-facing direction for engine configuration: new settings APIs should favor typed domain setters rather than introducing additional global mutation points.

Going Forward

The general pattern is:

setRendering(.property(value))
setPostFX(.effect(.property(value)))
setEngine(.property(value))
setGeometryStreaming(.property(value))
setBatching(.property(value))
setLOD(.property(value))
setSpatialDebug(.property(value))
setLogger(.property(value))
setCamera(.property(value))
setInput(.xr(.property(value)))
setSpatialManipulation(.property(value))
setLight(entityId: entity, .lightType(.property(value)))
setSceneChannel(.contextGeometry, .property(value))

The long-term goal is a public API that is organized around predictable domains, strongly typed settings, and compiler-guided discovery, while keeping the underlying implementation modular and extensible.

Thank you