How to Build a WeChat Mini Game: Architecture, APIs, and Best Practices

What Is a Mini Game?

Mini Games are a sub‑category of WeChat Mini Programs that can be launched instantly within WeChat, offering a seamless, app‑like experience. From a developer’s perspective, they run on a Canvas/WebGL layer combined with WeChat’s social open capabilities.

Mini Game Runtime Architecture

The runtime follows a layered architecture. The top blue layer contains the game code (logic, engine, and weapp‑adapter). Below it, the red layer implements the wx API, a JavaScript VM (V8Core on Android, JavaScriptCore on iOS), and the core rendering engines (Canvas 2D and WebGL). The runtime does not expose a page model (no wxss/wxml) and lacks a DOM/BOM, so developers must adapt code via the weapp‑adapter.

Webview Adapter

The Webview Adapter maps standard web APIs to their WeChat Mini Game equivalents, e.g., new Image() becomes wx.createImage(). It also adapts Canvas and document objects, allowing existing web‑oriented code to run with minimal changes. The adapter will no longer be maintained, so developers should rely on the underlying wx API directly.

Mini Game Capability Overview

WeChat Mini Games support Canvas 2D, WebGL 1.0, controllable frame rates, UI components (keyboard, modal dialogs), and a growing set of social APIs (friend lists, group rankings, anti‑addiction). Media streaming is limited, and some newer APIs are still being rolled out.

How to Develop a Mini Game

Choosing a Mini Game Engine

Popular engines such as Cocos Creator, Egret, and LayAir already provide WeChat export plugins. The adaptation work mainly consists of mapping wx API calls to the engine’s abstraction layer via the weapp‑adapter.

Device/Environment Adaptation

Mini Games run on iOS and Android devices with varying screen sizes and pixel ratios. Developers should query wx.getSystemInfo() for width, height, and devicePixelRatio, and test on the official device‑lab to ensure compatibility with older base library versions.

WeChat Login

Login follows the same flow as Mini Programs: the developer obtains appsecret and session_key on the server, validates access_token, and never embeds secret keys in client code.

Cache

Two cache types are available: data cache (key‑value, up to 10 MB) and file cache (full file‑system API, up to 50 MB). Developers must implement their own eviction strategy.

Open Data Domain

The open data domain runs in an isolated JavaScript context. It can receive data from the main domain via postMessage but cannot upload data to third‑party servers. It is used for friend and group leaderboards rendered on a shared canvas.

Sharing

Mini Games can trigger custom or system sharing to WeChat contacts or groups. Developers should balance social virality with user‑experience to avoid spamming.

Payment

Payments are handled via a virtual‑currency model: users purchase game coins (RMB → coins) and then spend coins on in‑game items. The flow includes a recharge API and a consumption API with idempotent order handling.

Performance

Memory usage is the primary performance bottleneck. Developers should release unused objects, call wx.triggerGC(), and consider off‑loading non‑critical logic to worker threads.

Version Update Mechanism

Mini Games support cold and hot starts. On cold start the platform checks for a newer version; if found, it downloads the package for the next launch. Developers can enforce mandatory updates via the provided API.

Operations

The management console (mp.weixin.qq.com) offers release, rollback, and stop‑service capabilities. Built‑in monitoring captures script errors and performance metrics; developers should enable the “Operations Center” and the “Mini Game Data Assistant” for analytics.

Q&A

Q: Is the initial package size limit 4 MB?

A: Yes, the 4 MB limit balances download time and user experience.

Q: How large can sub‑packages be?

A: Sub‑packages have no hard size limit, but developers should consider device storage and network constraints.

Q: What is the role of session_key?

A: It secures login state between the Mini Game server and WeChat, and is required for group sharing and payment APIs.