Skip to content

Dynamic Objects

The Dynamic Object component allows you to track the position and state of different game objects during a user session. These can be used to track things like controllers, AI characters, and interactive objects.

Dynamic Objects

We take snapshots of Dynamic Objects the same way we take snapshots of a player's Gaze.

Step 1: Register the object

First, you need to register an object with 

c3d.dynamicObject.registerObjectCustomId(name, meshName, customId position, rotation);

  • name: the name of this object. For example: "SodaBottle"
  • meshName: a name of a mesh which represents this object in SceneExplorer.
  • customId: the ID of an object*
  • position: the initial position of an object
  • rotation: the initial rotation of an object

* This Id can be any unique string. The CustomId allows us to track aggregated metrics on this object.

If you do not need metrics on your objects, you can use 

c3d.dynamicObject.registerObject(name, meshname, position, rotation)
which does not take a CustomId. This function returns a generated objectId (similar to the customId in the registerObjectCustomId method). This is useful for things like bullets or other objects that don't require metrics associated with them but are useful for viewing in SceneExplorer.

Step 2: Take an object snapshot

Like with Gaze, you must take snapshots of your Dynamic Objects. You can do this with the addSnapshot function.

c3d.dynamicObject.addSnapshot(objectId, position, rotation, props /*optional*/);
  • objectId: the Id associated with this object. If you registered a customId, that's where this goes. If you did not register a customId, you can use the generated value from the registerObject method.
  • position: the current position in world space of the object
  • rotation: the current Quaternion rotation in world space of the object
  • props: additional properties of the object, for now only "enabled" is available. "Enabled" should be toggled on at the start, and turned off again when an object is no longer active in the scene.
// Set some example variables:
let rot   = [0, 0, 0, 0];   // Quaternion rotation of object
let pos   = [1, 2, 3];      // X Y Z position of object
let props = {enabled: true} // Object props. Only "enabled" is available for now. 

// Register your Dynamic Object:
const myExampleGeneratedObjectId = c3d.dynamicObject.registerObject("myObject", "someObjectMesh", pos, rot);

// Create first snapshot:
c3d.dynamicObject.addSnapshot(myExampleGeneratedObjectId, pos, rot, props);

Object Engagements

Object Engagements allow you to record precise information about how a user manipulates objects in the scene. An Engagement could represent a state such as grabbing an object, proximity to an object, pointing to an object, etc. Generally we recommend calling the Engagement APIs when a user manipulates the object with their hand(s).

To begin or end an Engagement, call the beginEngagement OR endEngagement function on the dynamicObject class.

beginEngagement(objectId, engagementType, parentId);
  • objectId: The Id of the object that is being engaged with.
  • engagementType: The type of engagement that is happening. This is customizeable. For example: "Grab"
  • parentId: The objectId of the parent which is engaging with the object. This is generally the controller that is grabbing the object.

The example below shows how you could implement an Engagement onto a grab event:

function myStartGrab() {

    // some grabbing code for your app...

    c3d.dynamicObject.beginEngagement('1', 'grab', 'right_hand');
}

To end an engagement:

function myEndGrab() {

    // some end grabbing code for your app...

    c3d.dynamicObject.endEngagement('1', 'grab', 'right_hand');
}