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
`ui`	object[]		React UI roots (canvases) attached to the scene graph (A1)

`environment`

Scene-level environment settings

Field	Type	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

`ambient`

Global ambient light

Field	Type	Req	Description
`color`	string	✓	Ambient light color
`intensity`	number	✓	Ambient light intensity

`fog`

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`

Tone mapping configuration

Field	Type	Req	Description
`mode`	”none” \	“linear” \	“reinhard” \
`exposure`	number		Exposure level

`postProcessing`

Post-processing effects (bloom, vignette)

Field	Type	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`

Bloom glow effect

Field	Type	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`

Screen-edge darkening effect

Field	Type	Description
`enabled`	boolean	Enable vignette effect
`darkness`	number	Vignette darkness intensity
`offset`	number	Vignette offset from center

`brightnessContrast`

Brightness and contrast color adjustment

Field	Type	Description
`enabled`	boolean	Enable brightness/contrast adjustment
`brightness`	number	Brightness adjustment (-1 to 1)
`contrast`	number	Contrast adjustment (-1 to 1)

`hueSaturation`

Hue rotation and saturation color adjustment

Field	Type	Description
`enabled`	boolean	Enable hue/saturation adjustment
`hue`	number	Hue rotation in radians
`saturation`	number	Saturation adjustment (-1 to 1)

`sepia`

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`

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`

Lens chromatic aberration (color fringing at screen edges)

Field	Type	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`

Barrel/pincushion lens distortion

Field	Type	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`

Physically-based depth of field with bokeh blur

Field	Type	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`

Tilt-shift miniature-world blur effect

Field	Type	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

`noise`

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`

Horizontal scanline overlay (CRT monitor look)

Field	Type	Req	Description
`enabled`	boolean		Enable scanline overlay
`density`	number		Number of scanlines across screen height

`dotScreen`

Halftone dot pattern (newspaper/comic look)

Field	Type	Description
`enabled`	boolean	Enable dot screen halftone
`angle`	number	Pattern angle in radians
`scale`	number	Pattern dot scale

`grid`

Visible grid pattern overlay

Field	Type	Description
`enabled`	boolean	Enable grid overlay
`scale`	number	Grid cell scale
`lineWidth`	number	Grid line width

`pixelation`

Reduce resolution for pixel-art / mosaic effect

Field	Type	Req	Description
`enabled`	boolean		Enable pixelation
`granularity`	number		Pixel size (higher = more pixelated)

`glitch`

Random digital glitch artifacts (block displacement, color shifting)

Field	Type	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`

Expanding spherical distortion wave from a point

Field	Type	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

`smaa`

Subpixel Morphological Anti-Aliasing

Field	Type	Req	Description
`enabled`	boolean		Enable SMAA anti-aliasing
`preset`	”low” \	“medium” \	“high” \

`ssao`

Screen-space ambient occlusion (darken creases and crevices)

Field	Type	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

`n8ao`

High-quality ambient occlusion (N8AO — alternative to SSAO)

Field	Type	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`

Volumetric light shafts from a light source entity

Field	Type	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`

Highlight entities matching tags with colored outlines

Field	Type	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

`ssr`

Screen-space reflections for reflective/glossy surfaces

Field	Type	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)

`ssgi`

Screen-space global illumination (indirect lighting bounce)

Field	Type	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`

Per-object motion blur from camera and object movement

Field	Type	Description
`enabled`	boolean	Enable motion blur
`intensity`	number	Motion blur intensity
`jitter`	number	Sample jitter amount
`samples`	number	Number of blur samples

`navigation`

Navigation mesh bake settings

Field	Type	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`

Physics world settings

Field	Type	Req	Description
`collisionLayers`	string[]		Named collision layers (up to 16). Index = bit position in collision bitmasks

`ui`

A UI root canvas attached to the scene graph (A1/A3)

