---
title: "GettingStarted"
disqus: hackmd
tags: 'ctrl'
---

## Chapter 2 Getting Started

### 2-1 Create a New Game

When developers decide to create a new game, they have to log in to the developers’ backstage and select “create a new game development project” on the “game” page. Then, enter “game’s name” and “notes” to complete creating.

After creating the game, please select it on the “game project index” to enter its management backstage:

Later on, the parameters they need to create a CloudGame item with Cloud API and all the services and functions, which are provided by Cloud, they need for future development, can be managed in the “game development project.”

### 2-2 Using Visual Csharp

When using the C# development application of Microsoft’s Visual Studio, please add the Cloud API file to the project after creating the project by choosing the “Browse” page in the “Project” → “Add Reference” in the main list, finding “SGC.dll,” and adding it to the project. If the project is a Windows Form program, the ColudGame item can be built in the Form Load event:

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Windows.Forms;

namespace a1
{
   public partial class Form1 : Form
   {
      public CloudGame ag = null;
      private string userid = "...";    // The player’s logged in account

      private string passwd = "...";    //  The player’s logged in password
      
      private const string gguid = "...";    // The game’s GGUID

      private byte[] cert = { ... };    	 // The game’s verification code CERT

      public Form1()
      {
        InitializeComponent();
      }

      private void Form1_Load(object sender, EventArgs e)
      {
        ag = new CloudGame(userid, passwd, gguid, cert);
        ag.Launch();
      }

      private void Form1_FormClosed(object sender, FormClosedEventArgs e)
      {
       if (ag != null) ag.Dispose();
      }
   }
}

### 2-3 Using Unity 3D

The preparation to use Unity 3D to develop a Cloud multi-player game is more complicated:

**Step one, create a Cloud management scene**

To use Cloud to develop an Unity 3D game, one needs to create a Cloud management scene and set this scene as the first scene after starting the game. The management scene only has an empty GameObject with a Cloud management program in it, which is the system core that is responsible for communicating with the Cloud server.

To make it easier to explain, we define several nouns and names, and here’s what they stand for:

- AGCCMain
the name for the management scene
- AX
GameObject the Cloud controller, which is also a GameObject
- AGCC
the control script of the Cloud controller AX

<mark>The above names are flexible and developers can name them the way they prefer in their own game project.</mark>

Next, follow the following steps to create an AGCCMain control scene:

1. Drag the API file “SGC.dll” from the file location it is stored to the project’s Assets.

2. Create a new scene, name it as AGCCMain, and save it as AGCCMain.unity.

3. Create an empty Game Object in “Create Empty” of “GameObject.”

4. Create a new C# script in the “Project” window, rename it as AGCC, and drag it into AX.

5. Set AGCCMain as the first scene after entry:
Add AGCCMain, which is in “Add Current” of “Build Settings,” to “Build In Scene” and then use the mouse to drag AGCCMain to the top, making it the first scene in the project.

**Step two, create the sample program code for the AGCC script**

Below is the sample program code for the AGCC script. Please copy and paste it onto the agcc.cs program file. Please be aware that there are three variables, `gguid,` `sguid,` and `gcert,` and they are not designated with the correct initial values. You will be taught on how to obtain the correct values later.

// AGCC.cs
using UnityEngine;
using System;

public class AGCC : MonoBehaviour
    {
        public CloudGame ag = null;
        private const string gguid = "...";  // the game’s GGUID

        private byte[] cert = { ...};        // the game’s verification code CERT
        private string userid;
        private bool CloudGameHasLaunched = false;

        void Awake()
        {
             DontDestroyOnLoad(this);
             CloudGameHasLaunched = false;
        }
         // Enter the first scene right away
        void Start()
        {
            CloudSystem.UnityEnvironment();
		    CloudSystem.ServerProvider("sgc-api-us.spkita.com"); // Set the server
            Application.LoadLevel(1);
        }

        public void CloudStartup(string userid, string passwd)
        {
            ag = new CloudGame(userid, passwd, gguid, cert);
            ag.UnityLaunch();
            CloudGameHasLaunched = true;
        }
    }

AGCC uses the `CloudStartup()` function to let developers call it to connect to the internet and log in to the game server. Produce the item with the `CloudGame` construction function and store it in variable ag, while the actual connection and login are constructed by calling `ag.Launch()`. Since Cloud API uses a non-plogged function to execute the background processing, the `Launch()` function will return immediately, and whether the login is successful will be discussed later.

**Step three, obtaining the system parameter of creating the CloudGame**

