05/15/2024 15:19:45

Extension Module Development

I. Plugin development

The Extension module is used to encapsulate functions that cannot reuse the existing MSDK interfaces, such as the built-in game mall of the channel. For the functions required by the game, it is recommended to reuse the existing MSDK interfaces as much as possible, so that the game can be released on different channels. If the game can't reuse such functions, it choose Extension module to implement them.

1.1 Extension module description

Instructions about how to call the Extension module: The Extension module can encapsulate the functions needed by any game. When using the functions of the Extension module, the game needs to pass in the channel name (channel), method name (extendMethodName) and the method parameter list (paramsJson, Json format) to it. MSDK Core will find the corresponding method according to the channel name and method name and call Extend plugin to process them.

The Extension module's method running threads:

Calling thread: When a method in the Extension module is called, it will directly use the thread called by the game to execute it without automatic thread switching. If there are time-consuming operations or UI processing to be made in the method, it is needed to switch threads autonomously before calling the method of the Extension module
Callback thread: When a method is called back, the callback thread will switch to the UI thread for processing by default (UnrealEngine will automatically switch to the Game Thread) due to considerations about that the UI operation is likely to exist in the callback

[info] Caution The Extension module does not support method overloading, so it is needed to redefine the new method's name

1.2 Description of the Extension module's returns

The Extension module's call result data, which supports synchronous return and asynchronous callback. The synchronous return result will be returned as a string, and the asynchronous callback result can be returned through Observer preset by the game. The specific process is shown in the following diagram:

Synchronous return , whose result data will be transparently transmitted to the game from Extend Plug-In through MSDK Extend Core. The specific filling rules can be user-defined. For example, it can return true orfalse, and it can also return a Json string. If the game does not care about the result of this synchronous call, it can also return null directly.

Asynchronous callback . The game needs to pass in the corresponding Observer when calling the callback. The result data will also be accordingly returned to the game's processing function through Observer.

II. Client Plugin Development

2.1 Android Platform

2.1.1 Class rule description

Package naming rule: fixed as com.tencent.gcloud.msdk.extend
Class naming rule: channel + Extend, such as: GarenaExtend
Must implement a public CLASSNAME (String seqID) constructor, which is usually used for function initialization
The Extension module does not need to implement other interfaces, but MSDK makes the following rules for the Extension module's method parameter list, return values and access modifiers:
- Method parameter list, which are only String paramsJson, String seqID
  - paramsJson
    String type, JSON format, is the parameter list required by the functions. For example, the Garena mall requires region,roleId and serverId parameters, and paramsJson can be {"region":"TW","roleId":234234,"serverId":4}. In the method implementation, it is needed to parse paramsJson to get the parameter information required by the method.
  - seqID
    String type, MSDK function call sequence ID, which is used to mark which function is called. It is recommended to add the corresponding tag in the log to location problems
- The return value must be String type. This value is used for the call result of the game's synchronous return method
- Access modifiers, which must be public to make the method exposed

2.1.2 Description of callback fields

As for the description of the callback function, please refer to Client Plugin Development Rules

observerID callback function ID
- MSDKObserverID.MSDK_EXTEND_OBSERVER_RET, the Extension module's unified observerID
ret return struct, which is unified as MSDKExtendRet
- In addition to the necessary success/failure information in the callback result, it is also needed to set 'channel' and 'extendMethodName'. The game will further process the callback according to 'channel' and 'extendMethodName'. Among them, channel is the channel name (such as Garena), and extendMethodName is the function name of the method (such as openMS)
- If the game needs to return complex callback data (such as special friends list information), it can assign it to ret.extraJson in Json format
methodNameID Function ID defined by MSDK, used to define the callback method
- MSDKMethodNameID.MSDK_EXTEND is the unified method ID of the Extension module

2.1.3 Framework example

package com.tencent.gcloud.msdk.extend;    

public class GarenaExtend {    

  public GarenaExtend(String seqID) {    
      MSDKLog.d("[ " + seqID + "] Garena Extend initialize");    
      // TODO  Initialize the Garena environment    
      ...    
  }    

  public String openMS(String paramsJson, final String seqID) {    
      MSDKLog.d("[ " + seqID + "] openMS paramsJson: " + paramsJson);    
      // The Extend method's name at the callback    
      final String extendMethodName = "openMS";    
      // Parse specific parameters according to paramsJson    
      final String region = IT.getJsonString(paramsJson, "region");    
      MSDKLog.d("[ " + seqID + "] openMS region: " + region);    
      // Call the channel method    
      ...    

      // The return method is called successfully    
      IT.onPluginRetCallback(MSDK_EXTEND_OBSERVER_RET, new MSDKExtendRet(MSDK_EXTEND, MSDKErrorCode.SUCCESS, GarenaConst.Channel.CHANNEL, extendMethodName), seqID);    
      // If the game doesn't care about the synchronous call result, it can return null directly; the synchronous result returned here is "success"    
      return "{\"retCode\":\"0\",\"retMsg\":\"open success\"}";    
  }    
}

2.2 iOS Platform

2.2.1 Class rule description

Naming rules: Fixed as MSDKExtend + channel, such as: MSDKExtendGarena
The Extension module does not need to implement other interfaces, but MSDK makes the following rules on the method signature , method parameter list and return value of the Extension module:
- Method signature must be "Method name:seqID:"
- Method parameter list, which are only NSString * paramsJson, NSString * seqID
  - paramsJson
    NSString * type, JSON format, is the parameter list required by the functions. For example, the Garena mall requires region,roleId and serverId parameters, and paramsJson can be {"region":"TW","roleId":234234,"serverId":4}. In the method implementation, it is needed to parse paramsJson to get the parameter information required by the method.
  - seqID
    NSString * type, MSDK function call sequence ID, which is used to mark which function is called. It is recommended to add the corresponding tag in the log to location problems
- The return value must be NSString * type. This value is used to return the call result of the method to the game synchronously
Methods in the Extension module must be exposed in the header file

2.2.2 Description of callback fields