GettingStarted

第 2 章 開始

2-1 建立新遊戲

開發者決定製作新遊戲時，首先要登入開發者後台，並在「遊戲」主頁中點選「建立新的遊戲開發專案」，輸入「遊戲名稱」與「說明」兩項資料後，遊戲專案便已建立完成。 遊戲建立後，請從「遊戲專案目錄」中點選剛才建立的遊戲，進入此遊戲的管理後台：

稍後使用 SGC API 建立 CloudGame 物件所需要的參數，或是未來遊戲開發時所要用到 SGC 提供之各項服務與功能，都在此處「遊戲開發專案」中進行管理。

2-2 使用 Visual Csharp

使用微軟 Visual Studio 的 C#開發應用程式，請在建立新專案後，先將 SGC API 檔加入到專案中， 做法是從主選單的「Project」→「Add Reference」功能中選擇「Browse」頁籤，找到「SGC.dll」後將它加入到專案中。如果專案是 Windows Form 的程式，可以在 Form Load 事件中建立 CloudGame 物件：

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;
using GameCloud;

namespace a1
{
   public partial class Form1 : Form
   {
      public CloudGame ag = null;
      private string userid = "...";         // 玩家登入帳號
      private string passwd = "...";         // 玩家登入密碼
      private const string gguid = "...";    // 遊戲的GGUID
      private byte[] cert = { ... };         // 遊戲認證碼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 使用 Unity 3D

使用 Unity3D 開發 SGC 多人互動遊戲的準備工作比較複雜 :

第一步，建立 SGC 主控場景

使用 SGC 開發 Unity3D 遊戲必須先建立一個 SGC 主控場景，並且要將這個場景設定為遊戲開始後的第一個場景。主控場景內只有一個空的 GameObject，內有 SGC 主控程式，這個主控程式也就是遊戲專案中負責與 SGC 伺服器溝通的系統核心。
為了方便說明，我們定義了幾個名詞與名稱，以下是它們所代表的意義：

• AGCCMain
  主控場景名稱
• AX
  SGC 主控器，同時也是一個 GameObject
• AGCC
  SGC 主控器 AX 的控制腳本

以上名稱並非固定不變，開發者可以在自己的遊戲專案中自行定喜好的名稱。

接著依照下列步驟建立 AGCCMain 主控場景：

1. 將 API 檔「SGC.dll」從它存放的檔案位置拖曳到專案的 Assets 中。
2. 建立一個空的 Scene，取名為 AGCCMain，隨後存檔為 AGCCMain.unity。
3. 在「GameObject」的「Create Empty」建立一個空的 Game Object，更名為 AX。
4. 在「Project」窗中新增一個 C# 腳本，更名為 AGCC，然後拖拉至 AX 中。
5. 把 AGCCMain 設定為第一個進入的 Scene： 從「Build Settings」中的「Add Current」AGCCMain 加入「Build In Scene」，然後使用滑鼠拖曳把 AGCCMain 拉到最上面，成為此專案的第一個 Scene。

第二步，建立 AGCC 腳本的樣版程式碼

以下是 AGCC 腳本的樣版程式碼，請直接複製貼到 agcc.cs 程式檔，請注意，此處有三個變數 gguid、sguid、gcert 並沒有指定正確的初始值，稍後會告訴您如何取得正確的值。

// AGCC.cs
using UnityEngine;
using System;
using GameCloud;

public class AGCC : MonoBehaviour
    {
        public CloudGame ag = null;
        private const string gguid = "...";  // 遊戲的GGUID
        private byte[] cert = { ...};        // 遊戲認證碼CERT
        private string userid;
        private bool CloudGameHasLaunched = false;

        void Awake()
        {
             DontDestroyOnLoad(this);
             CloudGameHasLaunched = false;
        }

