Appearance

RepresentationEntity ​

Visual representation of an entity (model, shape, etc.)

Access via entity.representation or entity.findRepresentation(). Controls visual properties like opacity, transform, and material parameters.

Example:

javascript
var rep = entity.representation;
rep.opacity = 0.5;
rep.position = Vector3(0, 1, 0);
rep.bindMaterialParameter("baseColor", "myColor");

Properties ​

boundingBox ​

entity ​

eulerAngles ​

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

id ​

  • Type: string
  • Unique representation identifier

isEnabled ​

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

mesh ​

  • Type: Mesh
  • Dynamic mesh handle for this representation. Nil unless the kind is .dynamicMesh. Use this to write vertex/index buffers and update per-part bounds from a script. Bulk-copy semantics – one call moves many vertices, no per-element overhead.

Example:

javascript
var mesh = entity.representation.mesh;
mesh.writeVertices("position", 0, new Float32Array([
    -0.25, 0.0, 0.0,
     0.25, 0.0, 0.0,
     0.0,  0.4, 0.0
]));
mesh.writeIndices(0, new Uint32Array([0, 1, 2]));
mesh.drawCount = 3;            // sugar for updatePart(0, { indexCount: 3 })
mesh.setBounds({ min: [-1,-1,-1], max: [1,1,1] });

opacity ​

  • Type: number
  • Opacity (0-1)

position ​

  • Type: Vector3
  • Local position relative to parent.

rootView ​

  • Type: UIView
  • Root view of the panel content. Nil unless this representation's kind is .userInterface.

Example:

javascript
var root = rep.rootView;
root.setProperty("isHidden", true);

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 representation by relative values

Parameters:

  • properties (Object) - Relative change properties
  • 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 representation from starting to target properties

Parameters:

  • fromProperties (Object) - Starting properties
  • toProperties (Object) - Target properties
  • 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 representation to target properties

Parameters:

  • properties (Object) - Target properties (position, rotation, scale, opacity)
  • duration (number) - Animation duration in seconds
  • options (Object) (optional) - Animation options

Returns: Promise<void>

applyAngularImpulse() ​

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

Spin this representation with a one-off rotational force.

The rotational counterpart of applyImpulse. There is no application point – an angular impulse acts on the body as a whole.

Example:

javascript
// Put backspin on a thrown ball.
ball.applyAngularImpulse(Vector3(-0.02, 0, 0), { space: 'pointOfView' });

Parameters:

  • impulse (Vector3) - Rotational force around each axis.
  • options (Object) (optional)
  • options.space (string | Object) (optional) - Coordinate frame. Same values as applyImpulse.

Returns: Promise<void>

applyImpulse() ​

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

Push this representation with a one-off force.

The object needs a dynamic physics body – see t.physics({ mode: 'dynamic' }).

Example:

javascript
// Throw a ball away from the camera.
ball.applyImpulse(Vector3(0, 1, -6), { space: 'pointOfView' });

