---
# System prepended metadata

title: Game_Method
tags: [API]

---

---
title: 'Game_Method'
disqus: hackmd
tags: 'API'
---

## **Method**
## **Launch**  
***• void Launch()***   
          
After establishing the CloudGame object, call Launch() to connect to the server. There are two overloadings. One of the overloadings has no designated the numbers of seconds of timeout, and the other functions under the system's default value. If the connection fails to work within the time limit, OnCompletion will be triggered due to timeout.
   
***• void Launch(int timeout)***   

| parameter   | note             |
|:------- |:---------------- |
| timeout | designate the number of seconds of timeout |
   
## **UnityLaunch**
***• void UnityLaunch()***    
       
In the development environment of Unity3D, please call this function at the beginning of processing the program. In practice, if the function is not called, there may be unpredictable errors on some platforms such as Android phones.
This function only needs to be called once, but calling it several times will not lead to negative results. However, the first call must be executed before the new CloudGame().

         
***• void UnityLaunch(int timeoutSec)***   
      
| parameter    | note            |
|:------- |:---------------- |
| timeoutSec | designate the number of seconds of timeout|
          
## **Dispose**
***• void Dispose()***   
       
After ending the connection to the server, the CloudGame object cannot be used again. If there is a need for re-connection, another new CloudGame object have to be established, and then do the Launch().   
      
## **GetUserGrade**
***• int GetUserGrade()***   
         
After the player logs in successfully, this method sends back player's member status.
    

| status code | note                                                                |
|:------ |:------------------------------------------------------------------- |
| 0      | an account obtained by the system               |
| 1      | A formal account registered by player or a formal account that upgrades from Level 0, which has not passed the email verification yet.|
| 2      | Formal account that passes the email verification. |
| 3      | A VIP player, who is not restricted by the game's CCU Max.  |

## **SendOnClose**
***• void SendOnClose(string msg, uint poid)***   
       
Pre-save message data to the server, so a player can send the message to other players when disconnected. This overloading can designate receiver's poid and send offline messages to particular online users, which is often the poid of DP in practice.

| parameter | note          |
|:---- |:------------- |
| msg  | Message data.      |
| poid | Receiver's poid. |

***• void SendOnClose(string msg, CloudScene scene)***      
    
Pre-save message data to the server, so a player can send the message to other players when disconnected. This overloading can designate specific scenes and send offline messages to users in this scene.     

| parameter  | note             |
|:----- |:---------------- |
| scene | designate to send the offline messages to this scene|
| msg   | message data  |

## **PrivacySend**
***• void PrivacySend(string msg, uint poid)***    
   
Send messages to selected players and designate receivers with poid (private scene id).

| parameter | note          |
|:---- |:------------- |
| msg  | Message data.      |
| poid | Receiver's poid. |

   
## **StartDelayDetectionRadar**
***• void StartDelayDetectionRadar(int speed)***   
       
Start the packet delay detection radar to detect the delay time of the packet-sending between the local and the game server.   

| parameter  | note         |
|:----- |:------------ |
| speed | detect interval blocks |

Start the packet delay detection radar to detect the delay time of the packet-sending between the local and the game server.   

|block | note                                       |
|:---- |:------------------------------------------ |
| 0    | stops detecting                                   |
| 1    | has the longest interval time, making it more suitable for games that require less instancy.   |
| 5    | has the shortest interval time, making it more suitable for games that require more instancy. |

Supplementary Note : 

Please depend the choice of levels on the games' characteristics. When using the high-speed level, the received information is the latest and the most accurate, but user's broadband will experience a more tremendous consumption. By contrast, the low-speed level consumes less broadband, but the obtained information may be detected earlier.     
Before activating the CloudGame object, please activate the detection radar, which is when CloudGame.OnCompletion() is triggered and the status code is successful    
  

     
## **GetDelayMillisecond**
***• int GetDelayMilliseconds()***   
        
Obtain the delay time of the packet-sending between the current location and the game server, and the unit is millisecond. In order to use this information, activate the packet delay detection radar with StartDelayDetectionRadar() first.   

      
## **SetPlayerStatus**
***• void SetPlayerStatus(int status, OnCallCompletion cb, object token)***    
       
Set the local player's status to let other players search for all those who have the same status with FindPlayersByStatus().   

