@relu-interactives/spatial-ecs

---

@relu-interactives/spatial-ecs / components

components

Classes

Components

Class	Description
AnimationComponent	Animation catalog and runtime state for an entity. Combines clips imported from a model with externally added clips, exposes a state machine for named transitions, and is queried each frame by the animation system to advance mixer time.
AudioComponent	Plays an audio clip from path. Supports both global stereo (positional: false) and 3D positional audio with the configured distance model. Runtime fields (object, audio, isPlaying, isPaused) are recreated when the project loads and are never persisted to saved snapshots.
CameraComponent	Camera entity state. Supports perspective and orthographic projections, a 3d or ar runtime type, and an isDefault flag for the camera that the preview/editor renders through. Field-of-view, near/far, ortho frustum, and zoom are persisted; the live THREE.Camera is recreated when the project loads.
EntityType	Tags an entity with the kind it was created from (cube, sphere, model, directionalLight, etc.). Factories use this to drive kind-specific behavior; the editor inspector uses it to select component editors.
Environment	Scene environment settings: skybox (gradient/color/image), fog (linear/exponential), and gravity vector for the physics world. Singleton-style — attached to one environment entity per scene.
ImageComponent	Renders a 2D image as a textured quad in the scene. Width/height are in world units. Texture loading is handled by the image system, which populates ImageComponent.texture and ImageComponent.object asynchronously.
ImageTarget	Image-tracking target metadata used by AR projects. Holds the source images users uploaded plus the URL of the compiled .mind target file produced by the image-target compiler. Pair with ImageTargetAnchor on child entities that should appear when the target is detected.
ImageTargetAnchor	Marks an entity as an anchor for an image-tracking target. The image tracking system reveals the entity when the referenced target is found and hides it when the target is lost.
InstanceSlotComponent	Marks an entity as an instance slot owned by an InstancedMeshComponent group entity.
InstancedMeshComponent	Holds authored instanced-mesh data for an entity that renders as a THREE.InstancedMesh. Supports primitive geometry kinds (cube, sphere, plane, capsule, cylinder).
LightComponent	Light source attached to an entity. type selects the underlying three.js light class (directional, point, spot, ambient, hemisphere, rect-area). values carries authoring state including color, intensity, and type-specific fields (distance, decay, angle, penumbra, width, height).
MaterialComponent	Material catalog for an entity. Tracks the live three.js materials (materials, material) plus serialized authoring state (values[]) mirrored from the inspector. Supports standard, basic, phong, and physical PBR types with optional texture map slots.
MeshComponent	Holds the live three.js Object3D for an entity that renders as a primitive mesh (cube, sphere, plane, capsule, cylinder). For loaded GLTF/GLB models see ModelComponent; for the editable geometry parameters see MeshGeometryComponent.
MeshGeometryComponent	Editable geometry parameters for primitive meshes (cube, sphere, plane, capsule, cylinder) and the placeholder for model entities. Holds the authoring values plus shadow casting/receiving flags. The mesh-geometry system rebuilds the underlying BufferGeometry when parameters change.
ModelComponent	References a GLTF/GLB asset loaded from path. The model loading system resolves the asset asynchronously and populates ModelComponent.object once available; loading is deferred-tolerant so the entity exists before the model finishes loading.
Name	Human-readable name for an entity. Shown in the editor hierarchy panel and preserved across save/reload.
Object3DRef	Wraps the live THREE.Object3D for an entity. Almost every entity that renders to the scene carries an Object3DRef so transform sync, selection, and parenting systems can manipulate the underlying object.
ParentId	Records the parent entity id for hierarchical scene graphs. null means the entity is at the world root. The ObjectManagementSystem reconciles scene-graph parenting from this component each frame.
PhysicsComponent	Marker base class for every ECS component. Subclass Component to declare a typed data container that systems can query.
Postprocessing	Postprocessing stack settings (depth-of-field, bloom, vignette, chromatic aberration, noise, pixelation, tone mapping, hue/saturation, sepia, SMAA,
PrefabInstance	Marks the ROOT entity of a prefab instance and records its link to the source .prefab asset plus the instance's per-property overrides.
PrefabNode	Stable identity for an entity that originated from a prefab asset.
ScriptComponent	Component holding the list of scripts attached to an entity. Loaded from the saved project; the runtime-side fields (scriptInstance, scriptInstances) are non-enumerable so they never leak into save data or undo history.
ScriptObjectComponent	Component for a script object — a single ScriptObject whose THREE.js visual is built by user code and runs in the editor AND at runtime. Unlike ScriptComponent this holds ONE script (not an entries array). The live instance ref is non-enumerable so it never leaks into save data or undo history.
Selectable	Toggles whether the editor selection system can pick this entity. When enabled is false, the entity is excluded from raycast hit tests.
SelectionTransformState	Singleton-style component (attached once to a system entity) that mirrors the editor's current transform-gizmo state into the ECS world. Persisted in snapshots so undo/redo restores the exact gizmo configuration.
SpriteComponent	Camera-facing 2D sprite. Unlike ImageComponent, sprites use THREE.Sprite and always render as billboards.
TransformComponent	Position, rotation, and scale of an entity in its parent's local space.
UIButtonComponent	A pressable control.
UIPanelComponent	A flat UI surface in the world — the backdrop menus and HUDs are built on.
UISliderComponent	A draggable value control.
UITextComponent	A block of text drawn onto a transparent canvas quad.
UIToggleComponent	An on/off switch.
VRTeleportAreaComponent	Marks an entity's surface as a valid teleport destination.
VideoComponent	Plays a video file as a texture on a quad. Supports green-screen keying (isGreenScreen, backgroundColor, similarity, smoothness, spill). The video element, texture, and material are runtime-only and re-created when the project loads.
XRAnchorComponent	Pins an entity to a real-world position.
XREnvironmentComponent	Marks an entity as a piece of the user's REAL room, detected at runtime.
XRHandPoseComponent	Listens for hand poses and reports them to the entity's Behaviours.
XRInteractableComponent	Makes an entity respond to XR pointers and hands.
XRInteractorComponent	Configures what the user sees as their hands, and hosts custom hand content.
XRInteractorSideComponent	Marks an entity as the left or right hand slot of an XRInteractorComponent.
XRRigComponent	Marks an entity as the XR rig — the player's movable origin.

Type Aliases

Type Alias	Description
AnimationComponentOptions	Initializer for AnimationComponent.
CameraRuntimeType	Runtime camera mode. 3d is a free camera; ar is composited over a tracked image/face feed; xr is driven by an immersive WebXR session (the headset owns the pose and projection — locomotion moves the camera's XR rig parent).
CameraProjection	Projection model.
CameraComponentOptions	Optional initializer for CameraComponent. Any field omitted falls back to the defaults documented on the component.
EnvironmentSkyboxType	Skybox rendering modes. none disables skybox rendering entirely.
EnvironmentGradientEffect	Gradient distribution applied when EnvironmentSkyboxState.type is "gradient".
EnvironmentFogType	Fog distance models. none disables fog.
EnvironmentSkyboxState	Skybox configuration. Only the fields relevant to type are read at render time.
EnvironmentFogState	Fog configuration. Mirrors three.js Fog / FogExp2.
EnvironmentState	Aggregated authoring state owned by Environment.
ImageTargetReference	Single uploaded image used as input to the image-target compiler.
ImageTargetAnchorOptions	Optional initializer for ImageTargetAnchor.
InstanceTransform	Per-instance transform stored inside InstancedMeshComponent. All rotations are in radians.
InstancedMeshKind	Primitive geometry kinds and custom 3D model kind supported by instanced mesh rendering.
LightValueState	Authoring state for LightComponent. Common fields apply to every light kind; the optional fields are only meaningful for specific kinds.
MaterialTypeValue	Supported material classes. Each maps to a three.js Mesh*Material type.
TextureFilteringValue	Texture sampling mode. smooth uses linear filtering; sharp uses nearest filtering for pixel-art look.
MaterialValueState	Authoring state for a single slot in MaterialComponent.values. Mirrors the live three.js material so it can be re-applied when the project loads.
EditableMeshObjectKind	Editable primitive kinds the mesh-geometry system can rebuild on the fly. model is a passthrough placeholder for entities that own a loaded GLTF/GLB instead.
CubeMeshParameters	Box geometry parameters in world units.
PlaneMeshParameters	Plane geometry parameters in world units.
RadiusMeshParameters	Radius-only primitive parameters (sphere).
RadiusHeightMeshParameters	Radius + height primitive parameters (capsule, cylinder).
MeshGeometryParametersByKind	Map from EditableMeshObjectKind to its parameter shape.
MeshGeometryParameters	-
RigidbodyType	Rigidbody body type: - dynamic: simulated by physics; affected by forces and gravity. - fixed: immovable static body. - kinematicPosition: moved by setting next position; ignores forces. - kinematicVelocity: moved by setting velocity; ignores forces.
RigidbodyState	Authoring state for the rigidbody half of PhysicsComponent. Saved with the project.
ColliderShape	Collider primitive shape. trimesh derives geometry from the entity's mesh.
ColliderState	Authoring state for the collider half of PhysicsComponent. Only the size fields relevant to ColliderState.shape are read at simulation time.
PhysicsState	Combined authoring state for PhysicsComponent. Saved with the project.
PostprocessingState	Aggregated post-processing effect chain authored on the scene environment. Each sub-effect has its own enabled flag plus per-effect parameters.
ScriptEntry	One script attached to an entity. Multiple entries may target a single entity (different classes from the same or different files).
ScriptObjectRuntimeState	-
ScriptObjectComponentInput	-
TransformModeValue	Active gizmo mode in the editor.
TransformSpaceValue	Reference frame for the active gizmo.
Vec3	Plain XYZ vector. All ECS transform fields use this shape rather than THREE.Vector3 so they save cleanly with the project.
TransformData	Optional initial values passed to TransformComponent. Missing axes default to 0 for position/rotation and 1 for scale.
UIButtonOptions	Optional initializer for UIButtonComponent.
UiFollowMode	How a panel orients itself while the experience runs.
UIPanelOptions	Optional initializer for UIPanelComponent.
UISliderOptions	Optional initializer for UISliderComponent.
UiTextAlign	-
UiTextVAlign	-
UITextOptions	Optional initializer for UITextComponent.
UIToggleOptions	Optional initializer for UIToggleComponent.
VrTeleportShape	Footprint of a teleport destination.
VRTeleportAreaOptions	Optional initializer for VRTeleportAreaComponent.
XRAnchorOptions	Optional initializer for XRAnchorComponent.
XrEnvironmentKind	Which WebXR module reported this piece of the room.
XrEnvironmentOrientation	How a detected plane sits in the world, when the runtime says.
XrHandPoseEntry	One pose an entity listens for.
XRHandPoseOptions	-
XrGrabReach	How close the user must be to grab.
XrDistanceGrabBehavior	What a distance grab does to the object.
XrGrabGesture	Which gesture grabs the object.
XrAttachPoint	A hand-hold authored on the object.
XrGrabHands	How many hands may hold the object at once, and what a second grab does.
XrTwoHandRotation	How the second hand affects orientation. See solveTwoHandTransform.
XRInteractableOptions	Optional initializer for XRInteractableComponent.
XrInteractorType	-
XrHandPreset	Look applied to tracked-hand meshes.
XrInteractorSide	Which hand a child interactor entity follows.
XRInteractorOptions	Optional initializer for XRInteractorComponent.
XrTrackingOrigin	Where the headset's origin sits in the scene.
XrLocomotionMode	How the player moves through the scene in an immersive session.
XrEnvironmentPhysics	Which real-world geometry becomes physics colliders in a passthrough session.
XRRigOptions	Optional initializer for XRRigComponent.

Variables

Variable	Description
DEFAULT_ENVIRONMENT_STATE	-
DEFAULT_INSTANCE_TRANSFORM	Default identity instance transform.
DEFAULT_INSTANCED_MESH_PARAMETERS	Default geometry parameters per instanced mesh kind. For "model" kind, cube params are stored as a placeholder (unused).
DEFAULT_MESH_GEOMETRY_PARAMETERS	-
DEFAULT_RIGIDBODY_STATE	-
DEFAULT_COLLIDER_STATE	-
DEFAULT_PHYSICS_STATE	-
DEFAULT_POSTPROCESSING_STATE	-
DEFAULT_POSE_CURLS	-
DEFAULT_POSE_DIRECTIONS	-

Functions

Function	Description
defaultMaterialValue	-
normalizePhysicsState	-
setPhysicsLiveRef	-
createHandPoseEntry	A pose entry with every field populated, for the editor and AI tools.
handPoseDefinitionFor	Resolve an entry to the definition the matcher consumes.
createAttachPoint	An attach point with every field populated, for the editor and AI tools.