spine 浏览器产物在 Engine 2.0 上不可用:UMD 走已删除的 Shader.create 两字符串重载,静默拿到坏 shader

Aperta
#3,122 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
4/5
Tempo stimato
3-5 giorni
Idoneità per principianti
35/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
typescript
Ambito
backend

Direzione di ricerca

Start with the Shader.create overloads and runtime implementation in Shader.ts, then inspect the shader tests and the history of the removed two-string overload. Add coverage showing that this call shape is rejected without writing a malformed shader into _shaderMap; done means callers receive a clear error. The Spine UMD compatibility and whether to remove Spine from the ecosystem preload are separate decisions described in the issue.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

问题

@galacean/engine-spine 的浏览器(UMD)产物在 Engine 2.0 上构造材质即崩,但崩溃点看起来与 spine 无关:

new Galacean.Spine.SpineMaterial(engine)
// TypeError: Cannot read properties of undefined (reading 'blendState')

同一份源码的 ESM 产物在同一个 Engine 上正常。也就是说:Editor 预载(ecosystem bundle)里的 Spine 是不可用的,而 import-map / npm ESM 路径里的 Spine 是可用的,两条路径解析到的是同一个版本号。

复现

浏览器里按顺序加载两份 UMD,然后构造材质:

const engine = await Galacean.WebGLEngine.create({ canvas });
new Galacean.Spine.SpineMaterial(engine); // throws

实测矩阵(Chromium,产物取自 CDN):

engine spine 产物 new SpineMaterial(engine)
2.0.0-alpha.43 4.2.8 UMD ❌ blendState undefined
2.0.0-alpha.43 4.2.7 UMD ❌ 同上
2.0.0-alpha.43 4.2.5 UMD ❌ 同上
2.0.0-alpha.43 4.2.8 ESM(esm.galacean.com/@galacean/[email protected]) ✅ 正常
1.6.0 4.2.5 UMD ✅ 正常

即:所有 4.2.x 的 UMD 在 2.0 上都坏(不是 4.2.8 独有,也没有可回退的旧版本),ESM 产物不受影响。

根因

spine 的 UMD 产物在构造材质时才惰性建 shader,用的是 1.x 的两字符串重载:

var shader = Shader.find("galacean-spine-shader")
  || Shader.create("galacean-spine-shader", SpineMaterial._spineVS, SpineMaterial._spineFS);

该重载 create(name: string, vertexSource: string, fragmentSource: string) 在 ShaderLab 迁移里被移除了:

  • v2.0.0-alpha.30 仍存在该重载;
  • v2.0.0-alpha.31 起已移除(refactor(shader): migrate GLSL shaders to ShaderLab and clean up shader infrastructure #2961,2026-05)。

但 Shader.create 的运行时实现没有对这个调用形态设防:shaderPassesOrSubShadersOrPlatformTarget 拿到的是第二个字符串(fragment 源码),它既不是 number 也不是 SubShader[] | ShaderPass[],于是走进 else 分支被当作 SubShader[] 处理(.length / [0] / .slice() 对字符串全部成立)。结果是:

  • 返回一个坏 Shader 对象:subShaders 退化成 String(实测 typeof shader.subShaders === "string"、length === 73、subShaders[0].passes 不存在);
  • 这个坏 shader 被写进 Shader._shaderMap["galacean-spine-shader"] 并长期驻留;
  • 随后 Material 构造读 passes[0].renderState,抛 blendState undefined。

TypeScript 消费方有编译期保护(重载已删,调用即报错);但 UMD / 手写 JS 消费方没有任何门禁,静默拿到损坏对象并污染全局 shader 表。这是本 issue 里属于 engine 自己的那一半。

影响

  • Editor 2.0 预载产物 @galacean/editor-preload-ecosystem/engine-2.0/browser.js 里的 Galacean.Spine 不可用;Editor 侧 SpineAnimationRenderer 仍被登记为 2.0 可运行组件(packages/model/src/modules/components/domain/componentRuntimeCapabilities.ts),@galacean/engine-spine 仍被 feature 依赖解析到 engine-2.0(packages/constants/src/builder.ts)。
  • esm.galacean.com 的 import-map 路径(ESM 产物)可用,因此该问题在"编辑器内预览"与"打包产物/预载"之间表现为不一致,容易误判为随机问题。
  • engine#3120 新增的发布门禁用 typeof Galacean.Spine.SpineAnimationRenderer === "function" 判断可用性,过不了这一类缺陷(符号存在、构造才崩)。

需要决策的两半

  1. spine 侧:engine-spine 只发布了 4.2.8 的 legacy GLSL/Shader.create(name, vs, fs) 产物,其 4.2 分支已停滞(最后提交 2025-11)。需要迁到 ShaderLab 并发布 2.0 可用版本;在那之前,2.0 的预载是否应该继续带 spine?(参考 Lottie 的处理:Editor 移除支持后即从 ecosystem 配置中摘除。)
  2. engine 侧:Shader.create 应当明确拒绝已删除的调用形态(抛出可诊断的错误,例如提示改用 ShaderLab 源码或显式 SubShader[]/ShaderPass[]),而不是静默构造坏对象并缓存。当前实现让"API 已移除"这件事在 JS 消费方变成"运行时随机崩溃 + 全局状态污染"。

验收

  • Engine 2.0 + engine-spine 浏览器产物能 new SpineMaterial(engine) 并渲染出 spine 动画;或明确宣布 2.0 暂不支持 spine 并把它从 ecosystem 预载配置中移除。
  • 传入已删除的 Shader.create(name, vs, fs) 形态时得到明确报错,Shader._shaderMap 不被写入坏对象。

来源:galacean/engine#3120 发布链路核查(Chromium 实测 + Shader.ts 重载历史 bisect)。

Lingua principale
TypeScript
Stelle
5.9k
Fork
413
Merge medio
16h 17m
PR unite (30g)
41

Preparare l'ambiente

  • Nessun Dockerfile né file Docker Compose
  • Ha un modello di pull request
  • Nessuna guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di galacean/engine

Tutte le issue di galacean/engine

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.