3D

Overview

The 3D face allows you to create vAtoms that are displayed as 3D objects. 3D objects can have animations, and can change depending on certain conditions, such as when the user taps it.

We currently support binary glTF 2.0 for vAtom models.

Registering the face

This example below shows how to register the 3D face onto your vatom's template.

POST /v1/publisher/face

{
    "template": "MyTemplateName",
    "display_url": "native://generic-3d",
    "package_url": ".",
    "constraints": {
        "bluetooth_le": false,
        "contact_list": false,
        "gps": false,
        "three_d": true,
        "view_mode": "engaged",
        "platform": "generic",
        "quality": "high"
    },
    "config": {}
}

Face configuration

All fields in the face's config object are optional.

Field name	Type	Default value	Description
`placeholder_image`	string	`"ActivatedImage"`	The name of the image resource to be displayed while the 3D model is being downloaded.
`scene`	string	`"Scene"`	The name of the resource containing the model file.
`animation_rules`	array	`[]`	Rules for controlling which animation is displayed.

Animation rules

Each object in the animation_rules array contains a trigger which describes when to play a certain named animation. If no animation rules are present, the first animation in the model is played on a loop.

On start

This is triggered when the model is loaded. You can use this to specify which animation should play on startup.

{ "on": "start", "play": "MyAnimationName" }

On click

This is triggered when the user clicks on the 3D object. You can optionally specify a target field, which limits this trigger to only run if the specified animation is currently playing.

{ "on": "click", "target": "WalkAnimation", "play": "RunAnimation" }

On animation complete

This is triggered when an animation completes. This can be used to loop an animation (by specifying the same value for target and play) or to transition to another animation when one animation ends.

{ "on": "animation-complete", "target": "Walking", "play": "Walking" }

{ "on": "animation-complete", "target": "FallDamage", "play": "StandIdle" }

On vatom state

This event is fired when a vAtom property matches a certain value. This can be used to control the animation from a reactor or server-side state change.

{ "on": "state", "target": "private.myfield", "value": "myvalue", "play": "Anim1" }

Example

This example plays Walking on a loop until the user clicks it, then plays Running on a loop:

"animation_rules": [
  { "on": "start", "play": "Walking" },
  { "on": "animation-complete", "target": "Walking", "play": "Walking" },
  { "on": "click", "play": "Running", "target": "Walking" },
  { "on": "animation-complete", "target": "Running", "play": "Running" }
]

Embedding in your own viewer

The renderer for this face is provided as a separate module, and not embedded into the SDKs. To use the 3D face from your own viewer, you can import the module. See the readme for more information.

Info