---
# System prepended metadata

title: WhizToys SDK(Unity) 說明文件

---

# 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` 方法來初始化藍牙模塊：

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

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

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

### 掃描設備

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

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

### 連接設備

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

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

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

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

### 格子布局

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

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

### 改寫顏色

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

```csharp
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[] 分別為左上、左下、右下、右上。
    
以下為範例：

```csharp
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
定義格子的位置
    
```csharp
public struct WhizToysLayout
{
    public int Row;
    public int Column;

    public bool Compare(WhizToysLayout layout) // 用來比較兩個位置是否相同
}
```
    
### WhizToysBlock
定義格子的狀態
    
```csharp
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
定義格子的排列
    
```csharp
public class WhizToysMap
{
    public WhizToysLayout Layout; //這邊裡面的 Row 和 Column 是總共的數量
    public WhizToysBlock[,] Blocks;
}
```
    
### WhizToysSendModel
改變顏色用的格式
    
```csharp
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
接收壓力用的格式
    
```csharp
public class WhizToysSignal
{
    public WhizToysLayout Layout;
    
    // 壓力順序分別為 0:左上、1:左下、2:右下、3:右上。 
    // 壓力又有分為4個階段 0:無壓力 1:弱壓力 2:中壓力 4:強壓力
    public int[] Pressures; 
}
```
    
## 可調用事件
    
### OnInitSuccess

當初始化成功時觸發
    
接應方式：
    
```csharp
public void OnInitSuccess(){}
whizToys.OnInitSuccess = OnInitSuccess;
```
    
### OnScanDevice

當偵測到設備時觸發
    
接應方式：
    
```csharp
public void OnScanDevice(string address, string deviceName){}
whizToys.OnScanDevice = OnScanDevice;
```
    
### OnScanEnd

當偵測時間到時觸發
    
接應方式：
    
```csharp
public void OnScanEnd(){}
whizToys.OnScanEnd = OnScanEnd;
```
    
### OnConnected

當成功連線到設備時觸發
    
接應方式：
    
```csharp
public void OnConnected(WhizToysMap whizToysMap){}
whizToys.OnConnected = OnConnected;
```
    
### OnDisconnect

當設備斷線時觸發
    
接應方式：
    
```csharp
public void OnDisconnect(){}
whizToys.OnDisconnect = OnDisconnect;
```
    
### OnReceiveSignal

當收到壓力訊號時觸發
    
接應方式：
    
```csharp
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  | 白色 |
