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

Ouverte
#7,285 3 commentaires 1 réaction 1 personne assignée Voir sur GitHub

Les mainteneurs répondent en général sous 3 jours

@BenjaminDRichards y travaille déjà.

Depuis le 20/4/2026.

Évaluation

Cette issue n'a pas encore été évaluée.

Description

[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.

Langage dominant
JavaScript
Étoiles
40.7k
Forks
7.2k
Métriques de merge des PR
Aucune PR mergée en 30 j

Préparer son environnement

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de phaserjs/phaser

Toutes les issues de phaserjs/phaser

Issues similaires

Plus d'issues JavaScript

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.