@relu-interactives/spatial-ecs
@relu-interactives/spatial-ecs / index / World
Class: World ​
Defined in: World.ts:68
Constructors ​
Constructor ​
new World(options): World;Defined in: World.ts:99
Parameters ​
| Parameter | Type |
|---|---|
options | { scene: Scene; camera: PerspectiveCamera; renderer: WebGLRenderer; featureFlags?: WorldFeatureFlags; } |
options.scene | Scene |
options.camera | PerspectiveCamera |
options.renderer | WebGLRenderer |
options.featureFlags? | WorldFeatureFlags |
Returns ​
World
Methods ​
createEntity() ​
createEntity(): number;Defined in: World.ts:118
Returns ​
number
destroyEntity() ​
destroyEntity(entityId): void;Defined in: World.ts:126
Parameters ​
| Parameter | Type |
|---|---|
entityId | number |
Returns ​
void
hasEntity() ​
hasEntity(entityId): boolean;Defined in: World.ts:153
Parameters ​
| Parameter | Type |
|---|---|
entityId | number |
Returns ​
boolean
getEntities() ​
getEntities(): number[];Defined in: World.ts:157
Returns ​
number[]
getEntityCount() ​
getEntityCount(): number;Defined in: World.ts:161
Returns ​
number
addComponent() ​
addComponent<T>(entityId, component): void;Defined in: World.ts:165
Type Parameters ​
| Type Parameter |
|---|
T extends Component |
Parameters ​
| Parameter | Type |
|---|---|
entityId | number |
component | T |
Returns ​
void
addComponents() ​
addComponents<T>(entityId, components): void;Defined in: World.ts:180
Type Parameters ​
| Type Parameter |
|---|
T extends Component |
Parameters ​
| Parameter | Type |
|---|---|
entityId | number |
components | T[] |
Returns ​
void
removeComponent() ​
removeComponent<T>(entityId, componentType): void;Defined in: World.ts:201
Type Parameters ​
| Type Parameter |
|---|
T extends Component |
Parameters ​
| Parameter | Type |
|---|---|
entityId | number |
componentType | ComponentClass<T> |
Returns ​
void
getComponent() ​
getComponent<T>(entityId, componentType): T | undefined;Defined in: World.ts:209
Type Parameters ​
| Type Parameter |
|---|
T extends Component |
Parameters ​
| Parameter | Type |
|---|---|
entityId | number |
componentType | ComponentClass<T> |
Returns ​
T | undefined
hasComponent() ​
hasComponent<T>(entityId, componentType): boolean;Defined in: World.ts:216
Type Parameters ​
| Type Parameter |
|---|
T extends Component |
Parameters ​
| Parameter | Type |
|---|---|
entityId | number |
componentType | ComponentClass<T> |
Returns ​
boolean
query() ​
query(...componentTypes): number[];Defined in: World.ts:223
Parameters ​
| Parameter | Type |
|---|---|
...componentTypes | ComponentClass<Component>[] |
Returns ​
number[]
isEntityVisible() ​
isEntityVisible(entityId): boolean;Defined in: World.ts:237
Returns true if the entity is currently visible (its Object3DRef.visibility is true), or if the entity has no Object3DRef component (entities without a scene object are always considered active). Systems use this to skip per-entity updates for hidden objects.
Parameters ​
| Parameter | Type |
|---|---|
entityId | number |
Returns ​
boolean
getInputSystem() ​
getInputSystem(): EcsSystem | null;Defined in: World.ts:242
Returns ​
EcsSystem | null
getKeyDown() ​
getKeyDown(key): boolean;Defined in: World.ts:254
Parameters ​
| Parameter | Type |
|---|---|
key | KeyboardKey |
Returns ​
boolean
getKeyUp() ​
getKeyUp(key): boolean;Defined in: World.ts:263
Parameters ​
| Parameter | Type |
|---|---|
key | KeyboardKey |
Returns ​
boolean
getKey() ​
getKey(key): boolean;Defined in: World.ts:272
Parameters ​
| Parameter | Type |
|---|---|
key | KeyboardKey |
Returns ​
boolean
getMouse() ​
getMouse(button): boolean;Defined in: World.ts:281
Parameters ​
| Parameter | Type |
|---|---|
button | string | number |
Returns ​
boolean
getMouseDown() ​
getMouseDown(button): boolean;Defined in: World.ts:290
Parameters ​
| Parameter | Type |
|---|---|
button | string | number |
Returns ​
boolean
getMouseUp() ​
getMouseUp(button): boolean;Defined in: World.ts:299
Parameters ​
| Parameter | Type |
|---|---|
button | string | number |
Returns ​
boolean
getScrollClick() ​
getScrollClick(): boolean;Defined in: World.ts:308
Returns ​
boolean
getScrollClickDown() ​
getScrollClickDown(): boolean;Defined in: World.ts:317
Returns ​
boolean
getScrollClickUp() ​
getScrollClickUp(): boolean;Defined in: World.ts:326
Returns ​
boolean
getScrollDelta() ​
getScrollDelta(): {
x: number;
y: number;
};Defined in: World.ts:335
Returns ​
{
x: number;
y: number;
}| Name | Type | Defined in |
|---|---|---|
x | number | World.ts:335 |
y | number | World.ts:335 |
consumeScrollDelta() ​
consumeScrollDelta(): {
x: number;
y: number;
};Defined in: World.ts:344
Returns ​
{
x: number;
y: number;
}| Name | Type | Defined in |
|---|---|---|
x | number | World.ts:344 |
y | number | World.ts:344 |
getMousePosition() ​
getMousePosition(): {
x: number;
y: number;
};Defined in: World.ts:353
Returns ​
{
x: number;
y: number;
}| Name | Type | Defined in |
|---|---|---|
x | number | World.ts:353 |
y | number | World.ts:353 |
getMouseDelta() ​
getMouseDelta(): {
x: number;
y: number;
};Defined in: World.ts:362
Returns ​
{
x: number;
y: number;
}| Name | Type | Defined in |
|---|---|---|
x | number | World.ts:362 |
y | number | World.ts:362 |
consumeMouseDelta() ​
consumeMouseDelta(): {
x: number;
y: number;
};Defined in: World.ts:371
Returns ​
{
x: number;
y: number;
}| Name | Type | Defined in |
|---|---|---|
x | number | World.ts:371 |
y | number | World.ts:371 |
getRapierModule() ​
getRapierModule(): Promise<__module>;Defined in: World.ts:380
Returns ​
Promise<__module>
getPhysicsWorld() ​
getPhysicsWorld(): World | null;Defined in: World.ts:398
Returns ​
World | null
setPhysicsWorld() ​
setPhysicsWorld(physicsWorld): void;Defined in: World.ts:402
Parameters ​
| Parameter | Type |
|---|---|
physicsWorld | World | null |
Returns ​
void
createPhysicsWorld() ​
createPhysicsWorld(options?): Promise<World | null>;Defined in: World.ts:406
Parameters ​
| Parameter | Type |
|---|---|
options? | { gravity?: { x?: number; y?: number; z?: number; }; } |
options.gravity? | { x?: number; y?: number; z?: number; } |
options.gravity.x? | number |
options.gravity.y? | number |
options.gravity.z? | number |
Returns ​
Promise<World | null>
lockMousePointer() ​
lockMousePointer(): boolean;Defined in: World.ts:425
Returns ​
boolean
unlockMousePointer() ​
unlockMousePointer(): boolean;Defined in: World.ts:456
Returns ​
boolean
isMousePointerLocked() ​
isMousePointerLocked(): boolean;Defined in: World.ts:477
Returns ​
boolean
getSystem() ​
getSystem<T>(system): T;Defined in: World.ts:493
Type Parameters ​
| Type Parameter |
|---|
T extends EcsSystem |
Parameters ​
| Parameter | Type |
|---|---|
system | T |
Returns ​
T
hasSystem() ​
hasSystem<T>(system): boolean;Defined in: World.ts:510
Type Parameters ​
| Type Parameter |
|---|
T extends EcsSystem |
Parameters ​
| Parameter | Type |
|---|---|
system | T |
Returns ​
boolean
addSystem() ​
addSystem(system): void;Defined in: World.ts:519
Parameters ​
| Parameter | Type |
|---|---|
system | EcsSystem |
Returns ​
void
addSystems() ​
addSystems(systems): void;Defined in: World.ts:523
Parameters ​
| Parameter | Type |
|---|---|
systems | EcsSystem[] |
Returns ​
void
setup() ​
setup(__namedParameters): {
objectManagementSystem: ObjectManagementSystem;
transformSyncSystem: TransformSyncSystem;
renderSystem: RenderSystem;
};Defined in: World.ts:529
Parameters ​
| Parameter | Type |
|---|---|
__namedParameters | { systems: EcsSystem[]; isEditor?: boolean; } |
__namedParameters.systems | EcsSystem[] |
__namedParameters.isEditor? | boolean |
Returns ​
{
objectManagementSystem: ObjectManagementSystem;
transformSyncSystem: TransformSyncSystem;
renderSystem: RenderSystem;
}| Name | Type | Defined in |
|---|---|---|
objectManagementSystem | ObjectManagementSystem | World.ts:530 |
transformSyncSystem | TransformSyncSystem | World.ts:531 |
renderSystem | RenderSystem | World.ts:532 |
isEditorMode() ​
isEditorMode(): boolean;Defined in: World.ts:627
Returns ​
boolean
isXrPresenting() ​
isXrPresenting(): boolean;Defined in: World.ts:644
true while an immersive WebXR session is actively presenting.
While presenting, three's WebXRManager OWNS the render camera: each frame updateUserCamera() writes the headset pose into the camera's position/quaternion/scale and copies the XR projection (including a derived fov) onto it. Systems that also drive the camera must stand down for the duration, or they ping-pong with the headset every frame and defeat their own dirty-checks.
Locomotion therefore moves the camera's PARENT (the XR rig) — three composes the head pose as parent.matrixWorld × headPose.
Returns ​
boolean
isXrPassthrough() ​
isXrPassthrough(): boolean;Defined in: World.ts:661
true while the session is compositing over the real world (passthrough).
Read from the session's environmentBlendMode rather than from what the app ASKED for: a request for immersive-ar can be granted as a plain opaque session, and the blend mode is the only thing that says what the user is actually looking at. additive (optical see-through) and alpha-blend (video passthrough) both mean the real world is visible behind the render.
The load-bearing consequence is that nothing may paint an opaque background: a skybox drawn over the whole framebuffer hides the room completely, which looks exactly like passthrough having failed.
Returns ​
boolean
pause() ​
pause(): void;Defined in: World.ts:674
Pauses world simulation. While paused, update() skips all system ticks so physics, animation, scripts, and rendering stop advancing. The last rendered frame remains frozen on-screen.
Call resume to continue.
Returns ​
void
resume() ​
resume(): void;Defined in: World.ts:682
Resumes world simulation after a previous pause call. Has no effect if the world is not paused.
Returns ​
void
isPaused() ​
isPaused(): boolean;Defined in: World.ts:696
Returns true if the world is currently paused.
Returns ​
boolean
Example ​
if (this.world.isPaused()) {
this.world.resume();
}getScene() ​
getScene(): Scene;Defined in: World.ts:700
Returns ​
Scene
getCamera() ​
getCamera(): PerspectiveCamera;Defined in: World.ts:704
Returns ​
PerspectiveCamera
getRenderer() ​
getRenderer(): WebGLRenderer;Defined in: World.ts:708
Returns ​
WebGLRenderer
update() ​
update(deltaTime): void;Defined in: World.ts:712
Parameters ​
| Parameter | Type |
|---|---|
deltaTime | number |
Returns ​
void
dispose() ​
dispose(): void;Defined in: World.ts:719
Returns ​
void
setSelectedEntity() ​
setSelectedEntity(entityId): void;Defined in: World.ts:731
Parameters ​
| Parameter | Type |
|---|---|
entityId | number | null |
Returns ​
void
getSelectedEntity() ​
getSelectedEntity(): number | null;Defined in: World.ts:753
Returns ​
number | null
getEntitiesByComponent() ​
getEntitiesByComponent(component): WorldEntityView[];Defined in: World.ts:813
Parameters ​
| Parameter | Type |
|---|---|
component | Component |
Returns ​
WorldEntityView[]
getEntitiesByName() ​
getEntitiesByName(name): WorldEntityView[];Defined in: World.ts:827
Parameters ​
| Parameter | Type |
|---|---|
name | string |
Returns ​
WorldEntityView[]
getEntityByName() ​
getEntityByName(name): WorldEntityView | null;Defined in: World.ts:836
Parameters ​
| Parameter | Type |
|---|---|
name | string |
Returns ​
WorldEntityView | null
getEntityById() ​
getEntityById(entityId): WorldEntityView | null;Defined in: World.ts:841
Parameters ​
| Parameter | Type |
|---|---|
entityId | number |
Returns ​
WorldEntityView | null
getEntitiesChildren() ​
getEntitiesChildren(entityId): WorldEntityView[];Defined in: World.ts:849
Parameters ​
| Parameter | Type |
|---|---|
entityId | number |
Returns ​
WorldEntityView[]
getEntitiesParent() ​
getEntitiesParent(entityId): WorldEntityView | null;Defined in: World.ts:863
Parameters ​
| Parameter | Type |
|---|---|
entityId | number |
Returns ​
WorldEntityView | null
spawnPrefab() ​
spawnPrefab(source, options?): Promise<number>;Defined in: World.ts:878
Instantiate a prefab asset into this world at runtime — see spawnPrefab. Convenience wrapper so scripts and embedding apps can spawn without reaching for the object management system.
Parameters ​
| Parameter | Type |
|---|---|
source | SpawnPrefabSource |
options? | SpawnPrefabOptions |
Returns ​
Promise<number>
despawnPrefab() ​
despawnPrefab(rootEntityId): number;Defined in: World.ts:886
Remove a spawned prefab instance (root + descendants).
Parameters ​
| Parameter | Type |
|---|---|
rootEntityId | number |
Returns ​
number
getObjectManagementSystem() ​
getObjectManagementSystem(): ObjectManagementSystem;Defined in: World.ts:890
Returns ​
getEnvironmentComponent() ​
getEnvironmentComponent(): Environment | undefined;Defined in: World.ts:918
Returns the singleton Environment component for the scene, or undefined if no environment entity exists yet.
Mutate component.values directly to change skybox, fog, or gravity at runtime — EnvironmentSyncSystem picks up the changes next frame.
Returns ​
Environment | undefined
Example ​
const env = this.world.getEnvironmentComponent();
if (env) {
env.values.fog.type = "exponential";
env.values.fog.exponential.density = 0.01;
}getPostprocessingComponent() ​
getPostprocessingComponent():
| Postprocessing
| undefined;Defined in: World.ts:941
Returns the singleton Postprocessing component for the scene, or undefined if no postprocessing entity exists yet.
Mutate component.values directly to enable/disable effects or tweak parameters at runtime — PostprocessingSyncSystem picks up the changes next frame.
Returns ​
| Postprocessing | undefined
Example ​
const pp = this.world.getPostprocessingComponent();
if (pp) {
pp.values.bloom.enabled = true;
pp.values.bloom.intensity = 2.0;
}raycast() ​
raycast(
origin,
direction,
near?,
far?): IntersectionResult[];Defined in: World.ts:971
Cast a ray from origin along direction and return every intersected entity-bound mesh, sorted by distance. Each result is a standard THREE.Intersection augmented with the owning entityId (or null if the hit object is not part of any tracked entity).
Parameters ​
| Parameter | Type | Default value | Description |
|---|---|---|---|
origin | Vec3 | undefined | World-space origin of the ray (THREE.Vector3 or { x, y, z }). |
direction | Vec3 | undefined | World-space direction of the ray. Will be normalized internally; magnitude is ignored. |
near | number | 0 | Minimum hit distance from the origin. Defaults to 0. |
far | number | Infinity | Maximum hit distance from the origin. Defaults to Infinity. |
Returns ​
Example ​
const hits = world.raycast(
{ x: 0, y: 1, z: 0 },
{ x: 0, y: 0, z: -1 },
);
if (hits[0]?.entityId !== null) {
console.log("hit entity", hits[0].entityId, "at", hits[0].point);
}raycastFrom() ​
raycastFrom(
entityId,
near?,
far?): IntersectionResult[];Defined in: World.ts:1022
Cast a ray from an entity's world-space position along its forward direction (the +Z axis of its world matrix). Returns intersected entity-bound meshes sorted by distance, with the source entity itself filtered out so the ray does not hit the caster.
Parameters ​
| Parameter | Type | Default value | Description |
|---|---|---|---|
entityId | number | undefined | Entity to cast the ray from. Must have an Object3DRef. |
near | number | 0 | Minimum hit distance from the origin. Defaults to 0. |
far | number | Infinity | Maximum hit distance from the origin. Defaults to Infinity. |
Returns ​
Example ​
const hits = world.raycastFrom(this.entityId, 0, 50);
const closest = hits[0];
if (closest && closest.entityId !== null) {
console.log("looking at", closest.entityId);
}getEntityScript() ​
getEntityScript<T>(entityId): T | null;Defined in: World.ts:1105
Type Parameters ​
| Type Parameter | Default type |
|---|---|
T | unknown |
Parameters ​
| Parameter | Type |
|---|---|
entityId | number |
Returns ​
T | null
getScripts() ​
getScripts<T>(className): T[];Defined in: World.ts:1118
Type Parameters ​
| Type Parameter | Default type |
|---|---|
T | unknown |
Parameters ​
| Parameter | Type |
|---|---|
className | string |
Returns ​
T[]
getScript() ​
getScript<T>(className): T | null;Defined in: World.ts:1159
Type Parameters ​
| Type Parameter | Default type |
|---|---|
T | unknown |
Parameters ​
| Parameter | Type |
|---|---|
className | string |
Returns ​
T | null
getAllEntities() ​
getAllEntities(): WorldEntityView[];Defined in: World.ts:1164
Returns ​
WorldEntityView[]
onSelectionChanged() ​
onSelectionChanged(listener): () => void;Defined in: World.ts:1170
Parameters ​
| Parameter | Type |
|---|---|
listener | SelectionListener |
Returns ​
() => void
subscribe() ​
subscribe(listener): () => void;Defined in: World.ts:1178
Parameters ​
| Parameter | Type |
|---|---|
listener | StoreListener |
Returns ​
() => void
getDebugSnapshot() ​
getDebugSnapshot(maxDepth?): unknown;Defined in: World.ts:1186
Parameters ​
| Parameter | Type | Default value |
|---|---|---|
maxDepth | number | 3 |
Returns ​
unknown
getDebugSignature() ​
getDebugSignature(maxDepth?): string;Defined in: World.ts:1236
Parameters ​
| Parameter | Type | Default value |
|---|---|---|
maxDepth | number | 3 |
Returns ​
string
getEntitiesSnapshot() ​
getEntitiesSnapshot(entityIds, maxDepth?): {
entities: number[];
components: {
component: string;
entries: {
entityId: number;
value: unknown;
}[];
}[];
};Defined in: World.ts:1245
Serialize ONLY the given entities into the same columnar {entities, components} shape as getDebugSnapshot (no systems, no selection). Used by prefab/scene subtree serialization.
Parameters ​
| Parameter | Type | Default value |
|---|---|---|
entityIds | number[] | undefined |
maxDepth | number | 10 |
Returns ​
{
entities: number[];
components: {
component: string;
entries: {
entityId: number;
value: unknown;
}[];
}[];
}| Name | Type | Defined in |
|---|---|---|
entities | number[] | World.ts:1249 |
components | { component: string; entries: { entityId: number; value: unknown; }[]; }[] | World.ts:1250 |
createHistorySnapshot() ​
createHistorySnapshot(): WorldHistorySnapshot;Defined in: World.ts:1287
Returns ​
WorldHistorySnapshot
applyHistorySnapshot() ​
applyHistorySnapshot(snapshot): void;Defined in: World.ts:1308
Parameters ​
| Parameter | Type |
|---|---|
snapshot | WorldHistorySnapshot |
Returns ​
void