Migrating from v3 to v3.3
Overview
From version 3.0 to 3.3, each release has seen relatively significant modifications. This article will assist you in smoothly updating from your current version to the latest one.
3.0 to 3.1
From 3.0 to 3.1, we introduced progressive loading for the first time, which means loading the core package first and then other assets. Functionally, we primarily provided AEC support for Windows (with Mac support coming in version 3.3.1) and microphone support for WebGL.
3.1 to 3.2
Continuing the modular approach, the transition from 3.1 to 3.2 mainly involved architectural changes: we integrated the core package Assets/Inworld/Inworld.AI
directly into the Package. This is primarily to prepare for the direct use of the core package in future Inworld Unity playgrounds.
3.2 to 3.3
The update from 3.2 to 3.3 represents the second-largest set of changes so far, mainly aimed at reducing connection times with the server. We altered the connection logic. Given the significant API changes between versions 3.2 and 3.3, we have created this document to explain them.
Connection Mechanism Adjustment
Due to the server-side behavior where a session is terminated if there's no interaction within 2 minutes, which is quite common in actual game design where there can be more than 2 minutes, even up to 2 hours of zero interaction, we made a significant change prior to version 3.3. When the game starts, if the AutoStart
setting of the InworldController
is set to true, the system would automatically reconnect whenever the server-side disconnects due to inactivity. This approach was aimed at maximizing stability but at the cost of increased overhead for both parties.
With server-side code adjustments in version 3.3, we refined the algorithm. AutoStart
is now a thing of the past. The client will not connect to the server until the player sends any text or a character is selected again. At that point, the server will connect to the client and resend the previously cached, unsent data.
Character-Based Approach
API Parameter Adjustments
When each LiveSession
is established, a new LiveSessionID
is assigned to each character (different from the previous LiveSession). When users send text or audio, the underlying API parameters actually target this LiveSessionID
. In the new system, to prepare for future multi-character interactions and the broadcasting system, in version 3.3, all Unity-side functions like SendText
and SendAudio
will no longer use SessionID
as a parameter. Instead, they will use a list of Character IDs (not character names, as this parameter uniquely identifies characters).
Our system will automatically establish a connection, acquire the SessionID, and send the data. For compatibility with previous versions, we have retained the old SendText and SendAudio APIs that take a SessionID as a parameter. The new APIs, currently used by all demos, are named SendTextTo, SendAudioTo, etc.
More Character Events
In version 3.3, we provide more detailed UnityEvents for each character that users can invoke. These events cover various common situations, such as characters entering or leaving a conversation, being selected, or being deselected. Most of these events have added a new parameter, the Character ID of the character.
Decoupling of InworldController
Previously, many users reported that our InworldController took on too many responsibilities. In version 3.3, we've changed this setup. Specific functionalities are now carried out by other Components on the InworldController GameObject, such as CharacterHandler and AudioCapture. InworldController itself does not carry any functionality; users can remove the InworldController and only need to maintain the scripts built on top of it.
Additionally, to maintain compatibility with previous versions, we have retained InworldController, which now serves as an API Hub. It can receive all the original APIs and then delegate them to the specific Components attached to it.
Following these changes, InworldController's own Events, especially OnCharacterInteraction
, will be removed. To implement a system that listens to all character Packets, you now need to register with CharacterHandler's OnCharacterJoined/Left events. Here, you would register the events corresponding to the specific character.