微信小游戲開(kāi)發(fā)配置API接口

微信小游戲開(kāi)發(fā)者通過(guò)在根目錄編寫一個(gè)game.json文件進(jìn)行配置，開(kāi)發(fā)者工具和客戶端需要讀取這個(gè)配置，完成相關(guān)界面渲染和屬性設(shè)置，只能使用JavaScript來(lái)編寫微信小游戲，微信小程序游戲的運(yùn)行環(huán)境是一個(gè)綁定了一些方法的JavaScript VM。

小游戲開(kāi)發(fā)者：微信小游戲開(kāi)發(fā)配置API接口

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

小游戲只有以下兩個(gè)必要文件：

├── game.js
└── game.json

1. game.js 小游戲入口文件
2. game.json 配置文件

配置

小游戲開(kāi)發(fā)者通過(guò)在根目錄編寫一個(gè) game.json 文件進(jìn)行配置，開(kāi)發(fā)者工具和客戶端需要讀取這個(gè)配置，完成相關(guān)界面渲染和屬性設(shè)置。

deviceOrientation	String	支持的屏幕方向	portrait
showStatusBar	Boolean	是否顯示狀態(tài)欄	false
networkTimeout	Number	網(wǎng)絡(luò)請(qǐng)求的超時(shí)時(shí)間，單位：毫秒	60000
networkTimeout.request	Number	wx.request 的超時(shí)時(shí)間，單位：毫秒	60000
networkTimeout.connectSocket	Number	wx.connectSocket 的超時(shí)時(shí)間，單位：毫秒	60000
networkTimeout.uploadFile	Number	wx.uploadFile 的超時(shí)時(shí)間，單位：毫秒	60000
networkTimeout.downloadFile	Number	wx.downloadFile 的超時(shí)時(shí)間，單位：毫秒	60000
workers	String	多線程 Worker 配置項(xiàng)，詳細(xì)請(qǐng)參考 Worker文檔	無(wú)
key	數(shù)據(jù)類型	說(shuō)明	默認(rèn)值

deviceOrientation

portrait	豎屏
landscape	橫屏
值	說(shuō)明

示例配置

{ "deviceOrientation": "portrait", "networkTimeout": { "request": 5000, "connectSocket": 5000, "uploadFile": 5000, "downloadFile": 5000 }
}

wx API

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

創(chuàng)建 Canvas

調(diào)用 wx.createCanvas() 接口，可以創(chuàng)建一個(gè) Canvas 對(duì)象。

var canvas = wx.createCanvas()

此時(shí)創(chuàng)建的 canvas 是一個(gè)上屏 Canvas，已經(jīng)顯示在了屏幕上，且與屏幕等寬等高。

console.log(canvas.width, canvas.height)

在整個(gè)小游戲代碼中首次調(diào)用 wx.createCanvas() 創(chuàng)建的是上屏 Canvas，之后調(diào)用則創(chuàng)建的是離屏 Canvas。如果你的項(xiàng)目中使用了官方提供的 Adapter 即 weapp-adapter.js（關(guān)于什么是 Adpater 請(qǐng)參考官方教程 Adapter），那么你此時(shí)創(chuàng)建的會(huì)是一個(gè)離屏 Canvas。因?yàn)樵?weapp-adapter.js 已經(jīng)調(diào)用了一次 wx.createCanvas()，并把返回的 canvas 作為全局變量暴露出來(lái)。假設(shè)你的項(xiàng)目目錄結(jié)構(gòu)如下：

├── game.js
├── weapp-adapter.js
└── game.json

在 weapp-adapter.js 中已經(jīng)調(diào)用了一次 wx.createCanvas()，并把返回的 canvas 作為全局變量暴露出來(lái)。

// weapp-adapter canvas = wx.createCanvas()

如果你在 require weapp-adapter.js 之后再調(diào)用 wx.createCanvas()，那么創(chuàng)建的 Canvas 會(huì)是一個(gè)離屏的 Canvas，因?yàn)榇藭r(shí)已經(jīng)不是對(duì)該 API 的首次調(diào)用。

require('./weapp-adapter') var myCanvas = wx.createCanvas()

在 Canvas 上進(jìn)行繪制

但是由于沒(méi)有在 canvas 上進(jìn)行繪制，所以 canvas 是透明的。使用 2d 渲染上下文的進(jìn)行簡(jiǎn)單的繪制，可以在屏幕左上角看到一個(gè) 100x100 的紅色矩形。

var context = canvas.getContext('2d')
context.fillStyle = 'red' context.fillRect(0, 0, 100, 100)

通過(guò) Canvas.getContext() 方法可以獲取 2d 或 WebGL 渲染上下文 RenderingContext，調(diào)用渲染上下文的繪制方法可以在 Canvas 上進(jìn)行繪制。小游戲基本上支持 2d 和 WebGL 1.0 所有的屬性和方法，詳情請(qǐng)見(jiàn) RenderingContext。由于使用 WebGL 的繪制過(guò)程較為復(fù)雜，所以本文中的示例代碼都以 2d 渲染上下文的繪制方法編寫。

