ObjectTraits

Builder object passed to the compatibility-only .traits(t => …) callback. New code should skip this entirely and use the direct descriptor methods (.physics(…), .material(…), .shadow(…), .gestures(…), .transform(…), .opacity(…), .fittingBox(…), .pivot(…), .revealAnimation(…), .removalAnimation(…), .hideByDefault(…), .flatten(…)), which expose the same configuration and chain.

Instance Methods

transform()

transform(transform: Transform): ObjectTraits

Set initial transform

Parameters:

• transform (Transform) - Transform object

Returns: ObjectTraits

fittingBox()

fittingBox(size: number): ObjectTraits

Scale model to fit within a cubic bounding box

Parameters:

• size (number) - Maximum dimension in meters (model will fit inside this cube)

Returns: ObjectTraits

pivot()

pivot(pivot: string): ObjectTraits

Set pivot adjustment

Parameters:

• pivot (string) - which face of the model sits at its origin: "automatic", "top", "center", "bottom", "left", "right", "front", or "back". "back" seats a model flat against a wall the way "bottom" stands one on a floor.

Returns: ObjectTraits

revealAnimation()

revealAnimation(animation: Object | string | boolean): ObjectTraits

Choose how the object animates in when it appears.

Mirrors the editor's Reveal Animation picker, so a script-created object can look like an authored one. Omit it and the object uses the app default, the same as the picker's "Default".

Example:

// A script that owns the reveal itself: no built-in animation to play over it.
createSplat(assetId).revealAnimation(false);

Parameters:

