[4.0.0] BatchHandlerQuad produces black pixels after any third-party WebGL renderer (e.g. Spine) runs — RebindContext does not fully isolate state

Đang mở
#7,285 3 bình luận 1 reaction 1 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 3 ngày

@BenjaminDRichards đang làm issue này rồi.

Từ ngày 20/4/2026.

Đánh giá

Issue này chưa được đánh giá.

Mô tả

[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_object extension
  • 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 Extern game 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):

  1. BatchHandlerQuad should 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)
  2. RebindContext.run() should invalidate per-RenderNode caches, not just glWrapper.state
  3. Extern.renderWebGL should bracket its yield with gl.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.

Ngôn ngữ chính
JavaScript
Star
40.7k
Fork
7.2k
Chỉ số merge pull request
Không có pull request nào được merge trong 30 ngày

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của phaserjs/phaser

Tất cả issue của phaserjs/phaser

Issue tương tự

Thêm issue về JavaScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.