GGIUD (Game GUID) and GCERT (Game Certificate) are two important parameter for creating the CloudGame item. When developers create a new game in the SGC management backstage, the “game development project” function page will provide these two parameters. All one needs to do are copy and paste the data in the backstage website to the AGCC script and design them to the three variables, such as `gguid` and `gcert,` with string constants and byte array constants.

### 2-4 Processing Logins

After creating the `CloudGame` item and calling its `Launch()` functions, API will log in to the Cloud server’s program in the background. To know whether the login is successful, we need to take over the `OnCompletion` event.

The following program demonstrates with Unity 3D and only lists the necessary part. For the complete program code, please refer to the previous session:

// AGCC.cs
using UnityEngine;
using System;
public class AGCC: MonoBehaviour
{
    // …some of the program code are omitted…
    public void CloudStartup(string userid, string passwd)
    {
        ag = new CloudGame(userid, passwd, gguid, cert);
        ag.onCompletion += LoginCompletion;
        ag.UnityLaunch();
        CloudGameHasLaunched = true;
    }
    private void LoginCompletion(int code, CloudGame game)
    {
        if (code == 0)
        {
            //  Login succeeds
        }
        else
        {
            //  Login fails
        }
    }
}

The value of the OnCompletion event’s parameter can be used to distinguish whether the login is successful, and here is what the code’s value stands for:

| code | meaning |
| -------- | -------- |
| 101 | the account cannot be empty |
| 102 | no user’s data found |
| 103 | the game project does not exist |
| 104 | login fails, and the account or password is wrong |
| 105 | abnormality found in the CCU checkup |
| 106 | exceed the maximum capacity of the number of online players |
| 107 | repeated login |
| 108 | fail to subscribe to Channel |
| 109 | fail to update player’s data |
| 110 | the authorization is expired |
| 111 | overflow |
| 199 | other errors |
| 201 | fails to obtain subscription on Channel |
| 202 | fails to obtain nickname |
| 203 | currently no in-time connection server is availabl |
| 204 | cannot connect to the back-edge server |

Another parameter `game` sends back the `CloudGame` item that executes this Cloud connection work. Normally, developers do not create several `CloudGame` items in the system, so there is no need to use this parameter to distinguish which `CloudGame` item’s connection work triggers the OnCompletion event.

### 2-5 Player’s Data

There are two important attributes for the CloudGame item:

1. uint poid
This is the identification code name the system assigns for the player’s current connection after the player logs in successfully. This code name allows developers to identify the players, but please be aware that it is not the player’s permanent code name. It is produced actively after the player logs in to the game, which means every time the player logs in, he gets a different `poid`. Besides, `poid` can be also viewed as the “scene id” of the player’s personal scene.

2. object token
This parameter is for program designers to store the data that are related to this game in the CloudGame item, according to their needs. Normally, if the program designers define their own item categories by succeeding CloudGame, they can define the necessary data variables in the categories. However, if they do not execute the definition by succession, to let CloudGame obtain related data when it is triggered, prgram designers can use the item attribute `token` to store these data.

### 2-6 System Status

No matter is when logging into the game or when the game is processing, we need to monitor the system’s status at any time. When the system status changes, API triggers the OnStateChanged event and this we need to design our own OnStateChanged event-handling function:

// AGCC.cs
using UnityEngine;
using System;
public class AGCC: MonoBehaviour
{
    // …some of the program code is omitted…
    public void CloudStartup(string userid, string passwd)
    {
        ag = new CloudGame(userid, passwd, gguid, cert);
        ag.onCompletion += LoginCompletion;
        ag.onStateChanged += CloudStateChanged;
        ag.Launch();
        CloudGameHasLaunched = true;
    }
    private void CloudStateChanged(int state, int code, CloudGame game)
    {}
    // …the LoginCompletion() program code is omitted…
}

| State | meaning |
| -------- | -------- |
| 0 | not connected yet |
| 100 | connected, enter Binary Mode |
| 300 | the game project does not exist |
| 400 | logged in, the user’s Poid is obtained |
| 410 | obtaining the nickname |
| 600 | entered this game |
| 900 | cannot connect to the Cloud Server |
| 901 | error occurs when receiving data (disconnected) |
| 902 | error occurs when receiving data (disconnected) |
| 903 | error occurs when examining the internet quality (disconnected) |
| 900~999 | connection error |

The biggest function for OnStateChanged is that when handling a 90X status, which is when there are errors about the connection to the server, the connection is ended when the system triggers a 90X status event. At this moment, players need to be notified with the error message, and if they want to reconnect to the server, please create a new CloudGame item again.