Scene¶

Description¶

A Scene is the root container for all objects, systems, and resources in a project. It manages the active camera, background color, global illumination, shadow settings, and the update/draw lifecycle. You typically create one or more scenes at startup and set the active one with Engine::setScene.

Inherits: EntityRegistry

#include "Doriax.h"
using namespace doriax;

Scene scene;

void MySystem::onUpdate() {
    scene.setBackgroundColor(0.1f, 0.1f, 0.2f);
}

local scene = Scene()
scene:setBackgroundColor(0.1, 0.1, 0.2)
Engine.setScene(scene)

Properties¶

Methods¶

Entity and hierarchy methods — createEntity, destroyEntity, setEntityName / getEntityName, findEntity, addEntityChild, getEntityList — are inherited from EntityRegistry.

Enumerations¶

LightState¶

• OFF — Disables all lights in the scene; objects are rendered with no dynamic lighting.
• ON — Forces dynamic lighting on regardless of light objects present.
• AUTO — Activates lighting automatically when at least one light entity exists in the scene (default).

UIEventState¶

• NOT_SET — Inherits UI event behaviour from the engine default.
• ENABLED — This scene receives UI pointer events.
• DISABLED — This scene ignores UI pointer events.

ShadowQuality¶

PCF filter quality of shadow edges, shared by shadowQuality (3D shadow maps) and shadow2DQuality (2D lights).

• NONE — 1 tap, no filtering (hard edges)
• LOW — 3×3 taps in 3D / 5 taps in 2D (default)
• MEDIUM — 5×5 taps in 3D / 9 taps in 2D
• HIGH — 7×7 taps in 3D / 13 taps in 2D

Property details¶

backgroundColor¶

• Setter: void setBackgroundColor(Vector4 color)
• Getter: Vector4 getBackgroundColor() const

Background clear color for the scene, in RGBA [0, 1] range. Convenience overloads accept (r, g, b) or (r, g, b, a) floats directly.

shadowQuality¶

• Setter: void setShadowQuality(ShadowQuality quality)
• Getter: ShadowQuality getShadowQuality() const

Filter quality of 3D shadow map edges (PCF kernel size, applied instantly with no shader rebuild):

• NONE — 1 tap, hard edges (or performance savings on mobile)
• LOW — 3×3 taps (default)
• MEDIUM — 5×5 taps
• HIGH — 7×7 taps

The same ShadowQuality enum also drives shadow2DQuality for 2D lights.

Lua exposes this setting as the shadowQuality property:

scene.shadowQuality = ShadowQuality.MEDIUM

There is no separate shadow3DQuality Lua property; shadowQuality is the 3D shadow quality setting.

lightState¶

• Setter: void setLightState(LightState state)
• Getter: LightState getLightState() const

Controls whether the render system activates the lighting pass. See LightState.

globalIlluminationIntensity¶

Part of setGlobalIllumination. Controls the brightness of the ambient light applied uniformly across the scene.

globalIlluminationColor¶

Part of setGlobalIllumination. Controls the tint of the ambient light (linear color, [0,1] per channel).

ambientLight2DIntensity¶

Part of setAmbientLight2D. Controls the brightness of the 2D ambient light applied to 2D-lit objects. Defaults to 1.0 (fully lit), so a scene looks unchanged until you dim it.

ambientLight2DColor¶

Part of setAmbientLight2D. Controls the tint of the 2D ambient light.

shadow2DQuality¶

• Setter: void setShadow2DQuality(ShadowQuality quality)
• Getter: ShadowQuality getShadow2DQuality() const

Filter quality of 2D light shadows (PCF taps along the 1D polar shadow map). More taps smooth the same penumbra width (set per light by Light2D — shadowSoftness), removing banding on wide penumbras. Changing it takes effect immediately (no shader rebuild).

• NONE — 1 tap, no filtering (hard edges regardless of softness)
• LOW — 5 taps (default)
• MEDIUM — 9 taps
• HIGH — 13 taps

scene.setShadow2DQuality(ShadowQuality::MEDIUM);

scene.shadow2DQuality = ShadowQuality.MEDIUM

gravity2D¶

