Appearance

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(…)), which expose the same configuration and chain.

Instance Methods ​

transform() ​

javascript
transform(transform: Transform): ObjectTraits

Set initial transform

Parameters:

Returns: ObjectTraits

fittingBox() ​

javascript
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() ​

javascript
pivot(pivot: string): ObjectTraits

Set pivot adjustment

Parameters:

  • pivot (string) - "automatic", "top", "center", or "bottom"

Returns: ObjectTraits

opacity() ​

javascript
opacity(opacity: number): ObjectTraits

Set opacity adjustment

Parameters:

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

Returns: ObjectTraits

shadow() ​

javascript
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:

javascript
// 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() ​

javascript
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() ​

javascript
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:

javascript
// 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() ​

javascript
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:

javascript
// 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() ​

javascript
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() ​

javascript
build(): Object

Build and return the traits object

Returns: Object