Appearance

ObjectEntity ​

Entity in the scene

Access properties and representations, listen to events.

Example:

javascript
var entity = scene.findEntity({ name: "My Box" });
entity.position = Vector3(0, 1, 0);
entity.on('tap', function() {
    console.log('Tapped!');
});

Properties ​

boundingBox ​

eulerAngles ​

  • Type: Vector3
  • Local rotation as euler angles (radians).

id ​

  • Type: string
  • Unique entity identifier

isEnabled ​

  • Type: boolean
  • Whether this representation is enabled/visible

opacity ​

  • Type: number
  • Opacity (0-1)

position ​

  • Type: Vector3
  • Local position relative to parent.

representation ​

rotation ​

  • Type: Rotation
  • Local rotation as quaternion. Assign a whole Rotation; per-component quaternion mutation is not meaningful, so use rotation/eulerAngles assignment or animateTo.

scale ​

transform ​

  • Type: Transform
  • Local transform (position, rotation, scale combined)

worldBoundingBox ​

worldEulerAngles ​

  • Type: Vector3
  • World-space rotation as euler angles (radians)

worldPosition ​

worldRotation ​

  • Type: Rotation
  • World-space rotation as quaternion

worldScale ​

worldTransform ​

Methods ​

animateBy() ​

javascript
animateBy(properties: Object, duration: number, options?: Object): Promise<void>

Animate this entity's representation by relative values (additive animation)

Parameters:

  • properties (Object) - Relative change values
  • duration (number) - Animation duration in seconds
  • options (Object) (optional) - Animation options

Returns: Promise<void>

animateFromTo() ​

javascript
animateFromTo(fromProperties: Object, toProperties: Object, duration: number, options?: Object): Promise<void>

Animate this entity's representation from starting to target properties

Parameters:

  • fromProperties (Object) - Starting property values
  • toProperties (Object) - Target property values
  • duration (number) - Animation duration in seconds
  • options (Object) (optional) - Animation options

Returns: Promise<void>

animateTo() ​

javascript
animateTo(properties: Object, duration: number, options?: Object): Promise<void>

Animate this entity's representation to target properties

Parameters:

  • properties (Object) - Target properties to animate to
  • properties.position (Vector3) (optional) - Target position
  • properties.rotation (Rotation) (optional) - Target rotation
  • properties.scale (Vector3) (optional) - Target scale
  • properties.transform (Transform) (optional) - Target transform (overrides position/rotation/scale)
  • properties.opacity (number) (optional) - Target opacity (0-1)
  • duration (number) - Animation duration in seconds
  • options (Object) (optional) - Animation options
  • options.timingFunction (string | Object) (optional) - Easing: "linear", "easeIn", "easeOut", "easeInOut", or custom
  • options.delay (number) (optional) - Delay before animation starts (seconds)
  • options.repeatCount (number) (optional) - Number of times to repeat (-1 for infinite)
  • options.repeatMode (string) (optional) - "default", "autoReverse", or "cumulative"

Returns: Promise<void>

applyAngularImpulse() ​

javascript
applyAngularImpulse(impulse: Vector3, options?: Object): Promise<void>

Spin this object with a one-off rotational force. Proxies to the primary representation.

Parameters:

Returns: Promise<void>

applyImpulse() ​

javascript
applyImpulse(impulse: Vector3, options?: Object): Promise<void>

Push this object with a one-off force. Proxies to the primary representation.

Parameters:

Returns: Promise<void>

clearInstances() ​

javascript
clearInstances(): void

Remove instancing from this object, reverting to the single base mesh. Proxies to the primary representation.

Returns: void

clone() ​

javascript
clone(options?: Object): Promise<ObjectEntity>

Deep-copy this object and add the copy to the scene.

The copy carries fresh ids, so it behaves like any other object – attach events, move it, remove it independently. Pose overrides merge into the copy's transform, so an omitted field keeps this object's value.

If this object was authored "disabled by default" (a common template pattern), the copy is added hidden with its physics body off until you toggle(true) it – so a batch can be revealed together on one frame.

Cloning rejects past 512 live copies of one source object. That ceiling exists only to stop a runaway loop (while (true) clone()) from exhausting memory – reaching it means a bug, not a budget. Remove copies you no longer need with entity.remove().

Example:

javascript
// Scatter ten copies of an editor-authored template.
const template = scene.findEntity('coin');
for (let i = 0; i < 10; i++) {
    await template.clone({ position: Vector3(i * 0.2, 0, -1), enabled: true });
}

Parameters:

  • options (Object) (optional)
  • options.position (Vector3) (optional) - World position for the copy.
  • options.rotation (Rotation) (optional) - Rotation for the copy.
  • options.scale (Vector3) (optional) - Scale for the copy.
  • options.anchor (Object) (optional) - An Anchor.* descriptor, replacing the anchor.
  • options.enabled (boolean) (optional) - Reveal immediately (true) or keep deferred (false). Omit to inherit the source's disabled-by-default state.
  • options.id (string) (optional) - Explicit id for the copy; generated otherwise.

Returns: Promise<ObjectEntity>

createAudioStream() ​

javascript
createAudioStream(options?: Object): AudioStream

Create a streaming audio player on this entity

Parameters:

  • options (Object) (optional) - Stream options

Returns: AudioStream

findRepresentation() ​

javascript
findRepresentation(query: any): RepresentationEntity

Find a representation by ID or name

Example:

javascript
// By ID
var rep = entity.findRepresentation("ABC123");

// By name
var rep = entity.findRepresentation({ name: "Main Model" });

Parameters:

  • query (any) - Representation ID string, or object with { id: "..." } or { name: "..." }

Returns: RepresentationEntity

followPath() beta ​

javascript
followPath(path: Path, options?: Object): void

Move this entity along a path from scene.createPath(...).

Parameters:

  • path (Path) - Path handle from scene.createPath(...)
  • options (Object) (optional) - { duration?: number, constantSpeed?: boolean, alignsToTangent?: boolean, timing?: "linear"|"easeIn"|"easeOut"|"easeInOut", repeat?: boolean|number }
  • options.repeat (boolean | number) (optional) - true or -1 loops forever; a positive number loops that many times; false/0/omitted plays once.

Returns: void

off() ​

javascript
off(eventId: string): void

Remove an entity event listener

Example:

javascript
var eventId = entity.on('tap', function() {});
// Later...
entity.off(eventId);

Parameters:

  • eventId (string) - Event ID returned from on()

Returns: void

on() ​

javascript
on(type: string, options?: Object | function, listener?: function): string

Register an entity event listener

Example:

javascript
entity.on('tap', function(event) {
    console.log('Entity tapped!');
});

Parameters:

  • type (string) - Event type: "tap", "doubleTap", "longPress", "add", "collision", "distance", "lookAt", "mediaPlayback", "gesture"
  • options (Object | function) (optional) - Event options or callback. For "longPress", minimumDuration (seconds) is optional.
  • listener (function) (optional) - Callback if options provided

Returns: string

once() ​

javascript
once(type: string, options?: Object | function, listener?: function): string

Register a one-time entity event listener

Example:

javascript
entity.once('tap', function(event) {
    console.log('First tap only!');
});

Parameters:

  • type (string) - Event type
  • options (Object | function) (optional) - Event options or callback
  • listener (function) (optional) - Callback if options provided

Returns: string

play() ​

javascript
play(animation: Animation): Promise<void>

Play an animation on this entity's representation

Parameters:

  • animation (Animation) - Animation object from Animation.to(), Animation.spin(), etc.

Returns: Promise<void>

playAudio() ​

javascript
playAudio(source: string, options?: Object): Promise<void>

Play audio asset on this entity

Parameters:

  • source (string) - HTTPS URL or asset ID from project
  • options (Object) (optional) - Playback options

Returns: Promise<void>

playAudioBuffer() ​

javascript
playAudioBuffer(base64: string, options?: Object): Promise<void>

Play audio buffer on this entity

Parameters:

  • base64 (string) - Base64-encoded PCM audio data
  • options (Object) (optional) - Buffer and playback options

Returns: Promise<void>

remove() ​

javascript
remove(): Promise<void>

Remove this entity from the scene

Returns: Promise<void>

setAngularVelocity() ​

javascript
setAngularVelocity(angularVelocity: Vector3): void

Set the world-space angular velocity of this object's physics body (axis-angle, radians per second). Proxies to the primary representation.

Parameters:

  • angularVelocity (Vector3) - World-space angular velocity, axis-angle in rad/s.

Returns: void

setInstances() beta ​

javascript
setInstances(transforms: Object | Array): void

GPU-instance this object's mesh – draw one copy per transform. Proxies to the primary representation. Pass Instances.transforms([...]) or a bare array of Transform / Vector3. Rendering-only; gate with environment.features.has('instancing').

Parameters:

  • transforms (Object | Array) - An Instances.* handle, or a bare transforms array.

Returns: void

setMaterial() ​

javascript
setMaterial(options?: Object): Promise<void>

Set material on this entity's representation

Parameters:

  • options (Object) (optional) - Material options, omit to clear

Returns: Promise<void>

setMaterials() ​

javascript
setMaterials(materials: Array<Object>): Promise<void>

Set materials on this entity's representation

Parameters:

  • materials (Array<Object>) - Array of material options

Returns: Promise<void>

setPhysicsMode() ​

javascript
setPhysicsMode(mode: string): void

Set the physics body mode at runtime. Proxies to the primary representation.

Parameters:

  • mode (string) - "static", "kinematic", or "dynamic".

Returns: void

setVelocity() ​

javascript
setVelocity(velocity: Vector3): void

Set the world-space linear velocity of this object's physics body. Proxies to the primary representation.

Parameters:

  • velocity (Vector3) - World-space velocity, in metres per second.

Returns: void

stopAnimations() ​

javascript
stopAnimations(options?: Object): Promise<void>

Stop and remove animations from this entity's representation

Parameters:

  • options (Object) (optional) - Options
  • options.transitionDuration (number) (optional) - Fade out duration in seconds

Returns: Promise<void>

stopAudio() ​

javascript
stopAudio(): Promise<void>

Stop audio playback on this entity

Returns: Promise<void>

toggle() ​

javascript
toggle(enabled: boolean): Promise<void>

Enable or disable this entity's representation

Parameters:

  • enabled (boolean) - Enable (true) or disable (false)

Returns: Promise<void>

toggleAnimations() ​

javascript
toggleAnimations(options?: Object): Promise<void>

Toggle (pause/resume) animations on this entity's representation

Parameters:

  • options (Object) (optional) - Options
  • options.play (boolean) (optional) - Explicit play (true) or pause (false), toggles if omitted
  • options.animationIds (Array<string>) (optional) - Specific animation IDs to toggle

Returns: Promise<void>

waitUntilReady() ​

javascript
waitUntilReady(): Promise<void>

Wait until this entity's primary representation has finished loading.

Convenience that proxies to entity.representation.waitUntilReady(). Resolves immediately if there's no primary representation.

Returns: Promise<void>