Mugeda API 提供一種結構化的方式,讓開發者可以即時控制 Mugeda 內容。你可以取得內容中的物件、讀取或設定屬性、控制動畫播放,也能新增、移除與編輯場景中的元素,並處理滑鼠與觸控事件。
Mugeda API 以原生 JavaScript 為基礎,不需要額外載入其他函式庫。
在 Mugeda IDE 中,只要點擊腳本工具列上的按鈕,就能打開編輯環境並開始撰寫程式。
Mugeda API 的核心集中在 Mugeda 命名空間。最常見的三個類別是內容、場景與元素:內容代表整個作品,場景代表舞台,元素則代表畫面中的每個物件。
每一個 Mugeda 內容都可以用內容物件表示。取得方式如下:
var content = Mugeda.getMugedaObject();
接著就能讀取標題、寬度與高度等基本資訊:
var title = content.title;
var width = content.width;
var height = content.height;
場景物件只有在內容載入完成並準備好渲染之後才可使用。因此,通常會先監聽 renderReady 事件,再取得場景物件並進行後續操作。
mugeda.addEventListener('renderReady', function () { var scene = mugeda.scene; });
取得場景後,你可以用名稱找到元素,也可以複製元素、建立元件實例,或把元素加入與移出舞台。
取得元素:
var element = scene.getObjectByName('face');
複製元素:
var copy = element.clone();
建立元件實例:
var instance = mugeda.createInstanceOfSymbol('symbol_name');
新增與移除元素:
scene.appendChild(element);
scene.removeChild(element);
若要新增元素,可以先複製既有元素,或從元件建立實例;若要刪除元素,則先用 getObjectByName 取得它。
常見元素屬性包括 x、y、寬高、旋轉、可見性與透明度。若是圖片元素,可以用 src 取得圖片網址;若是文字元素,可以用 text 取得文字內容。
元素事件的使用方式與 DOM 事件類似。你可以為元素加上點擊、滑鼠移入、觸控等事件監聽。
element.addEventListener('click', callback);
支援的事件包含 mousedown、mouseup、click、dblclick、mouseover、mouseout、mousemove、touchstart、touchmove、touchend,以及 inputstart、inputmove、inputend。
其中 input 系列事件把滑鼠與觸控統一處理,特別適合需要同時支援電腦與行動裝置的互動作品。
element.addEventListener('inputmove', function (event) { var x = event.inputX; var y = event.inputY; });
預設情況下,播放器會等所有資源載入完成後才開始播放。若希望縮短等待時間,可以手動快取部分影格。使用 cacheZone 時,可以指定起始影格、結束影格與回呼函數,並透過百分比判斷是否載入完成。
mugeda.cacheZone(startFrame, endFrame, [], function (percent) { if (percent === 1) { } });
接下來用一個時鐘範例說明 Mugeda API 的實際用法。這個範例會建立一個能顯示目前時間的時鐘,並讓時針、分針與秒針持續更新。
在 Mugeda IDE 中建立時鐘模型,於第 0 圖層與第 1 影格匯入鐘面、時針、分針與秒針四張圖片。
選取每一支指針,組合後使用縮放工具,將旋轉中心拖曳到鐘面中心,確保指針能正確旋轉。
在 IDE 中選取每個圖片並命名。範例中可將鐘面、時針、分針與秒針分別命名為 face、hour_hand、minute_hand 與 second_hand。
點擊工具列中的腳本按鈕,打開編輯器。
先取得 Mugeda 物件,並在 renderReady 事件中取得場景與指針:
var mugeda = Mugeda.getMugedaObject();
mugeda.addEventListener('renderReady', function () { var scene = mugeda.scene; var hourHand = scene.getObjectByName('hour_hand'); var minuteHand = scene.getObjectByName('minute_hand'); var secondHand = scene.getObjectByName('second_hand'); });
接著依目前時間計算旋轉角度。可先把時、分、秒與毫秒換算成總秒數,再換算成弧度:
var now = new Date();
hourHand.rotate = sec / (6 * 3600) * Math.PI;
minuteHand.rotate = sec / 1800 * Math.PI;
secondHand.rotate = sec / 30 * Math.PI;
若要讓時鐘持續運行,可以在場景的 enterframe 事件中呼叫更新函式,讓指針在每一影格都重新計算角度。
scene.addEventListener('enterframe', function () { updateTime(); });
完成後,點擊預覽即可看到時鐘依實際時間運行。
透過 Mugeda API,你可以用 JavaScript 控制動畫內容、操作場景元素,並建立具有互動性的網頁作品。掌握內容、場景與元素這三個核心概念後,就能進一步製作小遊戲、動態圖表與跨裝置互動應用。