字節(jié)跳動小游戲

字節(jié)跳動小游戲是一種開放能力。允許用戶基于給定的 API 編寫游戲代碼，最終生成可運(yùn)行在接入小游戲功能的各產(chǎn)品 APP 上。

快速上手

安裝開發(fā)工具

前往開發(fā)者工具下載頁面 ，根據(jù)自己的操作系統(tǒng)下載對應(yīng)的安裝包進(jìn)行安裝。

文件結(jié)構(gòu)

.
├── game.js               =>  小游戲入口文件
├── game.json             =>  小游戲配置文件
└── project.config.json   =>  工程配置文件

以上三個文件為小游戲的三個必要文件，開發(fā)者如有其它資源可以在根目錄下自由建立 js, audio, images 等目錄，規(guī)范自己的開發(fā)文件。

配置

game.json 示例

{
  "deviceOrientation": "portrait",
}

deviceOrientation

project.config.json 示例

{
    "description": "項(xiàng)目描述",
    "setting": {
        "es6": true,   // 聲明使用的 js 語法版本
    }
}

平臺能力

tt API

本平臺只能使用 JavaScript 來編寫小游戲。小游戲的運(yùn)行環(huán)境是一個 綁定了一些方法的 JavaScript VM。不同于瀏覽器，這個運(yùn)行環(huán)境沒有 BOM 和 DOM API，只有 tt系列 API。接下來我們將介紹如何用 tt API 來完成創(chuàng)建畫布、繪制圖形、顯示圖片以及響應(yīng)用戶交互等基礎(chǔ)功能。

創(chuàng)建 Canvas

var canvas = tt.createCanvas();

通過調(diào)用 tt.createCanvas() 接口，可以創(chuàng)建一個 Canvas 對象。用戶第一次調(diào)用時， 獲取到的是一個上屏 Canvas，該 Canvas 已經(jīng)顯示在了屏幕上，且與屏幕等寬等高。小游戲運(yùn)行期間，有且僅有一個上屏 Canvas。

繪制

var context = canvas.getContext("2d");
context.fillStyle = "#ff00ff";
context.fillRect(0, 0, 100, 100);

觸摸事件

平臺提供了一系列監(jiān)聽觸摸事件的 API：

• tt.onTouchStart()
• tt.onTouchMove()
• tt.onTouchEnd()
• tt.onTouchCancel()

動畫能力

開發(fā)者可以利用定時器相關(guān) API 實(shí)現(xiàn)動畫效果，如下

• setTimeout
• setInterval
• requestAnimationFrame
• clearTimeout
• clearInterval
• cancelAnimationFrame

全局對象

小游戲的運(yùn)行環(huán)境不同于 Web 環(huán)境，在真機(jī)上運(yùn)行時，沒有BOM API，因此也就沒有 window 對象以及其上面的各種屬性。所以，從 H5 遷移過來的游戲，開發(fā)者需要自己實(shí)現(xiàn) window 對象的兼容(如果是利用游戲引擎開發(fā)的小游戲，導(dǎo)出的小游戲版本一般已經(jīng)包含了一份 adapter，適配了 window 對象)。同時，在小游戲的運(yùn)行環(huán)境中，提供了全局對象 GameGlobal，所有全局定義的變量都是 GameGlobal 的屬性。如：

setTimeout === GameGlobal.setTimeout; // true
requestAnimationFrame === GameGlobal.requestAnimationFrame; // true

同時，GameGlobal 是一個全局對象，也是一個循環(huán)引用的對象。

GameGlobal.GameGlobal === GameGlobal

關(guān)系鏈數(shù)據(jù)使用

為了豐富游戲的社交、對戰(zhàn)玩法，目前在字節(jié)跳動平臺上，對于部分宿主 APP（如抖音），我們?yōu)樾∮螒蛱峁┝双@取關(guān)系鏈數(shù)據(jù)的 API：

• tt.getCloudStorageByRelation 獲取指定關(guān)系類型的同玩該游戲的用戶數(shù)據(jù)

該接口返回的數(shù)據(jù)結(jié)構(gòu)可參考 API 文檔。除此之外，我們還提供了配套的操作用戶數(shù)據(jù)的一系列 API：

• tt.getUserCloudStorage
• tt.setUserCloudStorage
• tt.removeUserCloudStorage

開放數(shù)據(jù)域

為了讓開發(fā)者安全使用平臺的關(guān)系數(shù)據(jù)，我們提供了一個名為開放數(shù)據(jù)域的環(huán)境。這是一個封閉、獨(dú)立的 JavaScript 作用域。通過在 game.json 中添加配置項(xiàng) openDataContext 指定開放數(shù)據(jù)域的代碼目錄，來開啟該項(xiàng)功能，以便使用對應(yīng)的關(guān)系鏈數(shù)據(jù)接口，同時，在使用這一功能時，也會有一些限制。

{
  "deviceOrientation": "portrait",
  "openDataContext": "src/myOpenDataContext"
}

對應(yīng)的代碼目錄應(yīng)該如下：

├── src
|   └── myOpenDataContext
|       ├── index.js
|       └── ...
├── game.js
├── game.json
└── ...

index.js 作為開放數(shù)據(jù)域的入口文件是必需的，平臺構(gòu)建工具會將開放數(shù)據(jù)目錄下的文件自動打包為一個獨(dú)立文件，其代碼運(yùn)行在開放數(shù)據(jù)域。而 game.js 其代碼運(yùn)行在主域。

注意：

• 主域和開放數(shù)據(jù)域中的代碼不能相互 require。

主域和開放數(shù)據(jù)域的通信

開放數(shù)據(jù)域不能向主域發(fā)送消息。

