Implement live comment-based games on mobile devices as a host

This topic describes how to implement a live comment-based game on an iOS device as a host by using ZEGO MiniGameEngine SDK and ZEGO Express SDK.

Prerequisites

Before you implement a live comment-based game as a host, make sure that the following prerequisites are met:

• A project is created in the ZEGOCLOUD console. The value of the AppID parameter of the project is obtained. For more information, see How to view project information.
• The mini-game service is activated by contacting ZEGOCLOUD business staff.
• ZEGO MiniGameEngine SDK is integrated with your project. For more information, see Integrate the SDK.
• ZEGO Express SDK is integrated with your project. For more information, see Integrate the SDK in the "Video Call" documentation.

Sample code

ZEGOCLOUD provides sample code on how to implement a live comment-based game for your reference.

Procedure

The following figure shows the flowchart of implementing a live comment-based game as a host.

The implementation process involves two main classes of ZEGO MiniGameEngine SDK: ZegoMiniGameEngine and ZegoCloudGameEngine.

ZegoMiniGameEngine is used for initialization and obtaining a game list and game details.

ZegoCloudGameEngine is used to configure a container for the live comment-based game and stop the live comment-based game.

1. (Server) Connect to the ZEGOCLOUD server and obtain a token

1.1 Connect to the ZEGOCLOUD server

For more information about how to connect to the ZEGOCLOUD MiniGameEngine server, see Server API - Make API requests. For more information about how to obtain a game start code, see Obtain a game start code. This way, the host can obtain the game start code before the host starts the live comment-based game. ZEGOCLOUD provides sample server code for your reference. For your data security, do not use the sample server code in a production environment.

1.2 Obtain a token

When a user uses the ZEGOCLOUD mini-game service, the ZEGOCLOUD server checks whether the user has the required permissions based on the token that is specified when the user initializes ZEGO MiniGameEngine SDK. This prevents risks caused by insufficient permissions or improper operations.

Generate a token on your server and return the token to the client of the user. For more information, see Token Authentication.

2. (Client) Initialize SDKs

2.1 Create a ZegoExpressEngine instance and log in to an RTC room

For more information about how to create a ZegoExpressEngine instance, see the "Create a ZegoExpressEngine instance" section of the Implement a basic video call topic in the "Video Call" documentation.

After the initialization, log in to the real-time communication (RTC) room. For more information, see the "Log in to a room" section of the Implement a basic video call topic in the "Video Call" documentation.

2.2 Initialize ZEGO MiniGameEngine SDK

Import the header file.

#import <ZegoMiniGameEngine/ZegoMiniGameEngine.h>

Call the ZegoMiniGameEngine > sharedEngine operation to create a ZegoMiniGameEngine object. Call the init operation and specify your AppID, the token generated by your server, the custom user ID and username, and the URL of the avatar image. Then, initialize ZEGO MiniGameEngine SDK.

Call the ZegoCloudGameEngine > sharedEngine operation to obtain a ZegoCloudGameEngine instance.

// Initialize ZEGO MiniGameEngine SDK.
ZegoGameUserInfo *userInfo = [[ZegoGameUserInfo alloc] init];
// After you create a project in the [ZEGOCLOUD console] (https://console.zegocloud.com), you can obtain the AppID from Project Management. Append an "L" to the application ID. Example: 1234567890L.
long appID = Your application ID; 
NSString *token = @"your token"; // The token that your server generates.
userInfo.userID = @"your user ID"; // Required. The custom user ID, which must be the same user ID that is used to generate the token.
userInfo.userName = @"your user name"; // Required. The custom username.
userInfo.avatar = @"your user avatar"; // Optional. The URL of the avatar image. The HTTPS protocol must be used.
[ZegoMiniGameEngine.sharedEngine init:appID token:token userInfo:userInfo callBack:^(int errorCode, id _Nullable object) {
 
}];

// Obtain the ZegoMiniGameEngine instance.
ZegoCloudGameEngine *cloudGameEngine = [ZegoCloudGameEngine sharedEngine];

2.3 Set the game container and register a listener for live comment-based game events

Call the setCloudGameContainer operation to configure the parent container of the game for subsequently starting the game. Call the setCloudGameEngineHandler operation to register a listener for listening to live comment-based game events. The relevant events are returned in the ZegoCloudGameEngineHandler callback after the live comment-based game is started.

UIView *gameContainer = xxx; // You need to configure a common view at the UI layer to display the game.

// Configure a game container.
[ZegoCloudGameEngine.sharedEngine setCloudGameContainer:gameContainer];

// Configure a game event delegate.
[ZegoCloudGameEngine.sharedEngine setCloudGameEngineHandler:self];

// Implement a game event.
#pragma mark----ZegoCloudGameEngineHandler
- (void)onCloudGameError:(int)errorCode message:(NSString *)message {
    // An error message is returned for the live comment-based game.
}

- (void)onCloudGameFirstFrame {
    // First frame of the game is rendered successfully
    // During the process of launching a live comment-based game until the game is successfully loaded, you can play a custom loading animation or implement other logic
    // After receiving this callback, you can stop playing the custom animation or performing other logic
}

3. (Client) Start the game

3.1 Get the game list

