跳至主要内容

WhizToys SDK(Unity) 說明文件

系統需求
  • SDK 版本：待補
  • 支援 Unity 版本：待補
  • Android 最低版本：待補
  • iOS 最低版本：待補

安裝​

下載 SDK：Whiztoys_SDK.unitypackage（Google Drive）

在您的 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&lt;WhizToysSignal&gt;){}
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編號顏色
00000
2550001紅色
25525002
25550003
25575004
255100005
255125006
255150007
255175008
255200009
255225010
255255011黃色
225255012
200255013
175255014
150255015
125255016
100255017
75255018
50255019
25255020
0255021綠色
02552522
02555023
02557524
025510025
025512526
025515027
025517528
025520029
025522530
025525531淺藍
022525532
020025533
017525534
015025535
012525536
010025537
07525538
05025539
02525540
0025541藍色
25025542
50025543
75025544
100025545
125025546
150025547
175025548
200025549
225025550
255025551紫色
255022552
255020053
255017554
255015055
255012556
255010057
25507558
25505059
25502560
25525525561白色