NUGANUGA Web SDK

你的遊戲會在 https://play.nuganuga.com 上的沙箱 iframe 中執行。SDK 是通往平台的唯一管道 — 驗證、排名、分享、廣告與分析都不必自己實作。

1. 載入 SDK

一律使用這個絕對路徑。散布與版本管理由平台負責。

<script src="/sdk/nuga-sdk.js"></script>
<script src="./game.js"></script>

2. 四個呼叫

const ctx = await Nuga.ready();       // 等待平台就緒
await Nuga.game.start();              // 玩家真正開始一場時
await Nuga.score.submit({ score });    // 每場只送出一個數值分數
await Nuga.game.finish();             // 平台繪製結果畫面

不要自己畫結果畫面、重玩按鈕、分享按鈕或排行榜 — finish() 之後平台會為每款遊戲繪製完全一致的介面。

3. 其他功能

Nuga.game.getContext();
Nuga.player.get();
Nuga.challenge.get();
Nuga.storage.get(key);
Nuga.storage.set(key, value);
Nuga.audio.setMuted(true);
Nuga.locale.get();               // 'en' | 'ko' | ...
Nuga.event.track('level_up', { level: 3 });
Nuga.on('pause', () => pauseLoop());

4. 資訊檔

放在封包根目錄的 nuga.json：

{
  "schemaVersion": 1,
  "name": "Reaction Hunter",
  "slug": "reaction-hunter",
  "description": "Click 10 targets as fast as possible.",
  "rule": "Tap every target as fast as you can.",
  "category": "REACTION",
  "orientation": "PORTRAIT",
  "duration": { "min": 5, "max": 30 },
  "input": ["POINTER", "TOUCH"],
  "ranking": { "type": "LOW_TIME", "unit": "ms" },
  "entry": "index.html",
  "locales": {
    "ko": { "name": "리액션 헌터", "description": "10개의 타겟을 빠르게 클릭하세요." }
  }
}

排名類型：HIGH_SCORE, LOW_SCORE, LOW_TIME, HIGH_TIME, CUSTOM。分類：REACTION、TIMING、ACCURACY、MEMORY、PUZZLE、LUCK、ARCADE。

5. 沙箱規則

違反其中任何一項的封包，都會在送到玩家面前之前被靜態驗證擋下：

禁止外部 URL — 不可使用 CDN、網路字型或遠端圖片。所有資源都要打包進去。
禁止 eval、new Function、document.write 與 document.cookie。
禁止自建網路連線：指向絕對 URL 的 fetch、XMLHttpRequest、WebSocket 與 Service Worker 會同時被 CSP 和靜態驗證擋下。
禁止最上層導覽與彈出視窗。
封包小於 5 MB；微型遊戲建議控制在 1 MB 以內。
至少呼叫一次 Nuga.score.submit() — 產生不了分數的遊戲無法進入排名。
平台外殼是固定的：index.html、外殼樣式表和 game.js 中的框架必須保持不變。只有 run() 主體和 #field 樣式可以修改。

下載入門套件 ↓

6. 分數會在伺服器端驗證

每一場都會配發一個伺服器端工作階段。你的遊戲看不到工作階段權杖 — 由平台外殼保管並代為送出 — 伺服器會先比對實際經過時間與資訊檔宣告的範圍，才讓成績進入排行榜。

你還可以做得更好。用伺服器發放的種子產生亂數，並記錄實際發生的過程，伺服器就會依據這些事件重新計算分數，而不是相信你回報的數字。紀錄無法支撐的成績會被直接拒絕。

const rng = Nuga.random();          // 由伺服器提供種子 — 與 Math.random() 不同，可重現
const target = rng.int(0, 8);

Nuga.replay.record('hit', 172);     // 一筆與分數相關的事件，每場最多 400 筆

在 nuga.json 宣告玩法機制即可啟用。不宣告也能進入排名，只是僅有時間與範圍檢查。

"verification": { "kind": "REPLAY_V1", "mechanic": "REACTION",
                   "params": { "rounds": 5 } }

7. 發布

壓縮封包的根目錄（不是外層資料夾），再到創作者主控台上傳。靜態驗證、建置、執行期、響應式、玩法與安全測試都會自動執行，全部通過後就能發布。