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

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>

bindMaterialParameter() ​

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

Bind a shader 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)

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]
});

Parameters:

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

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

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

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

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>

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)

Example:

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

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>

Internal API dev only ​

WARNING

These methods are internal implementation details and not part of the public API.

waitUntilReadyRaw() internal ​

javascript
waitUntilReadyRaw(callback?: any): void

Internal callback-style "wait until the model has finished loading". JS authors use the Promise-returning rep.waitUntilReady() exposed by the runtime, which wraps this. Required because JSExport methods can't directly expose async/Promise-returning signatures.

Parameters:

  • callback (any) (optional)

Returns: void