The types of back-sendings:    
`void cb(int code, object token)`    

The following are the codes' status codes and their notes.    
             
| status code | note                   |
|:------ |:---------------------- |
| 0      | the setting succeeds.               |
| not 0   |the setting fails and the code is the error code |
       
***• void SetPlayerStatus(int status, int level, OnCallCompletion cb, object token)***   
        
Set the local player's status and level to let other players search for all those who have the same status or level with FindPlayersByStatus() or FindplayersbyLevel().   

The types of back-sendings:    
`void cb(int code, object token)`   
   
The following are the codes' status codes and their notes.    
         
| status code | note                   |
|:------ |:---------------------- |
| 0      |  the setting succeeds.               |
| not 0   |  the setting fails and the code is the error code. |
              
## **SetPlayerLevel**
***• void SetPlayerLevel(int level, OnCallCompletion cb, object token)***       
                  
Set the local player’s level to let other players search for all those who have the same level with FindPlayersByLevel().              
                        
| parameter  | note       |
|:----- |:---------- |
| level | player's level |

The types of back-sendings:    
`void cb(int code, object token)`   
   
The following are the codes' error codes and their notes.    
         
| error code | note                   |
|:------ |:---------------------- |
| 0      | the setting succeeds              |
| not 0   | the setting fails and the code is the error code |
    
## **FindPlayersByStatus**
***• void FindPlayersByStatus(int status, OnCallCompletionWithData cb, object token)***   
      
Search for all players that meet the conditions according to their status      
      
| parameter  | note       |
|:----- |:---------- |
| status | player's status |
        
The types of back-sendings:    
`void cb(int code, object obj, object token)`    
     
The following are the codes' status codes and their notes.    
       
|status code | note                                                 |
|:------ |:---------------------------------------------------- |
| 0      | Find functions successfully                                       |
| not 0   | Find fails to function. The code is the error code and obj is meaningless and negligible.  |

obj is shaped as List<Hashtable>, in which the players' data are stored. When List.Count is 0, there is no players' data that match the status found. Also, the Key and Value each Hashtable contains are：   

| Key    | Value    |
|:------ |:-------- |
| userid | Player's account. |
| poid   | Personal scene. |
   
Example: obj obtains the player’s data that are sent back.
   
   
```
C#

List<Hashtable> s = (List<Hashtable>)obj;
string userid;
uint poid;

foreach (Hashtable node in s) 
{
	userid=(string)node["userid"];
	poid=(uint)node["userid"];
	// to process userid and poid here
}
```
   
## **FindPlayersByLevel**
***• void FindPlayersByLevel(int level, OnCallCompletionWithData cb, object token)***   
      
Search for all players that meet the conditions according to their level. To see further information, please go to `FindPlayersByStatus()`。  

## **GetSceneInstance**
***• void GetSceneInstance(string sguid, OnCallCompletionWithData cb, object token)***    
        
Obtain the scene copy that is already set in active scene

The types of back-sendings    
`void cb(int code, object obj, object token)`   

The following are the codes' status codes and their notes.  
             
| status code | note                                           |
|:------ |:---------------------------------------------- |
| 0      | the obtaining succeeds.                                        |
| not 0   | the obtaining fails and the code is the error code. Obj is meaningless and negligible |

obj is shaped as List<Hashtable>. The Key and Value each Hashtable contains are：
    
| Key   | Value                |
|:----- |:-------------------- |
| sid   | stands for the scene copy's ID          |
| count | stands for the number of players entering that scene |

    
Example: obj obtains the information of the scene copy that is sent back.
   
         
```
C#

List<Hashtable> s = (List<Hashtable>)obj;
uint sid;
int count;
string status; // status = open or private

foreach (Hashtable node in s) 
{
	sid=(uint)node["sid"];
	count=(int)node["count"];
	status=(string)node["status"];
	// to process sid userid and count here
}
```
   
## **SetPlayerNickname**
***• void SetPlayerNickname(string nickname, OnCallCompletion cb, object token)***    
       
To set (change) player's nickname, there should be no blank space in nicknames and the special symbols can only be "." or "-."

             
| parameter     | note       |
|:-------- |:---------- |
| nickname | player's nickname |
               
The types of back-sendings:   
`void cb(int code, object token)`     
         