通過(guò)設(shè)置 width 和 height 屬性可以改變 Canvas 對(duì)象的寬高，但這也會(huì)導(dǎo)致 Canvas 內(nèi)容的清空和渲染上下文的重置。

canvas.width = 300 canvas.height = 300 

顯示圖片

通過(guò) wx.createImage() 接口，可以創(chuàng)建一個(gè) Image 對(duì)象。Image 對(duì)象可以加載圖片。當(dāng) Image 對(duì)象被繪制到 Canvas 上時(shí)，圖片才會(huì)顯示在屏幕上。

var image = wx.createImage()

設(shè)置 Image 對(duì)象的 src 屬性可以加載一張本地圖片或網(wǎng)絡(luò)圖片，當(dāng)圖片加載完畢時(shí)會(huì)執(zhí)行注冊(cè)的 onload 回調(diào)函數(shù)，此時(shí)可以將 Image 對(duì)象繪制到 Canvas 上。

image.onload = function () { console.log(image.width, image.height)
    context.drawImage(image, 0, 0)
}
image.src = 'logo.png' 

創(chuàng)建多個(gè) Canvas

在整個(gè)小游戲運(yùn)行期間，首次調(diào)用 wx.createCanvas 接口創(chuàng)建的是一個(gè)上屏 Canvas。在這個(gè) canvas 上繪制的內(nèi)容都將顯示在屏幕上。而第二次、第三次等后幾次調(diào)用 wx.createCanvas 創(chuàng)建的都會(huì)是離屏 Canvas。在離屏 Canvas 上繪制的內(nèi)容僅僅只是繪制到了這個(gè)離屏 Canvas 上，并不會(huì)顯示在屏幕上。

以如下代碼為例，運(yùn)行后會(huì)發(fā)現(xiàn)屏幕上并沒(méi)有在 (0, 0) 的位置顯示 100x100 的紅色矩形。因?yàn)槲覀兪窃谝粋€(gè)離屏的 Canvas 繪制的。

var screenCanvas = wx.createCanvas() var offScreenCanvas = wx.createCanvas() var offContext = offScreenCanvas.getContext('2d')
offContext.fillStyle = 'red' offContext.fillRect(0, 0, 100, 100)

為了讓這個(gè)紅色矩形顯示在屏幕上，我們需要把離屏的 offScreenCanvas 繪制到上屏的 screenCanvas 上。

var screenContext = screenCanvas.getContext('2d')
screenContext.drawImage(offScreenCanvas, 0, 0)

動(dòng)畫

在 JavaScript 中，一般通過(guò) setInterval/setTimeout/requestAnimationFrame 來(lái)實(shí)現(xiàn)動(dòng)畫效果。小游戲?qū)@些 API 提供了支持：

• setInterval()
• setTimeout()
• requestAnimationFrame()
• clearInterval()
• clearTimeout()
• cancelAnimationFrame()

另外，還可以通過(guò) wx.setPreferredFramesPerSecond() 修改執(zhí)行 requestAnimationFrame 回調(diào)函數(shù)的頻率，以降低性能消耗。

觸摸事件

響應(yīng)用戶與屏幕的交互是游戲中必不可少的部分，小游戲參照 DOM 中的 TouchEvent 提供了以下監(jiān)聽(tīng)觸摸事件的 API：

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

wx.onTouchStart(function (e) { console.log(e.touches)
})

wx.onTouchMove(function (e) { console.log(e.touches)
})

wx.onTouchEnd(function (e) { console.log(e.touches)
})

wx.onTouchCancel(function (e) { console.log(e.touches)
})

全局對(duì)象

window 對(duì)象是瀏覽器環(huán)境下的全局對(duì)象。小游戲的運(yùn)行環(huán)境中沒(méi)有 BOM API，因此沒(méi)有 window 對(duì)象。但是提供了全局對(duì)象 GameGlobal，所有全局定義的變量都是 GameGlobal 的屬性。

console.log(GameGlobal.setTimeout === setTimeout) console.log(GameGlobal.requestAnimationFrame === requestAnimationFrame) // true 

開(kāi)發(fā)者可以根據(jù)需要把自己封裝的類和函數(shù)掛載到 GameGlobal 上。

