# WhizToys SDK(Unity) 說明文件

## 安裝

下載地址：
https://drive.google.com/file/d/1-YAiSqnrTy-lzcavDKJU22pNm6qwymde/view?usp=sharing

在您的Unity項目中加入SDK：
1. 將 `Whiztoys_SDK.unitypackage` 安裝至您的專案中。

### 範例場景

#### NormalDemo
最基礎的範例，其中包括 格子排列，壓力偵測，顏色顯色等。

#### Muti_Demo
支持對多個控制器做連線的範例。

#### Rotate_Demo (操作格子需大於2x2)
用2x2的區塊做為遊戲區，展示了旋轉，以及指定區塊做為工作區塊。

## 快速入門

### 初始化

要使用SDK，首先需要創建 `WhizToys` 類的實例並調用 `Initialize` 方法來初始化藍牙模塊：

WhizToys whizToys = new WhizToys();
whizToys.Initialize();

初始化後，需對要使用的每個事件做函式接應

whizToys.OnInitSuccess = () => { print("初始化成功"); };
whizToys.OnScanDevice = OnScanDevice;
whizToys.OnScanEnd = OnScanEnd;
whizToys.OnConnected = OnConnected;
whizToys.OnDisconnect = () => { print("連接斷掉"); };
whizToys.OnReceiveSignal = OnReceiveSignal;

### 掃描設備

啟動設備掃描以尋找可用的控制器：

whizToys.StartScan(5); // 掃描5秒

### 連接設備

啟動設備掃描以尋找可用的控制器：

whizToys.Connect(address); // 藍芽地址

掃描到設備後會以 <string address, string deviceName> 傳送設備資料：

private void OnScanDevice(string address, string deviceName)
{
}

### 格子布局

連接成功後，SDK會將布局透過OnConnected發送給使用者：

private void OnConnected(WhizToysMap whizToysMap)
{
    // 由此去操作格子布局
}

### 改寫顏色

改寫顏色需透過 List<WhizToysSendModel> 來更改，且colorIndex需對照色碼表。
以下為全部改某個顏色的範例：

public void WriteColor(int colorIndex)
{
    List<WhizToysSendModel> sendModels = new List<WhizToysSendModel>();

    int rows = _whizToysMap.Layout.Row;
    int columns = _whizToysMap.Layout.Column;

    for (int i = 0; i < rows; i++)
    {
        for (int j = 0; j < columns; j++)
        {
            if (_whizToysMap.Blocks[i, j].Active)
            {
                WhizToysSendModel sendModel = new WhizToysSendModel();
                sendModel.Layout.Row = i;
                sendModel.Layout.Column = j;
                sendModel.ColorIndex = colorIndex;
    
                sendModel.LightMode = LightModeType.All;
                sendModel.CommandMode = CommandModeType.Immediately;
                sendModel.FeedBackMode = FeedBackModeType.Basic;
                sendModel.ShowTimeMode = ShowTimeModeType.Short;

                sendModels.Add(sendModel);
            }
        }
    }

    whizToys.WriteSignals(sendModels);
}

### 接收壓力訊號

SDK會傳送List<WhizToysSignal>，使用者需用相對應函式去接應
壓力分為3級並且有4個角，其中int[] 分別為左上、左下、右下、右上。

以下為範例：

private void OnReceiveSignal(List<WhizToysSignal> values)
{
    for (int i = 0; i < values.Count; i++)
    {
        WhizToysSignal whizToysSignal = values[i];

        int row = whizToysSignal.Layout.Row;
        int column = whizToysSignal.Layout.Column;
            
        PressBlock pressBlock = _pressBlocks[row, column];

        int[] pressures = whizToysSignal.Pressures;

        for (int j = 0; j < pressures.Length; j++)
            pressBlock.blocks[j].color = ConvertColor(pressures[j]);
    }
}

## 資料格式

### WhizToysLayout
定義格子的位置

public struct WhizToysLayout
{
    public int Row;
    public int Column;

    public bool Compare(WhizToysLayout layout) // 用來比較兩個位置是否相同
}

### WhizToysBlock
定義格子的狀態

public class WhizToysBlock
{
    public readonly bool Active; // 是否啟用，若實際情況這個為空 就會為False

    public bool IsPressure // 是否有踩踏
    public bool AllPressure // 四個角同時被踩踏
    public bool IsLeft // 左上、左下 被踩踏
    public bool IsRight // 右上、右下 被踩踏
    public bool IsUp // 左上、右上 被踩踏
    public bool IsDown // 左下、右下 被踩踏
}

### WhizToysMap
定義格子的排列

public class WhizToysMap
{
    public WhizToysLayout Layout; //這邊裡面的 Row 和 Column 是總共的數量
    public WhizToysBlock[,] Blocks;
}

### WhizToysSendModel
改變顏色用的格式

public class WhizToysSendModel
{
    public WhizToysLayout Layout;
    public int ColorIndex; // 顏色需對照顏色表
    public LightModeType LightMode = LightModeType.All; // 下方有對照表
    public CommandModeType CommandMode = CommandModeType.Immediately; // 下方有對照表
    public FeedBackModeType FeedBackMode = FeedBackModeType.Basic; // 下方有對照表
    public ShowTimeModeType ShowTimeMode = ShowTimeModeType.Short; // 下方有對照表
    
}

### WhizToysSignal
接收壓力用的格式

public class WhizToysSignal
{
    public WhizToysLayout Layout;
    
