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, mesh detail levels, the optional depth prepass, 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

ShaderType¶

The shader types that can have a scene default, as taken by setDefaultShaderUniform. The C++ enum has more values, for the engine's internal passes; Lua exposes only these.

• MESH — Mesh components (defaultMeshShader)
• UI — UI components (defaultUIShader)
• SKYBOX — the Sky component (defaultSkyShader)
• POINTS — Points components (defaultPointsShader)
• LINES — Lines components (defaultLinesShader)
• WATER — the water surface (defaultWaterShader)

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.

meshLodEnabled / meshLodThreshold¶

• meshLodEnabled Setter: void setMeshLodEnabled(bool enabled)
• meshLodEnabled Getter: bool isMeshLodEnabled() const
• meshLodThreshold Setter: void setMeshLodThreshold(float pixels)
• meshLodThreshold Getter: float getMeshLodThreshold() const

Scene-wide mesh detail levels. meshLodEnabled (default false) turns them on: each mesh gets simplified index ranges and draws one once its geometric error projects below meshLodThreshold screen pixels (default 1). While it is off no levels are built, and turning it off frees their GPU buffers. The threshold is clamped to ≥ 0. Changing either takes effect immediately; a mesh can opt out with lodEnabled.

In the editor these are Scene → Mesh Detail (LOD) when nothing is selected.

scene.setMeshLodEnabled(true);
scene.setMeshLodThreshold(2.0f);

scene.meshLodEnabled = true
scene.meshLodThreshold = 2.0

depthPrepassEnabled¶

• Setter: void setDepthPrepassEnabled(bool enabled)
• Getter: bool isDepthPrepassEnabled() const

Writes a depth-only pass for the main camera before the opaque colour draws, so overlapping pixels fail the depth test instead of running the lit shader. Off by default. Toggling it reloads meshes (the prepass pipelines are built with each mesh).

scene.setDepthPrepassEnabled(true);

scene.depthPrepassEnabled = true

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. The fork's uniform values can be set for the whole scene with setDefaultShaderUniform. 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.

defaultWaterShader¶

• Setter: void setDefaultWaterShader(const std::string& path)
• Getter: const std::string& getDefaultWaterShader() const

Scene-wide custom shader for Water components. Same semantics as defaultMeshShader. It covers the water surface only; the underwater fade has no scene default and is forked per water with customUnderwaterShader.

postProcessPasses¶

• Setter: void setPostProcessPasses(const std::vector<PostProcessPass>& passes)
• Getter: const std::vector<PostProcessPass>& getPostProcessPasses() const

Ordered chain of fullscreen post-process passes run over the scene's finished image, on the main camera only. Each entry is a PostProcessPass with the fork to run, an enable flag, and the values of its u_fs_postParams members. In Lua the property is a 1-based sequence of PostProcessPass values (a copy — assign it back to apply changes); build the chain as a sequence (a {...} literal or table.insert), whose array order is the pass order, and note that pass_index arguments such as setPostProcessUniform count from 0.

Setting the chain rebuilds the passes on the next frame, unless only uniform values changed (same shaders and enable flags), in which case the compiled chain is kept and just the values are rewritten. For a single value or pass on a live chain, setPostProcessUniform and setPostProcessPassEnabled are the direct route. See Custom Shaders — Post-process passes.

PostProcessPass sharpen;
sharpen.shader = "shaders/sharpen";
sharpen.setUniform("amount", 0.5f);

scene.setPostProcessPasses({sharpen});

local sharpen = PostProcessPass()
sharpen.shader = "shaders/sharpen"
sharpen:setUniform("amount", 0.5)

scene.postProcessPasses = {sharpen}

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.

setViewCamera¶

• void setViewCamera(Entity camera)

Draws the scene from camera instead of the active camera, while getCamera keeps returning the active one, so scripts, audio, and UI events are unaffected. Effects tied to the main camera (shadows, SSAO, SSR, post-processing, terrain and mesh detail) follow the view camera. Pass NULL_ENTITY to draw from the active camera again. The editor uses it for its detached camera.

