Sparkle Morpher v1.2.6

Sparkle Morpher 1.2.6

Responsive 3D card catalog / i18n completion / Paper Doll split and ride fixes

Release date: 2026-09-12
Supported branches: Fabric 1.21.1, Fabric 26.1.2, Fabric 26.2, NeoForge 1.21.1, NeoForge 26.1.2, NeoForge 26.2

English | 中文

Sparkle Morpher 1.2.6 brings a responsive live-3D card catalog to the model picker, adds Traditional Chinese (Hong Kong) and Literary Chinese (lzh) while localizing built-in model metadata into 15 languages, splits the player paper-doll rendering out of a single file into a maintainable preview package with a set of classic HUD doll options, and fixes two bugs: Happy Ghast sit pose and non-player model selection leaking into the player's own selection. All six source repositories are synchronized, clean-built, and pushed to their GitHub branches.

Highlights

Responsive 3D card catalog (model picker)

The model picker gains a three-state view, cycled from a bottom-toolbar button through Auto → Cards → List (config ModelPickerStyle, default Auto, session-pinned after an in-UI switch):

• Auto: uses cards when space allows, otherwise falls back to the original icon + text grid. The list path is fully retained, so a complete rollback is always possible.
• Cards: forces card mode, preferring cards even when only one minimum readable card (40×48) fits; falls back only below that.
• List: the existing icon + text grid.

Every card face is a live 3D model. The first design rendered live 3D only for hovered/selected cards (at most two preview entities) and used static covers elsewhere; on real hardware that produced mostly blank cards and "no model unless hovered". It now renders every visible card's model live — the model is the card face. Cost is bounded by a per-page-slot preview entity pool (slots are rebound on page turns and do not grow with catalog size); lazy models show a placeholder until ready.

Card-art geometry is now calibrated against the real YSM spec:

• The card-art size is confirmed as 52×90 (aspect 1.7308); CARD_ASPECT was corrected from 1.62 to 90/52, removing the side letterboxing.
• The gui_background → live 3D → gui_foreground border three-layer order was restored; the earlier two-layer simplification lost the front border and darkened the background.
• Doll scale changed from coverH*0.62 to the long-validated coverH*0.43, with a hard "never exceed cover height" clamp on figureScale(), fixing head clipping.
• Column count is now chosen by searching for the column count that maximizes cards per page (ties prefer larger cards): horizontal fill 99–100%, vertical 72–98% (limited by the 52:90 ratio).

Catalog defects fixed in the same batch (each with its root cause):

• ModelPanelLayout.create() decided the vertical-tab layout from guiScale >= 3.0, but guiScale is a physical/logical ratio unrelated to available logical space, so layouts flipped on monitor or scale changes. It now tests logical width/height.
• The fixed 16px nameBandH floor could exceed the card height on very short cards, producing a negative coverH; now min(band, cellH - 1) with a regression test.
• markModelUsed was called after the readiness check, so not-yet-ready cards were never marked in-use and lazy/TTL eviction could reclaim the model being viewed; it now marks before checking readiness.

Card look (cover shading, doll size, name-band wrap threshold, palette) was built headless and has not been calibrated item-by-item in-game; models without embedded card art show live 3D only and get no static placeholder. Card mode intentionally has no scrollbar (paging by design).

Traditional Chinese (Hong Kong) and Literary Chinese (lzh)

Root cause: Minecraft's language fallback chain is only [en_us, selected locale] — there is no sibling or same-family fallback. Only zh_tw.json existed, so selecting "香港繁體 / zh_hk" resolved all mod text to English. There is no zh_sg/zh_my/other Simplified locale in vanilla, so no Simplified file was added.

• zh_hk.json (new): generated from zh_tw.json as the base, not via OpenCC (its t2hk mixes Simplified into Traditional). Only two verified HK glyph adaptations (平臺→平台, 臥→卧); key order and structure match zh_tw, with just 13 differing values.
• lzh.json (Literary Chinese, new): built by aligning vanilla 1.21.1 zh_cn.json and lzh.json into a 4852-entry Simplified→Literary glossary, then translating 789 unique English strings across 8 parallel passes under a style guide and the Touhou Little Maid lzh.json reference; key order matches en_us.json exactly.

Built-in model metadata localization

Built-in model names/descriptions/authors previously fell back to English only (ModelMetadataPresenter.getLocalizedString recognizes en_us). It now covers 15 languages, up from {en_us, zh_cn}: added zh_tw, zh_hk, plus es_es, fr_fr, id_id, ja_jp, ko_kr, pt_br, ru_ru, tr_tr, uk_ua, vi_vn, lzh. For the ten pre-existing non-Chinese locales, 611 unique English strings that were missing or still equal to English were translated.

• One real defect fixed: ru_ru.json's open_model_folder.tips used Cyrillic п/а in place of Latin n (§папка), breaking vanilla format codes; corrected.
• All 11 groups of "identical English, different Chinese meaning" keys were reviewed, and the 3 genuinely ambiguous ones were rewritten.

Translations were spot-checked, not proofread by native speakers (~1400 entries across 10 languages plus Literary Chinese). 12 placeholder warnings were confirmed pre-existing and harmless via git diff (dead keys or correct argument counts) and left untouched.

Paper Doll split and classic HUD doll options

On the 26.x branches, the 999-line ModelPreviewRenderer.java was split into a compatibility facade (999 → 177 lines, all 25/25 public APIs preserved, zero call-site migration) plus a new client/renderer/preview/ package: PreviewSceneRenderer (bed/ground/vehicle preview props), PreviewMath (deliberately MC-free projection and mouse math for pure-JVM tests), PreviewRenderBridge (GUI preview queue and InventoryScreen handshake), GuiModelRenderer, PaperDollRenderer, PaperDollLayout (pure math, including the inverse), PaperDollVisibilityPolicy, and PaperDollActivity. Tests added: PaperDollIsolationTest, PaperDollHeadModeContractTest, PaperDollLayoutTest, PaperDollVisibilityPolicyTest.

The classic HUD doll gains a set of options (config section extra_player_render, defaults equal historical behavior, so installing the jar changes nothing until the config is edited):

Option	Config key	Default	Meaning
Head mode	ClassicHudHeadMode	STRAIGHT	STRAIGHT head follows body (legacy); FOLLOW head tracks the real view yaw, clamped ±85°
Anchor	ClassicHudAnchor	TOP_LEFT	9-position anchor plus X/Y offset; TOP_LEFT with the original pixel value is the exact legacy position
Idle auto-hide	ClassicHudAutoHideIdleSeconds	0 (off)	Hide the doll after N idle seconds
Hide in third person	ClassicHudHideInThirdPerson	false	Hide in third-person view
Vehicle alignment	ClassicHudAlignWithVehicle	false	Align doll yaw with the vehicle
Action-only visibility	ClassicHudShowOnActionOnly	false	Show only while moving/sneaking/swimming/gliding/climbing/in water/riding/using/attacking/hurt/sleeping

These options are config-file only — there is no GUI settings screen.

Ride and selection fixes

• Happy Ghast sit pose used the wrong animation: LivingMovementAnimationPredicate used Saddleable (saddleable mobs) for riding on 1.21.1, but 26.x replaced it with a vehicle instanceof LivingEntity → ride fallback after the API was removed. HappyGhast extends Animal → LivingEntity, so it was treated as a straddle vehicle and played the horse-style ride pose. It is now explicitly matched before the fallback and routed to sit, matching the mod's own sit ("sitting on an entity") semantics. Only the four 26.x branches are affected (1.21.1 has no Happy Ghast).
• Setting a model for a non-player polluted the player's own selection: ModernPlayerModelScreen#applyModelAndTexture's custom-target branch (maid/NPC) unconditionally called ClientModelManager.rememberSelectedModel(...), which writes the player selection track and persists it; on the next join restorePersistedModelSelection() then applied the target entity's model to the player. A new rememberPlayerSelection flag now defaults to true only for the player's own panel, with shouldRememberPlayerSelection() / setRememberPlayerSelection(boolean) exposed so third-party NPC panels can override it precisely.

Blaze3D frame-graph channel (experimental, default off)

Diagnosis of "most in-world models vanish when enabled": geometries were successfully deferred (the log shows [SM-BLAZE3D] ... ACTIVE) and removed from the vanilla collector, but the frame-graph pass never executed them, so models were neither in the collector nor drawn — hence invisible. Six alternatives were ruled out: config not applied, mixin not loaded, missing target signature, unreachable injection point, accessor mismatch, and frame-graph culling.

Rather than add a high-privilege mechanism, this release ships a self-healing fallback plus staged diagnostics: new per-frame counters, and if a frame deferred draws that were not all rendered (pass never ran, ran late, or was refused), the channel is permanently auto-disabled for the session with a lost-geometry log line, falling back to the normal submit path — so the defect can affect at most one frame. Registration exceptions now self-heal too.

The true root cause is not confirmed; the diagnosis document's retest section is still awaiting user lo...

Sparkle Morpher v1.2.5

Sparkle Morpher 1.2.5

Player Visual Runtime / Render Pipeline and Developer Tooling

Release date: 2026-09-11
Supported branches: Fabric 1.21.1, Fabric 26.1.2, Fabric 26.2, NeoForge 1.21.1, NeoForge 26.1.2, NeoForge 26.2

English | 中文

Sparkle Morpher 1.2.5 delivers the Player Visual Runtime stage of the 1.2.x plan, adds a default-off Blaze3D frame-graph render channel, and gives model authors a unified Developer options panel. All six actual source repositories were synchronized, cleanly built, and pushed to their matching GitHub branches.

Highlights

Player Visual Runtime (render context convergence)

Render state that used to be scattered across ThreadLocals and ad-hoc boolean flags is now centralised in RenderContext:

• RenderPass gains FIRST_PERSON and PAPER_DOLL, appended at the end so existing ordinal semantics stay unchanged.
• RenderContext moves from ThreadLocal<RenderPass> to an immutable record ThreadLocal<RenderScope>(pass, modelPreview, entity, partialTick). The old API (enter/restore/currentPass/isGuiPreview/isOldHud) keeps its previous semantics.
• First-person detection converges on RenderContext: the standalone FIRST_PERSON_MODE field is removed while the global PBR and FirstPerson-mod fallbacks remain. A worker-thread behaviour audit confirmed this is safe — worker threads already read the default value and receive their semantics through method parameters.
• The model-preview flag joins RenderScope, with a new isAnyPreview() collapsing the two union reads of "model preview ∪ GUI preview".
• A new PhysicsDomain (WORLD / PREVIEW / EXTRA_PLAYER / FIRST_PERSON) makes the physics domain explicit.
• New PlayerFrameSnapshot (frame-level render inputs plus a testable sanitizePartialTick) and PlayerRenderPolicy (pure decision logic with no Minecraft dependency, unit-testable) pull render gating out of call sites and into policy inputs.

Default-off Blaze3D frame-graph render channel

A new channel registers GPU draws as deferred draws and inserts them into the Minecraft frame graph as a first-class pass:

Submit stage   IGeoRenderer → register (deep-copied pose)
Frame graph    inject at the tail of LevelRenderer frame-graph construction,
               declaring readsAndWrites(main)
MC scheduling  Minecraft owns ordering, barriers, and resource lifetime