    // 壓力順序分別為 0:左上、1:左下、2:右下、3:右上。 
    // 壓力又有分為4個階段 0:無壓力 1:弱壓力 2:中壓力 4:強壓力
    public int[] Pressures; 
}

## 可調用事件

### OnInitSuccess

當初始化成功時觸發

接應方式：

public void OnInitSuccess(){}
whizToys.OnInitSuccess = OnInitSuccess;

### OnScanDevice

當偵測到設備時觸發

接應方式：

public void OnScanDevice(string address, string deviceName){}
whizToys.OnScanDevice = OnScanDevice;

### OnScanEnd

當偵測時間到時觸發

接應方式：

public void OnScanEnd(){}
whizToys.OnScanEnd = OnScanEnd;

### OnConnected

當成功連線到設備時觸發

接應方式：

public void OnConnected(WhizToysMap whizToysMap){}
whizToys.OnConnected = OnConnected;

### OnDisconnect

當設備斷線時觸發

接應方式：

public void OnDisconnect(){}
whizToys.OnDisconnect = OnDisconnect;

### OnReceiveSignal

當收到壓力訊號時觸發

接應方式：

public void OnReceiveSignal(List<WhizToysSignal>){}
whizToys.OnReceiveSignal = OnReceiveSignal;

## 改顏色基本設定

### LightModeType (enum)
描述燈光亮燈位置。當被設定為整片亮時不管踩哪一個位置感測器，4顆 LED 燈會一起亮燈。

* All -> 整片亮
* LeftUp -> 左上單獨亮
* LeftDown -> 左下單獨亮
* RightUp -> 右下單獨亮
* RightDown -> 右上單獨亮
* Only -> 全部單獨亮

### CommandModeType
描述觸發機制，當指令下達時，是否立即顯示一次回饋。

* Immediately -> 直接觸發一次回饋
* AfterClick -> 踩踏後觸發

### FeedBackModeType
描述踩踏的回饋模式。當作不是設定回饋模式時，所下的指令將直接控制燈光亮暗。

* None -> 不指定（代表現在不是在設定回饋方式）
* ClickNone -> 踩踏無回饋
* Basic -> 基本
* Flash -> 閃爍
* Marquee -> 跑馬燈
* Breathe -> 呼吸燈
* Neon -> 霓虹燈

### ShowTimeModeType
描述回饋時間長短。閃爍以及跑馬燈的時間長短。

* Short -> 短
* Long -> 長

## 顏色表

| 紅色值 R | 綠色值 G | 藍色值 B | 編號 | 顏色 |
|:--------:|:--------:|:--------:|:----:|:----:|
| 0 | 0 | 0 | 00 | |
| 255 | 0 | 0 | 01 | 紅色 |
| 255 | 25 | 0 | 02 | |
| 255 | 50 | 0 | 03 | |
| 255 | 75 | 0 | 04 | |
| 255 | 100 | 0 | 05 | |
| 255 | 125 | 0 | 06 | |
| 255 | 150 | 0 | 07 | |
| 255 | 175 | 0 | 08 | |
| 255 | 200 | 0 | 09 | |
| 255 | 225 | 0 | 10 | |
| 255 | 255 | 0 | 11 | 黃色 |
| 225 | 255 | 0 | 12 | |
| 200 | 255 | 0 | 13 | |
| 175 | 255 | 0 | 14 | |
| 150 | 255 | 0 | 15 | |
| 125 | 255 | 0 | 16 | |
| 100 | 255 | 0 | 17 | |
| 75 | 255 | 0 | 18 | |
| 50 | 255 | 0 | 19 | |
| 25 | 255 | 0 | 20 | |
| 0 | 255 | 0 | 21 | 綠色 |
| 0 | 255 | 25 | 22 | |
| 0 | 255 | 50 | 23 | |
| 0 | 255 | 75 | 24 | |
| 0 | 255 | 100 | 25 | |
| 0 | 255 | 125 | 26 | |
| 0 | 255 | 150 | 27 | |
| 0 | 255 | 175 | 28 | |
| 0 | 255 | 200 | 29 | |
| 0 | 255 | 225 | 30 | |
| 0 | 255 | 255 | 31 | 淺藍 |
| 0 | 225 | 255 | 32 | |
| 0 | 200 | 255 | 33 | |
| 0 | 175 | 255 | 34 | |
| 0 | 150 | 255 | 35 | |
| 0 | 125 | 255 | 36 | |
| 0 | 100 | 255 | 37 | |
| 0 | 75 | 255 | 38 | |
| 0 | 50 | 255 | 39 | |
| 0 | 25 | 255 | 40 | |
| 0 | 0 | 255 | 41 | 藍色 |
| 25 | 0 | 255 | 42 | |
| 50 | 0 | 255 | 43 | |
| 75 | 0 | 255 | 44 | |
| 100 | 0 | 255 | 45 | |
| 125 | 0 | 255 | 46 | |
| 150 | 0 | 255 | 47 | |
| 175 | 0 | 255 | 48 | |
| 200 | 0 | 255 | 49 | |
| 225 | 0 | 255 | 50 | |
| 255 | 0 | 255 | 51 | 紫色 |
| 255 | 0 | 225 | 52 | |
| 255 | 0 | 200 | 53 | |
| 255 | 0 | 175 | 54 | |
| 255 | 0 | 150 | 55 | |
| 255 | 0 | 125 | 56 | |
| 255 | 0 | 100 | 57 | |
| 255 | 0 | 75 | 58 | |
| 255 | 0 | 50 | 59 | |
| 255 | 0 | 25 | 60 | |
| 255 | 255 | 255 | 61 | 白色 |