Field	Type	Req	Description
`id`	string		Stable unique node id. Auto-generated if omitted
`name`	string	✓	Human-readable node name (shown in the UI hierarchy)
`kind`	”canvas”	✓	A UI root is always a canvas
`visible`	boolean		Whether the node renders
`locked`	boolean		Prevent selection/editing in the editor
`tags`	string[]		Arbitrary tags for runtime queries
`layout`	object		Layout/anchor/flex properties (D/E)
`style`	object		Base style (F1/F2)
`states`	object		Per-state style overrides (F3)
`variant`	string		Named theme variant to apply (F4)
`props`	object		Control/component props (text, value, placeholder, min/max, …). May be bound (G)
`bindings`	object		Explicit prop/style bindings keyed by target path (G1/G2)
`events`	object		Event wiring: eventName (“onClick”) -> game handler/action id (J2)
`component`	string		For kind:“component” — referenced React component name or saved UI prefab path (H)
`repeat`	object		Make this node a data-bound list template (G3)
`space`	”screen” \	“world-tracked”
`trackEntity`	string		Entity id this canvas is screen-tracked to (world-tracked space) (A3)
`scaling`	object		Responsive scaling config (I1/I2)
`theme`	object		Inline theme resource (F1)
`themeRef`	string		Path to a shared .uitheme.json theme asset (F1)
`locale`	string		Active locale for localized text (G5)
`children`	object[]		Child UI nodes (A2)

`layout`

Layout/anchor/flex properties (D/E)

Field	Type	Req	Description
`position`	”flow” \	“absolute”
`anchor`	object		Anchor fractions (absolute/anchored nodes) (D1)
`offset`	object		Pixel offsets from anchors (absolute/anchored) (D1)
`pivot`	any[]		Pivot/alignment point (0..1 each axis) for rotation/scale/position origin (D3)
`width`	number \	string
`height`	number \	string
`minWidth`	number \	string
`maxWidth`	number \	string
`minHeight`	number \	string
`maxHeight`	number \	string
`aspectRatio`	number		Locked width/height ratio (AspectRatio container)
`direction`	”row” \	“column” \	“row-reverse” \
`justify`	”start” \	“center” \	“end” \
`align`	”start” \	“center” \	“end” \
`wrap`	boolean		Wrap children to the next line (Wrap/Flow container) (E3)
`gap`	number		Gap (px) between children
`columns`	number		Column count for grid containers (E2)
`grow`	number		Flex grow factor (expand to fill / stretch ratio)
`shrink`	number		Flex shrink factor
`basis`	number \	string
`alignSelf`	”auto” \	“start” \	“center” \
`padding`	number[]		Padding [top,right,bottom,left] in px (MarginContainer / slot padding)
`margin`	number[]		Margin [top,right,bottom,left] in px
`zIndex`	number		Stacking order within the parent (Overlay/Canvas z) (E3)
`overflow`	”visible” \	“hidden” \	“scroll” \

`anchor`

Anchor fractions (absolute/anchored nodes) (D1)

Field	Type	Req	Description
`left`	number	✓	Left-edge anchor as a fraction of parent width (0=left, 1=right)
`top`	number	✓	Top-edge anchor as a fraction of parent height (0=top, 1=bottom)
`right`	number	✓	Right-edge anchor as a fraction of parent width
`bottom`	number	✓	Bottom-edge anchor as a fraction of parent height

`offset`

Pixel offsets from anchors (absolute/anchored) (D1)

Field	Type	Req	Description
`left`	number	✓	Left offset in px from the left anchor
`top`	number	✓	Top offset in px from the top anchor
`right`	number	✓	Right offset in px from the right anchor
`bottom`	number	✓	Bottom offset in px from the bottom anchor

`style`

Base style (F1/F2)