• animation (Object | string | boolean) - A style name, an options object, or false for no animation at all (true restores the app default).
• animation.style (string) - "default" (the app's own reveal), "disabled" (appear instantly), "fade", or "fadeAndScale" (fades in while growing from scaleFactor).
• animation.duration (number) (optional) - Seconds, for "fade" and "fadeAndScale".
• animation.scaleFactor (number) (optional) - The fraction of full size the object grows from, for "fadeAndScale".

Returns: ObjectTraits

removalAnimation()

removalAnimation(animation: Object | string | boolean): ObjectTraits

Choose how the object animates out when it is removed. Same options as {@link ObjectTraits#revealAnimation}, and mirrors the editor's Removal Animation picker.

Parameters:

• animation (Object | string | boolean)

Returns: ObjectTraits

hideByDefault()

hideByDefault(hidden?: boolean): ObjectTraits

Hide the object when it is first added to the scene, so a script can prepare it before anyone sees it. Mirrors the editor's Hide By Default toggle.

The object still loads: its representation is built and its physics body precomputed, it is simply not shown and its physics stays paused. Bring it up with scene.toggle([entity], true), which reveals a batch on a single frame.

Example:

// Create it hidden, write the state it should appear in, then bring it up.
var capture = await scene.createEntity(createSplat(assetId).hideByDefault());
await capture.waitUntilReady();
await scene.toggle([capture], true);

Parameters:

• hidden (boolean) (optional) - true to start hidden, false for the normal behaviour.

Returns: ObjectTraits

flatten()

flatten(flatten?: boolean): ObjectTraits

Load a model as one mesh instead of its authored node tree. Mirrors the editor's Flatten toggle. Models only.

setInstances needs it, since instancing works on a single mesh. The cost is the hierarchy: once flattened, findChild, getChildNames and per-node material targeting have no nodes to work with.

Example:

createModel(assetId).flatten().fittingBox(0.2);

Parameters:

• flatten (boolean) (optional) - true to collapse the model, false to keep its nodes.

Returns: ObjectTraits

opacity()

opacity(opacity: number): ObjectTraits

Set opacity adjustment

Parameters:

• opacity (number) - Opacity value (0.0 to 1.0)

Returns: ObjectTraits

shadow()

shadow(options: Object): ObjectTraits

Configure how this object interacts with the scene's two shadow systems. Mirrors t.physics({…}) / t.gestures({…}): pass only the keys you want to change.

Example:

// A dense instanced field: skip the directional shadow it can't render cleanly.
createBox(0.03, 0.03, 0.03).shadow({ directional: false });

Parameters:

• options (Object)
• options.directional (boolean) (optional) - Cast a shadow from the scene's directional light (the main projected shadow). Set false where it isn't wanted – e.g. a dense instanced field, whose many small copies alias the shared shadow map into streaks.
• options.grounding (boolean | Object) (optional) - The soft AR contact shadow beneath the object. true to cast it, or an object to configure: { casts?: boolean, receives?: boolean, fadeNearObjects?: boolean } – receives takes grounding shadows cast by other objects; fadeNearObjects fades the shadow as it approaches detected physical surfaces (otherwise constant).

Returns: ObjectTraits

material()

material(materialOrId: string | Material, target?: Object): ObjectTraits

Apply a material – either a library reference by ID or an inline Material instance.

Parameters:

• materialOrId (string | Material) - Library material ID, or a Material instance.
• target (Object) (optional) - Optional target override.
• target.type (string) (optional) - "allModels", "firstModel", or "selectedModels"
• target.models (Array) (optional) - Array of model names (for selectedModels)
• target.materialSlots (Array<number>) (optional) - Material slot indices

Returns: ObjectTraits

physics()

physics(options: Object): ObjectTraits

Give the object a physics body so it can collide, fall, and be pushed.

Mirrors the editor's Physics inspector, so anything set here stays visible and editable there. Sub-groups are written only when you supply at least one of their keys – t.physics({ mode: 'static' }) produces a plain static body with no mass, damping, or material overrides.

Physics also needs scene-level setup: enable the floor mesh and scene mesh collisions in the scene's settings, or bodies will fall forever.

Example:

// A ball you can throw.
createSphere(0.05).physics({
    mode: 'dynamic', shape: 'sphere', mass: 0.15, restitution: 0.4
});

Parameters:

• options (Object)
• options.mode (string) - "static" (never moves, others collide with it), "dynamic" (gravity, impulses, collisions), or "kinematic" (you move it; it pushes others but isn't pushed).
• options.shape (string) (optional) - Collision shape: "box", "sphere", or "convex" (hull of the object's geometry).
• options.mass (number) (optional) - Mass in kilograms. Omit for the default.
• options.gravity (boolean) (optional) - Whether the body reacts to gravity.
• options.linearDamping (number) (optional) - How quickly movement slows on its own, like drag.
• options.angularDamping (number) (optional) - How quickly spin slows on its own.
• options.friction (number) (optional) - Resistance to sliding.
• options.restitution (number) (optional) - Bounciness. 0 lands with a thud.
• options.translationLock (Object) (optional) - { x, y, z } booleans constraining movement.
• options.rotationLock (Object) (optional) - { x, y, z } booleans constraining rotation.

Returns: ObjectTraits

gestures()

gestures(options: Object): ObjectTraits

Let the user move, rotate or resize this object with a gesture, and choose what happens when they let go.

Omit a gesture to leave it disabled – an object with no gestures configured cannot be manipulated at all.

Example:

// A ball you can pick up and throw. Trait methods chain directly on the descriptor.
createSphere(0.06)
    .physics({ mode: 'dynamic', shape: 'sphere', mass: 0.2 })
    .gestures({ drag: true, releaseBehavior: 'momentum', momentumScale: 0.6 });

Parameters:

• options (Object) - Gesture configuration.
• options.drag (Object | boolean) (optional) - Drag/move the object. true enables it on all axes, or pass { axes: { x, y, z } } to restrict which axes it may move along.
• options.rotate (Object | boolean) (optional) - Rotate the object. true enables it on all axes, or pass { axes: { x, y, z } }.
• options.resize (Object | boolean) (optional) - Scale the object. true enables it on all axes, or pass { axes: { x, y, z }, minScale, maxScale }.
• options.releaseBehavior (string) (optional) - What the object does when released:
  • 'stay' – stays where it was let go, then falls under gravity if it has a dynamic body.
  • 'reset' – animates back to where the gesture started.
  • 'momentum' – keeps the motion the gesture gave it. A flick throws it; a slow release lets it drift. Requires a dynamic physics body.
• options.momentumScale (number) (optional) - Scales the released linear velocity when releaseBehavior is 'momentum'. 1.0 is the object's true world-space speed, which usually feels too fast on a touchscreen – a finger flick maps to a large velocity once projected out to the object's distance. Lower it for a gentler toss.
• options.angularMomentumScale (number) (optional) - Scales the released spin. Kept below the linear scale because gesture-derived spin is noisy and tumbles heavily at full strength.
• options.disableAudio (boolean) (optional) - Suppress the built-in interaction sound.

Returns: ObjectTraits

set()

set(path: string, value: any): ObjectTraits

Directly set a property path in traits

Parameters:

• path (string) - Dot-separated path (e.g., "modelAdjustments.flatten")
• value (any) - Value to set

Returns: ObjectTraits

build()

build(): Object

Build and return the traits object

Returns: Object