Skip to main content

Migrating from v2 to v3


Our Unity Integration has had a few significant changes between v2 and v3. Chief among them being a modular transport layer for client-server communication that allows you to switch between using Unity Websockets as well as a NDK implementation.

Inspector Component Changes

The screenshot below shows v3 on the left utilizing the NDK as the transport layer and v2 on the right to show differences in the context of their Unity Editor components and references.

The Inworld Controller script will need:

  • The full name of your scene in the format workspaces/[your-workspace-name]/scenes/[your-scene-name]

  • A corresponding client script reference (either Inworld NDK Client or Inworld WebSocket CLient) set accordingly

The Inworld Client script will need:

  • The API key and secret corresponding to the workspace being used in this scene

  • The Server Config reference provided with the integration

Inworld Controller

Callback Changes

Our callbacks have also changed and been extended. Any scripts that are setup to add listeners to these callbacks will need to be refactored to account for updated names such as:

  • OnStateChanged -> OnStatusChanged
  • RuntimeEvent -> OnStatusChanged
  • OnBeginSpeaking -> onBeginSpeaking
  • OnFinishedSpeaking -> onEndSpeaking
  • OnCharacterSpeaks -> onCharacterSpeaks
  • OnGoalCompleted -> onGoalCompleted

The screenshot below serves to illustrate the corresponding events between v2 and v3.

Inworld v2 & v3 Events/Actions

The Inworld Character script has also been extended to have events for onPacketReceived and onEmotionChanged

The onPacketReceived event now exists on a per character basis in the InworldCharacter script as well. This event is invoked through the onPacketReceived event in the InworldClient script any time a packet is received from the server (the chain of events is represented in red in the above screenshot going from the Client script to the Interaction script and finally to the corresponding Character script).

Inworld Interaction adding listener

The OnInteractionChanged method in the InworldCharacter script is added as a listener to the Action with the same name in the InworldInteraction script as shown in the screenshot above. The screenshot below shows how said method in turn invokes the character specific onPacketReceived event.

Inworld Character Event Chaining

Migration Process

Note: Before proceeding with any changes, please make a copy or backup of your project to ensure you do not lose anything and to use as reference.


  • Remove v2 of the Inworld AI integration from your project being careful not to remove any necessary assets, models, textures, etc such as for ReadyPlayerMe characters

  • Add v3 of the Inworld AI integration to your project

  • At this point you will have various missing script references

  • Replace the obsolete PlayerController object in the relevant scenes and nested prefabs with one of the updated PlayerController prefabs which most suits your purpose

  • Replace the obsolete Inworld Controller missing script reference with the one provided in v3 and ensure a valid client reference and Scene Full Name are set

  • Ensure the Client script has the correct API key and secret corresponding to the Inworld Scene

  • Replace the obsolete InworldCharacter missing script reference with the updated v3 InworldCharacter script or one of it's derived scripts which best suits your use case

  • Ensure the Data field has a valid corresponding Brain Name for the chosen character which can be obtained from the url of your character on Inworld Studio

Inworld Character Brain Name

  • Add Inworld Body Animation, and Facial animation scripts as necessary

  • Add any missing Unity Event scene references again

Inworld Character v3

  • Resolve compile errors where necessary by refactoring any scripts using obsolete callbacks to utilize the updated and new Actions & Events detailed above accordingly