Skip to content

godothub/godot-minigame / skills

godot-wechat-minigame-adapter

Unverified

Apply the bundled self-contained Godot WeChat Mini Game adapter kit to an official Godot checkout. Use when the user wants to port official Godot to WeChat Mini Game, refresh a nearby 4.6-based port, or inspect the shipped patch/source bundle for WXMEMFS, `wx.request`, audio cleanup, display/input, WXGLX dual-path rendering, `.wasm.br`, and `wx.exitMiniProgram`. This skill is version-locked to the bundled upstream base and must not be described as a generic “Godot 4.x” patch dump.

FileKindSize
SKILL.mdskill md6.0 KB
agents/openai.yamlconfig269 B
assets/min-runtime/godot-loader.jsscript16.6 KB
assets/min-runtime/godot-sdk.jsscript7.8 KB
patches/fixes/4.7-webgl-context/001-context-swap-control.patchother4.2 KB
patches/fixes/4.7-webgl-context/README.mdmarkdown1.5 KB
patches/godot-4.6.2-rc-a16e481cf4/core/001-build-and-runtime-glue.patchother12.4 KB
patches/godot-4.6.2-rc-a16e481cf4/core/002-native-audio-routing.patchother6.3 KB
patches/godot-4.6.2-rc-a16e481cf4/core/003-wxglx-nine-patch-expansion.patchother5.7 KB
patches/godot-4.6.2-rc-a16e481cf4/core/004-wxglx-nine-patch-runtime-scope.patchother7.2 KB
patches/godot-4.6.2-rc-a16e481cf4/core/series.txtmarkdown142 B
patches/godot-4.6.2-rc-a16e481cf4/manifest.jsonconfig993 B
patches/godot-4.6.2-rc-a16e481cf4/optional/001-audio-worker.patchother820 B
patches/godot-4.6.2-rc-a16e481cf4/optional/series.txtmarkdown23 B
references/compatibility-matrix.mdmarkdown1.2 KB
references/migration-modules.mdmarkdown5.8 KB
references/recent-commit-deltas.mdmarkdown2.2 KB
references/runtime-shell.mdmarkdown3.8 KB
references/validation-checklist.mdmarkdown3.4 KB
references/wxglx-adaptation.mdmarkdown8.8 KB
scripts/apply_godot_patchset.pyscript5.6 KB
scripts/compress_wasm.batscript100 B
scripts/compress_wasm.shscript91 B
scripts/godot_process.jsscript5.3 KB
scripts/install_min_runtime.pyscript1.1 KB
scripts/validate_template_runtime.jsscript2.8 KB
sources/godot-4.6.2-rc-a16e481cf4/compress_wasm.batscript237 B
sources/godot-4.6.2-rc-a16e481cf4/compress_wasm.shscript215 B
sources/godot-4.6.2-rc-a16e481cf4/godot_process.jsscript5.3 KB
sources/godot-4.6.2-rc-a16e481cf4/optional/platform/web/js/libs/audio.worker.jsscript6.6 KB
sources/godot-4.6.2-rc-a16e481cf4/optional/platform/web/js/libs/lib.wx.api.d.tsscript516.7 KB
sources/godot-4.6.2-rc-a16e481cf4/platform/web/js/libs/library_blob.jsscript27.1 KB
sources/godot-4.6.2-rc-a16e481cf4/platform/web/js/libs/library_godot_audio.jsscript88.8 KB
sources/godot-4.6.2-rc-a16e481cf4/platform/web/js/libs/library_godot_crypto.jsscript116 B
sources/godot-4.6.2-rc-a16e481cf4/platform/web/js/libs/library_godot_display.jsscript26.4 KB
sources/godot-4.6.2-rc-a16e481cf4/platform/web/js/libs/library_godot_fetch.jsscript8.9 KB
sources/godot-4.6.2-rc-a16e481cf4/platform/web/js/libs/library_godot_fs.jsscript29.4 KB
sources/godot-4.6.2-rc-a16e481cf4/platform/web/js/libs/library_godot_input.jsscript23.2 KB
tests/test_godot_process_commit_frame.jsscript2.6 KB
tests/test_min_runtime_loader.jsscript3.8 KB
tests/test_template_glx_config.jsscript1.3 KB
tests/test_wechat_audio_context_source_reuse.jsscript3.9 KB
tests/test_wxglx_nine_patch_patch.jsscript2.2 KB

references/wxglx-adaptation.md

View on GitHub
# WXGLX Adaptation