• Setters: void setGravity2D(Vector2 gravity), void setGravity2D(float x, float y)
• Getter: Vector2 getGravity2D() const

Gravity of the 2D physics world (Box2D), in meters per second squared. Affects every dynamic Body2D in the scene, scaled per body by gravityScale. Independent from gravity3D. Changing it at runtime does not wake sleeping bodies. Forwards to the scene's PhysicsSystem. Default (0, -9.81).

scene.setGravity2D(Vector2(0, -20));

scene.gravity2D = Vector2(0, -20)

gravity3D¶

• Setters: void setGravity3D(Vector3 gravity), void setGravity3D(float x, float y, float z)
• Getter: Vector3 getGravity3D() const

Gravity of the 3D physics world (Jolt), in meters per second squared. Affects every dynamic Body3D in the scene, scaled per body by gravityFactor. Independent from gravity2D. Changing it at runtime does not wake sleeping bodies. Forwards to the scene's PhysicsSystem. Default (0, -9.81, 0).

scene.setGravity3D(Vector3(0, -3.7f, 0)); // Mars

scene.gravity3D = Vector3(0, -3.7, 0) -- Mars

ssaoEnabled¶

• Setter: void setSSAOEnabled(bool enabled)
• Getter: bool isSSAOEnabled() const

Enables screen-space ambient occlusion. SSAO darkens the ambient/indirect lighting (IBL or global illumination) in creases and contact areas; it does not affect direct light. Toggling it recompiles lit mesh shaders. Applies to the main camera; terrain is currently excluded.

ssaoRadius¶

• Setter: void setSSAORadius(float radius)
• Getter: float getSSAORadius() const

View-space sampling radius (world units). Larger values gather occlusion from farther surfaces (broader, softer AO); smaller values keep it to tight contact creases.

ssaoIntensity¶

• Setter: void setSSAOIntensity(float intensity)
• Getter: float getSSAOIntensity() const

Strength of the effect, applied as an exponent on the occlusion factor — higher values darken occluded areas more.

ssaoBias¶

• Setter: void setSSAOBias(float bias)
• Getter: float getSSAOBias() const

View-space depth bias that prevents self-occlusion artifacts (acne) on flat surfaces. Increase slightly if flat areas appear dirty; keep small to preserve fine contact detail.

ssaoDebug¶

• Setter: void setSSAODebug(bool debug)
• Getter: bool isSSAODebug() const

Debug aid: when enabled, lit meshes output the raw screen-space AO buffer as grayscale instead of their shaded color, so you can inspect and tune the occlusion directly. Not serialized.

ssrEnabled¶

• Setter: void setSSREnabled(bool ssrEnabled)
• Getter: bool isSSREnabled() const

Enables screen-space reflections. SSR reflects on-screen geometry by marching the camera depth/G-buffer, and where it finds a hit it replaces the surface's IBL environment reflection rather than adding to it (falling back to IBL where the ray misses). Requires a framebuffer destination (editor viewport, render-to-texture camera, or engine framebuffer) and applies to the main camera. Toggling it reloads meshes to build the G-buffer shaders.

ssrMaxDistance¶

• Setter: void setSSRMaxDistance(float maxDistance)
• Getter: float getSSRMaxDistance() const

Maximum reflection ray length in view-space units. Longer rays catch more distant reflections at higher cost. Default 8.0.

ssrThickness¶

• Setter: void setSSRThickness(float thickness)
• Getter: float getSSRThickness() const

Depth-compare tolerance (view-space units) for accepting a ray hit. Smaller is stricter; larger fills gaps but can smear at object contacts. Default 0.5.

ssrMaxSteps¶

• Setter: void setSSRMaxSteps(int maxSteps)
• Getter: int getSSRMaxSteps() const

Linear march sample count. Higher gives sharper, longer reflections (and helps thin contacts register) at more cost. Default 48.

ssrIntensity¶

• Setter: void setSSRIntensity(float intensity)
• Getter: float getSSRIntensity() const

Overall reflection strength multiplier applied in the composite. Default 1.0.

ssrBlur¶

• Setter: void setSSRBlur(float blur)
• Getter: float getSSRBlur() const

Glossy blur amount in [0..1]. 0 keeps mirror-sharp reflections; higher values blur the reflection in proportion to each surface's roughness. Default 0.0.

ssrDebugMode¶

• Setter: void setSSRDebugMode(int mode)
• Getter: int getSSRDebugMode() const

Debug visualization of the SSR G-buffer, rendered full-screen: 0 off, 1 reflection buffer, 2 normal, 3 roughness, 4 metallic, 5 albedo, 6 IBL specular. Not serialized.

fixedResolutionEnabled¶

• Setter: void setFixedResolutionEnabled(bool fixedResolutionEnabled)
• Getter: bool isFixedResolutionEnabled() const

Renders the main camera into an internal buffer of fixedResolutionWidth × fixedResolutionHeight and upscales the result to the view rect, instead of rendering at the window's native resolution. Takes effect only when this scene is the Engine main scene; scenes added as layers always render at native resolution. Letterboxing, input mapping, and object coordinates keep following the canvas and scaling mode. In the editor, the fixed resolution is applied during play mode only. Toggling at runtime rebuilds the scene's render pipelines, which may cause a brief hitch — prefer changing the size instead. See Multiple Resolutions.

scene.setFixedResolutionSize(320, 180);
scene.setFixedResolutionFilter(TextureFilter::NEAREST);
scene.setFixedResolutionEnabled(true);

scene:setFixedResolutionSize(320, 180)
scene.fixedResolutionFilter = TextureFilter.NEAREST
scene.fixedResolutionEnabled = true

fixedResolutionWidth, fixedResolutionHeight¶

• Setters: void setFixedResolutionWidth(unsigned int width), void setFixedResolutionHeight(unsigned int height), void setFixedResolutionSize(unsigned int width, unsigned int height)
• Getters: unsigned int getFixedResolutionWidth() const, unsigned int getFixedResolutionHeight() const

The internal render resolution in pixels used when fixedResolutionEnabled is on. Can be changed at any time — the internal buffer is recreated on the next frame with no interruption, which makes render-scale options and dynamic resolution scaling cheap. Keep the aspect ratio equal to the canvas aspect ratio to avoid non-square pixels. Defaults 640 × 360.

fixedResolutionFilter¶

• Setter: void setFixedResolutionFilter(TextureFilter filter)
• Getter: TextureFilter getFixedResolutionFilter() const

Sampling filter used when the fixed-resolution image is upscaled to the view rect: TextureFilter::NEAREST (default) keeps hard pixel edges for a pixel-art look; TextureFilter::LINEAR interpolates smoothly, which suits fixed resolution used purely as a performance measure.

defaultMeshShader¶

• Setter: void setDefaultMeshShader(const std::string& path)
• Getter: const std::string& getDefaultMeshShader() const

Scene-wide custom shader for Mesh components. The value is a project-relative base path to a forked shader (for example "shaders/myMesh", resolving to .vert/.frag), or "a.vert|b.frag" for separately named files. Every Mesh whose own custom shader is empty uses it; an empty string (default) means the engine built-in. A shader assigned on the component always takes priority. Changing the value reloads the affected meshes. See Custom Shaders — Scene default shaders.

scene.setDefaultMeshShader("shaders/toon");

scene.defaultMeshShader = "shaders/toon"

defaultUIShader¶

• Setter: void setDefaultUIShader(const std::string& path)
• Getter: const std::string& getDefaultUIShader() const

Scene-wide custom shader for UI components. Same semantics as defaultMeshShader.

defaultSkyShader¶

• Setter: void setDefaultSkyShader(const std::string& path)
• Getter: const std::string& getDefaultSkyShader() const

Scene-wide custom shader for the Sky component. Same semantics as defaultMeshShader.

defaultPointsShader¶

• Setter: void setDefaultPointsShader(const std::string& path)
• Getter: const std::string& getDefaultPointsShader() const

Scene-wide custom shader for Points components. Same semantics as defaultMeshShader.

defaultLinesShader¶

• Setter: void setDefaultLinesShader(const std::string& path)
• Getter: const std::string& getDefaultLinesShader() const

