# OptiTrack Godot Plugin

## Overview

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

### 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 on GitHub in OptiTrack's optitrack-godot repository:&#x20;

{% embed url="<https://github.com/OptiTrack/optitrack-godot>" %}

* Click the green ![A screenshot of the <> Code button in Github. ](https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2FCuH0IbYfspQcRgOVKC2u%2FGithub%20Code%20download%20button.png?alt=media\&token=c3990b05-eb45-4eba-b5c4-9e752cc6a1ce) code button at the top of the file list.&#x20;
* Select **Download ZIP** to download the plugin locally.&#x20;

<figure><img src="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2FShzxRaa2WSuOuij1WL8E%2FGodot%20Plugin%20-%20how%20to%20download.png?alt=media&#x26;token=2939ac08-0c55-4f3e-a644-96aa0832bd70" alt="A screenshot of the OptiTrack\optitrack-godot repository in GitHub, with the code button activated to show the menu options. Download ZIP is at the bottom of the list. "><figcaption></figcaption></figure>

* Once downloaded, unzip the plugin to a local directory.&#x20;
* In Windows Explorer, open the extracted folder, *optitrack-godot-main*, 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2F3Tde0Io5hQAlyySGjOCk%2FGodot%20Create%20Project%20Step%201%20.png?alt=media&#x26;token=a5f5afd9-ad8e-41b9-9ffa-e9246427d2d5" 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. ](https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2Fe208WXpLtWrWCZm4SQ4z%2FGodot%20Create%20button.png?alt=media\&token=009daf1d-d094-4629-92ed-118557aa5796) 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2F18ReObkd1jycgrd0hVX4%2FGodot%20Create%20Project%20Step%202.png?alt=media&#x26;token=23adb637-02b5-4e4f-bd26-3e5d1ed3e72e" 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. ](https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2Fj83874L3eUS2Js5qnHZ5%2FGodot%20Create%20Project%20Step%202%20-%20Create%20button.png?alt=media\&token=6e4fda9c-e456-4763-b64a-cbdc577d66d8) 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2Fl8Yumepho6OlWRstJKNG%2FGodot%20-%20Activate%20OptiTrack%20plugin%20Step%201%20-%20Drag%20Addons%20to%20project.gif?alt=media&#x26;token=2d5422d2-7b8f-4405-99b6-ec6ea1ca5568" 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2FtVt2ItFAt521MoNC5vkB%2FGodot%20-%20Activate%20OptiTrack%20plugin%20step%203%20-%20open%20Program%20settings.png?alt=media&#x26;token=032303fd-4a4d-44a6-a357-def624a8ac06" 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2Flp0EkOz32aZYSJY0pRxc%2FGodot%20-%20Activate%20Step%204png.png?alt=media&#x26;token=29bf6ec5-ede3-421c-ad36-1dc158f340c6" 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2FTgPtoCbx59yQK2gOeLpu%2FGodot%20-Optitrack%20pane.png?alt=media&#x26;token=3c905e50-9de0-4815-a4c4-76a6154d0c23" 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. ](https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2F0gD62JdYqNp4KEsrFOhC%2FControl%20Deck%20-%20Streaming%20Off%20SMALL.png?alt=media\&token=f954eab1-adf8-49d9-9b82-6ce88ff2c5a8) 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;

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

<figure><img src="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2FXVxlkgny0dBfEYEPxpXy%2FMotive%20-%20Streaming%20Settings%20for%20Godot.png?alt=media&#x26;token=382fdac2-e0c8-4592-ae0d-cb0307ca7105" 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 Rigid Bodies

In Motive, create the Rigid Bodies that you wish to stream into Godot. Refer to the [Rigid Body Tracking](https://docs.optitrack.com/motive/rigid-body-tracking) page for detailed instructions on how to create a Rigid Body in Motive.&#x20;

Once you have Rigid Bodies 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2FHo61M8mJoGFNSjiQu4Et%2FGodot%20-Scene%20Pane.png?alt=media&#x26;token=a821d908-d13e-44e1-ba18-67df75261f92" 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2Fd8eMf6vLSu9Xv9IiGI8f%2FGodot%20-%20Add%20child%20node%20step%201.png?alt=media&#x26;token=684cc9c2-b733-4272-adfb-7fa616db9699" 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2FXjibJr0XlZq3lu97ixl4%2FGodot%20-%20Add%20Child%20Node%20-%20search%20for%20Optitrack.png?alt=media&#x26;token=6b906866-be3e-4641-bd52-2c381fc33710" 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2FmPNIJEc9tEXAozxjH5yG%2FGodot%20-%20Scene%20and%20Optitrack%20panes%20-%20Motive%20Streaming%20OFF.png?alt=media&#x26;token=345a5f9e-3703-4da9-9eb4-3d2194ca8a6a" 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2FoF17nsI3DAX0AwzksZKr%2FGodot%20-%20Scene%20and%20Optitrack%20panes%20Streaming%20ON.jpg?alt=media&#x26;token=52f98232-2add-405f-994a-8959c8567d0b" 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2FqlYLSQjqyMSv6GG1rhyU%2FGodot%20-%20Add%20MeshInstance3D.png?alt=media&#x26;token=328b18a3-eb30-4c85-872e-300a0f11b7b3" 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2FiqrCOU1jKVejAC8EiCxd%2FGodot%20-%20MeshInstance%20Inspector%20tab%20step%201.png?alt=media&#x26;token=1373fdfc-bbd8-4657-abbd-d21b3441f07a" 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2FJZUcmy0ptILc2y2J6XwC%2FGodot%20-%20MeshInstance%20Inspector%20tab%20step%202.png?alt=media&#x26;token=58154f06-4481-4ac2-ae27-7a4dd0d7cc1e" 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2FtSEG9kMmUUESJrTsTEGC%2FGodot%20-%20MeshInstance%20Inspector%20tab%20step%203.png?alt=media&#x26;token=c099fcbc-865a-4218-9d6e-404860683385" 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2FZ9FvMKif6CQZ0Dsu2wXW%2FGodot%20-%20Mesh%20applied%20in%203D%20view.png?alt=media&#x26;token=7562acea-c1c6-4731-bc7c-370d95a7ae34" 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2F9K3scQDC3fal7wpFtkrL%2FGodot%20-%20MeshInstance%20Inspector%20tab%20step%204%20-%20Animate%20in%20Editor.png?alt=media&#x26;token=9eaeec1d-fe05-4f9c-bc0f-647fd5d8bbdc" 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="https://4232084498-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGaZwzcsVav6zPBRZpapU%2Fuploads%2FlL6TIWu1eFD1jqHFr8mD%2FGodot%20-%20Motive%20Play%20and%20Pause%20buttons.jpg?alt=media&#x26;token=4dc75302-bba2-4ed6-b13b-6f417b8d4912" alt="A screenshot of the Motive Timeline Play and Motive Timeline Pause buttons from the OptiTrack plugin 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.
