YSMParser decrypts .ysm models back into editable Blockbench projects

A parser for a file format the mod author deliberately obscured

YSMParser is a parser to recover Yes-Steve-Model encrypted binaries. The project tagline describes it as one-click decryption of .ysm models and conversion to Blockbench projects, with support for all encrypted format versions, and there is an online demo hosted at ysm.rip so you can try it without building anything.

The context matters for understanding what kind of tool this is. Yes Steve Model is a Minecraft model-loading mod. The README explains that after public attacks emerged against the original insecure encryption scheme, the author rewrote both the encryption and the rendering in C++, and wrote the renderer in C++ specifically to prevent exporting models through Java hooks. The original scheme was Java based, so a hook on the JVM could pull the model data out of memory, and moving the renderer into native code closed that path.

YSMParser's stated job is to provide a complete decryption solution for both the C++ rewritten encrypted version and all older encrypted versions. In other words, it is a reverse engineering tool for a file format whose author was trying to make it unreadable.

That framing tells you what the output can and cannot be. Decryption recovers the model's data, but the exported file also carries editorial parameters, and those are the subject of one of the most useful sections in the README, which is the FAQ.

The project is MIT licensed, the default branch is main, and the releases are v0.3.6 on 2026-09-27, v0.3.5 on 2026-05-06 and v0.3.4 on 2026-05-05, with the last push on 2026-09-27.

Every format version is covered, including the ones that changed mid-series

The format support table is where the maintenance burden of this project shows.

Version 1 and version 2 are supported outright. Then the version 3 family is broken into sub-ranges, because the format field inside a version 3 file has itself changed: below 4, 4 to 15, above 15, 26 and above, and 32 and above are each listed as supported. That is six separate format branches to keep working, and it implies the author of the mod changed the format more than once without bumping the major version.

The practical meaning is that a tool written for one of those ranges will fail on files from another, and this parser handles all of them. For a user with a folder of models collected over years, that breadth is the feature.

The feature list has three entries, and the middle one is the substantial one. Beyond supporting all format versions, the tool automatically reconstructs the Blockbench origin, size, pivot, rotation and per-face uv fields when a model stores only vertices, normals and UVs. The third entry lists the project files it restores: models, animations, controller, textures, sounds, lang, avatar and ysm.json.

That list is the difference between a decryptor and a converter. Decrypting the container would give you a file you could not open in Blockbench. Restoring the animations, the controller, the textures, the sounds, the language file and the avatar means the result is a working project rather than a set of coordinates, and it is why the tool describes itself as producing Blockbench projects rather than raw models.

The geometry reverse engineering is the risky part

The FAQ answers two questions, and both are about the reconstruction rather than the decryption.

The first question asks why the restored model parameters, such as dimensions, rotation angles and pivot points, differ from the original unencrypted file. The answer is that the YSM export bakes the model down into raw vertex and face data, losing the original intuitive size parameters. To make the model editable again in Blockbench, YSMParser uses a geometric inference algorithm that guesses the parameters back from the points and faces.

The README is explicit about the consequence: since many different parameter combinations can produce exactly the same appearance, the inferred parameters may differ from the original, but the model renders identically in practice.

That is an honest framing, and it is the right way to think about the output. The renderer sees geometry, so a reconstructed model that looks the same is functionally correct even if the numbers differ. But a modeller who edits the model in Blockbench afterwards is editing parameters that were guessed, and the guess may not survive a change. If you plan to modify the model rather than just view it, keep the original.

The second question asks what to do when the restored model is badly misaligned, or a cube that is twisted and collapsed. The answer names the cause as a misjudgement by the geometric inference algorithm: with extremely complex nested rotations, very close coincident vertices, or non-standard geometry, the algorithm can compute the wrong pivot point or rotation direction for a particular bone, which displaces or collapses the associated parts. The README asks for an issue with the offending .ysm file, and preferably the unencrypted original as well, since that is what helps fix the algorithm.

Two arguments, one optional verbosity flag and a thread count

The tool is a command line program with a deliberately small surface.

The usage line is:

YSMParser -i <input-directory> -o <output-directory> [-v] [-j <thread-count>]

