[4.0.0] BatchHandlerQuad produces black pixels after any third-party WebGL renderer (e.g. Spine) runs — RebindContext does not fully isolate state
维护者通常 3 天内回复
@BenjaminDRichards 已经在做这个了。
开始于 2026年4月20日。
评估
这个 Issue 还没有评估数据。
描述
[4.0.0] BatchHandlerQuad produces black pixels after any third-party WebGL renderer (e.g. Spine) runs — RebindContext does not fully isolate state
Versions
- Phaser:
4.0.0(latest stable) - Build: ESM via Vite 7.3.2
- Browser: Chrome (any recent), Windows + ANGLE/Direct3D11
- WebGL context: WebGL 1 with
OES_vertex_array_objectextension - Third-party renderer triggering this:
@esotericsoftware/[email protected](the official Spine plugin)
Summary
After a third-party WebGL renderer (Spine in our case) runs through the documented YieldContext.run() → external render → RebindContext.run() flow (the same flow the Migration Guide recommends and that Phaser.GameObjects.Extern uses), all subsequent BatchHandlerQuad draws produce no visible pixels. Image, Sprite, and Image-inside-Container all fail. Rectangle (FillRect render node) works correctly. RebindContext.run() is supposed to restore the WebGL state to a known baseline, but the corruption survives it.
Expected behavior
Per the migration guide:
Use
Externgame objects for direct access (state resets after execution).
After Extern.renderWebGL (which internally calls YieldContext → external → RebindContext), BatchHandlerQuad should be able to render Image Game Objects normally on subsequent draws.
Actual behavior
BatchHandlerQuad runs without errors but produces no visible pixels for Image Game Objects until the next frame. By next frame the bug recurs as soon as another spine-like external renderer runs.
scene.add.rectangle(...) (which uses FillRect, a different render node) renders correctly through this same state.
Minimal repro
import * as Phaser from "phaser";
import { SpinePlugin } from "@esotericsoftware/spine-phaser-v4";
class DemoScene extends Phaser.Scene {
constructor() { super("DemoScene"); }
preload() {
this.load.image("test-tile", "/path/to/any-image.png");
this.load.spineJson("spineboy-data", "/path/to/spineboy-pro.json");
this.load.spineAtlas("spineboy-atlas", "/path/to/spineboy.atlas");
}
create() {
// Top-level Image — EXPECT visible at center, ACTUAL invisible
this.add.image(540, 800, "test-tile").setDepth(1000).setTint(0xff00ff);
// Rectangle (different render node) — works fine
this.add.rectangle(540, 1100, 200, 100, 0x00ff00).setDepth(1000);
// Spine — triggers the corruption
const spine = this.add.spine(960, 540, "spineboy-data", "spineboy-atlas");
spine.setScale(0.5);
spine.animationState.setAnimation(0, "idle", true);
}
}
new Phaser.Game({
type: Phaser.WEBGL,
parent: "app",
width: 1080,
height: 1920,
scene: [DemoScene],
plugins: { scene: [{ key: "spine.SpinePlugin", plugin: SpinePlugin, mapping: "spine" }] },
});
Workaround that pinpoints it as render-time corruption:
function hideAllSpines(obj) {
if (obj?.skeleton && obj?.animationState) obj.setVisible(false);
if (obj?.list) obj.list.forEach(hideAllSpines);
}
hideAllSpines(scene.sys.displayList);
After hiding all Spine objects, the magenta image immediately appears next frame. The render path for Image is fine; the state Spine leaves behind (or that RebindContext fails to restore) breaks the batch handler.
What we patched (none fixed it)
We spent ~12 hours instrumenting the running game and patching every GL state vector we could identify. Each patch successfully addressed its specific symptom; none made BatchHandlerQuad recover after a Spine render:
| Vector patched | Mechanism | Result |
|---|---|---|
gl.activeTexture left non-zero |
glWrapper.update({ bindings: { activeTexture: 0 } }, true, true) |
Cache + actual GL match. Image still black. |
Blend state desync after Spine's raw gl.enable(BLEND) |
glWrapper.update({ blend: renderer.blendModes[0] }, true, true) |
Cache + actual blend match. Image still black. |
Spine's Mesh.unbind calling gl.bindBuffer(EBO, null) while a Phaser VAO is active |
Patched Mesh.prototype.unbind to switch to default VAO around the call |
Phaser VAOs no longer corrupted. Image still black. |
Same for Mesh.bind |
Patched Mesh.prototype.bind to do the same |
Same outcome. |
WebGLVAOWrapper.createResource:128 cache-skip on indexBuffer.bind() when index buffer is shared across VAOs |
Patched WebGLBufferWrapper.bind to force-fire EBO binds |
All glVAOWrappers end frame with ebo=bound, all attribs enabled. Image still black. |
| Pre-existing pipeline VAOs born broken before patches install | One-shot repair pass on renderer.glVAOWrappers (rebind EBO + re-enable attribs + vertexAttribPointer) |
Diagnostic shows all 7+ VAOs healthy. Image still black. |
After all patches, this snapshot was clean every frame:
// Per-VAO snapshot during MainScene render:
VAO 0: ebo=bound, attrs=11000 // background batch
VAO 1: ebo=bound, attrs=11111
VAO 2: ebo=bound, attrs=11111
VAO 3: ebo=bound, attrs=11111
VAO 4: ebo=bound, attrs=11111 // image batch
VAO 5: ebo=bound, attrs=11111
VAO 6: ebo=bound, attrs=11111
// glWrapper.state after spine render:
PMA: true ✓ (matches actual gl.getParameter)
FLIP_Y: true ✓ (matches)
activeUnit: 0 ✓ (matches)
currentProgram: set ✓ (matches)
blendEnabled: true ✓ (matches actual)
blendFunc: [1, 771, 1, 771] ✓ (matches actual)
cached EBO matches actual ✓
Yet BatchHandlerQuad still produces no visible pixels for any Image after Spine renders. The state we can inspect is fully consistent — there's something BatchHandlerQuad reads that we don't know how to reset.
Bisect
| Configuration | Image renders? |
|---|---|
| Phaser 4.0.0 + spine-phaser-v4 4.2.110 + spines visible | ❌ |
| Phaser 4.0.0 + spine-phaser-v4 4.2.110 + spines hidden | ✅ |
| Phaser 4.0.0 + spine-phaser-v4 4.2.110 + spines visible + custom in-house Spine integration | ❌ (same bug) |
| Phaser 3.90.0 + spine-phaser 4.1.55 (same scene code) | ✅ |
The bug reproduces on BatchHandlerQuad regardless of which Spine integration we use — official upstream plugin or the custom integration we wrote — so the failure point is in Phaser 4's render system, not Spine's bridge.
Hypothesis
BatchHandlerQuad likely caches additional state in its RenderNode instance — possibly:
- A pipeline-internal VAO it created lazily that points to attribute pointers / uniforms that were valid at batch start but invalidated by Spine's raw GL calls
- A vertex-format setup or attribute-divisor on the batch's own VAO that became stale
- A texture unit / shader sampler binding that points to a Spine atlas page after Spine renders
RebindContext.run() resets glWrapper.state (vao, bindings, blend) and unbinds all texture units — but it doesn't appear to invalidate per-RenderNode cached state. If BatchHandlerQuad's internal pipeline VAO was modified by Spine's raw gl.enableVertexAttribArray / gl.bindBuffer(EBO, ...) calls while it happened to be the active GL VAO, no amount of glWrapper.state clearing would un-corrupt the VAO itself.
Possible fix directions (we'd love your team's input):
BatchHandlerQuadshould re-validate or re-bind its own VAO + attributes at the start of every batch (not rely on cached state being correct after a yield)RebindContext.run()should invalidate per-RenderNodecaches, not justglWrapper.stateExtern.renderWebGLshould bracket its yield withgl.bindVertexArray(null)so external GL calls land on the default VAO instead of whatever Phaser VAO was active
We tried (3) ourselves; it prevents some VAO corruption but doesn't fully fix the batch handler.
Cross-reference
We also filed this with Esoteric Software so they're aware: spine-runtimes#3063. Their plugin is following Phaser 4's documented integration pattern correctly — the issue is on Phaser's side, but Spine users are the ones hitting it.
Workaround
We rolled our project back to Phaser 3.90 + spine-phaser 4.1.55. Phaser 4 migration deferred until this is resolved.
Repro repository
(Optional — let us know if a minimal Vite-based reproducer would help. Happy to carve one out from our project.)
Time investment context
~12+ hours of incremental patching and diagnostics before concluding this isn't solvable at the application level. Filing this so other teams attempting Phaser 4 + Spine (the most common animation runtime in Phaser games) don't repeat that effort.
Happy to run additional diagnostics, test fixes, or build a minimal reproducer. Tag us in the response.
- 主要语言
- JavaScript
- 星标
- 40.7k
- 派生
- 7.2k
- PR 合并指标
- 30 天内没有已合并 PR
环境准备
- 没有 Dockerfile 或 Docker Compose 文件
- 有 Pull Request 模板
- 阅读贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
phaserjs/phaser 的其他 Issue
-
难度 1/5 1 小时以内 新手友好度 80/100
维护者通常 3 天内回复
-
难度 2/5 1-3 小时 新手友好度 80/100
维护者通常 3 天内回复
-
Type definition for TilemapLayer.getTileAt is wrong可能已有人在做 @hkbughk 于 34 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 70/100
维护者通常 3 天内回复
-
Shader.preDestroy leaks its ShaderQuad's vertex buffer and VAO on every create/destroy cycle (4.2.1)可能已有人在做 @k1epg01ng129-eng 于 32 天前认领。 未关闭
难度 2/5 1-3 小时 新手友好度 86/100
维护者通常 3 天内回复
-
Black opaque background on transparent Phaser.Text textures in Phaser 4.2.1 on older iOS WebGL可能已有人在做 @SamuelMalmfors 于 14 天前认领。 未关闭
难度 1/5 1 小时以内 新手友好度 85/100
phaserjs/phaser#7392 · 1 条评论 ·
维护者通常 3 天内回复
相似的 Issue
-
enhancement ready
难度 2/5 1-3 小时 新手友好度 84/100
-
enhancement
难度 2/5 1-3 小时 新手友好度 75/100
DCGM/semant-demo#708 ·
维护者通常 1 天内回复
-
难度 2/5 1-3 小时 新手友好度 78/100
-
agents area: runtime automation chore cli consistency dependencies developer-experience difficulty: easy documentation enhancement good first issue help wanted hygiene json-output priority: P3 starters tests
难度 2/5 1-3 小时 新手友好度 82/100
维护者通常 1 天内回复
-
Client codegen: an import repeated in an impl file is emitted twice, and the browser rejects the module可能已有人在做 @MalithaPrabhashana 今天认领。 未关闭
难度 2/5 1-3 小时 新手友好度 64/100
jaseci-labs/jac#10756 ·
维护者通常 1 天内回复