# LabFrame 2022 beta

## What Is This
實驗室資料上傳框架（Unity），提供即時存檔，關閉遊戲自動存檔功能

* Features:
* 資料存檔管理
* ~~資料上傳功能~~
* 跨場景資料使用
* 目前支援：Windows、Android、Pico
* Support Unity version：2019.4、2020.3 or above

## How To Use
* 從 LabFrame 2022 -> Prefab 資料夾底下找到 LabFrame ，放入遊戲第一個場景
* 需要儲存的資料 Class 繼承 LabDataBase，並且加上 `[Serializable]`（腳本要加入`using System;`），如果有 `{get;set;}` 要刪除
* 設定 Config（LabFrame 2022 -> Resources -> LabDataConfig），詳細說明在底下 Config Data
* 至少要設定 GameID，才能保證資料跟其他遊戲分開
* 非 Windows 系統要設定 LocalPath
* ProjectSettings -> Script Execution Order 加入 LABApplication（使框架先執行）
* 遊戲確定開始前要呼叫 LabDataManager.Instance.LabDataInit，詳情

### 退出提示
* 如果在遊戲仍然在儲存嘗試退出遊戲（`Application.Quit()`），那麼會因為正在儲存而停止，透過以下設定可以自動出現醒目提示
1. ProjectSettings -> Tags and Layers
2. 新增一個 `MainCanvas` 的 **Tag**
3. 在每一個場景中的主要 Canvas （盡量選取為可以覆蓋整個螢幕的）上給予 MainCanvas 的 Tag

### 其他功能
* Prefab 可以讓你在遊戲中動態更改 Config 檔
* ~~Uploader 為上傳專案場景~~

## Prefab
* LabFrame：框架主體
* Upload：將其放在主頁面 UI 上，遊戲中勾選代表資料需要上傳、反之則只存本地
* Test：將其放在主頁面 UI 上，遊戲中勾選代表資料是測試非重要收案資料，反之則是
* Option
* 遊戲模式用，如果有遊戲有多模式可以使用
* 將其放在主頁面 UI 上，可以直接用 Unity 介面增加選項
* 框架會讀取選項的 Label 來分別模式，盡量不要使用中文
* QuittingPanel：遊戲退出時通知面板（不清楚請不要動，除非是想調整它的布局）

~~## Uploader~~
~~1. 開一個新的專案，並匯入框架~~
~~2. 開啟場景 LabFrame 2022 -> Uploader（或 UplaoderVR）~~
~~3. 根據輸出平台調整 Project Settings
~~ * Product Name：LabData Uploader~~
~~4. 調整 Config 到你遊戲指定的存檔目錄（`LabDataConfig` 中的 `LocalPath`）~~
~~ * 記得 遊戲 和 上傳程式 的 Config 必須一致~~
~~ * Pico / Android 平台：`/storage/emulated/0/LabData`~~
~~7. 輸出~~

## Local Data
* 預設儲存在對應裝置的 `Application.persistentDataPath` 中
* Windows 或 Editor 在 `文件 -> LabData -> [遊戲ID]`
* 可以透過 Config 檔案修改，如果需要背景上傳，必須修改
* Config 儲存設定檔
* ForSend 儲存還未上傳但需要上傳的資料
* ForStore 儲存已經上傳或不需要上傳的資料

## API
* 呼叫方式：`[ClassName].Instance.[FunctionName or EventName]`
* ex. `LabDataManager.Instance.LabDataInit("");`
* 存檔命名：`[TimeStamp]_[GameID+LocID_[UserID]_[GameMode]_[DataClassName].json`
* GameMode 非必要項
* 不同的 DataClassName 會存在不同檔案中

### LABApplication Class
> **void AppRestart()**
* 重啟本框架，用於結束資料收集後，可以收下一筆
* 呼叫後，程式會完成本地存檔
* 呼叫後如需再使用框架，需要重新 LabDataInit

