# Egret Manual

## Visual Studio Code
### 開啟專案
開啟資料夾

選擇專案目標

---

### 運行專案
開啟 <font color = #FF0000>**Terminal**</font>

運行專案 <font color = #FF0000>**egret run**</font> -a
-a 為 auto-compile 自動編譯，可不輸入

---

## 引擎架構與流程
### Stage
每個項目必須存在且唯一的容器，你可以把 stage 想像成是 scene 的容器

### Lifecycle
* onPause：當網頁進入 unfocus 狀態時觸發
* onResume：當網頁恢復 focus 狀態時觸發
* [官方文件](http://developer.egret.com/en/2d/getStarted/lifecycle)

### 專案結構

| | 內容 |
| -------- | -------- |
| .wing | 放置專案設定 (如：Screen 寬高、版本)、任務配置、啟動配置 |
| bin-debug | 編譯調試後的 js 檔案，內容應與 src 底下的檔案一致 (ts to js) |
| libs | 各種 module、底層與第三方 library |
| **resource** | 各種美術資源 (如：圖檔、Skin) |
| scripts | 發佈平台用的底層腳本群 |
| <font color = #FF0000>**src**</font> | 專案程式碼 (放置我們實作功能的地方) |
| template | 放置模板 (如：index.html、native loader) |
| **egretProperties.json** | 放置專案設定 (如：引擎版本、resource 來源) |
| favicon.ico | 即網頁 icon 圖示 |
| **index.html** | 即網頁入口 (來自 template 的 index.html) |
| manifest.json | 紀錄網頁清單 (你可以想像成 js list) |
| tsconfig.json | 設定編譯方式與編譯來源 |
| wingProperties.json | Expose 給 Egret Wing 的設定 (理論上不影響編譯) |

---

## Skin Part
白話文：UI 元件，如 Button, Label, Rect 這些都是
Skin 就是透過這些 UI 元件組成的，所以被命名為 Skin Part

當 Logic (ts) 綁定 Skin (exml)時，引擎底層會自動 bind 相同 ID 的 UI 元件

示例：


只要綁定的 Skin (exml) 有設定 UI 的 ID 就會觸發 partAdded，這個方法主要是讓你可以對 UI 做一些初始化設定，而不是在 Skin 端寫死

protected partAdded(partName: string, instance: any): void

---

## Visual Studio 2019
### 安裝必要套件
開啟 **Visual Studio Installer**, 選擇安裝 **Node.js 開發**

開啟專案方法和VS Code相同

### 運行專案
* 開啟 **View/Terminal** (預設是PowerShell, 可到Setting更換)
* 開啟 **Tools/Command Line/**
* **Developer Command Prompt**
* **Developer PowerShell**
* 開啟 **Tools/NuGet Package Manager/Package Manager Console**

### Issue
* NuGet Package Manager Console的中文會變成亂碼
* NuGet Package Manager Console執行egret run後就無法停止

---

## Egret UI Editor
### 開啟專案
開啟資料夾

選擇專案目標

---

### Skin
UI 元件 (*exml*)

---

#### 新增 Skin

此時你的畫面應該要長這樣，mySkin 為剛剛創立的 Skin

拖入一個 Rect 元件 (此步驟非必要，單純方便演示)

將 Rect 佈滿畫面 (此步驟非必要，單純方便演示)

放入一個 Label (此步驟非必要，單純方便演示)

---

#### 匯入 Skin
回到 VS Code 並創建一個 TestMySkin.ts

第一種宣告 skin 來源的方式：
在 constructor 宣告位置 (即上述步驟所創建的 mySkin 位置)

第二種宣告 skin 來源的方式：
在 resource/default.thm.json 裡新增位置 (即上述步驟所創建的 mySkin 位置)
類別對應 Skin

在 Main.ts (專案核心) 呼叫創建 TestMySkin

重新編譯後就能看到剛剛的創建的 Skin 囉

---

#### 定義自己的 Skin 位置
在 resource 底下新增資料夾

在 egretProperties.json 新增 eui 來源位置

回到 Egret UI Editor 沒有看見，請先試著 Reload
如果還是無法顯示, 請檢查 egretProperties.json 是否有語法錯誤

**<font color=#ff0000>skin更名, exml 的 class name 會被加料, 需要自行檢查</font>**

---

### Anchor設定
* 假設有個 50x20 的矩形, 想設定中心點在正中間
* unity: **x=0.5 y=0.5**
* egret: **x=25 y=10**

---

## Tween

Sequence 基本用法

let tween = egret.Tween.get(指定物件, { loop: true });
tween.to({ alpha: 1}, 200);
tween.wait(500);
tween.to({ alpha: 0.5}, 200);
tween.wait(500);
tween.play();

同時播放多個效果

let tween = egret.Tween.get(指定物件, { loop: true });
tween.to({ alpha: 1, scaleX: 1.5, scaleY: 1.5 }, 200);
tween.wait(500);
tween.to({ alpha: 0.5, scaleX: 1, scaleY: 1 }, 200);
tween.wait(500);
tween.play();

---

## Atlas

可以使用 **Texture Merger** 來產生 Atlas 的圖片檔

打開之後選擇 **Sprite Sheet**

將選擇的圖片拖到右側

這樣就產生熟悉的畫面了

左下角可以變更圖片排列的設定

接著使用 Export 匯出 Atlas 和 json 檔案

將這兩個檔案放到 egret 的 resource\assets 下面，並且將兩個檔案拖到 資源編輯器(default.res.json)裡面

這樣就能看到 Atlas 被匯入到資源編輯器裡面了

Subkeys 代表這個 Atlas 下所有圖片的名稱，最後就可以在 UI Editor 的 asset 裡面看到 Atlas 所有的圖片了

---

### 使用 particle
* [導入particle library](https://hackmd.io/laBGtO7NRVGkXu8kIbZoIA#%E4%BB%A5%E5%AE%98%E6%96%B9%E6%8E%A8%E8%96%A6%E7%9A%84%E7%89%A9%E7%90%86%E5%BC%95%E6%93%8Ep2%E7%82%BA%E4%BE%8B)
* 使用工具 **Egret Feather** 輸出 snow 範本, 會有2個檔案

檔名.json
檔名.png

* 將檔案匯入到resource - [參考DragonBones匯入方法](https://hackmd.io/P7dkrekcS-GFM8IaZqWjKg#%E5%8C%AF%E5%85%A5%E8%B3%87%E6%BA%90%E5%88%B0-Egret-%E5%B0%88%E6%A1%88)
* 使用方法

let config = RES.getRes("檔名_json");
let tex: egret.Texture = RES.getRes("檔名_png");
let sys = new particle.GravityParticleSystem(tex, config);

sys.explosionParticle.start();
this.addChild(sys);

---

### 發佈正式版本
* 打開 console 輸入 **egret publish**
* 專案底下會出現資料夾 **bin-release**
* 需要放到 http server 才能觀看
* 只要修改專案中 **\*.min** 的檔案，修改後的內容也會被發佈出來

---

### eui.ItemRenderer 的 data
* data 預設型別是 any
:::warning
class 繼承 eui.ItemRenderer 可複寫 data, 並指定型別
:::

:::danger
data 不能指定預設值, 否則會經由 eui.js 定義的 setter 觸發 dataChanged(), 造成流程上的問題
:::

:::spoiler

get: function () {
    return this._data;
},
set: function (value) {
    this._data = value;
    eui.PropertyEvent.dispatchPropertyEvent(this, eui.PropertyEvent.PROPERTY_CHANGE, "data");
    this.dataChanged();
},

:::

---

### 5.3.5 之前的版本使用 TTF
:::success

<style type="text/css">
    @font-face {
        font-family: 'myFont';
        src:url('font/myFont.TTF') format('truetype');
        font-weight: normal;
        font-style: normal;
    }		
	.egret-player{
		font-family: "myFont";	
	}		
</style>

label 的 fontFamily 需要手動指定成 css 上面設定的字型名稱
:::

---

## 相關文章
[官方手冊](http://developer.egret.com/cn/github/egret-docs/Engine2D/index.html?home=2)

[無痛起手 Egret](https://ithelp.ithome.com.tw/articles/10211534)

[Egret FAQ](/b1E2Ft89Q9K25m9xVh31OA)

###### tags: `教學`