The following are the codes' status codes and their notes.         
                
| syayus code | note                                       |
|:------ |:------------------------------------------ |
| 0      | the setting functions successfully, and the value for CloudGame.nickname will be updated simultaneously |
| not 0   | When the code is not 0, the setting fails, and the code is the error code.
                     |
                  

## **SetPlayerRegister**
***• void SetPlayerRegister(object AX, object BX, object CX, object DX, OnCallCompletion cb, object token)***    
       
Set player's register data.

| parameter | note                                                          |
|:---- |:------------------------------------------------------------- |
| AX   | The AX register data for setting AX has to be an integer. When one chooses to not set AX, send the AX register to null. |
| BX   |  The BX register data for setting BX has to be an integer. When one chooses to not set BX, send the BX register to null. |
| CX   | The CX register data for setting CX has to be an integer. When one chooses to not set CX, send the CX register to null. |
| DX   | The DX register data for setting DX has to be an integer. When one chooses to not set DX, send the DX register to null. |
          
Supplementary Note :            
Register is a data system that is faster and more convenient in storing player's data than CloudItem.
Every player has his own four registers in the game, which is named AX, BX, CX, and DX. The four registers function as integers, and the developers can define their purposes. Aside from reading their values with `GetPlayerRegister()`, more importantly, when the game wants to ask the system to randomly select unspecified players with`CloudGame.GetRandomPlayer()`(such as when doing random teaming), it can designate the registers' conditions. In this way, only the players that meet the conditions will be chosen. To see further explanation on randomly selecting players, please go to
    
<mark>Please be aware that CX and DX can only be read by users themselves and super users. The players that CloudGame.GetRandomPlayer() randomly selects will only send back userid, nickname, AX, and BX.
</mark>        

The types of back-sendings:          
`void cb(int code, object token)`   
    
The following are the codes' status codes and their notes.    
       
| status code | note                   |
|:------ |:---------------------- |
| 0      | the setting succeeds               |
| not 0   | the setting fails the code is the error code |

## **GetPlayerRegister**
***• void GetPlayerRegister(OnCallCompletionWithData cb, object token)***   
        
obtain player's register data      
            
The types of back-sendings:    
`void cb(int code, object obj, object token)`      

The following are the codes' status codes and their notes.    
       
| status code | note                                           |
|:------ |:---------------------------------------------- |
| 0      | the obtaining succeeds                                       |
| not 0   | the obtaining fails and the code is the error code and obj is meaningless and negligible |
         
obj is shaped as List<Hashtable>, in which the Key and Value that the read register contains are：
               
| Key     | Value                     |
|:------- | ------------------------- |
| userid  | player's userid              |
| ax      | player's ax register value       |
| bx      | player's bx register value      |
| cx      | player's cx register value       |
| dx      | player's dx register value       |
| axstamp | the last time when ax register is set |
| bxstamp | the last time when bx register is set
 |
| cxstamp | the last time when cx register is set |
| dxstamp | the last time when dx register is set |

## **GetRandomPlayer**
***• void GetRandomPlayer(OnCallCompletionWithData cb, object token)***  

Randomly send back a player's data without setting any conditions.

The types of back-sendings:         
`void cb(int code, object obj, object token)`

The following are the codes' status codes and their notes.     
           
| status code | note                                           |
|:------ |:---------------------------------------------- |
| 0      | the obtaining succeeds                                        |
| not 0   |the obtaining fails and the code is the error code and obj is meaningless and negligible |
         
obj is shaped as List<Hashtable>, which sends back player's data. Since only one player's data are sent back, there is only one Hashtable in List.
    
The Key and Value each Hashtable contains are：    
              
| Key | Value |
| -------- | -------- |
| userid     | player's userid
     |
| nickname     | player's nickname, and if the player  does not set it, the key will not exist 
     |
| online     | 0: player is offline 1: player is online 
     |
| ax     | player's ax register value
     |
| bx     | player's bx register value
   |
| cx     | player's cx register value
     |
| dx     | player's dx register value
     |
| axstamp     | the last time when ax register is set
    |
| bxstamp     | the last time when bx register is set
     |
| cxstamp     | the last time when cx register is set
     |
| dxstamp     | the last time when dx register is set
     |

          