### LabDataManager Class
> **public LabGameData GameData**
* 跨場景資料，可以透過LabDataManager自由呼叫資料
* 裡面有範例：Language
* 定義在 Prefab 資料夾中
* 呼叫方式：`LabDataManager.Instance.GameData.[變數名稱]`
> **public void LabDataInit(string userID)**
* 開始遊戲後呼叫，不呼叫無法儲存資料
* userID 可填可不填（不填自動生成），代表本次收案資料 ID
> **public void SetConnectInfo(string jwt, string deviceID)**
* 以獲得的 JWT 和 DeviceID 來獲取上傳用 SSHKey
> **public void WriteData(LabDataBase data)**
* 寫入一筆有繼承 LabDataBase 的類別資料
~~> **public bool UploadData**~~
~~* 上傳所有本地資料~~
~~* 回傳是否開始上傳~~
> **public bool DeleteData(string motionId, DataDir dir)**
* 刪除特定 Motion ID 資料
* dir 設定選定刪除 ForSend、ForStore、或 Both（二者）（預設）
* 回傳 False 如果沒有刪除任何資料
> **public void SetConfig**
* 儲存目前設定到本地端 LabData Config
* 此為 Prefab 使用功能
> **public void ResetConfig**
* 重置本地端 LabData Config 到初始值，並重啟本框架
* 如果在開發期間不想每次重新設定 LabData Config 就要重裝遊戲，可以呼叫這個 API

#### 事件
> **public Action<LabDataBase> GetDataAction { get; set; }**
* 寫入資料完成事件，回傳已寫入資料
> **public Action<string> SendDataAction { get; set; }**
* 上傳資料完成或失敗事件，回傳上傳狀況字串

## Config Data
* 設定檔會在第一次進行程式後就儲存在裝置上，除非重裝否則不會覆蓋
* 也就是說開發中如果有調整 Config 檔，記得要將遊戲重裝才會生效
* Unity Editor 會在 `C:\Users\[使用者名稱]\AppData\LocalLow\[Company Name]\[Package Name]`
* Resourse 資料夾底下有 Application 和 LabData 兩個 .json 設定檔，讓開發者可以預設
* 如果 ID 部分不需要，讓他等於空白字串即可
* LabDataConfig 資料儲存和下載設定
* SendToServer：是否上傳
* IsTest：是否為測試
* ServerPath：伺服器位置
* LocalPath：本地儲存位置（絕對位置）
* Pico / Android：`/storage/emulated/0/LabData`
* LocalSaveDataTimeLayout：時間儲存格式
* GameID：本遊戲 ID
* 如果沒有設定 LocalPath，這會代表你的遊戲儲存位置
* LocID：地點 ID
* GameMode：遊戲模式 ID （可空白）
* SerialID：序列 ID ，建議保持為 0 ，裝置上仍可再次設定
* Application Config（暫時無用）

## 注意事項
* 儲存的資料 Class 必須是純資料
* 不能有 attribute，也就是 `{get; set;}`
* 不能 定義函數 或 呼叫函數（可以有建構式）
* LabDataConfig 的 GameID 不能空白
* 請勿嘗試把 LabGameData.cs 當成資料儲存

## FAQ
* Q：錯誤 `NullReferenceException，LabDataManager.Instance....`
A：沒有將 Prefab 資料夾底下 LabFrame 放入遊戲第一個場景，LabFrame 在切換場景時不會被刪除，請務必把它放在 Build Order 的第一個場景中。
* Q：錯誤 `FindObjectsOfType...`
A：沒有進行 ProjectSettings -> Script Execution Order 加入 LABApplication，或是有在 Script Execution 前面插入了其他自做的腳本
* Q：Android 錯誤 `UnauthorizedException`
A：請務必讓專案根據對應平台做專案調整，如 Pico 要進行 XR 環境建置，否則平台會無法辨識程式需要的權限而導致錯誤。

## More Information
110522166 楊政哲