[4.0.0] Phaser.Class (incl. Class.mixin) is not exposed on the public ESM namespace — forces third-party plugins into inadequate mixin fallbacks
Maintainer antworten meist innerhalb von 3 Tagen
Dieses Issue hat noch niemand übernommen.
Bewertung
- Schwierigkeit
- 2/5
- Geschätzter Aufwand
- 1-3 Stunden
- Anfängerfreundlichkeit
- 62/100
- Issue-Typ
- Bug
- Klarheit
- Klar beschrieben
- Aktivitätsstatus
- Ruhig
- Tech-Stack
- javascript, vite
Rechercherichtung
Beginne mit src/index.js oder dem ESM-Aggregator der öffentlichen Oberfläche und untersuche utils/Class.js. Vergleiche anschließend die Exporte aus dem Quellcode mit dem generierten phaser.esm.js-Manifest. Führe den minimalen repro.ts-Import aus und bestätige, dass Phaser.Class, Class.mixin und Class.extend im öffentlichen Namespace verfügbar sind.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Beschreibung
[4.0.0] Phaser.Class (incl. Class.mixin) is not exposed on the public ESM namespace — forces third-party plugins into inadequate mixin fallbacks
Versions
- Phaser:
4.0.0(latest stable) - Build: ESM via Vite
7.3.2(node_modules/phaser/dist/phaser.esm.js) - Browser: Chrome (any recent), renderer-agnostic (this is a JS-namespace ergonomics issue, not a render issue)
- OS: Windows
- Third-party plugin hitting the fallback:
@esotericsoftware/[email protected]
Summary
Phaser.Class is present inside the ESM bundle (the internal Class utility including Class.mixin, Class.extend, and the getProperty helper that unwraps { value: { get, set } } accessor descriptors) but is not re-exported on the public Phaser object that consumers receive via import * as Phaser from "phaser".
Third-party plugins that feature-detect Phaser.Class?.mixin (including the official @esotericsoftware/spine-phaser-v4) therefore always take their fallback branch on ESM builds. Those fallbacks typically don't replicate Class.mixin's def.value-unwrap semantics, which causes Phaser 4 component mixins (Transform, Origin, Alpha, Flip, ScrollFactor, Visible, Depth, ComputedSize, ...) to be installed as broken data descriptors instead of real accessors on the consuming class's prototype.
The consequence for my project: SpineGameObject.rotation reads as a literal { get, set } object, GetCalcMatrix produces NaN, and all Spine skeletons render invisible.
This request is a small API ergonomics fix on Phaser's side. The actual rendering bug is more accurately a bug in spine-phaser-v4's fallback (filed at EsotericSoftware/spine-runtimes#3065. But re-exporting Phaser.Class here would make that fallback path unreachable and pre-empt the same class of bug in every other plugin that does the same feature-detect.
Expected behavior
import * as Phaser from "phaser";
typeof Phaser.Class; // 'function'
typeof Phaser.Class.mixin; // 'function'
typeof Phaser.Class.extend; // 'function'
— identical to Phaser 3.x, where consumers and plugins have relied on Phaser.Class.mixin since at least 3.0 to correctly install Phaser's component accessors on their own classes.
Actual behavior
import * as Phaser from "phaser";
typeof Phaser.Class; // 'undefined'
Plugins feature-detecting Phaser.Class?.mixin fall back to hand-rolled mixin code that doesn't implement Phaser's descriptor-unwrap contract, and their users get invisible / broken Game Objects.
Minimal repro
// repro.ts
import * as Phaser from "phaser";
// fail
console.log("Phaser.Class:", Phaser.Class);
console.log("Phaser.Class.mixin:", (Phaser as any).Class?.mixin);
// Confirm Class exists inside the bundle but isn't re-exported:
// rg -n "Class\\.mixin|var Class|Class = " node_modules/phaser/dist/phaser.esm.js
Result on Phaser 4.0.0:
Phaser.Class: undefined
Phaser.Class.mixin: undefined
(Class + Class.mixin are present in phaser.esm.js; just not listed in the final export manifest.)
Why this matters (concrete downstream break)
@esotericsoftware/[email protected] contains this code in dist/mixins.js:
// ~L53
function applyMixins(target, mixins) {
if (Phaser.Class?.mixin) {
Phaser.Class.mixin(target, mixins); // never taken on ESM
} else {
applyMixinsFallback(target, mixins); // taken on ESM — broken
}
}
// ~L40
function applyMixinsFallback(target, mixins) {
for (const mixin of mixins) {
const source = mixin.prototype || mixin;
for (const key of Object.getOwnPropertyNames(source)) {
if (key === "constructor") continue;
const descriptor = Object.getOwnPropertyDescriptor(source, key);
if (descriptor) {
Object.defineProperty(target.prototype, key, descriptor); // naive
}
}
}
}
The fallback doesn't honor the def.value unwrap step that Phaser's own getProperty performs:
// phaser.esm.js — getProperty (invoked by Class.mixin)
var def = Object.getOwnPropertyDescriptor(definition, k);
if (def.value && typeof def.value === 'object') {
def = def.value; // ← the step every fallback fails to replicate
}
if (def && hasGetterOrSetter(def)) { /* install as accessor */ }
So Phaser.GameObjects.Components.Transform.scale, which ships as:
scale: {
get: function () { return (this._scaleX + this._scaleY) / 2; },
set: function (value) { /* ... */ }
}
gets installed on SpineGameObject.prototype as a data property whose value is { get, set }. hero.scale returns that object, NaN propagates, skeleton invisible.
A minimal prototype inspection confirms it:
const desc = Object.getOwnPropertyDescriptor(
Object.getPrototypeOf(hero),
"rotation"
);
// Phaser 4 ESM: { value: { get: ƒ, set: ƒ }, writable: true, enumerable: true, configurable: true }
// Expected: { get: ƒ, set: ƒ, enumerable: true, configurable: true }
Suggested fix
Re-export Class from the ESM entry so import * as Phaser from "phaser" receives it:
// src/index.js (or wherever the ESM public-surface aggregator lives)
export { default as Class } from "./utils/Class.js";
or, if the existing Phaser-namespace builder is centralized, add Class alongside the other already-exposed utilities (Math, Utils, Structs, Scenes.Events, etc.).
That's the entire fix. Class already exists in the bundle; only the public re-export is missing.
Bisect
| Configuration | Phaser.Class.mixin accessible? |
|---|---|
| Phaser 3.90.0 ESM | ✅ |
| Phaser 4.0.0 ESM | ❌ (this issue) |
| Phaser 4.0.0 global/UMD builds | ✅ |
Cross-reference
I filed the matching issue against spine-phaser-v4 so they're aware their fallback needs to match Class.mixin's semantics regardless of what Phaser decides here EsotericSoftware/spine-runtimes#3065
Either fix alone solves my specific symptom. Both fixes together would make it robust for every plugin author who reaches for Phaser.Class.mixin on instinct.
Workaround (what I'm shipping today)
Consumer-side prototype-walking shim against SpineGameObject.prototype that reinstalls the wrapped descriptors as real accessors. Works, but obviously not a pattern that scales to every plugin that touches Phaser mixins:
import * as Phaser from "phaser";
import { SpineGameObject } from "@esotericsoftware/spine-phaser-v4";
const FIXED = Symbol.for("spine-phaser-v4.accessorsPatched");
const isWrappedAccessor = (d) =>
d && typeof d.value === "object" && d.value !== null && "writable" in d &&
(typeof d.value.get === "function" || typeof d.value.set === "function");
export function installSpinePhaserCompat() {
const proto = SpineGameObject?.prototype;
if (!proto || proto[FIXED]) return;
const stopAt = Phaser.GameObjects.GameObject.prototype;
let current = proto;
while (current && current !== stopAt && current !== Object.prototype) {
for (const key of Object.getOwnPropertyNames(current)) {
if (key === "constructor") continue;
const desc = Object.getOwnPropertyDescriptor(current, key);
if (!isWrappedAccessor(desc)) continue;
const { get, set } = desc.value;
Object.defineProperty(current, key, { configurable: true, enumerable: desc.enumerable, get, set });
}
current = Object.getPrototypeOf(current);
}
Object.defineProperty(proto, FIXED, { value: true });
}
- Vorherrschende Sprache
- JavaScript
- Sterne
- 40.7k
- Forks
- 7.2k
- PR-Merge-Kennzahlen
- Keine gemergten PRs in 30 T.
Entwicklungsumgebung
- Kein Dockerfile und keine Docker-Compose-Datei
- Hat eine Pull-Request-Vorlage
- Beitragsleitfaden lesen
Erste Schritte
- Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
- Forken Sie das Repository und arbeiten Sie in einem Branch.
- Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.
Mehr aus phaserjs/phaser
-
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 80/100
Maintainer antworten meist innerhalb von 3 Tagen
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 80/100
Maintainer antworten meist innerhalb von 3 Tagen
-
Type definition for TilemapLayer.getTileAt is wrongEvtl. vergeben @hkbughk hat das vor 34 Tagen übernommen. Offen
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 70/100
Maintainer antworten meist innerhalb von 3 Tagen
-
Shader.preDestroy leaks its ShaderQuad's vertex buffer and VAO on every create/destroy cycle (4.2.1)Evtl. vergeben @k1epg01ng129-eng hat das vor 32 Tagen übernommen. Offen
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 86/100
Maintainer antworten meist innerhalb von 3 Tagen
-
Black opaque background on transparent Phaser.Text textures in Phaser 4.2.1 on older iOS WebGLEvtl. vergeben @SamuelMalmfors hat das vor 14 Tagen übernommen. Offen
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 85/100
phaserjs/phaser#7392 · 1 Kommentar ·
Maintainer antworten meist innerhalb von 3 Tagen
Alle Issues in phaserjs/phaser
Ähnliche Issues
-
topg.org functionalityOffen
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 65/100
-
needs:triage
Schwierigkeit 1/5 Unter einer Stunde Anfängerfreundlichkeit 92/100
Maintainer antworten meist innerhalb von 1 Tag
-
fix(readme): skills.sh badge says 'resource not found' and the skills.sh link is a 404; skills.sh still lists the old name tdk-skillsEvtl. vergeben @bfs2021 hat das heute übernommen. Offenarea: ci area: docs badge bug chore cleanup consistency developer-experience difficulty: easy docs documentation good first issue hygiene journey: first-visit links priority: P3 skills user-journey
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 65/100
flisk-sh/flisk-skills#39 ·
Maintainer antworten meist innerhalb von 1 Tag
-
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 62/100
Maintainer antworten meist innerhalb von 1 Tag
-
Bug
Schwierigkeit 2/5 1-3 Stunden Anfängerfreundlichkeit 82/100
Ionaru/easy-markdown-editor#656 ·