主域可以向開放數(shù)據(jù)域發(fā)送消息。調(diào)用 tt.getOpenDataContext() 方法可以獲取開放數(shù)據(jù)域?qū)嵗?，調(diào)用實(shí)例上的 OpenDataContext.postMessage() 方法可以向開放數(shù)據(jù)域發(fā)送消息。

// game.js
const openDataContext = tt.getOpenDataContext();
openDataContext.postMessage({
  text: "This is a test."
});

在開放數(shù)據(jù)域中通過 tt.onMessage() 方法可以監(jiān)聽從主域發(fā)來的消息

// src/myOpenDataContext/index.js
tt.onMessage(data => {
  console.log(data);
  /* {
    text: 'This is a test.',
  } */
});

如何使用關(guān)系鏈數(shù)據(jù)

通過關(guān)系鏈 API 獲取到的用戶數(shù)據(jù)，在繪制排行榜等業(yè)務(wù)場景下如果想要展示，需要將排行榜繪制到 sharedCanvas 上，再在主域?qū)?sharedCanvas 渲染上屏?？蓞⒖家韵率纠a：

1. sharedCanvas 是主域和開放數(shù)據(jù)域都可以訪問的一個離屏畫布。在開放數(shù)據(jù)域調(diào)用 tt.getSharedCanvas() 將返回 sharedCanvas。根據(jù)業(yè)務(wù)邏輯獲取關(guān)系鏈數(shù)據(jù)，然后繪制到 sharedCanvas 上。

   //  src/myOpenDataContext/index.jsconst sharedCanvas = tt.getSharedCanvas();
   const context = sharedCanvas.getContext("2d");
   
   function drawRankList(data) {
     data.forEach((item, index) => {
       // ...
       context.fillStyle = "red";
       context.fillRect(0, 0, 100, 100);
     });
   }
   
   tt.getCloudStorageByRelation({
     success: res => {
       const data = res.data;
       drawRankList(data);
     }
   });

2. 在主域中可以通過開放數(shù)據(jù)域?qū)嵗L問 sharedCanvas，通過 drawImage() 方法可以將 sharedCanvas 繪制到上屏畫布。

   // game.jsconst openDataContext = tt.getOpenDataContext();
   const sharedCanvas = openDataContext.canvas;
   
   const canvas = tt.createCanvas();
   const context = canvas.getContext("2d");
   context.drawImage(sharedCanvas, 0, 0);
   

   sharedCanvas 的寬高只能在主域設(shè)置，不能在開放數(shù)據(jù)域中設(shè)置。本質(zhì)上其也是一個離屏 Canvas，而重設(shè) Canvas 的寬高會清空 Canvas 上的內(nèi)容。所以可以通過 postMessage 通知開放數(shù)據(jù)域去重繪 sharedCanvas 。 

   // game.jssharedCanvas.width = 400;
   sharedCanvas.height = 200;
   
   openDataContext.postMessage({
     command: "render"
   });
   

   // src/myOpenDataContext/index.js
   openDataContext.onMessage(data => {
     if (data.command === "render") {
       // ... 重繪 sharedCanvas
     }
   });

運(yùn)行時限制

主域

1. sharedCanvas 只能被繪制到上屏 canvas 上。
2. 上屏 canvas 不能調(diào)用 toDataURL，其 context 不能調(diào)用 getImageData、readPixels。
3. sharedCanvas 不能調(diào)用 toDataURL 和 getContext。
4. 不能將上屏 canvas 和 sharedCanvas 以任意形式繪制到其他 canvas 上，包括 drawImage、createPattern、texImage2D、texSubImage2D。
5. sharedCanvas 的寬高只能在主域設(shè)置

開放數(shù)據(jù)域

1. 不能設(shè)置 sharedCanvas 的寬高
2. 開放數(shù)據(jù)域的 Image 只能使用本地或者是通過 tt.xx 系列 API 拿到的平臺本身的用戶頭像圖片，不能使用開發(fā)者自己服務(wù)器上的圖片。對于非本地或非用戶頭像圖片，可以先從主域 tt.downloadFile() 下載圖片文件，再通過 OpenDataContext.postMessage() 把文件路徑傳給開放數(shù)據(jù)域去使用。

開放數(shù)據(jù)域只能調(diào)用有限的 API，如下所示:

• 所有定時器相關(guān) API
• 所有觸摸事件 API
• tt.createCanvas()
• tt.createImage()
• tt.getUserCloudStorage()
• tt.setUserCloudStorage()
• tt.removeUserCloudStorage()
• tt.onMessage()

開放能力

平臺允許開發(fā)者可以利用一些產(chǎn)品宿主提供的如登錄，分享，以及不久的未來支持的支付，廣告等一系列開放能力，用以完善自己的產(chǎn)品邏輯和體驗(yàn)。具體可以參考開放能力一欄。

快速調(diào)試

其他說明

代碼包限制

通常情況下，每個小游戲允許上傳的代碼包總大小為 4MB，請開發(fā)者注意自己的游戲包大小。

文件類型

小游戲限制了可以上傳的文件類型。只有在以下列表中的文件可以上傳成功：

• png
• jpg
• jpeg
• gif
• svg
• json
• js
• cer
• obj
• dae
• fbx
• mtl
• stl
• 3ds
• mp3
• pvr
• wav
• plist
• ttf
• fnt
• gz
• ccz
• m4a
• mp4
• bmp
• atlas
• swf
• ani
• part
• proto
• bin
• sk
• mipmaps
• txt
• zip
• tt
• map
• ogg
• silk
• dbbin
• dbmv
• etc
• lmat
• lm
• ls
• lh
• lani
• lav
• lsani
• ltc