getRenderCamera¶

• Entity getRenderCamera() const

Returns the camera the scene is drawn from: the view camera when one is set, otherwise the 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.

setDefaultShaderUniform¶

• void setDefaultShaderUniform(ShaderType type, const std::string& name, const Vector4& value)
• void setDefaultShaderUniform(ShaderType type, const std::string& name, const Vector3& value)
• void setDefaultShaderUniform(ShaderType type, const std::string& name, const Vector2& value)
• void setDefaultShaderUniform(ShaderType type, const std::string& name, float value)
• Vector4 getDefaultShaderUniform(ShaderType type, const std::string& name) const
• bool removeDefaultShaderUniform(ShaderType type, const std::string& name)
• void setDefaultShaderUniforms(ShaderType type, const ShaderUniformValues& values) (C++ only)
• const ShaderUniformValues& getDefaultShaderUniforms(ShaderType type) const (C++ only)

Scene values for the custom blocks (u_vs_customParams / u_fs_customParams) of the scene default shader of type (see ShaderType), by member name. Every component that inherits that default reads them for the members it does not set itself; a value set on the component with setShaderUniform wins. Setting a value only rewrites the uploaded blocks, so it can run every frame. A narrower value leaves the remaining components at zero, and a member with no value on either side reads zero. A type without a scene default is ignored, and a reserved name (time, resolution) logs an error. getDefaultShaderUniform returns the scene's stored value, zero when unset; removeDefaultShaderUniform drops it and returns whether it existed. The values stay when the default shader changes, so a fork with the same member names picks them up. See Custom Shaders — Scene default shaders.

scene.setDefaultShaderUniform(ShaderType::MESH, "exposure", 0.5f);
scene.setDefaultShaderUniform(ShaderType::MESH, "rimColor", Vector4(0.2f, 0.6f, 1.0f, 1.0f));

scene:setDefaultShaderUniform(ShaderType.MESH, "exposure", 0.5)
scene:setDefaultShaderUniform(ShaderType.MESH, "rimColor", Vector4(0.2, 0.6, 1, 1))

setPostProcessUniform¶

• void setPostProcessUniform(unsigned int index, const std::string& name, const Vector4& value)
• void setPostProcessUniform(unsigned int index, const std::string& name, const Vector3& value)
• void setPostProcessUniform(unsigned int index, const std::string& name, const Vector2& value)
• void setPostProcessUniform(unsigned int index, const std::string& name, float value)
• Vector4 getPostProcessUniform(unsigned int index, const std::string& name) const
• bool removePostProcessUniform(unsigned int index, const std::string& name)

Sets one member of the u_fs_postParams block of the pass at index (0 = first pass of postProcessPasses), by member name. Only the uploaded block is rewritten — the chain is not rebuilt — so it can run every frame. A narrower value leaves the remaining components at zero; a member with no value reads zero. An index past the chain, or a reserved name (time, resolution, written by the engine every frame), logs an error and is ignored. getPostProcessUniform returns the stored value, zero when unset; removePostProcessUniform drops it (the member reads zero again) and returns whether it existed.

scene.setPostProcessUniform(0, "amount", 0.8f);
scene.setPostProcessUniform(0, "tintColor", Vector4(1.0f, 0.9f, 0.8f, 1.0f));

scene:setPostProcessUniform(0, "amount", 0.8)
scene:setPostProcessUniform(0, "tintColor", Vector4(1, 0.9, 0.8, 1))

setPostProcessPassEnabled¶

• void setPostProcessPassEnabled(unsigned int index, bool enabled)
• bool isPostProcessPassEnabled(unsigned int index) const

Turns the pass at index on or off. A change rebuilds the chain on the next frame (the compiled shader is kept, so it is cheap, but not something to toggle every frame). An index past the chain logs an error; isPostProcessPassEnabled returns false for it.

scene.setPostProcessPassEnabled(1, false);

scene:setPostProcessPassEnabled(1, false)

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.