Real-time Multi-user Status Synchronization
Function Overview
The real-time multi-user status synchronization function provides an ordered, high-frequency, low-latency, and large-scale status synchronization service, helping developers quickly implement real-time information synchronization capabilities such as player positions, actions, and appearances in virtual gameplay, while supporting 10,000 users online simultaneously in a single scenario.
In large virtual worlds, users generally do not need to perceive distant scenarios or remote users. ZEGO provides AOI (Area Of Interest) capability to reduce the acquisition of information outside the user's visible range, greatly reducing customer traffic costs, user-side traffic, and performance consumption.
This feature is not supported in WebGL environments.
Concept Explanation
- Scene: Users need to login to the scene first, and only users who enter the same scene can synchronize status information.
- AOI (Area of interest) range: The square size of the area of interest to the user, which is generally the user's visible range in the virtual scene. This range follows the user's position in real time and will only synchronize information about remote users within the AOI range.
Application Scenarios
- Metaverse scenarios such as virtual offices, virtual exhibitions, virtual social networking, and virtual KTV.
- General scenarios that require ultra-high frequency, low latency, and large-scale synchronization of information or control commands.
Prerequisites
Using this service will incur corresponding fees. Please contact ZEGO business personnel to learn about the specific fee structure.
Before implementing status synchronization, please ensure:
- You have contacted ZEGOCLOUD Technical Support to perform special packaging and enable the status synchronization service.
- You have integrated ZEGO Express SDK in the project.
- You have created a project in ZEGOCLOUD Console and applied for valid AppID and AppSign. For details, please refer to Console - Project Management.
Implementation Flow
1 Create engine
Call the CreateEngine interface and pass the applied AppID and AppSign into the parameters "appID" and "appSign" to create an engine singleton object. The engine currently only supports creating one instance at a time. If exceeded, it will return null.
/** Define SDK engine object */
ZegoExpressEngine engine;
ZegoEngineProfile profile = new ZegoEngineProfile();
/** Please obtain through official website registration, format is 123456789 */
profile.appID = appID;
/** 64 characters, please obtain through official website registration, format is "0123456789012345678901234567890123456789012345678901234567890123" */
profile.appSign = appSign;
/** General scenario access */
profile.scenario = ZegoScenario.Default;
/** Create engine */
engine = ZegoExpressEngine.CreateEngine(profile);2 Create range scene module
Call the CreateRangeScene interface to create a range scene instance. Currently only supports creating one instance at a time. If exceeded, it will return null.
/** Define range scene object */
ZegoRangeScene rangeScene;
/** Create range scene */
rangeScene = engine.CreateRangeScene();3 Listen to range scene event callbacks
Set range scene event delegates as needed to listen to range scene status, login status, enter/exit AOI notifications, etc. By setting range scene item management class event delegates, listen to events such as items entering/leaving the AOI range, item binding status changes, item status and command updates.
/** Range scene event callback */
public void OnSceneStateUpdate(ZegoRangeScene rangeScene, ZegoSceneState state, int errorCode) {
}
public void OnEnterView(ZegoRangeScene rangeScene, ZegoUser user, ZegoPosition position) {
}
public void OnLeaveView(ZegoRangeScene rangeScene, string userID) {
}
public void OnUserStatusUpdate(ZegoRangeScene rangeScene, string userID, ZegoPosition position, uint channel, byte[] status) {
}
public void OnUserCommandUpdate(ZegoRangeScene rangeScene, string userID, ZegoPosition position, uint channel, byte[] command) {
}
public void OnCustomCommandUpdate(ZegoRangeScene rangeScene, byte[] command) {
}
/** Range scene stream management event callback */
public void OnUserStreamStateUpdate(ZegoRangeScene rangeScene, string userID, string streamID, ZegoStreamState state) {
}
public void OnUserMicUpdate(ZegoRangeScene rangeScene, string userID, ZegoDeviceState state) {
}
public void OnUserCameraUpdate(ZegoRangeScene rangeScene, string userID, ZegoDeviceState state) {
}
public void OnUserSpeakerUpdate(ZegoRangeScene rangeScene, string userID, ZegoDeviceState state) {
}
// Set delegates
rangeScene.onSceneStateUpdate = OnSceneStateUpdate;
rangeScene.onEnterView = OnEnterView;
rangeScene.onLeaveView = OnLeaveView;
rangeScene.onUserStatusUpdate = OnUserStatusUpdate;
rangeScene.onUserCommandUpdate = OnUserCommandUpdate;
rangeScene.onCustomCommandUpdate=OnCustomCommandUpdate;
rangeScene.GetRangeSceneStream().onUserStreamStateUpdate = OnUserStreamStateUpdate;
rangeScene.GetRangeSceneStream().onUserMicUpdate = OnUserMicUpdate;
rangeScene.GetRangeSceneStream().onUserCameraUpdate = OnUserCameraUpdate;
rangeScene.GetRangeSceneStream().onUserSpeakerUpdate = OnUserSpeakerUpdate;4 Login scene
Call the LoginScene interface and pass in scene parameters: sceneID, user, position, broadcastMode to login to the scene.
- Within the same AppID, ensure that userID is globally unique. It is recommended that developers set it to a meaningful value and associate userID with their own business account system.
- userID cannot be empty, otherwise login to the scene will fail.
- Please do not call SDK interfaces in the callback OnLoginSceneCallback of the LoginScene interface, otherwise errors and crashes will occur (you can switch threads to call).
/** Login scene parameters */
ZegoSceneParam param = new ZegoSceneParam();
/** Create user */
ZegoUser user = new ZegoUser(userID);
/** Set user's scene coordinates, motion orientation, camera orientation */
ZegoPosition position = new ZegoPosition()
position.coordinate.z = self_pos[0];
position.coordinate.x = self_pos[1];
position.coordinate.y = self_pos[2];
position.motionOrientation.axisForward.z = axis_forward[0];
position.motionOrientation.axisForward.x = axis_forward[1];
position.motionOrientation.axisForward.y = axis_forward[2];
position.motionOrientation.axisRight.z = axis_right[0];
position.motionOrientation.axisRight.x = axis_right[1];
position.motionOrientation.axisRight.y = axis_right[2];
position.motionOrientation.axisUp.z = axis_top[0];
position.motionOrientation.axisUp.x = axis_top[1];
position.motionOrientation.axisUp.y = axis_top[2];
position.cameraOrientation.axisForward = axisForward;
position.cameraOrientation.axisRight = axisRight;
position.cameraOrientation.axisUp = axisUp;
/** Set scene ID */
param.sceneID = sceneID;
/** (Optional) Configure template ID */
param.templateID = template_id;
param.user = user;
param.position = position;
/** Set broadcast mode for user login scene */
param.broadcastMode = ZegoBroadcastMode.All;
rangeScene.LoginScene(sceneParam, (int errorCode, ZegoSceneConfig config) => {
});If you need to customize templates, please refer to Server API - Scene Template Configuration.
5 Synchronize status
Update user status and user commands through the UpdateUserStatus and UpdateUserCommand interfaces. Receive status information such as remote user positions and commands within the AOI range through the OnUserStatusUpdate and OnUserCommandUpdate callbacks.
- User status (status, S) is a full update, user commands are incremental updates (command, C), and user status can be calculated from a previous user status through a series of user commands.
- The model for user status updates should be Si->Ci->Ci+1->Ci+2->...Ci+j->S(i+1)->C(i+1)+1->C(i+1)+2->...C(i+1)+k->S(i+2)->C(i+2)->...
- The status synchronization service will ensure that incremental updates (command) between two full status (status) Si and Si+1 arrive in order.
/** Set user's scene coordinates, motion orientation, camera orientation */
ZegoPosition position = new ZegoPosition();
position.coordinate.z = self_pos[0];
position.coordinate.x = self_pos[1];
position.coordinate.y = self_pos[2];
position.motionOrientation.axisForward.z = axis_forward[0];
position.motionOrientation.axisForward.x = axis_forward[1];
position.motionOrientation.axisForward.y = axis_forward[2];
position.motionOrientation.axisRight.z = axis_right[0];
position.motionOrientation.axisRight.x = axis_right[1];
position.motionOrientation.axisRight.y = axis_right[2];
position.motionOrientation.axisUp.z = axis_top[0];
position.motionOrientation.axisUp.x = axis_top[1];
position.motionOrientation.axisUp.y = axis_top[2];
position.cameraOrientation.axisForward = axisForward;
position.cameraOrientation.axisRight = axisRight;
position.cameraOrientation.axisUp = axisUp;
/** Update user status */
byte[] status = new byte[10];
int errorCode = rangeScene.UpdateUserStatus(position, 0, status);
/** Update user command */
byte[] command = new byte[10];
int errorCode = rangeScene.UpdateUserCommand(position, 0, command);6 (Optional) Get user count in scene, get user list within AOI range
You can call the GetUserCount and GetUserListInView interfaces as needed to get the user count in the scene and the user list within the AOI range.
/** Get user count in scene */
rangeScene.GetUserCount((int errorCode, uint count) =>{
});
/** Get user list within AOI range */
rangeScene.GetUserListInView((int errorCode, List<string> userList) =>{
});7 Logout scene
Call the LogoutScene interface to logout of the scene.
/** Logout scene */
rangeScene.LogoutScene((int errorCode) => {
});8 Destroy range scene module
When the range scene module is no longer needed, you can call the DestroyRangeScene interface to destroy the range scene module.
engine.DestroyRangeScene(rangeScene);9 Destroy engine
When ZEGO Express SDK is no longer needed, you can call DestroyEngine to destroy the engine.
ZegoExpressEngine.DestroyEngine();