Spatial And Rendering Components

Last verified: 2026-06-17

TransformComponent

Use Transform to place an entity in the world. Position, rotation, and scale are the base for renderers, cameras, physics, particles, decals, terrain, water, world text, and spatial audio.

Gotcha: if you add a dependent component such as Renderable or Collider to an entity without Transform, the engine adds Transform automatically.

RenderableComponent

Use Renderable for visible primitives and mesh assets. It controls asset references, primitive shape, visibility, material reference, bounds, labels, roles, and draw-distance behavior.

Gotcha: material color changes belong in MaterialInstanceOverride or material assets, not ad hoc Renderable fields.

SpatialCaptureComponent

Use Spatial Capture for placed imported captures such as .splat, .ksplat, or point-cloud source assets that already exist as backend ProjectAssets with rendering.spatialCapture metadata. It controls the capture asset reference, source variant, visibility, safe point/splat presentation, and draw-distance behavior.

Gotcha: a rendered capture is only renderable. It becomes navigable or playable only when backend proxy and semantic-anchor receipts prove those capabilities.

MaterialInstanceOverrideComponent

Use Material Instance Override for per-entity visual variation: color tint, opacity multiplier, and emissive intensity multiplier.

Gotcha: it is most useful with Renderable material state, but the engine does not auto-add Renderable because that would invent a mesh or material target.

AnimationStateComponent

Use Animation State to select a clip, playback mode, speed, start time, and transition source for a renderable asset that has compatible animation clips.

Gotcha: the component is valid without an animated mesh, but visible playback requires a loaded asset with the named clip.

HairComponent

Use Hair for render-oriented groom bindings on characters or props. It controls groom asset references, binding keys, target entity binding, material overrides, representation/shadow preferences, simulation intent, and budget hints.

Gotcha: Hair is rendering state. Groom import, conditioning, and high-fidelity simulation proof live in the asset/rendering pipeline, not this component alone.

CameraComponent

Use Camera for runtime viewpoints. It supports perspective or orthographic projection, priority, active state, follow/look-at targets, viewport rectangles, clipping planes, clear behavior, exposure/tone mapping, and shake.

Gotcha: the highest-priority active camera wins. Add Transform to control camera pose; the engine auto-adds it if missing.

LightComponent

Use Light for directional, point, spot, area, hemisphere, and ambient lighting. Fields control mode, enabled state, color, intensity, shadow behavior, falloff, spot shape, area size, radius, and IES profile.

Gotcha: ambient lights still receive Transform through the normal dependency policy so component behavior is consistent.

ReflectionProbeComponent

Use Reflection Probe for local reflected environment lighting. It is an advanced component with enabled state, shape, radius/size, intensity, and cubemap key.

Gotcha: probe baking/binding depends on renderer support and the cubemap asset key.

LocalEnvironmentVolumeComponent

Use Local Environment Volume to override the global environment inside a bounded region: sealed interiors, caves, biome and weather zones, or a patch of denser fog. It is a sphere or box with a strict integer priority, a blend distance, and a sparse set of per-field overrides for fog density, ambient intensity, aerial haze, and exposure-compensation bias. Fields you do not override pass through from the global default unchanged, and the override fades to the global as the camera nears the boundary over the blend distance.

Gotcha: two overlapping volumes must not share the same priority because the blend order would be undefined; the inspector flags an equal-priority overlap so you can give one a distinct priority. A volume can push an exposure-compensation bias but cannot replace the tonemapper or synthesize a second sky.

TerrainComponent

Use Terrain for large authored surfaces. It controls dimensions, chunking, segment count, height range, heightmap/splat/material keys, texture layers, LOD distances, triplanar mode, shadow behavior, collision proxy, and fallback color.

Gotcha: Terrain is advanced because it affects rendering, asset loading, and optional collision proxy data.

WaterComponent

Use Water for water planes and surfaces. It controls size, level, colors, opacity, transparency, wave profile, reflection/refraction modes, normal map, shore foam, and depth blending.

Gotcha: use Transform for placement and surfaceLevel for water height behavior.

DecalComponent

Use Decal for projected marks, signs, scuffs, and other localized surface detail. It controls dimensions, projection volume, color, opacity, texture key, projection depth, blend mode, fade distance, and atlas slot.

Gotcha: decals are advanced because projection volume and render order matter.

ParticleEmitterComponent

Use Particle Emitter for effects such as sparks, dust, smoke, pickups, or ambient motion. It controls enabled state, max particles, particle size, color, opacity, lifetime, emission rate, random seed, bounds, and optional texture.

Gotcha: emission starts at the entity Transform and should be removed or disabled when effects are no longer needed.

TextRenderableComponent

Use Text Renderable for world labels and dynamic readouts. It controls text, text source, projection key, color, font size, alignment, anchor, offset, billboard mode, depth behavior, fade distance, background/outline styling, and optional lifetime.

Gotcha: long text can be hard to read in world space; prefer concise labels.