• Key finding: player shadows are submitted independently (relative position and shape only, no model geometry), so GPU skinning and shadows do not conflict — the channel does not have to sacrifice shadows.
• Conservative gating (first version covers only the most ordinary case): requires the config switch and the experimental switch, plus world rendering, no preview, not first person, no shader pack, non-glowing entity, opaque, and an empty part mask. Everything else keeps using the existing paths.
• Fail-safe: the whole chain is wrapped in try/catch; an exception is logged once and the frame's pending draws are cleared, with unconditional cleanup at frame begin/end.
• The switch is a standard mod config entry (EnableBlaze3DInPipelineDraw, default off, in the Performance group) and requires no JVM arguments. Two one-shot INFO lines that bypass the log gating ([SM-BLAZE3D]) were added so users who enable only the new channel still see output.
• Adjacent improvements in the same batch: select the translucent pipeline from translucentTexture (#2); replace the "backend name equals VULKAN" check with capability-based routing (#3, OpenGL fast-path behaviour unchanged); precompile both pipelines before the first draw while retaining lazy compilation as a fallback (#4).

This channel is off by default and represents a conservative first version intended to be opened up gradually. Translucent textures, glowing entities, split glow bones, preview, and first-person scenes still use the existing paths.

Model author "Developer options"

The former Debug group is promoted to Developer options and split into four sections — Panel state / Logging / Profiling / Renderer diagnostics (renderer diagnostics exists only on the 26.x branches, since four of its entries are version-specific):

• Panel state: dump the current panel state to the clipboard as JSON, reset panel state, and a default-off "apply panel state from clipboard" feature for reproducing the UI state an author reports. Writeback validates the whole batch first and applies it all-or-nothing; any invalid value rejects the batch, and the confirmation panel (which needs host context) cannot be restored this way.
• Logging / Profiling: two switches that previously existed in config but were never surfaced in the UI are now wired up (network online debug log, warn repeated animation evaluation).
• Panel state is now cached per context key: reopening the same target remembers its tab, search, and scroll position, while different targets no longer share state.

Compatibility fixes

• ParCool (three NeoForge branches): the NeoForge side previously had no loader implementation, so ParCool actions never entered animation resolution. A pure-reflection bridge (no compile-time dependency) maps the 38 action names from the bundled animation JSON and remembers direction per action instance to avoid mid-playback drift; ctrl.parcool_loaded and ctrl.parcool_doing Molang variables are provided as well. The Fabric side keeps its no-op stub (ParCool is NeoForge-only).
• SlashBlade (NeoForge 1.21.1, Issue #25): fixed attack animations being flipped vertically and horizontally, and the sheath being bound to the wrong side at the wrong height. The root cause was applying vanilla layer-space maths directly in YSM entity space without the scale(-1,-1,1) and vertical baseline compensation; the project's elytra and parrot layers already compensated explicitly, and only this branch had been missed. The maid's held-blade render branch was added too.
• Render backend decision drift: RenderBackendDecision on neo26.2 / neo26.1.2 had missed one synchronized commit, which could route GUI previews onto the direct-draw path. It is now aligned on isAnyPreview() and all four 26.x branches are byte-identical at that site.

Stability and other fixes

• Model face-culling escape hatch: a default-off self-rescue entry for "some models lose faces at certain angles", covering the GPU, Blaze3D, and SIMD paths.
• Native trust chain now fails closed: the YSM_CORE_LIB development override previously skipped content verification, while the native ABI version is identical before and after the culling fix, so a stale library could not be identified from it. The override now verifies the content hash against the manifest by default, refuses to load on mismatch, and prints the expected and actual hashes; an explicit escape hatch remains. Cache reuse and reinstall both log the manifest identity, making "which native build is actually loaded" visible in the log.
• Blaze3D mesh resource leak fixed: the mesh cache never released its GPU buffers or per-frame direct memory, and the release path only fired when the OpenGL handle was non-zero; release hooks were added and reclamation is now unconditional.

Dead code removal

Removed render paths verified unreferenced across all source sets: PiePortableRenderPath / PieMesh / PiePipeline / PieShader, IrisRenderPath, BoneXformCompute, and the shader assets that became unused with them. The live Pie fallback draw is retained.

Build and verification

• All six branches were pushed and fetch-verified so that local HEAD matches the corresponding remote branch; working trees are clean.
• The release build script performed clean builds (JDK 21 for 1.21.1, JDK 25 for 26.x) and all six branches produced full JARs; CurseForge variants are additionally checked to be free of native libraries.
• Tests: the full suite passes on Fabric 26.2 and NeoForge 26.2 (345 / 317 tests, 0 failures), including the new render-context, frame-snapshot, render-policy, backend-routing, and frame-pass tests added in this version.
• The remaining branches were compiled with their relevant tests.

Release assets

• Six full JARs (Fabric / NeoForge × 1.21.1 / 26.1.2 / 26.2).
• Bilingual release notes (this file and the Chinese version).

Compatibility matrix

Loader	Minecraft	Branch	Artifact
Fabric	26.2	fa26.2	sparkle-morpher-1.2.5-fa26.2.jar
Fabric	26.1.2	fa26.1.2	sparkle-morpher-1.2.5-fa26.1.x.jar
Fabric	1.21.1	main	sparkle-morpher-1.2.5-fa1.21.1.jar
NeoForge	26.2	neo26.2	sparkle-morpher-1.2.5-neo26.2.jar
NeoForge	26.1.2	neo26.1.2	sparkle-morpher-1.2.5-neo26.1.x.jar
NeoForge	1.21.1	neo1.21.1	sparkle-morpher-1.2.5-neo1.21.1.jar

Use the artifact matching both your loader and your Minecraft version. The 1.21.1 builds require the 1.21.1 loader/API line; do not mix them with 26.x installations.

Known limitations

• The new Blaze3D frame-graph channel is off by default with conservative gating and is not yet opened up for every scenario (translucent, glowing entities, preview, first person, shader packs).
• Panel-state writeback is off by default and is a model-author troubleshooting tool.
• The 1.21.1 branches still carry a shared static projection field whose value depends on call order; that semantic fragility has not been addressed yet.

Sparkle Morpher v1.2.4

Sparkle Morpher v1.2.4

发布日期：2026-09-06

Sparkle Morpher v1.2.4 completes the unified player-action runtime and extends full action coverage to imported BBModel/Figura and glTF models.

Highlights

Unified player action runtime

• Added a single PlayerActionState authority for player actions, covering the 19 base states plus ride/empty sentinels.
• Added frame-level PlayerActionSnapshot data and centralized state resolution in ControllerActionResolver.
• Converged animation registration on the unified resolver while keeping legacy registration APIs compatible.
• Added regression and architecture-boundary tests for state priority, ladder dead zones, movement, riding, and side-effect separation.

BBModel and Figura animation support

• Imported BBModel/Figura models now use the full keyframe action stack plus a procedural vanilla fallback.
• Added complete vanilla-skeleton action coverage for idle, walk, run, jump, fly, elytra flight, swimming, climbing, ladder movement, riptide, attack reaction, death, sleep, sneak, and related states.
• Added first-person arm animation slots and BBModel/Figura-only automatic weapon fallback animations for holding, using, and swinging items.
• Preserved model-authored animations with computeIfAbsent; built-in fallbacks never replace a model's own animation.
• Fixed the legacy VANILLA_HUMANOID gate that prevented BBModel/Figura keyframe animations from running. This was the root cause of elytra/swimming states falling back to walk/run-like procedural poses.
• Replaced non-portable Bedrock-derived swim and elytra poses with vanilla-style action-file poses. The elytra action file now only supplies the original Steve-like arm spread, avoiding duplicate body rotation and model-dependent clipping.
• Improved idle animation using the CC BY “Skin idle animation” Blockbench Workshop asset by splatty, with attribution and conversion details recorded in CREDITS.md.

glTF animation support

• Expanded the independent glTF animation state machine from eight states to the full player-action set, including fly, elytra flight, swim, sneak, ride, sleep, attack reaction, climbing, and ladder states.
• Added GltfPlayerActionMapper to map the unified player action state into the glTF runtime.
• Third-person and first-person glTF rendering now use the same action-state mapping.
• The 1.21.1 first-person glTF hand path was upgraded from fixed-first-clip playback to unified state selection.
• glTF files remain local-only and continue to play their embedded animations; no server upload is introduced.

Community and conversion tooling

• Added tools/convert_vanilla_animations.py to convert Bedrock player animation data into SparkleMorpher action keys, normalize vanilla bone names, filter unsupported channels, and bake supported Molang expressions into numeric keyframes.
• Added tools/convert_bbmodel_animations.py for converting Blockbench animation-only .bbmodel files into Bedrock 1.8.0 animation JSON.
• Added tools/refine_placeholder_animations.py for generating refined vanilla-skeleton keyframes for states not present in the source animation pack.
• Added tools/workshop_scan.py, using Playwright + Edge to scan Blockbench Workshop free animated assets. The scan found 142 animated free models: 117 CC BY and 25 CC0.
• The scan identified two vanilla-player-skeleton candidates; the Skin idle animation asset was converted and used. Other downloaded candidates were retained for evaluation but rejected where their skeletons or coordinate systems were not compatible.

Bug fixes

• BBModel/Figura elytra flight no longer inherits a walk/run-like procedural pose because the keyframe action state machine is now allowed to run.
• BBModel/Figura swimming and elytra poses no longer use extreme, non-portable Bedrock angles.
• Fixed first-person glTF hand animation selection on the 1.21.1 path.
• Fixed conversion-tool handling of query.anim_time, dotted math.* function names, constant-frame compression, and preservation of non-converted animation keys.
• Preserved loader-specific source mappings while synchronizing changes across Fabric and NeoForge branches.

Compatibility matrix

Loader	Minecraft	Branch	Artifact
Fabric	26.2	fa26.2	sparkle-morpher-1.2.4-fa26.2.jar
Fabric	26.1.2	fa26.1.2	sparkle-morpher-1.2.4-fa26.1.2.jar
Fabric	1.21.1	main	sparkle-morpher-1.2.4-fa1.21.1.jar
NeoForge	26.2	neo26.2	sparkle-morpher-1.2.4-neo26.2.jar
NeoForge	26.1.2	neo26.1.2	sparkle-morpher-1.2.4-neo26.1.2.jar
NeoForge	1.21.1	neo1.21.1	sparkle-morpher-1.2.4-neo1.21.1.jar

Use the artifact matching both the loader and Minecraft version. The 1.21.1 builds require the 1.21.1 loader/API line; do not mix them with 26.x installations.

Verification

• All six branches are maintained as independent repositories and were synchronized through the workspace sync workflow.
• Full clean builds are run by the release build script; each artifact is checked as a valid JAR and recorded with SHA-256.
• 1.21.1 branches use JDK 21; 26.x branches use JDK 25.
• Existing 1.2.4 action-runtime and glTF regression suites remain part of the verification run.

Attribution and licensing

• Vanilla Bedrock-derived animation data is transformed (renamed, filtered, and Molang-baked) rather than copied byte-for-byte. Mojang/Microsoft ownership remains acknowledged in the animation CREDITS.md.
• The idle animation adaptation is from Blockbench Workshop model “Skin idle animation” by splatty, under CC BY. Credit and source URL are included in the animation CREDITS.md.
• Workshop-derived assets must retain their individual attribution and license terms. Rights-reserved or unlicensed assets are not included in the built-in preset.

Known limitations

• BBModel/Figura refined states use a generic vanilla player skeleton; models with non-standard skeleton names or coordinate systems may require an authored animation override.
• glTF remains an independent embedded-animation pipeline and does not become a geckolib PlayerModelBundle.
• The built-in refined animation files are intentionally conservative vanilla-style keyframes; model authors can override them with same-key animations.

v1.2.3

Sparkle's Morpher 1.2.3

Platform Architecture（R12）

1.2.3 是 Platform Architecture 版本，完成了 R12.1–R12.4 四个方向的收敛：

• R12.1 Config Policy：统一渲染、内存、诊断、隐私、网络、音频和功能策略入口，减少业务代码直接读取底层配置。
• R12.2 Version Adapter：建立 Render、GUI、Packet、Entity、Resource、Camera、Capability/Component、GPU/RenderPipeline 等稳定适配边界。
• R12.3 Loader Boundary：Fabric 与 NeoForge 继续保留独立 loader 入口、元数据和平台实现；共享逻辑位于 common，NeoForge 专属逻辑位于 src/neoforge，Fabric 专属逻辑位于 fabric。
• R12.4 Distribution Variant：统一 native/original 与 CurseForge 分发变体。GitHub 和 Modrinth 使用同一份包含 native 的原版 JAR；CurseForge 使用不包含 native 库的 -curseforge.jar。-Pdist=modrinth 继续作为原版分发兼容别名。

六个实际分支均完成对应的源码、构建、测试和发行配置收敛：

• Fabric 1.21.1
• Fabric 26.1.2
• Fabric 26.2
• NeoForge 1.21.1
• NeoForge 26.1.2
• NeoForge 26.2

本次对话中的 Issue #22 修复

Issue #22 报告了 1.21.1 中手持 SlashBlade 时只有挥刀动画、拔刀剑刀模型不显示的问题。

本次在 NeoForge 1.21.1 分支加入了对 SlashBlade: Resharped 1.21.1 的兼容桥接：

• 检测 slashblade 模组是否加载，并保持缺少依赖时的安全降级。
• 识别 ItemSlashBlade 并读取 ISlashBladeState 的当前连招状态。
• 将 SlashBlade 连招状态接入 slashblade:combo_* 动画。
• 注册 slashblade_animation MoLang 变量。
• 复刻 SlashBlade LayerMainBlade 的刀身、刀鞘、发光和蓄力效果渲染。
• 支持主手挥刀轨迹以及副手腰间收刀姿态。
• 复用 SlashBlade 的 MMD 动作、hardpointA/hardpointB 和模型资源。
• 添加 NeoForge 可选依赖声明和 compile-only 依赖，不会把 SlashBlade 打包进 Sparkle's Morpher。

该修复已提交并推送到 neo1.21.1 分支。其余分支的 SlashBlade 适配需要分别针对 Refabricated 或对应版本 API 继续验证，不能直接视为已支持。

新功能与改进

独立 glTF 渲染管线

• 增加独立 glTF/GLB loader、场景评估、动画时钟、三角形顶点发射、材质解析和扩展注册边界。
• 支持 OPAQUE、MASK、BLEND、双面材质和 alpha cutoff 解析。
• 对未知 glTF 扩展保持严格拒绝策略。
• 对 NetEase 4D glTF 应用 1/16 像素空间缩放。
• 将 Minecraft tick 转换为 glTF 秒，限制 partial tick，修复动画高速抖动。
• 增加第三人称实体动画、第一人称手部入口、本地导入和模型缓存支持。

glTF 动画与持物

• 动画控制器改为持久化实例，避免每帧重建导致第三人称动画停止。
• 空 animation 占位项不再被错误选中。
• walk/run 支持双向回退。
• 攻击、使用物品和挥手动作支持多种命名匹配，并提供通用回退。
• 恢复第三人称实体主手和副手物品渲染。
• 支持左右手映射、左手主手设置、NetEase 4D hand/arm 节点和强制 3D 物品模型。

女仆模型与手持物品

• 六个 loader/版本组合加入女仆手持物品渲染层。
• 修复女仆主手、副手物品不显示。
• 修复渲染上下文和 collector 传递。
• Iris 阴影 pass 不再错误跳过女仆动画。

模型重载稳定性

• 新增有界重载队列、请求合并、旧结果丢弃和成功后的原子快照发布。
• 模型加载失败时保留旧活动装配，避免已显示模型和持物层消失。
• 单个模型失败不会阻塞其他模型。
• 成功替换后才释放旧装配，并同步切换本地模型上下文。

本地设置与兼容边界

• 在仅客户端、单人存档、未安装本模组的服务端和普通服务端场景中恢复本地 MoLang/漫游变量设置。
• 保留 Legacy 旧协议、模型同步、上传和格式工具作为 1.2.x 兼容实现。
• 继续完善 Fabric/NeoForge 物理目录边界和跨版本适配契约。

修复

• 修复头发、尾巴物理变量中的 NaN/Infinity 污染后续帧；异常浮点值现在安全转换为 0。
• Resource Station 使用独立有界下载线程池和 AbortPolicy，队列满载时不再回退到 Minecraft 客户端线程执行网络 I/O。
• glTF 缺少旧 YSM 元数据时安全回退，避免模型列表、预览和 PlayerCapability 中的 NullPointerException。
• ZIP 文件名 UTF-8 解码失败时回退 GBK。
• 双面 glTF 薄片使用带深度偏移的渲染层，减少 Z-fighting、闪烁、缺面和镂空。
• 更新 native manifest SHA-256，并在构建前自动刷新原生文件摘要。
• 修复跨平台模型扫描排序、音频待处理轨道去重和 1.21.1 音频缓存取消时的声明释放。

构建与验证

• 六个实际分支均执行发行构建。
• 普通原版/native JAR：包含 native 库，供 GitHub Release 和 Modrinth 使用。
• CurseForge JAR：不包含 native 库，文件名带 -curseforge，供 CurseForge 使用。
• 构建脚本会验证原版 JAR 的 native 内容，以及 CurseForge JAR 的 native 排除情况。
• 本版本的发行构建入口为 build_release_variants.py。
• GitHub、CurseForge、Modrinth 上传脚本已分离，分别执行文件类型校验和平台元数据校验。

已知限制

• 六分支尚未完成同一 glTF 模型在真实 Minecraft 客户端中的完整视觉回归；静态测试和构建通过不等于跨分支视觉验收完成。
• 1.21.1 的 glTF alphaCutoff 已解析和规范化，但尚未传入 shader；26.x MASK 材质使用管线默认 cutoff。
• Cloud HTTP/WSS、认证、下载缓存和新外观协议属于 1.3.0，不属于 1.2.3。
• Legacy 兼容代码仍保留，尚未物理迁移删除。
• 本次 SlashBlade 修复当前落地于 NeoForge 1.21.1；Fabric 的 Refabricated 以及 26.x 分支需要独立适配和验证。
• SlashBlade 修复已完成源码编译验证，但仍需要安装对应模组后进行真实客户端渲染回归。

后续路线

根据 1.2.x 路线图，后续阶段为：

• 1.2.4：Action & Animation Runtime
• 1.2.5：Player Visual Runtime
• 1.2.6：Paper Doll & Preview
• 1.2.7：Import & Resource Pipeline
• 1.2.8：Historical Cleanup（R13）
• 1.2.9：Final Multi-Branch Architecture Audit（R14）
• 1.3.0：Cloud Sync（R15）

感谢所有提交 Issue、测试模型和反馈兼容性问题的用户。

Sparkle Morpher v1.2.3 test1

v1.2.3 — Platform Architecture I/II

This release contains the completed 1.2.3 architecture work across all six supported loader/version branches:

• R12.1 Config Policy completed.
• R12.2 Version Adapter surface and bridge APIs completed.
• R12.3 NeoForge common/loader physical source split completed.
• R12.4 centralized distribution providers completed.
• Full native Gradle build and test suites passed on all six branches.

Test matrix

• fa1.21.1: Fabric 1.21.1
• fa26.1.x: Fabric 26.1.x
• fa26.2: Fabric 26.2
• neo1.21.1: NeoForge 1.21.1
• neo26.1.x: NeoForge 26.1.x
• neo26.2: NeoForge 26.2

Install only the JAR matching your Minecraft version and loader.

Sparkle Morpher 1.2.2

Sparkle Morpher 1.2.2

Cross-Backend Performance & Stabilization / Core Modernization Series

Release date: 2026-08-23
Supported branches: Fabric 1.21.1, Fabric 26.1.2, Fabric 26.2, NeoForge 1.21.1, NeoForge 26.1.2, NeoForge 26.2

English | 中文

Sparkle Morpher 1.2.2 delivers the main work planned for the 1.2.x “Cross-Backend Performance & Stabilization” phase. All six actual source repositories were synchronized, built, verified, and pushed to their matching GitHub branches.

Highlights

• Modern HUD modernization and stabilization:

  • 26.x uses explicit VAO, SSBO, BoneSkinShader, and a 144-byte-per-bone layout for the unified skeleton path.
  • Restored the separate translucent blend stage and alpha handling for transparent materials.
  • Fixed layout anchors, AABB/FBO framing, glow-bone exclusion, pose snapshots, scale, and yaw handling.
  • Fixed classic HUD input_vertical direction contamination and lost context during deferred world-model submit replay.
  • Every Modern HUD rendering, layout, and title option is marked “Experimental”. Modern HUD remains disabled by default while Classic HUD remains enabled by default.

• Minecraft 26.1.2/26.2 held-item crash fix:

  • 26.x Modern HUD now uses Mojang’s GUI item RenderState extraction API for main-hand and off-hand items.
  • Removed the erroneous manual ItemEntityRenderState creation path, which submitted an item through the GUI deferred/Picture-in-Picture pipeline to an EntityRenderDispatcher with no assigned renderer.
  • Main hand, off hand, Scale, Yaw, and HUD Layout behavior are preserved; 1.21.1 keeps its version-specific legacy API.

• Cross-backend rendering and performance:

  • Roulette stage 1 now uses cached geometry through GuiGraphicsExtractor.fill, avoiding raw GL/CommandEncoder submissions during extraction that were later overwritten; a CPU fallback keeps visibility consistent across OpenGL and Vulkan.
  • The 26.2 Vulkan path detects the actual Minecraft GpuDevice, uses the 144-byte-per-bone Vulkan ABI and Native SIMD bone calculation, and falls back to Java when the native path is not applicable.
  • The implementation keeps business logic behind the backend-neutral Blaze3D/vanilla boundary instead of coupling it to raw OpenGL/Vulkan.

• Compatibility and reliability:

  • Fixed TouhouLittleMaid sitting-state access and custom-model state synchronization across all six loader/version branches.
  • Fixed the 1.21.1 item-buffer/glint immediate path (Issue #18) and the Fabric 26.x flight animation frame-boundary stutter.
  • Added or tightened architecture-boundary, RenderState contract, material contract, and six-branch build checks while retaining the required 1.21.1 and 26.x adapters.

Build and verification

• All six branches were pushed with git push; each local HEAD was then compared with its matching remote branch after fetch.
• A clean release build completed on 2026-08-23 and produced a 1.2.2 original JAR for every branch. The six original JARs in this release are the primary downloads.
• Full build output is included as BUILD_LOG_1.2.2_2026-08-23.txt; branch logs were collected under .buildlogs/6branches/.
• This release does not claim real Minecraft 26.2 Vulkan client visual regression coverage; that still requires an actual Vulkan client environment. Fabric 26.2 also retains pre-existing ArchitectureBoundaryTest violations, which are not presented as fixed by this release.

Release assets

• Six original Fabric/NeoForge JARs.
• Chinese notes, English notes, and the build log.

The 1.2.2 scope freeze remains in effect: the large Action Runtime, Paper Doll, Import Pipeline, Cloud, and PortableGpuRenderPath rewrites are out of scope for this release.

Sparkle Morpher 1.2.1

English | 简体中文

Sparkle Morpher 1.2.1

Sparkle Morpher 1.2.1 fixes a singleplayer crash on the Fabric 26.x line, aligns the 26.2 branch with the real 26.2 APIs, and brings the rendering/network/Maid refactor series R0–R11 (recorded between 2026-08-10 and 2026-08-13, including everything from the 08-12 prerelease 1.2.0-beta-R11MAID) into a formal release across Fabric and NeoForge × 1.21.1 / 26.1.2 / 26.2.

---

Highlights

Crash fixes (focus of this release)

• Fixed IncompatibleClassChangeError on joining singleplayer (Fabric 26.1.2 / 26.2): removed the compile-time shadow stubs where Minecraft.execute/submit/isLocalServer were wrongly declared static, which made Minecraft.getInstance().execute(...) compile to invokestatic and crash at runtime against the real instance methods. Everything is now compiled back to invokevirtual (verified by a full ASM scan: 0 remaining).
• Fa26.2 stub cleanup & alignment with real 26.2 APIs: removed 24 vestigial/shadowing stubs, keeping only 4 runtime compat layers (MultiBufferSource / IrisApi / ModConfig / IForgeGuiGraphicsExtractor); 6 call sites (getScoreboard / renderNames / renderBuffers / getMainRenderTarget / screen etc.) moved to the real 26.2 APIs.
• Sync packet queue overflow → bounded backpressure: bursts no longer abort the whole sync when the queue briefly fills; the enqueue side now waits with a bounded budget (server bandwidth limiting + outbound drain form a backpressure loop).

Rendering & performance

• Classic HUD deep performance rewrite: FBO partial physical-pixel offscreen cache (was ~35 ms full CPU render per frame → ~0.17 ms); GPU path with a 60 Hz independent refresh budget, SIMD/compat path at 10 Hz throttle; 8-slot bone SSBO ring + GL_STREAM_DRAW streaming uploads, eliminating shared-buffer sync stalls; explicit alpha compositing and batching isolation.
• First-person hand rendering fix (26.x): the hand always uses the entityTranslucent pass.
• Preview rotation pollution fix (1.21.1): entity yaw and preview mode are reset even on exception paths (try/finally).
• Hand rendering NPE guard: getAnimationBundle()==null mid-state protection (12 sites across 6 branches).
• R10-series internal refactors: RenderBackend interface isolation (Blaze3D / OpenGL / SIMD / Java implementations), GpuMeshRegistry leases + orphan sweeps, unified resource ownership for model assemblies (deterministic release), weighted-LRU audio cache.

Networking & model sync

• Fixed crash when clients without SPM join: per-player channel pre-checks before sending (NeoForge/Fabric) + batch send fallback.
• Systemic fix for sync timeouts / stuck "receiving model data": LegacySyncFlowControl 64 KiB burst backpressure + 512 MiB in-flight budget; a dedicated single-threaded sync executor with a bounded ordered packet queue (decrypt/verify/disk-write no longer blocks network/main threads); termination frame sent when the server cache is unavailable so the client never hangs forever; the watchdog no longer reports false success.
• neo1.21.1 stuck-at-LOADING fix: toClientboundPacket null packet → wrapped in ClientboundCustomPayloadPacket.
• R9 networking modularization (internal): send-entry pre-checks, connection-state split, upload-transport interfaces.

Maid (TLM) compatibility (R11)

• MaidModelSync divergence converged across branches (byte-identical in all six).
• C2SSetMaidModelPacket (id 24) ported to all branches: maid model switching now uses SPM's own chain (auth pipeline); the official TLM protocol remains as fallback.
• TLM-environment startup crash fixed (@Mixin(targets=...) to avoid MixinTargetAlreadyLoaded).
• 26.x GUI maid preview not replacing YSM models — fixed.
• R11 compat.api service layer (internal, no startup-order dependencies).

GUI / HUD

• Classic / Modern HUD dual toggles: independent switches in settings; the legacy keybinding and old screen were removed.
• ClassicHudLayoutScreen layout editor: drag, unbounded scaling, scroll zoom, yaw rotation, one-click reset.
• ModernHudRenderer independent entry contract (off by default, internal).

Other fixes

• Abnormal head rotation while riding (RiderRotationMath pure-angle helper, verified on 6 branches).
• 1.21.1 default model rotation not following the camera (cross-frame cache registry retained).
• Server model pack name JSON-quote display fix.

Internal refactors (R0–R9, core of 1.2.1)

• S0 security hotfixes: YSM folder path-escape sandbox, atomic audio-cache dedup.
• R2 unified thread pools (SmExecutors bounded queues + CallerRuns backpressure + TaskScope).
• R3 ModelStoragePaths centralization + PersistentStore atomic writes.
• R4 unified resource container (folder / zip GBK / limits) + zip-bomb protection.
• R5 Model Domain / R6 EntityModelResolver (priority + revision race protection).
• R7 ClientModelManager split (3024 lines → 5 focused classes).
• R8 ServerModelManager split (1899 lines → 8 focused classes, atomic file moves + upload policy).
• Tests grown from 45 → 201 per branch (YsmCrypt golden vectors, model corpus, race acceptance).

---

Files (vanilla full builds)

File	Platform
sparkle-morpher-1.2.1-fa1.21.1.jar	Fabric 1.21.1
sparkle-morpher-1.2.1-fa26.1.x.jar	Fabric 26.1.2
sparkle-morpher-1.2.1-fa26.2.jar	Fabric 26.2
sparkle-morpher-1.2.1-neo1.21.1.jar	NeoForge 1.21.1
sparkle-morpher-1.2.1-neo26.1.x.jar	NeoForge 26.1.2
sparkle-morpher-1.2.1-neo26.2.jar	NeoForge 26.2

CurseForge builds (no natives) live in the Curseforge directory and are not attached to this release.

Sparkle Morpher 1.2.0-beta (R10.2–R11 + Maid 重构)

BETA 测试版 — 请玩家协助实测

本版本为 1.2.0 之后的重构中间产物，非正式发布。内容：R10.2 GPU mesh 租约 / R10.3 Audio weighted LRU / R10.4 模型装配统一资源 ownership / R11 兼容层服务接口 / MaidModelSync 分支收敛 / C2SSetMaidModelPacket 移植。

本轮改动范围

• GPU mesh 生命周期显式化（租约注册表 + GC 兜底回收）
• 音频缓存驱逐改 weighted LRU（优先释放大条目）
• 模型装配资源释放收拢到装配自身（close/releaseGpuOnly/releaseRuntime）
• 兼容层 compat.api（MaidModelService/MaidNetworkService 服务接口）
• MaidModelSync 全分支统一（含女仆 setModelId 清模型新行为）
• 女仆换模走 SPM 自有链路（server 端 auth 校验），官方女仆协议保留回退
• 26.x 第一人称手部修复（恒用 entityTranslucent）

请重点反馈

• 26.x 第一人称手部
• 模型切换/删除/换服后的资源回收（内存/显存）
• GPU 渲染 + 着色器 + 回退
• 女仆换模（SPM 链路 + auth）
• 音频播放/缓存淘汰

已知说明

• 仅编译 + 单元测试通过，尚未完整游戏内回归，可能出现渲染/资源问题
• 微软拼音全角输入法无法按键为原版 MC 已知问题，与本 mod 无关

Sparkle Morpher 1.2.0

English | 简体中文

SparkleMorpher 1.2.0

SparkleMorpher 1.2.0 expands Bedrock and Blockbench model compatibility, improves model loading and cache recovery, and delivers a set of rendering, animation, and gameplay hotfixes across Fabric and NeoForge (based on fixes recorded between 2026-08-06 and 2026-08-09).

---

Highlights

Model and format compatibility

• Direct Bedrock resource loading: import bare .geo.json / *geometry.json files and Bedrock resource packs (zip detection), with geometry selection by identifier (case-insensitive), multiple geometries, and optional attachments such as capes. Common Bedrock animation variables, the -this expression, and action-name mapping are supported.
• Blockbench per-cube rotation: support element.rotation from minecraft:geometry 1.12.0+ exports (cubes rotating around their own pivot), unified across both mesh and cube conversion paths.
• Bedrock-style limb naming: bone semantics for armLeft/armRight/legLeft/legRight, and case-insensitive armor-part matching.
• bbmodel animation mirror fix: convert Blockbench XYZ Euler angles to equivalent rotations in the renderer's order, eliminating mirrored or incorrectly played multi-axis animations; add action fallbacks for six high-frequency states (death, sleep, swim, climb, climbing, attacked).
• Client render compatibility API: expose model and texture lifecycle events to optional renderers (Caustica, Iris, etc.) through a common interface; official compatibility submodules ship as nested JARs, so a single main mod jar is enough.

Reliability and performance

• Model cache self-healing: server cache uses atomic writes, validation before sending, and instant rebuild from the source model; the client validates decrypted/decompressed content and rejects damaged data, reducing manual dual-end cache clearing.
• Cache identity no longer includes the mod jar hash: rebuilding or replacing the jar at the same version no longer forces a full re-download (only version changes invalidate the cache).
• Model-folder robustness: unrelated files (notes, images, videos, etc.) are safely ignored, fixing stutters/OOM from large files being fully read into memory; startup cache validation moved off the critical loading path (async).
• Roulette performance: corrected backend detection plus fallback scanline geometry caching on 26.x OpenGL; Vulkan mode now uses triangle-strip meshes, eliminating single-digit FPS from per-pixel CPU rendering.
• Fix concurrent model parsing races that produced ProcessorPipeline null-processor exceptions and repeated log spam (deduplicated and rate-limited per model).
• Sanitize NaN/Inf produced by YSM molang (fixes flying/flickering hair and tails); clean up 26.2 test log noise.
• Fix GUI preview crashes caused by parallel-controller blending between keyframes and transition points, and crashes from GUI preview entities without an assigned entity ID.
• Fix the 1.21.1 NPE crash when opening the model selection screen (animation bundle accessed before the model is ready), and fix built-in default models failing to load under some launchers (union resource scheme support).

Interaction and animation fixes

• /ysm model disable can now be used by regular players on themselves to restore the vanilla appearance; reload and set remain OP level 2 operations.
• Fix roulette selection so the selected animation key is the one that plays (1.21.1 misaligned roulette actions + legacy model extra-animation parsing), and fix the center-icon artifact after leaving the 26.2 roulette settings screen with ESC.
• Fix the inability to switch YSM maid models in survival mode (Issue #11, compatible with the TLM 26.x maid ownership API change).
• Improve Touhou Little Maid and large-modpack compatibility: fix the root cause of MixinTargetAlreadyLoaded startup crashes (the Mixin configuration phase no longer defines entity classes early via Class.forName), and fix the 26.2 maid issues where ESC could not exit the YSM model selection screen and maids did not render the selected YSM model (adapted to the 26.2 screen API migration).
• Fix vanilla 26.x spear/trident animation namespace conflicts; fix the looping lance animation (lance actions now use hold_on_last_frame).
• Empty-hand left click: removed mod-specific empty-hand logic (models can trigger their own attack animations via ctrl.swing('mainhand', 'empty')), keeping item-attack left-click and cross-tick spear input deduplication.
• Fix residual previous-state animations caused by empty-string placeholders in state animation arrays (no more walking/swinging while standing still).
• In 26.2, custom projectile models registered as minecraft:arrow now also apply to arrow subclasses when no more specific projectile model is supplied.

Sparkle Morpher 1.1.5

English | 中文版

Sparkle Morpher 1.1.5

Sparkle Morpher 1.1.5 is a hotfix release that resolves a critical NoClassDefFoundError in Fabric 1.21.1 caused by a package path mismatch for the Touhou Little Maid client compatibility implementation.

---

🐛 Touhou Little Maid Compatibility Hotfix (Fabric 1.21.1)

• Fixed NoClassDefFoundError on Fabric 1.21.1: Under the Fabric 1.21.1 multi-module setup (Architectury), the common client.compat expected com.micaftic.morpher.client.compat.touhoulittlemaid.fabric.TouhouLittleMaidClientCompatImpl. The implementation was incorrectly located under core.compat.touhoulittlemaid.fabric, causing @ExpectPlatform lookup to fail at runtime.
• Package Relocation & Visibility Adjustments:
  • Relocated TouhouLittleMaidClientCompatImpl.java to client.compat.touhoulittlemaid.fabric and updated imports.
  • Made TouhouLittleMaidAccess.java and its static methods public so it can be safely accessed across packages.
• Comprehensive Audit:
  • Fabric 1.21.1: Audited 40+ @ExpectPlatform bindings; TouhouLittleMaidClientCompatImpl was the only misplaced class and is now fixed.
  • Fabric 26.x & NeoForge (All Versions): Use single-module compile units and direct FQN calls without @ExpectPlatform, unaffected by this issue.

---

📦 Included Release Artifacts

• sparkle-morpher-1.1.5-fa1.21.1.jar (Fabric 1.21.1 / Java 21)
• sparkle-morpher-1.1.5-fa26.1.x.jar (Fabric 26.1.x / Java 25)
• sparkle-morpher-1.1.5-fa26.2.jar (Fabric 26.2 / Java 25)
• sparkle-morpher-1.1.5-neo1.21.1.jar (NeoForge 1.21.1 / Java 21)
• sparkle-morpher-1.1.5-neo26.1.x.jar (NeoForge 26.1.x / Java 25)
• sparkle-morpher-1.1.5-neo26.2.jar (NeoForge 26.2 / Java 25)