@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. |
| 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 | Unified physics component combining a Rapier rigid body and a Rapier collider into a single authoring and runtime container. |
| Postprocessing | Postprocessing stack settings (depth-of-field, bloom, vignette, chromatic aberration, noise, pixelation, tone mapping, hue/saturation, sepia, SMAA, SSAO, dot-screen, glitch). The render system applies enabled effects in a postprocessing-library composer when postEnabled is true. Singleton- style — attached to one entity per scene. |
| 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. |
| 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. |
| 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. |
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. |
| 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. |
| 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). |
| 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. |
Variables
| Variable | Description |
|---|---|
| DEFAULT_ENVIRONMENT_STATE | - |
| DEFAULT_MESH_GEOMETRY_PARAMETERS | - |
| DEFAULT_RIGIDBODY_STATE | - |
| DEFAULT_COLLIDER_STATE | - |
| DEFAULT_PHYSICS_STATE | - |
| DEFAULT_POSTPROCESSING_STATE | - |
Functions
| Function | Description |
|---|---|
| normalizePhysicsState | - |