Scene Schema
Scene file (.vscn.json)
| Field | Type | Req | Description |
|---|---|---|---|
version | number | ✓ | Scene file format version |
name | string | ✓ | Scene display name |
environment | object | Scene-level environment settings | |
entities | object[] | ✓ | Top-level entities in the scene |
environment
Section titled “environment”Scene-level environment settings
| Field | Type | Req | Description |
|---|---|---|---|
background | string | Background color as CSS hex string | |
ambient | object | Global ambient light | |
fog | object | Distance fog settings | |
skybox | string | Path to HDR/EXR skybox environment map | |
envMapIntensity | number | Environment map reflection intensity multiplier | |
toneMapping | object | Tone mapping configuration | |
postProcessing | object | Post-processing effects (bloom, vignette) | |
navigation | object | Navigation mesh bake settings | |
physics | object | Physics world settings | |
rendering | object | Scene-level render feature toggles (auto-batching, culling, LOD, shadows, etc.). Omit a field to inherit the engine default. Derived from the render-feature registry. |
ambient
Section titled “ambient”Global ambient light
| Field | Type | Req | Description |
|---|---|---|---|
color | string | ✓ | Ambient light color |
intensity | number | ✓ | Ambient light intensity |
Distance fog settings
| Field | Type | Req | Description |
|---|---|---|---|
type | ”linear” \ | “exponential” | ✓ |
color | string | ✓ | Fog color |
near | number | Fog start distance (linear only) | |
far | number | Fog end distance (linear only) | |
density | number | Fog density (exponential only) |
toneMapping
Section titled “toneMapping”Tone mapping configuration
| Field | Type | Req | Description |
|---|---|---|---|
mode | ”none” \ | “linear” \ | “reinhard” \ |
exposure | number | Exposure level |
postProcessing
Section titled “postProcessing”Post-processing effects (bloom, vignette)
| Field | Type | Req | Description |
|---|---|---|---|
bloom | object | Bloom glow effect | |
vignette | object | Screen-edge darkening effect | |
brightnessContrast | object | Brightness and contrast color adjustment | |
hueSaturation | object | Hue rotation and saturation color adjustment | |
sepia | object | Warm sepia tone for vintage photograph look | |
colorDepth | object | Reduce color bit depth for posterized/banded look | |
chromaticAberration | object | Lens chromatic aberration (color fringing at screen edges) | |
lensDistortion | object | Barrel/pincushion lens distortion | |
depthOfField | object | Physically-based depth of field with bokeh blur | |
tiltShift | object | Tilt-shift miniature-world blur effect | |
noise | object | Random per-pixel noise overlay (film grain) | |
scanline | object | Horizontal scanline overlay (CRT monitor look) | |
dotScreen | object | Halftone dot pattern (newspaper/comic look) | |
grid | object | Visible grid pattern overlay | |
pixelation | object | Reduce resolution for pixel-art / mosaic effect | |
glitch | object | Random digital glitch artifacts (block displacement, color shifting) | |
shockWave | object | Expanding spherical distortion wave from a point | |
smaa | object | Subpixel Morphological Anti-Aliasing | |
ssao | object | Screen-space ambient occlusion (darken creases and crevices) | |
n8ao | object | High-quality ambient occlusion (N8AO — alternative to SSAO) | |
godRays | object | Volumetric light shafts from a light source entity | |
outline | object | Highlight entities matching tags with colored outlines | |
ssr | object | Screen-space reflections for reflective/glossy surfaces | |
ssgi | object | Screen-space global illumination (indirect lighting bounce) | |
motionBlur | object | Per-object motion blur from camera and object movement |
Bloom glow effect
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable bloom effect | |
intensity | number | Bloom intensity multiplier | |
luminanceThreshold | number | Minimum luminance to trigger bloom | |
luminanceSmoothing | number | Smoothing applied to luminance threshold |
vignette
Section titled “vignette”Screen-edge darkening effect
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable vignette effect | |
darkness | number | Vignette darkness intensity | |
offset | number | Vignette offset from center |
brightnessContrast
Section titled “brightnessContrast”Brightness and contrast color adjustment
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable brightness/contrast adjustment | |
brightness | number | Brightness adjustment (-1 to 1) | |
contrast | number | Contrast adjustment (-1 to 1) |
hueSaturation
Section titled “hueSaturation”Hue rotation and saturation color adjustment
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable hue/saturation adjustment | |
hue | number | Hue rotation in radians | |
saturation | number | Saturation adjustment (-1 to 1) |
Warm sepia tone for vintage photograph look
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable sepia tone | |
intensity | number | Sepia effect intensity (0 to 1) |
colorDepth
Section titled “colorDepth”Reduce color bit depth for posterized/banded look
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable color depth reduction | |
bits | number | Number of color bits per channel (1–16) |
chromaticAberration
Section titled “chromaticAberration”Lens chromatic aberration (color fringing at screen edges)
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable chromatic aberration | |
offsetX | number | Horizontal color fringe offset | |
offsetY | number | Vertical color fringe offset | |
radialModulation | boolean | Increase effect toward screen edges | |
modulationOffset | number | Radial modulation offset from center |
lensDistortion
Section titled “lensDistortion”Barrel/pincushion lens distortion
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable lens distortion | |
distortionX | number | Horizontal barrel/pincushion distortion | |
distortionY | number | Vertical barrel/pincushion distortion | |
focalLengthX | number | Horizontal focal length | |
focalLengthY | number | Vertical focal length | |
skew | number | Lens skew angle |
depthOfField
Section titled “depthOfField”Physically-based depth of field with bokeh blur
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable depth of field | |
worldFocusDistance | number | Focus distance in world units | |
worldFocusRange | number | Focus range in world units | |
bokehScale | number | Bokeh blur scale | |
focalLength | number | Camera focal length in mm |
tiltShift
Section titled “tiltShift”Tilt-shift miniature-world blur effect
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable tilt-shift effect | |
offset | number | Focus band offset from center | |
rotation | number | Focus band rotation in radians | |
focusArea | number | Focus band width (0–1) | |
feather | number | Blur falloff smoothness |
Random per-pixel noise overlay (film grain)
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable film grain noise | |
premultiply | boolean | Multiply noise with input color instead of adding |
scanline
Section titled “scanline”Horizontal scanline overlay (CRT monitor look)
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable scanline overlay | |
density | number | Number of scanlines across screen height |
dotScreen
Section titled “dotScreen”Halftone dot pattern (newspaper/comic look)
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable dot screen halftone | |
angle | number | Pattern angle in radians | |
scale | number | Pattern dot scale |
Visible grid pattern overlay
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable grid overlay | |
scale | number | Grid cell scale | |
lineWidth | number | Grid line width |
pixelation
Section titled “pixelation”Reduce resolution for pixel-art / mosaic effect
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable pixelation | |
granularity | number | Pixel size (higher = more pixelated) |
glitch
Section titled “glitch”Random digital glitch artifacts (block displacement, color shifting)
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable digital glitch effect | |
delayX | number | Minimum delay between glitches (seconds) | |
delayY | number | Maximum delay between glitches (seconds) | |
durationX | number | Minimum glitch duration (seconds) | |
durationY | number | Maximum glitch duration (seconds) | |
strengthX | number | Minimum glitch strength | |
strengthY | number | Maximum glitch strength | |
columns | number | Number of glitch columns | |
ratio | number | Glitch ratio (0–1) |
shockWave
Section titled “shockWave”Expanding spherical distortion wave from a point
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable shock wave distortion | |
speed | number | Wave propagation speed | |
maxRadius | number | Maximum wave radius | |
waveSize | number | Width of the distortion wave | |
amplitude | number | Distortion strength | |
positionX | number | Wave origin X in world space | |
positionY | number | Wave origin Y in world space | |
positionZ | number | Wave origin Z in world space |
Subpixel Morphological Anti-Aliasing
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable SMAA anti-aliasing | |
preset | ”low” \ | “medium” \ | “high” \ |
Screen-space ambient occlusion (darken creases and crevices)
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable screen-space ambient occlusion | |
radius | number | Occlusion sampling radius | |
intensity | number | Occlusion intensity multiplier | |
bias | number | Depth bias to reduce self-occlusion artifacts | |
samples | number | Number of occlusion samples per pixel | |
rings | number | Number of spiral sample rings | |
fade | number | Distance at which occlusion fades out | |
color | string | Occlusion tint color as CSS hex |
High-quality ambient occlusion (N8AO — alternative to SSAO)
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable N8AO ambient occlusion | |
aoSamples | number | Number of AO samples (default 16) | |
aoRadius | number | AO sampling radius in world units | |
intensity | number | AO intensity multiplier | |
denoiseSamples | number | Number of denoise samples | |
denoiseRadius | number | Denoise blur radius | |
distanceFalloff | number | AO distance falloff | |
screenSpaceRadius | boolean | Use screen-space radius instead of world-space | |
color | string | AO tint color as CSS hex | |
halfRes | boolean | Render AO at half resolution for performance |
godRays
Section titled “godRays”Volumetric light shafts from a light source entity
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable god rays | |
sourceEntity | string | Entity ID of the light source mesh | |
density | number | Ray density | |
decay | number | Ray intensity decay along distance | |
weight | number | Ray weight / brightness | |
exposure | number | Overall god ray exposure | |
samples | number | Number of ray-march samples |
outline
Section titled “outline”Highlight entities matching tags with colored outlines
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable outline effect | |
tags | string[] | Entity tags to outline | |
edgeStrength | number | Outline edge thickness / strength | |
pulseSpeed | number | Outline pulse animation speed (0 = no pulse) | |
visibleEdgeColor | string | Color of visible edges as CSS hex | |
hiddenEdgeColor | string | Color of hidden/occluded edges as CSS hex | |
xRay | boolean | Show outline through occluding objects |
Screen-space reflections for reflective/glossy surfaces
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable screen-space reflections | |
intensity | number | Reflection intensity | |
exponent | number | Reflection falloff exponent | |
distance | number | Maximum reflection ray distance | |
thickness | number | Depth thickness for hit testing | |
maxRoughness | number | Maximum roughness for reflections (0–1) |
Screen-space global illumination (indirect lighting bounce)
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable screen-space global illumination | |
intensity | number | Indirect light intensity | |
distance | number | Maximum GI ray distance | |
thickness | number | Depth thickness for hit testing | |
maxRoughness | number | Maximum roughness for GI (0–1) |
motionBlur
Section titled “motionBlur”Per-object motion blur from camera and object movement
| Field | Type | Req | Description |
|---|---|---|---|
enabled | boolean | Enable motion blur | |
intensity | number | Motion blur intensity | |
jitter | number | Sample jitter amount | |
samples | number | Number of blur samples |
navigation
Section titled “navigation”Navigation mesh bake settings
| Field | Type | Req | Description |
|---|---|---|---|
cellSize | number | Navmesh voxel cell size (smaller = more detail, slower bake) | |
cellHeight | number | Navmesh voxel cell height | |
walkableSlopeAngle | number | Maximum slope angle (degrees) agents can walk on | |
walkableHeight | number | Minimum ceiling height for walkable areas (in voxels) | |
walkableClimb | number | Maximum step height agents can climb (in voxels) | |
walkableRadius | number | Agent radius for navmesh erosion (in voxels) | |
maxEdgeLen | number | Maximum contour edge length in the navmesh | |
maxSimplificationError | number | Maximum deviation for navmesh edge simplification | |
minRegionArea | number | Minimum region area — smaller regions are removed | |
mergeRegionArea | number | Regions smaller than this are merged with neighbors |
physics
Section titled “physics”Physics world settings
| Field | Type | Req | Description |
|---|---|---|---|
collisionLayers | string[] | Named collision layers (up to 16). Index = bit position in collision bitmasks |
rendering
Section titled “rendering”Scene-level render feature toggles (auto-batching, culling, LOD, shadows, etc.). Omit a field to inherit the engine default. Derived from the render-feature registry.
| Field | Type | Req | Description |
|---|---|---|---|
autoBatch | boolean | Automatically batch entities sharing geometry+material into one draw call (InstancedMesh/BatchedMesh) while keeping each Object3D as the handle. The headline perf win; opt out per-entity for custom-shader/skinned meshes. | |
frustumCulling | boolean | Per-instance frustum culling for batched content. | |
lod | boolean | Distance-based geometry swap (LOD) for eligible entities. | |
shadows | boolean | Enable the shadow map. Per-entity cast/receive still applies. | |
postProcessing | boolean | Master switch for the post-processing stack (individual effects nest beneath it). | |
resolutionScale | number | Device-pixel-ratio multiplier (1.0 = native). The cheapest perf dial. | |
antialias | boolean | MSAA via renderer construction. Applies on reload (renderer re-init). | |
backend | ”auto” \ | “webgl” \ | “webgpu” |