        // 馬上進入第一個場景
        void Start()
        {
            CloudSystem.ServerProvider("sgc-api-us.spkita.com"); // 設定伺服器
            Application.LoadLevel(1);
        }

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

AGCC 以 CloudStartup()函式讓開發者呼叫，用來進行網路連線與登入遊戲伺服器，透過CloudGame 建構函式產生物件，並存放於變數 ag，真正進行連線與登入則是呼叫 ag.Launch()， 由於 SGC API 採用非阻塞式進行背景處理，所以 Launch()函式會馬上返回，至於登入是否成功將在稍後介紹。

第三步，取得建立 CloudGame 的系統參數

GGUID (Game GUID)、GCERT(Game Certificate)是建立 CloudGame 物件的兩個重要參數，當開發者在 SGC 管理後台建立一個新遊戲時，該遊戲的「遊戲開發專案」功能頁面中，將會提供這兩個參數，只要將後台網頁上的資料複製貼上到 AGCC 腳本中，直接以字串常數與 byte 陣列常數依序指派給 gguid、gcert 等三個變數即可。

2-4 登入處理

建立 CloudGame 物件後呼叫其 Launch()函式後，API 便在背景執行登入 SGC 伺服器程序， 要知道登入是否成功，我們必須接手 OnCompletion 事件。 以下範例程式是以 Unity3D 為例，並且只列出必要的部份，完整的程式碼請參考上一節：

// AGCC.cs
using UnityEngine;
using System;
using GameCloud;

public class AGCC: MonoBehaviour
{
    // ...省略部份程式碼...
    public void CloudStartup(string userid, string passwd)
    {
        ag = new CloudGame(userid, passwd, gguid, cert);
        ag.onCompletion += LoginCompletion;
        ag.Launch();
        CloudGameHasLaunched = true;
    }
    private void LoginCompletion(int code, CloudGame game)
    {
        if (code == 0)
        {
            // 登入成功
        }
        else
        {
            // 登入失敗
        }
    }
}

OnCompletion 事件的參數 code，其值可用來判斷登入成功與否，以下是 code 值的意義：

code	意義
101	帳號不可為空
102	沒有用戶資料
103	遊戲專案不存在
104	登入失敗，錯誤的帳號或密碼
105	CCU檢查異常
106	超過專案最大在線人數
107	重複登入
108	訂閱Channel失敗
109	更新玩家資料失敗
110	授權過期
111	流量超過
112	專案暫停
199	其他錯誤
201	取得訂閱Channel失敗
202	取得暱稱失敗
203	目前沒有即時連線伺服器空閒中
204	無法連接到後端伺服器

另外一個參數 game，它會傳回執行此項 SGC 連線作業的 CloudGame 物件，一般來說開發者不會在系統中建立多個 CloudGame 物件，所以並不需要這個參數來區分是那一個 CloudGame 物件的連線作業完成所觸發的 OnCompletion 事件。

2-5 玩家資訊

CloudGame 物件有兩個重要的屬性：

1. uint poid
   這是玩家成功登入遊戲後，系統針對此玩家目前連線所指派的識別代號，這個代號可以讓遊戲開發者用來識別玩家身份，不過要注意 poid 並不是玩家的永久代號，它是玩家登入遊戲後動態產生，也就是玩家每次登入後獲得的 poid 都不一樣。此外，poid 也可以視為是玩家私人場景的「場景 id」。
2. object token
   這個參數是由程式設計師依其需要，在 CloudGame 物件中存放與此遊戲有關的資料，一般來說， 如果程式設計師採用繼承 CloudGame 的方式另外定義自己的物件類別，在類別中就可以自行定義必要的資料變數；但是，如果不是採用繼承的方式，為了在 CloudGame 的事件觸發時能夠存取相關的資料，程式設計師就可以透過 token 這個物件屬性來存放這些資料。

2-6 系統狀態

無論是登入遊戲，或是遊戲進行中，我們都需要隨時監控系統狀態，當系統狀態改變時，API 會觸發 OnStateChanged 事件，因此我們要設計自己的 OnStateChanged 事件處理函式：

// AGCC.cs
using UnityEngine;
using System;
using GameCloud;

public class AGCC: MonoBehaviour
{
    // ...省略部份程式碼...
    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)
    {}
    // ...省略LoginCompletion()程式碼...
}

State	意義
0	尚未連線
100	已連線，已進入 Binary Mode
300	遊戲專案不存在
400	已登入，取得用戶 Poid
410	取得暱稱中
600	已進入此遊戲
900	無法連線至 SGC Server
901	接收資料時發生錯誤(斷線)
902	傳送資料時發生錯誤(斷線)
903	偵測網路品質時發生錯誤(斷線)
900~999	連線發生錯誤

OnStateChanged 最大的用處是在處理 90X 的狀態，也就是與伺服器的連線發生異常，當系統觸發了 90X 的狀態事件後，連線就已經中止了，此時必須提示錯誤訊息讓玩家知道，若要重新連線，請重新建立新的 CloudGame 物件。

補充 : 若網路斷線時，剛好有其他API正在呼叫，會直接丟錯誤碼 20001 給正在等待的 Callback。 另外如果沒有正在呼叫的API，約1分鐘後，state 的狀態碼也會變成 999 ，並回傳錯誤碼 20001 。

備註 : 雖然收到錯誤碼 20001 但可能 webapi 已經收到 request 並會完成該任務。