Field	Type	Req	Description
`backgroundColor`	string \	number
`backgroundImage`	string		Background image asset ref or url (A5)
`backgroundSize`	string		Background sizing (e.g. “cover”,“9-slice”)
`color`	string \	number
`fontSize`	string \	number
`fontFamily`	string		Font family or font asset ref (A5)
`fontWeight`	string \	number
`fontStyle`	string		Font style (normal/italic)
`textAlign`	”left” \	“center” \	“right” \
`lineHeight`	string \	number
`letterSpacing`	string \	number
`opacity`	number		Opacity 0..1
`borderRadius`	string \	number
`borderWidth`	string \	number
`borderColor`	string \	number
`borderStyle`	”solid” \	“dashed” \	“dotted” \
`boxShadow`	string		Box shadow CSS value
`sliceInset`	number[]		9-slice inset [top,right,bottom,left] px for backgroundImage scaling (F4)
`cursor`	string		Cursor over this element (e.g. “pointer”)
`transition`	string		CSS-like transition for state changes (F6)

`states`

Per-state style overrides (F3)

Field	Type	Description
`hover`	object	Style applied on pointer hover
`pressed`	object	Style applied while pressed/active
`disabled`	object	Style applied when disabled
`focus`	object	Style applied when focused (keyboard/gamepad)

`hover`

Style applied on pointer hover

Field	Type	Req	Description
`backgroundColor`	string \	number
`backgroundImage`	string		Background image asset ref or url (A5)
`backgroundSize`	string		Background sizing (e.g. “cover”,“9-slice”)
`color`	string \	number
`fontSize`	string \	number
`fontFamily`	string		Font family or font asset ref (A5)
`fontWeight`	string \	number
`fontStyle`	string		Font style (normal/italic)
`textAlign`	”left” \	“center” \	“right” \
`lineHeight`	string \	number
`letterSpacing`	string \	number
`opacity`	number		Opacity 0..1
`borderRadius`	string \	number
`borderWidth`	string \	number
`borderColor`	string \	number
`borderStyle`	”solid” \	“dashed” \	“dotted” \
`boxShadow`	string		Box shadow CSS value
`sliceInset`	number[]		9-slice inset [top,right,bottom,left] px for backgroundImage scaling (F4)
`cursor`	string		Cursor over this element (e.g. “pointer”)
`transition`	string		CSS-like transition for state changes (F6)

`pressed`

Style applied while pressed/active

Field	Type	Req	Description
`backgroundColor`	string \	number
`backgroundImage`	string		Background image asset ref or url (A5)
`backgroundSize`	string		Background sizing (e.g. “cover”,“9-slice”)
`color`	string \	number
`fontSize`	string \	number
`fontFamily`	string		Font family or font asset ref (A5)
`fontWeight`	string \	number
`fontStyle`	string		Font style (normal/italic)
`textAlign`	”left” \	“center” \	“right” \
`lineHeight`	string \	number
`letterSpacing`	string \	number
`opacity`	number		Opacity 0..1
`borderRadius`	string \	number
`borderWidth`	string \	number
`borderColor`	string \	number
`borderStyle`	”solid” \	“dashed” \	“dotted” \
`boxShadow`	string		Box shadow CSS value
`sliceInset`	number[]		9-slice inset [top,right,bottom,left] px for backgroundImage scaling (F4)
`cursor`	string		Cursor over this element (e.g. “pointer”)
`transition`	string		CSS-like transition for state changes (F6)

`disabled`

Style applied when disabled

Field	Type	Req	Description
`backgroundColor`	string \	number
`backgroundImage`	string		Background image asset ref or url (A5)
`backgroundSize`	string		Background sizing (e.g. “cover”,“9-slice”)
`color`	string \	number
`fontSize`	string \	number
`fontFamily`	string		Font family or font asset ref (A5)
`fontWeight`	string \	number
`fontStyle`	string		Font style (normal/italic)
`textAlign`	”left” \	“center” \	“right” \
`lineHeight`	string \	number
`letterSpacing`	string \	number
`opacity`	number		Opacity 0..1
`borderRadius`	string \	number
`borderWidth`	string \	number
`borderColor`	string \	number
`borderStyle`	”solid” \	“dashed” \	“dotted” \
`boxShadow`	string		Box shadow CSS value
`sliceInset`	number[]		9-slice inset [top,right,bottom,left] px for backgroundImage scaling (F4)
`cursor`	string		Cursor over this element (e.g. “pointer”)
`transition`	string		CSS-like transition for state changes (F6)

`focus`

Style applied when focused (keyboard/gamepad)

Field	Type	Req	Description
`backgroundColor`	string \	number
`backgroundImage`	string		Background image asset ref or url (A5)
`backgroundSize`	string		Background sizing (e.g. “cover”,“9-slice”)
`color`	string \	number
`fontSize`	string \	number
`fontFamily`	string		Font family or font asset ref (A5)
`fontWeight`	string \	number
`fontStyle`	string		Font style (normal/italic)
`textAlign`	”left” \	“center” \	“right” \
`lineHeight`	string \	number
`letterSpacing`	string \	number
`opacity`	number		Opacity 0..1
`borderRadius`	string \	number
`borderWidth`	string \	number
`borderColor`	string \	number
`borderStyle`	”solid” \	“dashed” \	“dotted” \
`boxShadow`	string		Box shadow CSS value
`sliceInset`	number[]		9-slice inset [top,right,bottom,left] px for backgroundImage scaling (F4)
`cursor`	string		Cursor over this element (e.g. “pointer”)
`transition`	string		CSS-like transition for state changes (F6)

`repeat`

Make this node a data-bound list template (G3)

Field	Type	Req	Description
`items`	object	✓	Binding to the collection to repeat over (G3)
`as`	string	✓	Alias name each item is exposed under inside the template (e.g. “item”)
`keyPath`	string		Per-item key path for stable per-instance ids/selection (overcomes shared-OID) (G3)

`items`

Binding to the collection to repeat over (G3)

Field	Type	Req	Description
`source`	string	✓	Dotted path into the game data source, e.g. “player.health” or “settings.volume”
`mode`	”one-way” \	“two-way”
`transform`	string		Optional named transform/formatter applied to the value before display
`fallback`	string \	number

`scaling`

Responsive scaling config (I1/I2)

Field	Type	Req	Description
`referenceWidth`	number	✓	Design/reference resolution width (I1)
`referenceHeight`	number	✓	Design/reference resolution height (I1)
`mode`	”scale-with-size” \	“constant-pixel” \	“constant-physical”
`aspect`	”expand” \	“keep” \	“keep-width” \
`match`	number		0..1 width/height match factor for scale-with-size mode

`theme`

Inline theme resource (F1)

Field	Type	Req	Description
`name`	string	✓	Theme name
`tokens`	object	✓	Design tokens: tokenName -> value, referenced in styles as “$tokenName” (F1)
`variants`	object		Named style variations of a base type (F4 / type variations)

`children`

Field	Type	Req	Description
`id`	string		Stable unique node id. Auto-generated if omitted
`name`	string	✓	Human-readable node name (shown in the UI hierarchy)
`kind`	”canvas” \	“box” \	“grid” \
`visible`	boolean		Whether the node renders
`locked`	boolean		Prevent selection/editing in the editor
`tags`	string[]		Arbitrary tags for runtime queries
`layout`	object		Layout/anchor/flex properties (D/E)
`style`	object		Base style (F1/F2)
`states`	object		Per-state style overrides (F3)
`variant`	string		Named theme variant to apply (F4)
`props`	object		Control/component props (text, value, placeholder, min/max, …). May be bound (G)
`bindings`	object		Explicit prop/style bindings keyed by target path (G1/G2)
`events`	object		Event wiring: eventName (“onClick”) -> game handler/action id (J2)
`component`	string		For kind:“component” — referenced React component name or saved UI prefab path (H)
`repeat`	object		Make this node a data-bound list template (G3)
`children`	object[]		Child UI nodes (A2)