***• void GetRandomPlayer(int number, OnCallCompletionWithData cb, object token)***  		
Randomly send back several players’ data without setting any conditions. Please refer the format to the first overloading

| parameter   | note                                 |
|:------ |:-------------------------------------- |
| number | The number of players that is required to send back, and the maximum is 25. If exceeds, it's still 25. |

***• void GetRandomPlayer(bool online, OnCallCompletionWithData cb, object token)***  	

Randomly send back a player's data and designate whether online or offline player is desired. The format for back-sending can refer to the first overloading.
    
| parameter   | note                                           |
|:------ |:---------------------------------------------- |
| online | true : online players only / false : offline players only |
   
***• void GetRandomPlayer(string registercondition, OnCallCompletionWithData cb, object token)***  	 

Send back a player's data randomly when they fit with the condition expression of the register's status value. Please refer the format of back-sending to the first overloading.
    
| parameter              | note                          |
|:----------------- |:------------------------------ |
| registercondition | Designate the condition expression of the register's status value |
    
Supplementary Note :           
The expression is an expression string that is made up with 「>」、「<」、「=」、「&」、「|」and ax，bx，cx， dx，now-axstamp，now-bxstamp，now-cxstamp，now-dxstamp.

Example: “(ax > 3 & ax< 5) | ( cx = 3) & (now-axstamp>36800)”。          
          
***• void GetRandomPlayer(int number, bool online, OnCallCompletionWithData cb, object token)***  	 
      
Randomly send back several players' data and designate whether online or offline players are desired. The format for sending-back can refer to the first overloading.  
    
| parameter   | note                                           |
|:------ |:---------------------------------------------- |
| number | The number of players that is required to send back, and the maximum is 25. If exceeds, it's still 25.
         |
| online | true : online players only / false : offline players onl |
                     
***• void GetRandomPlayer(int number, string registercondition, OnCallCompletionWithData cb, object token)***     
        	
Send back several players' data randomly when they fit with the condition expression of the register's status value. Please refer the format of back-sending to the first overloading.
    
| parameter              | note                                   |
|:----------------- |:-------------------------------------- |
| number            | The number of players that is required to send back, and the maximum is 25. If exceeds, it's still 25.
 |
| registercondition | Designate the condition expression of the register's status value         |
    
Supplementary Note :         
The regidter expression is an expression string that is made up with「>」、「<」、「=」、「&」、「|」and ax，bx，cx， dx，now-axstamp，now-bxstamp，now-cxstamp，now-dxstamp.

Example : “(ax > 3 & ax< 5) | ( cx = 3) & (now-axstamp>36800)”。            
         
***• void GetRandomPlayer(bool online, string registercondition, OnCallCompletionWithData cb, object token)***  	
      
Randomly send back a player's data and designate whether online or offline player is desired. Also, demand that it is obtained randomly only by a condition expression which conforms to the register status value. The format for back-sending can refer to the first overloading.

| parameter              | note                                           |
|:----------------- |:---------------------------------------------- |
| online            | true : online players only / false : offline players only |
| registercondition |  Designate the condition expression of the register's status value.                 |
    
Supplementary Note :        
The expression is an expression string that is made up with「>」、「<」、「=」、「&」、「|」和 ax，bx，cx， dx，now-axstamp，now-bxstamp，now-cxstamp，now-dxstamp.

Example : “(ax > 3 & ax< 5) | ( cx = 3) & (now-axstamp>36800)”。         
                 
***• void GetRandomPlayer(int number, bool online, string registercondition, OnCallCompletionWithData cb, object token)***     
         
Randomly send back several players' data and demand that it is obtained randomly only by a condition expression which conforms to the register status value. The format for sending-back can refer to the first overloading.

| parameter              | note                                           |
|:----------------- |:---------------------------------------------- |
| number            | number The number of players that is required to send back, and the maximum is 25. If exceeds, it's still 25         |
| online            | true : online players only / false :  offline players only |
| registercondition | 指Designate the condition expression of the register's status value.                 |
    
Supplementary Note :          
The expression is an expression string that is made up with「>」、「<」、「=」、「&」、「|」和 ax，bx，cx， dx，now-axstamp，now-bxstamp，now-cxstamp，now-dxstamp.

Example : “(ax > 3 & ax< 5) | ( cx = 3) & (now-axstamp>36800)”。 
 