# FairyGUI in Egret

### 簡介
此UI編輯器可以跨引擎使用，產生的UI layout在Egret內是透過RES資源載入，
掛至skin的節點上顯示。

### 準備作業

[安裝FairyGUI](https://www.fairygui.com/)
[官方Demo專案](https://github.com/fairygui/FairyGUI-egret)
[官方文件](https://www.fairygui.com/docs/guide/sdk/egret.html)

首先要先從官方的Demo專案裡面將 FairyGUI 的 Library 複製到 Egret 專案的 lib 資料夾

並且在 **egretProperties.json** 加入以下敘述，記得加入後要執行 **egret build -e**

官方說 rawinflate 並不是必須要複製的 Library，只要在 FairyGUI 的發布設置中將 壓縮描述文件 的選項不要打勾，就不會使用到這個 Library

### 開始使用

創建項目時要選擇輸出的引擎

即使在創建時忘了選擇引擎，也可以在事後改變

| 對齊按鈕 | 功能 |
|:------------------------------------:|:------------:|
|  | 左對齊 |
|  | 左右居中對齊 |
|  | 右對齊 |
|  | 上對齊 |
|  | 上下居中對齊 |
|  | 下對齊 |
|  | 相同寬度 |
|  | 相同高度 |

執行 **相同寬度** + **相同高度** + **上下左右居中對齊** 後就是全部擴展了

設置關聯性，讓元件可以跟著Parent狀態變化 (例如，不管Parent大小如何變化都是置中)

當UI都編排好了之後需要進行發佈的動作，而egret就是將發佈後的檔案作為資源，載入到遊戲中，再顯示於場景
紅框的部分是發佈後的資源名稱

發佈位置要在 Egret 專案的 **assets** 資料夾裡面

發佈之後會產生 **\*.fui** 的檔案，若有圖片資源會另外產生一張 texture 檔案

打開 **ResDepot**，將 **FairyGUI** 匯出的資源匯入 **default.res.json**，資源類型是 **bin**

打開 VSCode，在載入資源之後加入

private _mainPanel: fgui.GComponent;

private showFairyGUI() {
        this.stage.addChild(fgui.GRoot.inst.displayObject);
        // FairyGUI 在 res 裡面的名稱
        fgui.UIPackage.addPackage("LobbyUI");
        // 從 Package 取得 Component 實體
        this._mainPanel = fgui.UIPackage.createObject("LobbyUI", "MainPanel").asCom;
        fgui.GRoot.inst.addChild(this._mainPanel);
    }

Package 和 Component 的名稱是對應

這樣就可以在 build 出來的網頁上看到 UI 了

---
### 點陣圖字體(BitmapFont)

在編輯器的最上方點擊這個按鈕

設定字體名稱

開啟功能畫面

從資源庫將數字圖片拖入功能畫面中

雙擊字符的框可以編輯 Font 在 Text 中代表的文字
占位表示固定給這個字符多少寬度，0為不設置，使用圖片寬度

使用時，在文字框的Inspector中這裡選擇要使用的BitmapFont

這樣就能使用BitmapFont

---
### 多國語言 (分支)

首先要在項目設置中設定分支的名稱

資源庫中，在需要多國語言的Package項目按右鍵新增分支(無法在Package以外的項目新增分支QQ)
並且將相同名稱的圖片，以同樣的資料夾結構方式放置(若放置位置不一樣時，分支不會起作用)

切換分支，場景上與分支相同名稱的圖片會被替換成分支的圖片，而沒有在分支的圖片不會被替換或消失

在程式中切換分支

// 在開始load任何fgui前設置，這樣之後載入的package都會是這個分支
fgui.UIPackage.branch = "id_id";

// 或是在載入package後設置，分支的編號從0開始，-1為主幹線
await fgui.UIPackage.loadPackage(packageName).then((pkg) => {
    pkg._branchIndex = 0;
});

---
### 動畫系統
1. 序列圖動畫
2. 龍骨動畫([需使用付費版](https://www.fairygui.com/pricing.html))
3. Tween(透過code，和egret內用法一樣)
4. <font color=#FF0000>Transition</font>(類似unity animation，如下圖)


| | 序列圖動畫 | 龍骨動畫 | Tween | Transition
| -------- | -------- | -------- | -------- | -------- |
| Egret | 無法在editor使用 | 無法在editor使用 | 無法在editor使用 | 無 |
| Fairy | `可預覽` | `可預覽` | 無法在editor使用 | `可預覽` |

---
### UI模組差異比較

| | Rect(圖形) | ComboBox(下拉式選單) | PopupWindow(彈出式視窗) | RichText |
| -------- | -------- | -------- | -------- | -------- |
| Egret | 支援橢圓 | 無 | 無 | 無 |
| Fairy | 支援多邊形 | 有 | 有 | 有 |

---
## 注意事項
* 變更遊戲畫面大小, 需要透過 egret 的 resize 事件, 去呼叫 GObject 執行 makeFullScreen() 位置才會更新

---

## FairyGUI 相較於 egret 的優點
* button容易客製每個狀態的外觀, 不需要額外寫code控制

## 缺點
* 對齊功能不容易使用
* 群組接近節點的概念, 但沒有anchor, pivot之類的功能
* 關閉物件需要勾選Invisible, 沒有其他能看出物件是否可見的依據

---
## 結語
FairyGUI在動畫系統各方面上比Egret方便，**<font color=#FF0000>缺點是龍骨需要付費</font>**。
UI系統上大多和EGUI的功能差不多，Inspector較美觀，多了一些細部設定(ex:圖片的填充模式)，有些設定在Egret也可以透過code補完(ex: 按鈕可直接在FairyGUI上設定click音效，但egret也可以透過code來實作此功能)，且Egret在排版對位上較為直覺。
由於其資源在發布時會自動打包成atlas，所以沒辦法和EGUI共用。(EGUI需要atlas的分割資訊json檔)
**可能給美術人員製作動畫來說是很方便的工具，且client可以直接套用至遊戲**。

###### tags: `Egret`