Sparkle Morpher 1.2.9 — Fin

Release date: 2026-09-20

Supported variants: Fabric 1.21.1, Fabric 26.1.2, Fabric 26.2, NeoForge 1.21.1, NeoForge 26.1.2, and NeoForge 26.2.

English | 中文

Sparkle Morpher 1.2.9 is the combined release for the 1.2.7, 1.2.8, and 1.2.9 work streams. Versions 1.2.7 and 1.2.8 were not published separately; their completed changes are included here together with the final 1.2.9 fixes.

Merged release scope

1.2.7 — Import & Resource Pipeline

• Split ModernPlayerModelScreen into clearer services/controllers while preserving the API differences between 1.21.1 and 26.x.
• Completed the import, download, file-picker, server-model-list, and client-catalog pipeline, with regression contracts across all six branches.
• Included the 1.2.7 issue fixes: maid sitting animation state (isSitting), vanilla equipment locator orientation compensation, and NeoForge 1.21.1 SlashBlade locator priority/fallback handling.
• Passed the six-branch CI gate, including the NeoForge 1.21.1 test-classpath correction and golden-vector checks.

1.2.8 — Historical Cleanup (R13)

• Completed the R13-B migration and removed obsolete YSMClientMapper, ResourceDownloadManager, ModelImportFilePicker, and AnimationRegister facades.
• Moved download, file-picker, model-mapping, and animation-registration ownership to the current queue/coordinator/manager implementations.
• Preserved the loader/version-specific boundaries while removing stale production imports and calls.

1.2.9 — Final Multi-Branch Audit (R14)

• Re-audited architecture, rendering, protocol registration, entity tracking, and six-branch release behavior.
• Corrected the protocol audit to reflect the actual registration split: channel 24 is registered through CompatProtocol on Fabric 26.x and LegacyModelProtocol on the other applicable branches.
• Restored the NeoForge 26.2 extra-player render gate and completed the final release verification.

Highlights

Unified fake-player and maid action workflow

• Press G to open a target selector containing server-provided manageable fake players and recognized maids loaded within 96 blocks.
• Selecting a target opens the existing UnifiedRouletteScreen; actions are routed to the selected entity instead of silently falling back to the local player.
• Z keeps the local-player action wheel, Shift+Y opens the fake-player manager, and Alt+Y opens the player model panel.
• The fake-player manager supports search, online/model/dimension/provider filters, sorting, and virtual scrolling for large lists.
• Search covers name, display name, UUID suffix, model name, and provider name. The workflow does not depend on crosshair targeting.
• Fake-player detection is provider-aware and keeps ordinary players and maids out of the fake-player list.
• Server-side permission, target validation, model validation, and entity tracking checks remain authoritative.

Appearance persistence and synchronization

• Fake-player appearance is restored after the server model catalog finishes loading and is re-sent to the player and tracking clients.
• Dimension changes and player lifecycle changes now trigger the required appearance resynchronization without leaking UUID state.
• Maid YSM appearance is no longer cleared during NBT restoration; persisted appearance is sent again after the maid entity loads and when clients begin tracking it.
• Vehicle model state is synchronized to reconnecting riders, newly tracking clients, and the current rider as well as other tracking clients.
• Added server/local model filters and included the complete server model catalog in the client model directory, so server-available models remain visible even while lazy loading is in progress.

Rendering and compatibility fixes

• First-person arm models now evaluate their visibility animations, preventing unselected outfit or arm variants from rendering on top of one another.
• Fabric 26.2 Touhou Little Maid rendering now uses the 26.2 submit/collector path instead of the removed legacy buffer API.
• Removed the duplicate transparent-background extraction that caused ModernUI on 26.x to throw Can only blur once per frame.
• On 1.21.1, the custom blur stack detects ModernUI's active blur without a compile-time dependency and skips the second screen capture, while preserving the original path when ModernUI is absent or disabled.
• Restored the NeoForge 26.2 extra-player render gate so its behavior matches the other 26.x branches.

Architecture cleanup

• Completed the R13-B migration by removing obsolete download, picker, model-mapper, and animation-registration facades.
• Consolidated download queue, file-picker, and animation registration ownership around their current implementations.
• Rechecked protocol registration across all six branches; maid model channel 24 is registered in the appropriate protocol group on every loader/version variant.
• Added regression contracts for target classification, appearance persistence, model filtering, vehicle synchronization, and ModernUI compatibility.

Compatibility and usage

Use the artifact matching both your Minecraft version and loader. Do not mix 1.21.1 artifacts with 26.x installations.

The default target-action key is G and can be rebound in Minecraft controls. Fake-player lists are server-authoritative; a target must also be loaded by the client before its action wheel can open. Maid selection is limited to recognized maids currently loaded within 96 blocks.

Carpet fake players are handled through the ServerPlayer/UUID/entity-tracking boundary rather than a hard dependency on Carpet internals. The server must provide the model resource for observers; a client-only custom model is not automatically a shared server model.

Known limitations

• The release does not replace a maid mod's native GUI with a standalone maid editor. The unified action selector is provided; a full independent maid appearance editor remains future work.
• SPM Cloud appearance broadcasting remains an optional hook; server-side Minecraft synchronization is the active path in this release.
• The 1.21.1 common source set retains documented historical loader-boundary exceptions.
• Full in-game OpenGL/Vulkan, Paper Doll, resource-reload, and real Carpet-server smoke coverage remains outside this release's automated build matrix.

Build and verification

• All six actual repositories passed clean release builds.
• Twelve artifacts were produced: six full/native jars and six CurseForge-safe jars.
• CurseForge jars were checked for native libraries and contain no natives/, DLL, SO, DYLIB, or EXE entries.
• Regression tests and branch-specific compile/test gates passed during the 1.2.9 work.

Artifacts

Issue reference: ModernUI compatibility issue #34.