Parameters:

  • impulse (Vector3) - Force along each axis, in newton-seconds.
  • options (Object) (optional)
  • options.space (string | Object) (optional) - Coordinate frame for the impulse: "local" (the object's own orientation), "world" (absolute scene axes), "pointOfView" (relative to the camera), or { sceneObject }.
  • options.at (Vector3 | string) (optional) - Where the force is applied. A point in the chosen space, or "userInteraction" to use the point the user touched. Omit to push through the centre of mass (no resulting spin).

Returns: Promise<void>

bindMaterialParameter() ​

javascript
bindMaterialParameter(parameterName: string, variableId: string, options?: any): void

Bind a material parameter to a variable for automatic updates

  • scope: Variable scope - "segment" (default) or "experience" - materialId: Target specific material by ID (optional, applies to all if omitted) - slots: Target specific material slots as array of integers (optional) - model: Target a single mesh by path ("/Root/…/foo") or name ("foo"). Omitted → bind every mesh that exposes the parameter. Call once per mesh to target several.

Example:

javascript
// Initialize variable
scene.setVariable("tintColor", Color.red());

// Bind parameter to variable
rep.bindMaterialParameter("baseColor", "tintColor");

// Now changing the variable updates the material automatically
scene.setVariable("tintColor", Color.blue());

// With experience scope
rep.bindMaterialParameter("intensity", "globalIntensity", { scope: "experience" });

// Target specific material
rep.bindMaterialParameter("emission", "glowAmount", {
    materialId: "glowMaterial",
    slots: [0]
});

// Target a single mesh (by name or path) – bind only that one, even if
// other meshes share the material.
rep.bindMaterialParameter("revealProgress", "reveal", { model: "_01_exterior_walls" });

Parameters:

  • parameterName (string) - Name of the material parameter (must match the name the material exposes)
  • variableId (string) - ID of the variable to bind
  • options (any) (optional) - Configuration object (optional)

Returns: void

clearInstances() ​

javascript
clearInstances(): void

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

Returns: void

createAudioStream() ​

javascript
createAudioStream(options?: Object): AudioStream

Create a streaming audio player on this representation

Example:

javascript
var stream = entity.createAudioStream({ sampleRate: 24000 });
stream.append(base64Data);
stream.stop();

Parameters:

  • options (Object) (optional) - Stream options
  • options.sampleRate (number) (optional) - Input sample rate in Hz
  • options.channels (number) (optional) - Number of channels (1 = mono, 2 = stereo)
  • options.format (string) (optional) - Sample format: "pcm16" or "float32"

Returns: AudioStream

findChild() ​

javascript
findChild(name: string, recursive?: any): Entity

Find a nested entity by name within the model hierarchy

Example:

javascript
var bone = rep.findChild("thumb_1");
bone.transform = hand.joints.thumbKnuckle.localTransform;

Parameters:

  • name (string) - Entity name to find
  • recursive (any) (optional) - Search all descendants (default: true)

Returns: Entity

findRepresentation() ​

javascript
findRepresentation(query: any): RepresentationEntity

Find a child representation by ID or name

Example:

javascript
var child = rep.findRepresentation({ name: "wheel" });
child.rotation = Rotation(0, Math.PI, 0);

Parameters:

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

Returns: RepresentationEntity

findView() ​

javascript
findView(query: any): UIView

Find a view in this representation's UI tree by ID or name

Example:

javascript
// By ID
var btn = rep.findView("save-btn");

// By name
var btn = rep.findView({ name: "Submit" });

Parameters:

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

Returns: UIView

followPath() ​

javascript
followPath(path: Path, options: any): void

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

(default true), alignsToTangent?: boolean (default false), timing?: "linear" | "easeIn" | "easeOut" | "easeInOut", repeat?: boolean | number }. repeat: trueor-1loops forever; a positive number loops that many times; false/0` / omitted plays once.

Example:

javascript
var path = scene.createPath({ points: [[0,0,-1],[0.5,0.3,-1.5],[1,0,-2]] });
entity.followPath(path, { duration: 3, alignsToTangent: true, repeat: true });

Parameters:

  • path (Path) - A Path handle.
  • options (any) - `{ duration?: number (s, default 1), constantSpeed?: boolean

Returns: void

getChildNames() ​

javascript
getChildNames(): Array<any>

List all nested entity names (for discovery)

Example:

javascript
var names = rep.getChildNames();
console.log(names); // ["wrist", "thumb_1", "thumb_2", ...]

Returns: Array<any>

off() ​

javascript
off(eventId: string): void

Remove an event listener from this representation

Parameters:

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

Returns: void

on() ​

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

Register an event listener on this representation

Example:

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

Parameters:

  • type (string) - Event type: "tap", "collision", "distance", etc.
  • options (Object | function) (optional) - Event options or callback
  • listener (function) (optional) - Callback if options provided

Returns: string

once() ​

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

Register a one-time event listener on this representation

Example:

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

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 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 representation

Example:

javascript
await entity.playAudio('https://example.com/sound.mp3');
await entity.playAudio('assetId123', { loops: true, gain: 1.5 });

Parameters:

  • source (string) - HTTPS URL or asset ID from project
  • options (Object) (optional) - Playback options
  • options.gain (number) (optional) - Volume gain (0.0 to 4.0, default 1.0)
  • options.loops (boolean) (optional) - Loop playback
  • options.inputMode (string) (optional) - "spatial", "nonSpatial", or "ambient"

Returns: Promise<void>

playAudioBuffer() ​

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

Play audio buffer spatially on this representation

Example:

javascript
await entity.playAudioBuffer(base64Data, { sampleRate: 24000 });

Parameters:

  • base64 (string) - Base64-encoded PCM audio data
  • options (Object) (optional) - Buffer and playback options
  • options.sampleRate (number) (optional) - Sample rate in Hz
  • options.channels (number) (optional) - Number of channels (1 = mono, 2 = stereo)
  • options.format (string) (optional) - Sample format: "pcm16" or "float32"
  • options.gain (number) (optional) - Volume gain (0.0 to 4.0, default 1.0)

Returns: Promise<void>

resetBlendShapeWeights() ​

javascript
resetBlendShapeWeights(options?: Object): void

Reset all blend shape weights to zero

Parameters:

  • options (Object) (optional) - Options (modelName, weightSetIndex, weightSetId)

Returns: void

setAngularVelocity() ​

javascript
setAngularVelocity(angularVelocity: Vector3): void

Set the world-space angular velocity of this representation's physics body (axis-angle, radians per second). The linear velocity is preserved. The rotational counterpart of setVelocity – e.g. give a thrown object spin.

Parameters:

Returns: void

setBlendShapeWeights() ​

javascript
setBlendShapeWeights(weights: Object | number, options?: Object): void

Update blend shape weights on this representation (for models with morph targets/blend shapes)

Example:

javascript
// Make a character smile
representation.setBlendShapeWeights({ mouthSmileLeft: 1, mouthSmileRight: 1 });

// Animate a blink
representation.setBlendShapeWeights({ eyeBlinkLeft: 1, eyeBlinkRight: 1 });
await wait(0.15);
representation.setBlendShapeWeights({ eyeBlinkLeft: 0, eyeBlinkRight: 0 });

// Reset all weights to zero
representation.setBlendShapeWeights(0);

Parameters:

  • weights (Object | number) - Blend shape name-value pairs, or a single number to set all weights
  • options (Object) (optional) - Options
  • options.modelName (string) (optional) - Target specific model by name (optional)
  • options.weightSetIndex (number) (optional) - Weight set index to update
  • options.weightSetId (string) (optional) - Weight set ID to update (alternative to index)

Returns: void

setInstances() ​

javascript
setInstances(transforms: any): void

GPU-instance this representation's mesh – draw one copy per transform, at a fraction of the cost of real entities. Pass Instances.transforms([...]) (or a bare array of Transform / Vector3, where a Vector3 places a copy at that position). Applies to every mesh in the representation.

Instances are rendering-only – no physics, collision, tap, or per-instance identity. Use them for pure visual repetition (a field of grass, a crowd, a particle-like scatter); keep real objects (clone()) for anything the user interacts with.

Gate with environment.features.has('instancing') – currently iOS 26 / visionOS 26 / macOS 26+; a no-op with a console warning below that floor.

A dense field of small copies aliases the directional light's shared shadow map into streaks. If you see that, author the object so it doesn't cast the projected shadow – add .shadow({ directional: false }) to the descriptor you pass to scene.createEntity(...) (grounding and received shadows are unaffected).

Example:

javascript
const spots = [];
for (let i = 0; i < 200; i++) {
    spots.push(new Vector3((i % 20) * 0.2, 0, Math.floor(i / 20) * 0.2));
}
rep.setInstances(Instances.transforms(spots));

Parameters:

Returns: void

setMaterial() ​

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

Set material on this representation

Example:

javascript
// Apply material to all models
entity.representation.setMaterial({ id: 'redMaterial' });

// Apply to first model only
entity.representation.setMaterial({ 
    id: 'redMaterial',
    target: { type: 'firstModel' }
});

// Clear custom materials (restore originals)
entity.representation.setMaterial();

Parameters:

  • options (Object) (optional) - Material options, omit to clear custom materials
  • options.id (string) - Material reference ID from scene
  • options.target (Object) (optional) - Target configuration
  • options.target.type (string) (optional) - "allModels", "firstModel", or "selectedModels"
  • options.target.models (Array<string>) (optional) - Model names for selectedModels
  • options.target.materialSlots (Array<number>) (optional) - Material slot indices

Returns: Promise<void>

setMaterials() ​

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

Set materials on this representation

Example:

javascript
// Apply multiple materials
entity.representation.setMaterials([
    { id: 'redMaterial', target: { type: 'firstModel' } },
    { id: 'blueMaterial', target: { type: 'selectedModels', models: ['body'] } }
]);

// Clear all custom materials (restore originals)
entity.representation.setMaterials([]);

Parameters:

  • materials (Array<Object>) - Array of material options
  • materials[].id (string) - Material reference ID from scene
  • materials[].target (Object) (optional) - Target configuration
  • materials[].target.type (string) (optional) - "allModels", "firstModel", or "selectedModels"
  • materials[].target.models (Array<string>) (optional) - Model names for selectedModels
  • materials[].target.materialSlots (Array<number>) (optional) - Material slot indices

Returns: Promise<void>

setPhysicsMode() ​

javascript
setPhysicsMode(mode: string): void

Set the physics body mode at runtime: "static", "kinematic", or "dynamic".

A general-purpose primitive for composing mechanics in a script – e.g. hold an object by switching it to kinematic and driving it by position, then release it to dynamic so the simulation takes over. No-op if the representation has no physics body configured or the string isn't a valid mode.

Example:

javascript
ball.setPhysicsMode('kinematic'); // hold: position-driven, ignores forces
ball.setPhysicsMode('dynamic');   // release: physics simulates it again

Parameters:

  • mode (string)

Returns: void

setVelocity() ​

javascript
setVelocity(velocity: Vector3): void

Set the world-space linear velocity of this representation's physics body.

Only integrated while the body is dynamic; the current angular velocity is preserved. Use it to throw or launch an object with a velocity you computed yourself – for example the speed of a gesture flick.

Example:

javascript
ball.setPhysicsMode('dynamic');
ball.setVelocity(Vector3(0, 2, -5)); // hurl it forward and up

Parameters:

Returns: void

stopAnimations() ​

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

Stop and remove animations from this 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 representation

Example:

javascript
entity.representation.stopAudio();

Returns: Promise<void>

toggle() ​

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

Enable or disable this 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 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 (optional, toggles all if omitted)

Returns: Promise<void>

toggleWithAnimation() ​

javascript
toggleWithAnimation(enable: boolean): void

Toggle visibility with fade animation

Example:

javascript
rep.toggleWithAnimation(false); // Fade out
rep.toggleWithAnimation(true);  // Fade in

Parameters:

  • enable (boolean) - Whether to show or hide

Returns: void

unbindMaterialParameter() ​

javascript
unbindMaterialParameter(parameterName: string, options?: any): void

Remove a variable binding from a material parameter

  • materialId: Target specific material by ID (optional) - slots: Target specific material slots (optional) - model: Unbind only on a single mesh by path ("/Root/…/foo") or name ("foo"). Omitted → unbind everywhere the parameter is bound. Mirrors bindMaterialParameter.

Example:

javascript
rep.unbindMaterialParameter("baseColor");
rep.unbindMaterialParameter("emission", { materialId: "glowMaterial" });
rep.unbindMaterialParameter("revealProgress", { model: "_01_exterior_walls" });

Parameters:

  • parameterName (string) - Name of the material parameter to unbind
  • options (any) (optional) - Configuration object (optional)

Returns: void

waitUntilReady() ​

javascript
waitUntilReady(): Promise<void>

Wait until this representation's model assets have finished loading and been attached to the scene.

Many setup calls – bindMaterialParameter, transform reads, animation triggers – depend on the model being present. On onWillAppear the representation proxy exists but the model itself usually hasn't been attached yet, and calling those methods too early silently no-ops. Await this before any model-dependent setup.

Example:

javascript
// On Cover Will Appear
var cover = scriptContext.sourceEvent.objectEntity.findRepresentation({ name: 'Cover' });
await cover.waitUntilReady();
cover.bindMaterialParameter('hueColor', 'myHue');

Returns: Promise<void>