Use this reference when forward-porting the current WeChat EmscriptenGLX implementation into a Godot Web source tree or validating a GLX-capable template.

## Scope And Status

The version-locked public bundle does not become GLX-capable merely because the runtime shell contains `wxwebgl2` selection logic. A GLX-capable engine also needs the matching vendor static library, build flags, context patch, native exports, runtime-mode bridge, and frame-presentation changes described below.

The current design produces one GLX-capable binary that chooses exactly one mode at startup:

- WXGLX: `wxwebgl2`, native GLX command submission, no Emscripten frame commit.
- Standard fallback in a GLX-capable build: `webgl2`, implicit swap control, frame-commit wrapper calling WeChat `flush()` / `commit()`.

This is a startup decision, not a live toggle.

## Non-Negotiable Invariants

1. The loading canvas and Godot engine must use the same context mode.
2. The loader must set `GameGlobal.__godotMinigameWXGLXEnabled` before Godot creates its context.
3. `GameGlobal.__GODOT_DISABLE_WXGLX === true` must force standard WebGL before any context exists.
4. A pinned WXGLX mode must fail loudly if `wxwebgl2` creation or native GLX bindings are missing. Do not silently create `webgl2` after pinning WXGLX.
5. Frame presentation must follow the selected runtime mode, not the compile-time `WECHAT_GLX_EXPERIMENTAL` define.
6. Post-processing must preserve Emscripten's `_emscripten_webgl_commit_frame`; replacing it with an empty function causes black screens on standard-WebGL fallback devices.

## Engine Integration Map

### Build capability

Update `platform/web/detect.py` to provide `use_wx_glx` and `wx_glx_lib`.

When enabled:

- require an exact `libemscriptenglx_<emscripten-version>.a` match
- define `WECHAT_GLX_EXPERIMENTAL`
- keep C++ exceptions enabled
- use `SUPPORT_LONGJMP=emscripten`
- disable `OFFSCREEN_FRAMEBUFFER`
- export the runtime/native functions required by the GLX patch
- use `threads=no`

The verified production combination is Emscripten `4.0.10`, `threads=no`, and `wasm_simd=no`. Do not guess compatibility between an Emscripten version and a differently versioned static library.

Add `platform/web/js/patches/patch_em_gl.js` through `platform/web/SCsub`. The patch must:

- intercept `canvas.getContext()` while `GL.createContext()` runs
- request `wxwebgl` / `wxwebgl2` only when the pinned mode is WXGLX
- call `glxInit` immediately after context creation
- call `glxInitBufferDataAndGlState` once
- call `glxUpdateContextId` whenever the current context changes
- verify that the actual context type matches the pinned mode

### Runtime mode bridge

Add a synchronous JS bridge in `platform/web/js/libs/library_godot_display.js` that returns whether `GameGlobal.__godotMinigameWXGLXEnabled === true`. Declare it in `platform/web/godot_js.h`.

Store that value on `DisplayServerWeb`. Context attributes depend on build capability, while frame presentation depends on runtime mode:

```cpp
wx_glx_enabled = godot_js_display_is_wx_glx_enabled() == 1;
// GLX-capable build: OFFSCREEN_FRAMEBUFFER is disabled in both runtime modes.
attributes.explicitSwapControl = false;
```

Keep `explicitSwapControl = true` only for standard-only builds that enable `OFFSCREEN_FRAMEBUFFER`. Requesting explicit swaps in a GLX-capable build makes Emscripten reject context creation before calling `canvas.getContext()`. On the implicit standard path, Emscripten's commit function returns `INVALID_TARGET`; the wrapper must still execute the WeChat `flush()` / `commit()` calls.

Call `emscripten_webgl_commit_frame()` only when `wx_glx_enabled` is false, including normal swaps and context destruction. A compile-time-only branch is incorrect because the same GLX-capable binary can start in standard WebGL mode.

For an already adapted 4.7 checkout with the previous runtime-dependent swap setting, apply [the scoped correction](../patches/fixes/4.7-webgl-context/README.md). This is not a patchset for unmodified upstream Godot.

Guard `GL.resizeOffscreenFramebuffer()` when `OFFSCREEN_FRAMEBUFFER` is absent. Keep the existing GLX compatibility handling for GLES timestamp queries and unsupported runtime GDExtension loading if those paths exist in the target branch.

### Canvas nine-patch compatibility

Some WXGLX replay drivers drop the GLES3 `USE_NINEPATCH` shader variant, which makes `NinePatchRect` content disappear while ordinary texture rectangles still render. In `RendererCanvasCull::canvas_item_add_nine_patch()`, expand valid nine-patch draws into regular `canvas_item_add_texture_rect_region()` commands before they reach the renderer, but only while the pinned runtime mode is WXGLX.

