spine 浏览器产物在 Engine 2.0 上不可用:UMD 走已删除的 Shader.create 两字符串重载,静默拿到坏 shader
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,抛blendStateundefined。
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"判断可用性,过不了这一类缺陷(符号存在、构造才崩)。
需要决策的两半
- 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 配置中摘除。) - 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
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di galacean/engine
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 64/100
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 85/100
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 4/5 3-5 giorni Idoneità per principianti 52/100
I maintainer di solito rispondono entro 1 giorno
-
RFC: Adopt Unity-style Collider components and hierarchical Rigidbody ownershipForse già presa Una pull request collegata a questa issue è aperta o già unita. Aperta
Difficoltà 5/5 Più di una settimana Idoneità per principianti 20/100
I maintainer di solito rispondono entro 1 giorno
-
SkinnedMeshRenderer should derive default rootBone-space localBounds from mesh and skinForse già presa Una pull request collegata a questa issue è aperta o già unita. Apertaenhancement
Difficoltà 4/5 3-5 giorni Idoneità per principianti 42/100
I maintainer di solito rispondono entro 1 giorno
Tutte le issue di galacean/engine
Issue simili
-
bug impact:low Team: SecuritySolution Team:Defend Workflows v9.6.0
Difficoltà 2/5 1-3 ore Idoneità per principianti 72/100
elastic/kibana#306401 · 3 commenti ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 68/100
agentes-chat/agentes-chat#927 ·
I maintainer di solito rispondono entro 1 giorno
-
[Bug]: Webapp workspace fails to render in Safari — "Can't find variable: requestIdleCallback"Apertacomp/desktop P2 type/bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
NousResearch/hermes-agent#157702 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
I maintainer di solito rispondono entro 1 giorno
-
e2e-failure ready-to-code
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 72/100
redhat-developer/rhdh-plugin-export-overlays#4794 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno