Mugeda API 提供了一套簡單又有結構的方式,讓你能在執行時動態操控 Mugeda 內容。以下依序說明它的能力範圍、基本用法與各個核心物件。
Mugeda API 建構在原生 JavaScript 之上,不需要額外的函式庫。
上手非常輕鬆。在 Mugeda IDE 中,只要點一下工具列上的腳本按鈕
,在開啟的腳本視窗裡寫下程式碼就可以了。

大部分 API 都掛在一個名為 Mugeda 的命名空間(物件)底下,其中最关键的三個類別是:內容(Mugeda)、場景(Scene)、元素(Element)。

每一個 Mugeda 內容都由一個內容物件代表:
var content = Mugeda.getMugedaObject(); var title = content.title; var width = content.width; var height = content.height;
只有在 Mugeda 內容載入完成、準備好被呈現之後,場景物件才是有效的。因此請務必監聽 renderReady 事件,等到觸發後再存取場景。
var mugeda = Mugeda.getMugedaObject();
mugeda.addEventListener('renderReady', function () {
var scene = mugeda.scene;
// 你的程式碼放在這裡
});
取得主舞台場景,以及取得元件實例的場景:
var scene = mugeda.scene;
var symbolInstance = mugeda.scene.getObjectByName('symObj');
var symbolScene = symbolInstance.scene;
常用的播放控制:
scene.play(); // 播放 scene.pause(); // 暫停 scene.gotoAndPlay(num); // 跳到指定影格後播放 scene.gotoAndPause(num); // 跳到指定影格後暫停 var id = scene.currentId; // 取得當前影格編號 scene.gotoPage(num); // 跳到指定頁(頁碼從 0 起算) scene.nextPage(); // 下一頁 scene.prevPage(); // 上一頁
在同一個元件場景中,你可以先定義好幾個段落並命名,執行時再指名播放,這樣就能精準控制元件場景的播放行為。
scene.setSegment('seg1', 0, 5, false); // 把 0~5 影格命名為 seg1,不循環
scene.setSegment('seg2', 6, 10, true); // 把 6~10 影格命名為 seg2,循環
scene.playSegment('seg1'); // 跳到第 0 影格,一路播到第 5 影格
scene.playSegment('seg2'); // 跳到第 6 影格,一路播到第 10 影格後循環
每一個影格被呈現之後,場景物件都會觸發一次 enterFrame 事件。掛上監聽器,就能在每幀執行自定的邏輯。
var callback = function (frameId) {
console.log('Current frame is: ' + frameId);
};
scene.addEventListener('enterframe', callback);
場景中的每一個物件都由一個元素物件代表,它可能是一張圖片、一段文字、一個圖形,或一個元件實例。

// 取得元素
var element = scene.getObjectByName('face');
// 複製元素
var copy = element.clone();
// 建立新的元件實例
var instance = mugeda.createInstanceOfSymbol('symbol_name');
// 加入與移除
scene.appendChild(element);
scene.removeChild(element);
要新增一個元素,應該先複製既有元素,或由元件建立一個實例;要刪除的元素,則先用 scene.getObjectByName 取得。
屬性的讀寫:
var x = element.x; // 讀取 x 座標 element.x = 100; // 設定 x 座標
除此之外,name、x、y、top、bottom、left、right、scaleX、scaleY、width、height、rotateCenterX、rotateCenterY、rotate、visible、alpha 都可以同樣存取。另外,圖片的 element.src 就是它的網址,換掉 src 就能換圖;文字的內容在 element.text;元件實例的場景則是唯讀的 obj.scene。
為物件掛事件,寫法跟處理 DOM 幾乎一樣:
element.addEventListener('click', callback);
支援的事件包含:mousedown、mouseup、click、dblclick、mouseover、mouseout、mousemove、touchstart、touchmove、touchend、inputstart、inputmove、inputend。
特別值得一提的是 Input 系列事件:它把滑鼠事件與觸控事件包在一起,只要監聽 input*,PC 上的滑鼠操作與手機、平板上的觸控操作就能用統一的方式處理,不必再分別寫兩套。
element.addEventListener('inputmove', function (event) {
var x = event.inputX;
var y = event.inputY; // 取得滑鼠或手指的位置
});
預設情況下,Mugeda 播放器會等所有資源(圖片、音訊等)都載入完才開始播放。若你想手動控制載入時機——例如先快取開頭幾幀,縮短等待時間讓動畫更快開始——可以呼叫 mugeda.cacheZone()。在 renderReady 監聽之前呼叫它來預載前段資源時,回呼函式不會被觸發;而在 renderReady 回呼裡再次呼叫以載入其餘影格時,回呼函式就會被呼叫,接著判斷參數 percent 是否等於 1 就能知道載入是否完成。
var mugeda = Mugeda.getMugedaObject();
mugeda.cacheZone(startFrame, endFrame, [], function (percent) {
console.log(percent);
if (1 === percent) {
// 載入完成,做相應處理
}
});
下面用一個顯示目前時間的時鐘,把前面的觀念串起來。

步驟 1:建立模型。在 0 圖層、第 1 影格,導入鐘面、時針、分針、秒針四張圖片。

步驟 2:調整旋轉中心。選每一根指針,右鍵選擇「群組 → 組合」,接著按下滑比例鈕 ,按住 Ctrl 鍵把旋轉中心拖到鐘面正中央。

步驟 3:命名。在 IDE 中逐一選取圖片並命名,本例分別取名為 face、hour_hand、minute_hand、second_hand。

步驟 4:編碼。點工具列上的腳本按鈕開啟編輯器。

寫法上分成幾小步:先取得 mugeda 物件,在 renderReady 中取得場景,用 getObjectByName 拿到三根指針,然後寫一個 updateTime 函式,依目前時間換算出各指針的旋轉角度。
var now = new Date(),
sec = now.getHours() * 3600 + now.getMinutes() * 60
+ now.getSeconds() + now.getMilliseconds() / 1000;
hourHand.rotate = sec / (6 * 3600) * Math.PI;
minuteHand.rotate = sec / 1800 * Math.PI;
secondHand.rotate = sec / 30 * Math.PI;
步驟 5:每幀更新。時鐘要動起來,就得在每一幀都重算指針位置。最省事的做法是監聽 enterframe,每幀呼叫一次 updateTime():
scene.addEventListener('enterframe', function () {
updateTime();
});
按下預覽鈕執行,時鐘就開始走了。完整程式碼如下:
var mugeda = Mugeda.getMugedaObject();
mugeda.addEventListener('renderReady', function () {
var scene = mugeda.scene;
var hourHand = scene.getObjectByName('hour_hand'),
minuteHand = scene.getObjectByName('minute_hand'),
secondHand = scene.getObjectByName('second_hand');
var updateTime = function () {
var now = new Date(),
sec = now.getHours() * 3600 + now.getMinutes() * 60
+ now.getSeconds() + now.getMilliseconds() / 1000;
hourHand.rotate = sec / (6 * 3600) * Math.PI;
minuteHand.rotate = sec / 1800 * Math.PI;
secondHand.rotate = sec / 30 * Math.PI;
};
scene.addEventListener('enterframe', function () {
updateTime();
});
});
有了這套 API,你就能用腳本控制動畫作品,做出光靠時間軸做不到的效果,小遊戲就是最典型的例子。下一節,我們要談的是「跨屏互動應用」的製作。