Call the getGameList operation, set the gameMode parameter as ZegoGameModeCloudGame to specify that the game is in live comment-based gaming mode, and then obtain the list of live comment-based games. Select a game ID from the list.

The following sample code provides an example on how to obtain the list of games that are in comment-based gaming mode:

// Obtain the list of live comment-based games.
// Set the `gameMode` parameter to `ZegoGameModeCloudGame`, which specifies the comment-based gaming mode.
[ZegoMiniGameEngine.sharedEngine getGameList:ZegoGameModeCloudGame callBack:^(NSInteger errorCode, NSArray<ZegoGameInfo *> *gameList) {
    // The `gameList` parameter specifies the list of live comment-based games.
}];

3.2 Obtain a game activation code

After the game to play is determined, the host needs to obtain a game activation code by call the ZEGOCLOUD server API. In this case, you need to send the game activation code to the client.

3.3 Start the live comment-based game

To start the game, Call the startCloudGame operation, and specify the room ID and the game ID.

NSString *roomID = @"your room id"; // The game room ID. We recommend that you use your business room ID.
NSString *gameID = @"your game id"; // The game ID. 

// Optional. Configure the game settings.
NSDictionary *gameConfig = @{
        // You can specify the game activation code and other parameters as required. The parameter formats are different for different games. You can contact ZEGOCLOUD support for help.
        // We recommend that you specify the game activation code. In this case, after the startCloudGame operation is called, the game is automatically started.
        // If you do not specify the game activation code. After the startCloudGame operation is called, you are required to enter the game activation code subsequently during the game.
        @"runningParameters" : @"Game activation code",
    };
// Load the game.
[ZegoCloudGameEngine.sharedEngine startCloudGame:gameID roomID:roomID gameConfig:gameConfig callBack:^(int errorCode, id  _Nullable object) {
    // Invoke a result callback.
}];

3.4 Publish the live comment-based game stream to the RTC room

After the game is started, call the startPublishCloudGameStream operation to publish the game stream to the RTC room.

NSString *roomID = @"your room id"; // The game room ID. We recommend that you use your business room ID.
NSString *gameID = @"your game id"; // The game ID. 
NSString *streamID = @"your stream id" // The stream ID. You can specify the stream ID as needed. The value can not exceed 256 characters in length.
                                         // The value can contain only digits, letters, hyphens (-), and underscores (_).
                                         // Make sure that the stream ID is globally unique under the same appID. If different streams are published with the same `streamID`, the latter stream will fail.

[ZegoCloudGameEngine.sharedEngine startPublishCloudGameStream:gameID roomID:roomID streamID:streamID callBack:^(int errorCode, id  _Nullable object) {
    // The result callback for stream ingestion.
}];

4. (Client) Stop the game

Before you stop the live comment-based game, you must stop publishing the stream.

4.1 Stop publishing the stream

Call the stopPublishCloudGameStream function to stop publishing the game streams.

NSString *roomID = @"your room id"; // The game room ID. We recommend that you use your business room ID.
NSString *gameID = @"your game id"; // The game ID. 
NSString *streamID = @"your stream id" // The stream ID.
[ZegoCloudGameEngine.sharedEngine stopPublishCloudGameStream:gameID roomID:roomID streamID:streamID callBack:^(int errorCode, id  _Nullable object) {
    // The result callback for stopping ingesting streams.
}];

4.2 Stop the live comment-based game

Call the stopCloudGame operation to stop the live comment-based game.

NSString *roomID = @"your room id"; // The game room ID. We recommend that you use your business room ID.
NSString *gameID = @"your game id"; // The game ID. 
[ZegoCloudGameEngine.sharedEngine stopCloudGame:gameID roomID:roomID callBack:^(int errorCode, id  _Nullable object) {
    // The result callback for stopping the live comment-based game.
}]; 

5. (Client) Uninitialize the SDK

If you no longer need to play live comment-based games, you can log out of the RTC room, destroy the ZegoExpressEngine instance, and uninitialize ZEGO MiniGameEngine SDK to release resources.

5.1 Log out of the RTC room

For more information about how to log out of the RTC room, see the "Log out of a room" section of the Implement a basic video call topic in the "Video Call" documentation.

5.2 Destroy the ZegoExpressEngine instance

For more information about how to destroy the ZegoExpressEngine instance, see the "Destroy a ZegoExpressEngine instance" section of the Implement a video call topic in the "Real-Time Audio/Video" documentation.

12.3 Uninitialize ZEGO MiniGameEngine SDK

Call the unInit operation to uninitialize the ZEGO MiniGameEngine SDK.

[ZegoMiniGameEngine.sharedEngine unInit];

More feature

Send a keyboard event

After the host starts the live comment-based game on a mobile device, if the game does not have an available keyboard, the host needs to call the sendKeyboardEvent function and specify the keyboard code to implement a keyboard event such as configuration of the forward step or adjustment of the field of view (FOV). This helps the game run smoothly. For more information about keyboard codes, see JavaScript Key Code Event.

int keyboardCode = 65; // The value corresponding to the letter "A" in the keyboard.
[ZegoCloudGameEngine.sharedEngine sendKeyboardEvent：keyboardCode];