Unity Integration

This guide is a walk-through of adding the Inhumate RTI Unity client to a project and getting it up and running for co-simulation purposes.

Getting started

Adding the package

TODO Package Manager…

Scaffold a Unity-based RTI simulator

Let’s make a home scene, which is a scene to be loaded when the simulator is not running. Kind of like a lobby.

  1. Create a new scene, name it something like Home and open it.
  2. Create an empty game object.
  3. Add an RTI Runtime Control GUI component. This is really handy for development. Notice the Scenario To Load parameter, by default specifying Demo which refers to the next step.

Now let’s make a scenario scene, which is a scene to be loaded when the simulator is requested to load a specific scenario.

  1. Create another new scene, name it Demo (or whatever you specified in the previous step) and open it.
  2. Put something visible into the scene, like a plane or cube in front of the main camera.
  3. Open File > Build Settings… and drag your two scenes Home and Demo into the Scenes In Build list. Make sure Home has index 0.
  4. Open the Home scene again, and press play.
  5. Press the Load button, and your scenario scene should be loaded.
  6. Press the Start button, notice the clock ticking.
  7. Press the Stop button, and you should get back to your home scene.

Congratulations, you now have a well-behaved RTI-enabled simulator! You can fire it up, load, start, pause, stop, and do it all over again as often as you please. Try controlling it from the RTI control panel or command line.

Spawn co-simulated entities

Entities are objects/actors that exist in the co-simulation “world”, and their life cycle (create -> destroy) and state (more on that later) are synchronized via the RTI.

  1. Create a cube in your Demo scene hierarchy.
  2. Add an RTI Entity component, set its Type property to cube.
  3. Add an RTI Position component.
  4. Make it a prefab by dragging the cube from the Hierarchy view into your Project view.
  5. Delete the cube from the scene.
  6. Create an empty game object.
  7. Add an RTI Spawner component.
  8. For the Spawnable Entities property, add an element with type set to cube and drag your cube prefab into the prefab property.

Now, if you play the scene, you can spawn and destroy a cube using the RTI CLI:

# create a cube
rti entity create --id thecube cube 0 1 2.5
# look around and find it with the editor camera, then move it
rti entity position thecube 2 2 2.5
# then destroy it
rti entity destroy thecube

Spawn a player

Your scenario scene is loaded upon reception of a load scenario message. At that point, no entities should be created. You need to spawn the player when the simulation starts, not when the scene is loaded. You also need to either:

  • create a “remote representation” prefab that the RTI Spawner can use for playback, or
  • use the same prefab but adapt your scripts to differentiate between simulation and playback behavior. Use the RTIEntity.publishing and RTIEntity.receiving properties for that.

Custom (project-specific) messages

Now let’s start digging into adding more functionality than just runtime control, entities and their whereabouts.

Pubsub custom messages (string or JSON) 

RTIConnection.Instance.Publish("mychannel", "my message");
RTICOnnection.Instance.PublishJson("mychannel", mySerializableObject);

Pubsub custom protobuf messages

TODO. Adding .proto, compiling it, publishing/serializing and subscribing/parsing.

Custom entity state messages

TODO. Add a .proto, derive from RTIEntityBehaviour class.

Scenario loading

Part of the runtime control standard message is a load scenario message, and querying for available scenarios. The default behavior of the Unity package is to load a home level on startup and stop message, and when a load scenario message is received, lookup the name in the scenarios list (which is populated with the scenes in build settings by default, or can be specified with Scenario objects in the editor) in the RTIConnection, and then load a scene with the same name as the scenario. This behavior can be overridden in a script that:

  • fills the RTIConnection.scenarios list with names of scenarios that can be loaded
  • implements delegates for RTIConnection.OnLoadScenario and RTIConnection.OnStop events

See RTITestCustomScenarioLoading.cs for an example.

Copyright © Inhumate AB 2024