The input directory is required and every .ysm file inside it is processed. The output root directory is also required. Both are directories rather than single files, so the tool is built around batch processing a collection rather than opening one model at a time.

The verbose flag is the one with a side effect worth knowing:

YSMParser -i input -o output

is the normal invocation, and the parameter table records that verbose output mode forces single-threaded execution. So the debugging aid and the parallelism are mutually exclusive, which makes sense for tracing but means you give up speed when you want detail. The threads option takes a parallel thread count and defaults to 0, which is documented as automatically detecting the CPU core count. A version flag prints the version.

The overall workflow in the tutorial is three steps: build or download the executable that matches your operating system, create an input directory and put the .ysm files that need decrypting in it, then run the command line.

Because the tool is directory in and directory out, it fits a pipeline naturally. A directory of models in, a directory of Blockbench projects out, with the per-file failures isolated to their own outputs.

One vendored dependency tree, a WASM target and a C++20 requirement

The build is CMake based and the requirements are CMake 3.12 or later and a C++20 compiler.

The executable build uses presets, with a configure step and a build step:

cmake --preset x64-release

cmake --build --preset x64-release

There is also a WebAssembly target, with separate presets for a Node.js build and a web build:

cmake --preset wasm-release

cmake --preset wasm-web-release

The WebAssembly build needs the EMSDK environment variable to point at the Emscripten installation directory. The existence of that target is what makes the online demo possible, since the same parser can then run in a browser instead of being shipped as an executable.

The dependency list explains the cryptography of the format being handled. All dependencies are vendored as source under a directory named external, and the list is zstd, zlib, cityhash, xchacha20, AES, md5, cpp-base64, fpng, json and CLI11. So the file format mixes compression, hashing, a stream cipher and symmetric encryption, with CityHash and a PRNG in the mix, and the tool carries all of it in-tree rather than depending on system packages.

That vendoring choice is a double-edged one. It makes the build reproducible and free of package manager surprises, which matters for a tool that has to run on a Windows build machine. It also means the tree carries a lot of third-party code, and updating those copies is the maintainer's job.

The repository layout follows the same split, with a directory for the parser source, a directory for the vendored dependencies, a cmake directory, a directory of images, a java directory that presumably holds the Java side of the mod's format, a CMakeLists.txt, a CMakePresets.json and a version.txt. The README also asks contributors, including those using coding assistants, to follow the development conventions in an AGENTS.md, particularly around code structure and commit guidelines.

Maintenance, the online demo and what a reviewer should ask

The release record shows steady work. v0.3.4 and v0.3.5 landed on consecutive days in May 2026, and v0.3.6 on 2026-09-27, the same day as the last push. The repository is not archived.

The MIT licence is the easy part of the assessment, and it is worth being precise about what it covers: the tool that decrypts the format. It says nothing about the rights in the decrypted models, which are the assets of whoever made them, and it says nothing about the mod itself, which is a separate project with its own terms. If your use of the output is commercial, that question is about the model files and not about this repository.

Two practical cautions remain. The first is that a tool whose job is reading a format that an author has repeatedly changed will keep needing updates, and the format support table shows why: the author has changed the format at least five times within version 3, so any given release is likely to lag the newest files. Check the version tag of the binary you use against the files you are decrypting.

The second is the online demo. It is convenient, and it means the tool runs on someone else's server with your model files going across the network. If the models are yours and private, the local build is the better option, and the build instructions are short enough that it is a reasonable default.

Editorial conclusion

YSMParser fits a Minecraft modeller who wants to edit a .ysm model in Blockbench and accepts that the recovered parameters are inferred rather than original, and it does not fit a workflow that needs the exported parameters to be exact, because the exporter bakes them away and the tool rebuilds them geometrically. Before you rely on the output, keep the unencrypted original alongside the recovered project so you can diff the two, and read the FAQ section on misjudged pivots, since complex nested rotations are where the reconstruction breaks. The tool is MIT licensed, release v0.3.6 was published on 2026-09-27, and the last push was on 2026-09-27.

Frequently asked questions

Official sources

1. License: MIT
2. OpenYSM/YSMParser on GitHub
3. Project website
4. README
5. Releases