# OptiTrack Godot Plugin

## Overview

The OptiTrack Godot Plugin enables real-time streaming of Rigid Body data from Motive into Godot for visualization and recording.

{% embed url="<https://youtu.be/KoKBG98iSOg>" %}

### Requirements

* Godot version 4.6 or higher. Download the Godot software from the [godotengine.org download page](https://godotengine.org/download/windows/). &#x20;
* Motive version 3.4 or higher.

## Godot Setup

### Download the Plugin

The OptiTrack Godot plugin is available from the [OptiTrack Plugins download](https://optitrack.com/software#motive-streaming-plugins) page. &#x20;

* Once downloaded, unzip the plugin to a local directory.&#x20;
* In Windows Explorer, open the extracted folder, *optitrack-godot-plugin\_1.0.0*, then open the ***example-project*** folder. Leave this folder open for a future step.&#x20;

### Import into the Godot Project

* Open Godot, version 4.6 or higher.&#x20;
* The Project Manager window will open.&#x20;

<figure><img src="/files/TvcnVjdW3dr1BmJWvGDA" alt="A screenshot of the Godot Project Manager screen, with no projects in the list. "><figcaption></figcaption></figure>

* Click the ![A screenshot of the Create button on the Godot Project Manager screen. ](/files/JZPCkOUjstxifYEDjwLP) Create button in the upper left.&#x20;
* Assign a Project Name and Browse to select the location to save the project.&#x20;

<figure><img src="/files/HTmP7dkc3EHf7H0qnH8U" alt="A screenshot of the Godot Create Project screen. "><figcaption></figcaption></figure>

* Click the ![A screenshot of the Create button that saves the Godot project. ](/files/ZduxBtOBV7zJWh88sufd) Create button at the bottom of the screen to open the project.
* Return to the Windows Explorer window where the extracted folder *optitrack-godot-main* is ope&#x6E;*.* Open the *example-project* folder and drag the ***addons*** folder into the *FileSystem* tab in Godot.&#x20;

{% hint style="info" %}
If your project already has a folder called ***addons***, open the plugin's *addons* folder and copy the folder named ***optitrack\_plugin*** into the project's existing *addons* folder.&#x20;
{% endhint %}

<figure><img src="/files/KxeaAjAoyvGPNvdB6eSu" alt="A screenshot of the Godot application just after dragging the OptiTrack Godot plugin addins folder into the Godot fileshare tab. "><figcaption></figcaption></figure>

{% hint style="info" %}
You may see several error messages after the application finishes registering global classes, even though the plugin has installed successfully. Look for the *optitrack\_plugin* in the *addons* folder in the Godot File System to verify that the installation completed.&#x20;
{% endhint %}

### Activate the Plugin in Godot

Now that the plugin is available in the project, it needs to be activated.&#x20;

* From the *Project* menu, go to *Project Settings...*

<figure><img src="/files/KRplVpCGMp9TJxxtQO02" alt="A screenshot of a project in Godot, with the Project menu open. "><figcaption></figcaption></figure>

* Open the Plugins tab.&#x20;
* Find the Optitrack plugin in the list and check the box to Enable it.&#x20;
* Click Close to return to the project.&#x20;

<figure><img src="/files/WiPK5vNyTIXmZMNyFC0d" alt="A screenshot of the Godot Project Settings, Plugins tab, with the Optitrack plugin enabled. "><figcaption></figcaption></figure>

The OptiTrack tab will now be available in the left-most pane, along with the File System and History tabs. You may need to expand the width of the pane to see all three.&#x20;

Once the plugin is enabled, restart Godot.&#x20;

<figure><img src="/files/kj0KDJcjZgXQRpz0RZX7" alt="A screenshot of the Optitrack pane in Godot. "><figcaption></figcaption></figure>

## Motive Setup

#### Enable Streaming

In Motive, click the ![A screenshot of the Streaming Settings button from the Motive Control Deck. ](/files/0wQpGdHfrbF43J0lLS2j) Streaming Settings button in the bottom right corner of the Control Deck. &#x20;

To stream to Godot, make sure Streaming is enabled in the NatNet settings and the Transmission Type is set to Multicast.&#x20;

To stream skeletons, set the Skeleton Coordinates to Local and the Bone Naming Convention to FBX. The skeleton should also be set with a Y-up axis.&#x20;

For more information about streaming from Motive, please see the [Data Streaming](/motive/data-streaming.md) page.&#x20;

<figure><img src="/files/EMUiYnXtwezpybMIFPC8" alt="A screenshot of the Motive Streaming Settings, with the &#x22;Enable&#x22; setting turned on and the &#x22;Transmission Type&#x22; setting set to Multicast. Both settings are highlighted. "><figcaption></figcaption></figure>

#### Create Assets in Motive

In Motive, create the Skeletons and Rigid Bodies that you wish to stream into Godot. Refer to the [Skeleton Tracking](/motive/skeleton-tracking.md) page and the [Rigid Body Tracking](/motive/rigid-body-tracking.md) page for detailed instructions on how to create a Skeleton or Rigid Body in Motive.&#x20;

Once you have assets to track in Motive, you're ready to stream them into Godot.&#x20;

## Godot Plugin Connection Setup

Now that Motive is streaming, you're ready to configure the object connection in Godot.&#x20;

### Create an OptiTrack Rigid Body Node

In the Scene pane, in the Create Root Node options, click *3D Scene*.&#x20;

<figure><img src="/files/i7wxTYnFZL6PJcjwWH7g" alt="A screenshot of the Scene pane in Godot, with the options to Create Root Node: shown. "><figcaption></figcaption></figure>

The Scene pane will change to show Node3D. The Inspector tab will display on the right.&#x20;

* Right click Node3D to access the context menu, then select *Add Child Node...*&#x20;

<figure><img src="/files/zWIltRM4XDZVhEBXLqcP" alt="A screenshot of the Godot project screen, with the context menu for the Node3D options displayed. "><figcaption></figcaption></figure>

The Create New Node window will open.&#x20;

* Type Optitrack in the search bar and press enter.&#x20;
* The search results will return *OptiTrackRigidBody*.&#x20;
* Select *OptiTrackRigidBody* then click the Create button at the bottom.&#x20;

<figure><img src="/files/wA28fpYTJfhqx5WZW9HJ" alt="A screenshot of the &#x22;Add Child Node&#x22; screen, with OptiTrack in the search criteria and OptiTrackRigidBody as the sole search results. " width="563"><figcaption></figcaption></figure>

The child node will appear in the Scene pane. To see the list of rigid body assets from Motive in the OptiTrack pane, click the *Start Connection* button. &#x20;

<div><figure><img src="/files/mkhVgnb2pUTYu41LLAxW" alt="A screenshot of the Godot Scene and OptiTrack panes, with the OptiTrackRigidBody child node added and the Streaming Connection stopped. "><figcaption></figcaption></figure> <figure><img src="/files/bxjpL3y1SoGmjoPS6ZNg" alt="A screenshot of the Godot Scene and OptiTrack panes, with the OptiTrackRigidBody child node added and the Streaming Connection enabled."><figcaption></figcaption></figure></div>

#### Add a Mesh

Apply a mesh to visualize the rigid body in the scene.&#x20;

* In the Scene tab, right click *OptiTrackRigidBody* and select *Create Child Node*.&#x20;
* Search for *MeshInstance3D*. When found, select it and click *Create*.&#x20;

<figure><img src="/files/AbdcFooeWGF4lC8wOlsI" alt="A screenshot of the Godot &#x22;Add Child Node&#x22; search results,with MeshInstance3d selected. " width="563"><figcaption></figcaption></figure>

* The MeshInstance3D properties will display in the Inspector Window.&#x20;
* Click the dropdown menu in the Mesh field to select a mesh. For testing, we recommend selecting a primitive mesh, such as a box or a sphere.&#x20;
* Once the mesh is applied, a graphical representation will display in the Inspector tab as well as in the 3D scene.&#x20;

<div><figure><img src="/files/Rm47F4dXLelt5BdPPCtC" alt="A screenshot of the Godot Inspector tab, showing the properties for the MeshInstance3D child node. No mesh has been applied yet. "><figcaption><p>Before a Mesh is added.</p></figcaption></figure> <figure><img src="/files/3uUQNT72dS5MZTw9IWw4" alt="A screenshot of the Godot Inspector tab, showing the properties for the MeshInstance3D child node. The dropdown menu to apply a mesh is open. "><figcaption><p>Adding the Mesh.</p></figcaption></figure> <figure><img src="/files/yKTvmDDHDY9JSyS3EaF4" alt="A screenshot of the Godot Inspector tab, showing the properties for the MeshInstance3D child node. A Box Mesh is now applied. "><figcaption><p>Mesh is now applied. </p></figcaption></figure></div>

<figure><img src="/files/a9noHEreezc7eqcmKBYK" alt="A screenshot of the Godot 3D perspective window, with a box mesh applied to the rigid body asset.. "><figcaption><p>Mesh shown in the 3D scene. </p></figcaption></figure>

#### Add Animation&#x20;

* &#x20;With the *MeshInstance3D* installed, select the *OptiTrackRigidBody* node in the Scene hierarchy.&#x20;
* In the Inspector panel, check the box to *Animate in Editor.*&#x20;

<figure><img src="/files/TeeePEklTzmDq94zR96O" alt="A screenshot of the top portion of the Godot Inspector tab, for the OptiTrack plugin."><figcaption></figcaption></figure>

* Use the buttons at the bottom of the OptiTrack pane to play or pause the selected take in Motive.&#x20;

<figure><img src="/files/gdiDF7ZsBewIYO9VCcDH" alt="A screenshot of the Motive Timeline Play and Motive Timeline Pause buttons from the OptiTrack plugin in Godot. "><figcaption></figcaption></figure>

### Configure Skeletons

The OptiTrack Godot plugin includes compiled skeleton assets in both gendered avatars (female and male) for each spine model (the classic 3-segment spine or the default 7-segment spine), for a total of four skeleton options:

* OptiTrackAvatarFemale3.tscn
* OptiTrackAvatarFemale7.tscn
* OptiTrackAvatarMale3.tscn
* OptiTrackAvatarMale7.tscn

These assets are located in the *addons* folder under *optitrack\_plugin > model scenes.*&#x20;

Before adding a skeleton to the scene, you will need to assign the mesh if using Godot 4.6 or higher. Note that these steps are *not* required if using Godot 4.5.

* double-click the .tscn file in the Godot File System. This will open the model in a new window in the 3D viewport.&#x20;

<figure><img src="/files/5iMp8WUnZvN05IkqUrig" alt="A screenshot of Godot 4.6.1 with an open .tscn file that does not have a mesh assigned. "><figcaption></figcaption></figure>

* In the Scene panel, select the Mesh. This will display the mesh properties in the Inspector panel.
* In the MeshInstance3D section, click the Assign button for the Skeleton property.&#x20;

<figure><img src="/files/4Y6p1ypxetJ2PWn68Mz5" alt="A screenshot of the Inspector tab in Godot, with an OptiTrack avatar mesh selected. The MeshInstance3D properties are shown, with the Skeleton property highlighted. This property is currently Unassigned. "><figcaption></figcaption></figure>

* Select the mesh from the list then click OK.&#x20;

<figure><img src="/files/9uRMBF7wDee2A8G2F9pp" alt="A screenshot of the Godot screen to select a mesh to assign to a skeleton. "><figcaption></figcaption></figure>

* The skeleton and avatar will now align in the 3D view:

<figure><img src="/files/plk2Y897AOU1Gseiwxaz" alt="A screenshot of Godot 4.6.1 with an open .tscn file that has a mesh assigned. "><figcaption></figcaption></figure>

* Close the tab for the .tscn file by clicking the x in the tab corner.&#x20;
* Godot will prompt to save the scene. Click OK and ignore any errors that display.&#x20;
* Repeat these steps for each avatar type that you plan to use in your scene.&#x20;

### Create an OptiTrack Skeleton Node

To add a child node for a skeleton to the project:&#x20;

* Open the *addons* folder and browse to *optitrack\_plugin > model scenes*&#x20;
* Click and drag the .tscn file that corresponds to the asset in Motive into the scene, directly below Node3D.&#x20;

<figure><img src="/files/ESPvneZx6whZLCbVX1dw" alt="A scene in Godot after an OptiTrack male avatar has been added."><figcaption><p>Adding a skeleton in Godot.</p></figcaption></figure>

* Select the skeleton to display its properties in the Inspector tab.&#x20;
* Click the Skeleton Asset ID dropdown to select the skeleton asset from Motive. &#x20;
* Make sure the *Animate in Editor* option is on.&#x20;

<figure><img src="/files/VLpZcDEe4uq3kpcVPqLk" alt="Assigning an Asset to a skeleton in Godot. "><figcaption></figcaption></figure>

* Click the *Refresh Asset List* button if the list of assets in the dropdown differs from the loaded Take in Motive.

<figure><img src="/files/HAawWCeXzefyObLvNsBB" alt="Skeleton Asset ID - unassigned in Godot, with the Refresh Asset List button. "><figcaption></figcaption></figure>

The skeleton should now animate properly in Godot.&#x20;

<figure><img src="/files/Mgn5C70GjgcBQqr7LqEQ" alt="Side-by-side screenshots of the same skeleton in Motive and in Godot. "><figcaption></figcaption></figure>

## Troubleshooting

If the object does not animate:&#x20;

* Restart Godot.
* Reopen the project.
* Click *Start Connection* again.

In most cases, the data stream will reconnect successfully after restarting.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.optitrack.com/plugins/optitrack-godot-plugin.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.