GameGlobal.render = function () { //省略方法的具體實(shí)現(xiàn)... }

render()

GameGlobal 是一個(gè)全局對(duì)象，本身也是一個(gè)存在循環(huán)引用的對(duì)象。

console.log(GameGlobal === GameGlobal.GameGlobal)

console.log 無(wú)法在真機(jī)上將存在循環(huán)引用的對(duì)象輸出到 vConsole 中。因此真機(jī)調(diào)試時(shí)請(qǐng)注釋 console.log(GameGlobal) 這樣的代碼，否則將會(huì)產(chǎn)生這樣的錯(cuò)誤

An object width circular reference can't be logged

小游戲更新

小游戲啟動(dòng)會(huì)有兩種情況，一種是「冷啟動(dòng)」，一種是「熱啟動(dòng)」。 假如用戶已經(jīng)打開(kāi)過(guò)某小游戲，然后在一定時(shí)間內(nèi)再次打開(kāi)該小游戲，此時(shí)無(wú)需重新啟動(dòng)，只需將后臺(tái)態(tài)的小游戲切換到前臺(tái)，這個(gè)過(guò)程就是熱啟動(dòng)；冷啟動(dòng)指的是用戶首次打開(kāi)或小游戲被微信主動(dòng)銷毀后再次打開(kāi)的情況，此時(shí)小游戲需要重新加載啟動(dòng)。

更新機(jī)制

小游戲冷啟動(dòng)時(shí)如果發(fā)現(xiàn)有新版本，將會(huì)異步下載新版本的代碼包，并同時(shí)用客戶端本地已有的包進(jìn)行啟動(dòng)，即新版本的小游戲需要等下一次冷啟動(dòng)才會(huì)應(yīng)用上。 如果需要馬上應(yīng)用最新版本，可以使用 wx.getUpdateManager() API 進(jìn)行處理。

getUpdateManager 的使用示例

v1.9.90 基礎(chǔ)庫(kù)以后，可以通過(guò) wx.getUpdateManager() 獲取全局唯一的版本更新管理器，用于管理小游戲更新；另外請(qǐng)下載最新版本的開(kāi)發(fā)者工具(1.02.1803130 以上)才支持在開(kāi)發(fā)者工具上調(diào)試。

由于是新版本才支持的 API，請(qǐng)?jiān)谑褂们跋扰袛嗍欠裰С郑纾?/p>

if (wx.getUpdateManager) { console.log('支持 wx.getUpdateManager')
}

獲取到 updateManager 實(shí)例后，updateManager 包含以下方法：

onCheckForUpdate	callback	當(dāng)向微信后臺(tái)請(qǐng)求完新版本信息，會(huì)進(jìn)行回調(diào)
onUpdateReady	callback	當(dāng)新版本下載完成，會(huì)進(jìn)行回調(diào)
onUpdateFailed	callback	當(dāng)新版本下載失敗，會(huì)進(jìn)行回調(diào)
applyUpdate		當(dāng)新版本下載完成，調(diào)用該方法會(huì)強(qiáng)制當(dāng)前小游戲應(yīng)用上新版本并重啟
方法	參數(shù)	說(shuō)明

onCheckForUpdate(callback) 回調(diào)結(jié)果說(shuō)明：

hasUpdate	Boolean	是否有新的版本
屬性	類型	說(shuō)明

注： 檢查更新操作由微信在小游戲冷啟動(dòng)時(shí)自動(dòng)觸發(fā)，不需由開(kāi)發(fā)者主動(dòng)觸發(fā)，開(kāi)發(fā)者只需監(jiān)聽(tīng)檢查結(jié)果即可。

onUpdateReady(callback) 回調(diào)結(jié)果說(shuō)明：

當(dāng)微信檢查到小游戲有新版本，會(huì)主動(dòng)觸發(fā)下載操作（無(wú)需開(kāi)發(fā)者觸發(fā)），當(dāng)下載完成后，會(huì)通過(guò) onUpdateReady 告知開(kāi)發(fā)者。

onUpdateFailed(callback) 回調(diào)結(jié)果說(shuō)明：

當(dāng)微信檢查到小游戲有新版本，會(huì)主動(dòng)觸發(fā)下載操作（無(wú)需開(kāi)發(fā)者觸發(fā)），如果下載失?。赡苁蔷W(wǎng)絡(luò)原因等），會(huì)通過(guò) onUpdateFailed 告知開(kāi)發(fā)者。

applyUpdate() 說(shuō)明：

當(dāng)小游戲新版本已經(jīng)下載時(shí)（即收到 onUpdateReady 回調(diào)），可以通過(guò)這個(gè)方法強(qiáng)制重啟小游戲并應(yīng)用上最新版本。

完整使用示例

if (typeof wx.getUpdateManager === 'function') { const updateManager = wx.getUpdateManager()

  updateManager.onCheckForUpdate(function (res) { // 請(qǐng)求完新版本信息的回調(diào) console.log(res.hasUpdate)
  })

  updateManager.onUpdateReady(function () { // 新的版本已經(jīng)下載好，調(diào)用 applyUpdate 應(yīng)用新版本并重啟 updateManager.applyUpdate()
  })

  updateManager.onUpdateFailed(function () { // 新的版本下載失敗 })
}