Scene-wide custom shader for Lines components. Same semantics as defaultMeshShader.

enableUIEvents¶

• Setter: void setEnableUIEvents(UIEventState enableUIEvents)
• Getter: UIEventState getEnableUIEvents() const

Per-scene override for UI event routing. See UIEventState.

Method details¶

load¶

• void load()

Initializes the scene subsystems. Called automatically by the engine when the scene is added via Engine::setScene or Engine::addSceneLayer. Only call manually when managing scenes outside the engine lifecycle.

destroy¶

• void destroy()

Tears down all subsystems and destroys every entity in the scene. Called automatically by the engine when the scene is removed from the stack.

draw¶

• void draw()

Triggers a render pass for this scene. Normally called by the engine each frame; use only for custom render pipelines.

update¶

• void update(double dt)

Runs one variable-step update for all subscribed systems. dt is the frame delta in seconds. Normally called by the engine.

fixedUpdate¶

• void fixedUpdate(double dt)

Runs one fixed-step update for physics and other time-sensitive systems. dt equals Engine::updateTime. Normally called by the engine.

setCamera¶

• void setCamera(Camera* camera)
• void setCamera(Entity camera)

Sets the active camera for this scene. Only one camera can be active at a time. Pass the Camera object or its underlying Entity handle.

Camera cam(&scene);
cam.activate();           // equivalent shortcut
// or:
scene.setCamera(&cam);

local cam = Camera(scene)
scene:setCamera(cam)

getCamera¶

• Entity getCamera() const

Returns the entity handle of the currently active camera.

setBackgroundColor¶

• void setBackgroundColor(Vector4 color)
• void setBackgroundColor(float red, float green, float blue)
• void setBackgroundColor(float red, float green, float blue, float alpha)

Sets the clear color used before rendering the scene each frame.

scene.setBackgroundColor(0.05f, 0.05f, 0.1f, 1.0f);

scene:setBackgroundColor(0.05, 0.05, 0.1, 1.0)

setLightState¶

• void setLightState(LightState state)
• LightState getLightState() const

Overrides automatic lighting detection. See LightState.

setGlobalIllumination¶

• void setGlobalIllumination(float intensity, Vector3 color)
• void setGlobalIllumination(float intensity)
• void setGlobalIllumination(Vector3 color)

Sets the ambient (global illumination) light for the scene. Intensity scales brightness; color tints the light. Flat-shaded or unlit materials are not affected.

scene.setGlobalIllumination(0.3f, Vector3(1.0f, 0.95f, 0.9f));

scene:setGlobalIllumination(0.3, Vector3(1.0, 0.95, 0.9))

setAmbientLight2D¶

• void setAmbientLight2D(float intensity, Vector3 color)
• void setAmbientLight2D(float intensity)
• void setAmbientLight2D(Vector3 color)

Sets the ambient light for the 2D lighting path (see Light2D). Every Light2D adds on top of this base level, so dim the ambient to make 2D lights visible. Separate from setGlobalIllumination, which drives the 3D PBR ambient.

scene.setAmbientLight2D(0.15f, Vector3(0.9f, 0.9f, 1.0f)); // dark, blueish night

scene:setAmbientLight2D(0.15, Vector3(0.9, 0.9, 1.0)) -- dark, blueish night

enableUIEvents¶

• void enableUIEvents()

Shorthand for setEnableUIEvents(UIEventState::ENABLED).

isEnableUIEvents¶

• bool isEnableUIEvents() const

Returns true if UI events are enabled for this scene (either via explicit ENABLED state or engine default).

canReceiveUIEvents¶

• bool canReceiveUIEvents()

Returns true if this scene is currently the topmost scene that is able to receive UI pointer events. The engine calls this internally to route events to the correct scene layer.

updateCameraSize¶

• void updateCameraSize()

Recalculates the active camera's projection to match the current canvas size. Called automatically when the canvas changes; call manually after resizing the viewport from script.

removeSubscriptionsByTag¶

• void removeSubscriptionsByTag(const std::string& substring)

Removes all event subscriptions whose tag string contains substring. Used to clean up callbacks belonging to a destroyed script or component.