Build and Test a WeChat/Weixin Mini Game

WeChat is also called Weixin in China. This guide uses “WeChat.”

Supported output

Needle creates a regular Mini Game project in dist/WeChat. The output includes the Needle WeChat platform adapter.

Mini Game Playable

The production Mini Game Playable is a different product. It has a separate AppID, API set, upload, and release process.

Requirements

A Mini Game test number or AppID
The current WeChat Developer Tools
Access to the AppID

Get a test number from the WeChat/Weixin sandbox.

1. Add the platform

import { defineConfig } from "vite";
import { loadConfig, needlePlugins } from "@needle-tools/engine/vite";

export default defineConfig(async ({ command }) => {
    const needleConfig = await loadConfig();
    return {
        plugins: [needlePlugins(command, needleConfig, {
            playableAds: {
                name: "MyGame",
                platforms: [{
                    platform: "wechat",
                    appId: "wx0000000000000000",
                    orientation: "portrait",
                }],
            },
        })],
    };
});

2. Build the project

npm run build -- --production

dist/WeChat contains these files:

game.js
game.json
project.config.json
Needle runtime files
Local game resources

AppSecret

Do not add the AppSecret to the project. Store the AppSecret on a trusted server.

3. Import the project

Open WeChat Developer Tools.
Select Mini Game.
Import dist/WeChat.
Enter the Mini Game AppID.
Select Compile.

Import the folder that contains game.json. Do not select its parent folder.

4. Test in the simulator

Check the scene, environment, textures, and UI.
Start and finish the game.
Test mouse input.
Test touch input.
Check that one touch creates one pointer.
Test audio after the first interaction.
Test particles and orientation.
Hide and restore the game.
Fix all red console errors.

5. Test on a device

Select Preview in Developer Tools.
Scan the QR code with WeChat/Weixin.
Test on iOS.
Test on Android.
Record the Developer Tools version.
Record the base-library version.
Record the build hash, device, OS, and console output.

Test with an agent

Use an Electron agent or the WeChat IDE driver. Compile the project and record the console output.

Interact with the canvas. Capture a rendered frame. A successful compile message does not prove that the game renders.

Do not change the AppID or domain checks without permission. Do not upload a build without permission.

Run the Needle browser integration test before the Developer Tools test. The browser test covers files, rendering, input, lifecycle, audio, and startup.

Use a custom platform entry

Most projects do not need a custom entry. For a custom host action, install the adapter before the Engine import.

import { installWechatPlatform } from "@needle-tools/engine/playable/wechat";

export const wechatPlatform = installWechatPlatform({
    title: "My Game",
    open: () => {
        // Call an approved host action.
        return true;
    },
});

Use @needle-tools/engine/playable/wechat-context for custom Needle context creation.

See the WeChat target reference for all options.

Error	Action
`game.json` is missing	Import `dist/WeChat`. Re-import the folder after a rebuild.
Device rejects JavaScript	Update Needle. Build the WeChat output again.
Browser global is missing	Update Needle. Remove each app-local platform shim.
Texture does not load	Check the file below `dist/WeChat`. Use a package-relative path.
Scene is black	Find the first renderer or file-load error. Check rendered pixels.
One touch acts twice	Remove the app-local touch bridge. Use the Needle adapter.

See the Mini Game API types and the Tencent Mini Game tutorial.