[4.0.0] Phaser.Class (incl. Class.mixin) is not exposed on the public ESM namespace — forces third-party plugins into inadequate mixin fallbacks

Đang mở Phù hợp với người mới
#7,286 3 bình luận 0 reaction 0 người được giao Xem trên GitHub

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

Chưa có ai nhận issue này.

Đánh giá

Độ khó
2/5
Thời gian dự kiến
1-3 giờ
Mức phù hợp với người mới
62/100
Loại issue
Lỗi
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Ít trao đổi
Công nghệ
javascript, vite
Lĩnh vực
api, game-dev

Hướng nghiên cứu

Bắt đầu với src/index.js hoặc trình tổng hợp ESM của public surface và kiểm tra utils/Class.js. Sau đó, so sánh các export của mã nguồn với manifest phaser.esm.js được tạo. Chạy import repro.ts tối thiểu và xác nhận rằng Phaser.Class, Class.mixin và Class.extend được expose trên namespace public.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

[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 });
}
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.