Fox Model Loader: Revival

Fox Model Loader: Revival follows the Sparkle Morpher 1.2.9 lineage. Its Mod ID and resource namespace are foxmodelloader. It retains the traditional Minecraft server synchronization architecture; multiplayer model sharing requires the mod on both server and clients. Individual model IDs and the .ysm format are preserved.

Official Chinese name: 绯绯狐的模型加载器：复兴.

English | 中文 | 日本語 | 한국어

QQ: 1104823534 | Discord: Join Discord | Patreon: cw/Soid211 | Afdian: Micaftic

A comprehensive Minecraft custom model loader that lets players mount custom models, animations, and sound effects onto players (and select entities, vehicles, and projectiles) — say goodbye to the default blocky character.

Fox Model Loader: Revival is a universal model loader. It currently supports the .ysm format (based on OpenYSM, MIT licensed) and .bbmodel format (Blockbench), with support for additional mainstream model formats planned for future releases.

The project follows a quarterly LTS-style release cycle: one planned feature release each quarter. Between quarterly releases, maintenance releases may address critical bugs, compatibility problems, or security issues.

This cadence is deliberate. Stability, compatibility, and predictable server deployments take priority over frequent feature releases.

See Releases for published versions, release notes, and changelogs.

Fox Model Loader originally evolved into Sparkle Morpher. The development paths diverged after Sparkle Morpher 1.2.9. Beginning with 2.0, Fox Model Loader resumed maintenance under the Revival identity, continuing the traditional Minecraft server synchronization architecture.

Replace vanilla player models with fully custom 3D models. All custom models are visible to other players in multiplayer

• .ysm — The native format powered by OpenYSM/YSMParser, supporting full skeletal models with weighted animations.
• .bbmodel — Direct import of Blockbench project files. Includes mesh triangulation (N-gon fan triangulation), UV normalization, face rotation, inflate expansion, embedded base64 texture extraction, and PNG IHDR header parsing.
• Figura Avatar Archives — Import Figura .zip packages directly. The built-in ZipModelSniffer automatically detects and routes YSM folders, Figura avatars, and plain BBModel zips.

• Animation Carousel (default key: Z) — A radial menu to quickly switch between animations and actions for the current model.
• Animation Controllers — Full support for state-machine-based animation controllers with loop, once, and hold playback modes.
• Molang Expressions — Data points support both raw numeric values and Molang expression strings for dynamic animation blending.

Play model-bundled voice lines and sound effects triggered by skills or actions. Audio decoding uses Opus with the bundled Java Concentus decoder.

• Import models from local files, directories, or URLs with accelerated downloading.
• Organize models with grouping and favorites.
• Automatic directory scanning recognizes .ysm, .zip, and .bbmodel files.

• Server operators can define model manifests and push models to clients.
• A configurable blacklist (config/foxmodelloader/blacklist.txt) lets servers restrict specific models.
• Client-server model state synchronization via Cardinal Components entity data.

Server operators can configure the global model-transfer limiter in config/foxmodelloader-server.toml:

[server_scheduler]
EnableGlobalBandwidthLimit = false
BandwidthLimit = 5

BandwidthLimit is in Mbps. When EnableGlobalBandwidthLimit is enabled, the limit is shared globally by server-to-client model sync packets and client-to-server model upload chunks. Small control packets, including favorite sync, are not throttled.

Compatibility depends on the Minecraft version, loader and installed mod release. Current adapter status:

See compatibility scope and verification for loader differences, the Mod ID migration and testing limits. Installing two mods together and supporting their special animations or item slots are separate compatibility claims.

Current release targets cover Fabric and NeoForge on Minecraft 1.21.1, 26.1.2, 26.2 and 26.3. The supported versions and downloadable builds are listed in Releases.

When you import a model file, Fox Model Loader: Revival runs it through an intelligent pipeline:

1. Zip Sniffing — Archives are classified by content: YSM folder, Figura avatar (contains avatar.json + .bbmodel), plain BBModel zip, or unknown.
2. Parsing — .ysm files go through YSMParser; .bbmodel files are parsed by the built-in BBModelParser which handles outliner trees, cube/mesh elements, textures, animations, and controller states.
3. Conversion — Parsed data is converted to the engine's internal RawGeometry format. Mesh faces with N vertices are triangulated via fan triangulation; UV coordinates are normalized against texture resolution; external PNG textures in zip archives override embedded base64 sources.
4. Rendering — The converted model replaces the vanilla player renderer when active, with automatic hiding of the default player model.

Full support for Blockbench's format including:

• Outliner tree with nested bone hierarchy and parent-child relationships
• Cube and mesh elements with proper face UV mapping
• Embedded textures (base64) with PNG header dimension detection
• Animation playback with loop mode mapping
• Blockbench 5 "free" format compatibility (thin outliner nodes with groups[] fallback)
• Orphan element handling (unreferenced elements auto-assigned to default bone)

Fox Model Loader: Revival uses a common + platform adapter layered architecture:

• common — Core logic shared across all variants: model parsing, mesh processing, zip sniffing, animation controllers, audio decoding, and Molang evaluation.
• fabric / neoforge — Platform-specific adapters for initialization, networking, component registration, and rendering hooks.
• Native renderer — SIMD acceleration rebuilt from this repository; see native source and build provenance.

Varies by build variant — see mods.toml (NeoForge) or fabric.mod.json (Fabric) for specifics. Fabric variants require Fabric API installed separately; other dependencies are bundled via Jar-in-Jar.

• Built upon OpenYSM (MIT License).
• Uses OpenYSMDev/YSMParser (MIT) for .ysm model parsing.
• Default model library: sdf123098/YSM-Model.
• Blockbench format is a product of JannisX11/Blockbench.

License: MIT

Java 21 is required for 1.21.1; Java 25 for 26.x. Run ./gradlew build for the standard distribution, or ./gradlew build -Pdist=curseforge for the Java fallback distribution. The standard distribution bundles the rebuilt SIMD renderer; the CurseForge distribution excludes project native libraries. To rebuild all six native platforms, run python scripts/rebuild-natives.py --zig <zig.exe> --ndk <Android NDK root>. See native source and build provenance.

From this repository, upload the workspace's eight standard Release/ JARs with Python 3.11+ and an authenticated GitHub CLI:

python scripts/upload-release.py --dry-run
python scripts/upload-release.py

The script validates the build index, mod identity, icon, native binaries and SHA-256 values before uploading. It creates v<version> as a draft, uploads the eight JARs, verifies their remote digests, and publishes only after all checks pass. Reruns skip identical assets and resume incomplete drafts; conflicting assets are never overwritten. --dry-run validates local files without contacting GitHub. Use --draft to keep the release unpublished, --workspace <folder> for another build workspace, or --tag, --target, --repo and --notes-file to select a different release.

The default release notes are docs/releases/v2.1/RELEASE_NOTES.md. Edit the notes before publishing; checksum tables must match the current JARs. Upload records go to D:/SparkleMorpher/docs/YYYY-MM-DD/fox-release-upload-*/result.json; override their base directory with --record-dir. The uploader requires the workspace's artifacts.json and icon.png, alongside Release/.