Keep the expansion behind `WECHAT_GLX_EXPERIMENTAL`, query the existing runtime-mode bridge once, and preserve stretch, tile, tile-fit, `draw_center`, source regions, and mirrored destination rectangles. Bound tiled expansion to 64 pieces per axis and use a single stretched middle segment above that limit. Invalid inputs and the standard-WebGL runtime path must continue through Godot's original `CommandNinePatch` implementation.

## Runtime Shell And Startup Configuration

Load configuration before `godot-loader.js`:

```js
const gameGlobal = typeof GameGlobal !== "undefined" ? GameGlobal : globalThis;

if (gameGlobal.__GODOT_DISABLE_WXGLX === undefined) {
    gameGlobal.__GODOT_DISABLE_WXGLX = false;
}
```

The import order must be:

```js
import "./weapp-adapter";
import "./glx-config";
import "./godot-loader";
```

The loader selects WXGLX only when all startup policy checks allow it:

```js
const useWXGLX =
    gameGlobal.__GODOT_DISABLE_WXGLX !== true &&
    typeof wx !== "undefined" &&
    wx.env &&
    wx.env.isSupportEmscriptenGLX;

gameGlobal.__godotMinigameWXGLXEnabled = !!useWXGLX;
```

Pair a GLX-selecting loader only with a GLX-capable engine. For a standard-only template, force `__GODOT_DISABLE_WXGLX = true` or use a loader that never requests `wxwebgl2`.

## Generated Glue And Frame Commit

Run `compress_wasm.bat` or `compress_wasm.sh` after every build. The post-processor must wrap an existing Emscripten implementation, not invent or replace it:

```js
var __godotMinigameOriginalCommitFrame = _emscripten_webgl_commit_frame;
_emscripten_webgl_commit_frame = function () {
    var result = __godotMinigameOriginalCommitFrame();
    var context = typeof GL !== "undefined" && GL.currentContext && GL.currentContext.GLctx;
    if (context && typeof context.flush === "function") context.flush();
    if (context && typeof context.commit === "function") context.commit();
    return result;
};
```

Never emit:

```js
var _emscripten_webgl_commit_frame = function () {};
```

## Build And Package

From the adapted Godot source root:

```powershell
& C:\global\emsdk\python\3.13.3_64bit\Scripts\scons.exe `
  platform=web target=template_release threads=no `
  wasm_simd=no use_wx_glx=yes

cmd /c compress_wasm.bat
```

If auto-detection cannot find the exact vendor library, pass `wx_glx_lib=<absolute-path>` explicitly. Package the processed `bin/.web_zip/godot.js` and `godot.wasm.br`, not the raw linker outputs.

## Required Validation

Run source-level tests in the adapted Godot checkout:

```powershell
node platform/web/js/tests/test_wechat_glx_runtime.js
node platform/web/js/tests/test_godot_process_commit_frame.js
node platform/web/js/tests/test_wechat_webgl_context_attributes.js
```

Run runtime-shell and package tests from this skill:

```powershell
node skills/tests/test_min_runtime_loader.js
node skills/tests/test_godot_process_commit_frame.js
node skills/tests/test_template_glx_config.js <unpacked-template>
node skills/scripts/validate_template_runtime.js <unpacked-template> wxglx
```

Verify both startup paths:

- default supported device requests `wxwebgl2` and pins `true`
- unsupported device or explicit disable requests `webgl2` and pins `false`
- pinned WXGLX cannot silently return a standard context
- generated `godot.js` contains `__godotMinigameOriginalCommitFrame`
- generated `godot.js` does not contain the empty commit-frame function
- the GLX and standard paths both reach scene rendering on real devices

## Failure Diagnosis

- Black screen only on iOS or non-GLX devices: inspect the standard frame-commit wrapper first.
- Loader renders but engine fails to create a context: verify loader/engine mode pinning and import order.
- `The loader selected WXGLX, but the native bindings are missing`: the loader was paired with a non-GLX engine or the vendor library was not linked/exported.
- `Canvas context mode mismatch`: a context was created before policy was pinned, or loading and engine canvases selected different modes.
- `resizeOffscreenFramebuffer is not a function`: an offscreen-framebuffer call is still unguarded.
- GLX starts and then stalls: verify context initialization timing, command-buffer flush registration, timestamp-query guards, and exact Emscripten/library version matching.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall