PackSquash: a compressor for Minecraft resource and data packs

What PackSquash does and the size it can save

PackSquash is a Minecraft: Java Edition resource and data pack optimizer which aims to achieve the best possible compression, performance and protection, improving pack distribution, storage and in-game load times.

The improvement is measured in the README, with one concrete anecdote. With the default options, version v0.2.1 was capable of reducing the size of the Witchcraft & Wizardary resource pack ZIP file by Floo Network, version 1.6.2, from 118 MiB to 57 MiB, a 51.69% size reduction. The README adds that it got better over time.

That is a single data point on one pack, and the README is careful to call it anecdotal evidence. Even so, the shape of the saving is informative. Halving a pack is not achievable with a better ZIP compressor alone, because most of the bytes in a resource pack are already-compressed PNG textures and Ogg audio. Halving it requires either reducing the number of colours in images and recompressing them, or transcoding the audio, and both of those are lossy. PackSquash does both, per file type, and that is what the tool is actually about.

The model is straightforward. PackSquash walks through the pack files it recognises in a directory, applies per-file configurable lossy and lossless compression techniques, and builds a ZIP file that can be directly used by the game. The word configurable is load-bearing, because the technique list is long and each one can be turned on or off.

The tool is a Rust application with a workspace layout, packages/ holding the members, a Dockerfile for container use, and the workspace lints set to deny missing documentation and unsafe code.

The per-file-type technique list

The README's overview is the most detailed part of the documentation, and it is organised by file type.

For PNG images the techniques are colour quantization to generate a colour palette, lossless bit depth, compression and colour type reduction, metadata removal, and downsizing of single-colour textures. The README is honest about the trade-off: the quantization, although it is pretty subtle or even unneeded for common texture sizes, can be disabled if lossless quality is desired, and downsizing can also be turned off. Some of the work is done by the well-known imagequant library, used in pngquant, and by oxipng.

For audio the formats covered are Ogg with .ogg and .oga extensions, MP3, M4A, FLAC and WAV, and the techniques are channel mixing, downsampling, transcoding with a state-of-the-art Vorbis encoder, pitch shifting, tag removal, silence truncation, and two-pass optimisation and validation with OptiVorbis. The default settings are meant to be good enough for in-game music, such that most listeners will think the quality is good and not distracting.

One default is deliberately off, and the reason is a good example of the tool's care. Because channel mixing may change how the Minecraft sound engine computes positional effects, referencing MC-146721, PackSquash will not do it by default.

For JSON files the extensions .json, .jsonc, .mcmeta and .mcmetac are minified by removing unneeded whitespace, and with OptiFine mod support enabled also .jem, .jemc, .jpm and .jpmc. Because minification requires parsing first, PackSquash also acts as a strict JSON validator as a side effect. Comments are the only syntax extension accepted and they are discarded by default, although they can be rejected too in files whose extension does not end with a c letter. The README is careful to note that the validation does not catch all possible errors that might confuse Minecraft.

For shader files, .vsh, .fsh and .glsl, there is minification and resolution and expansion of preprocessor directives, with basic validation. The README flags a limitation here and links an issue where some shaders may require tweaking, saying these limitations will be addressed in the future.

For structure files in .nbt format there is recompression with Zopfli, Gzip member concatenation and metadata removal.

For legacy language files, .lang, used in Minecraft 1.12.2 and lower, there is minification removing blank lines and comments, and duplicate keys and non-blank lines that are neither comments nor contain a key-value separator are treated as errors.

Two more types are behind opt-in feature flags. OptiFine properties files in Java .properties format are minified when OptiFine mod support is enabled. BlockBench model files in .bbmodel format are minified when Minecraft Transit Railway 3 support is enabled, and the README notes the minification might also improve privacy, since some keys containing environment-specific metadata are removed.

Zopfli, the iteration knob, and what is off by default

Beyond the per-type techniques, there is a layer applied to everything, and it is the part that makes the tool lossless by default.

The files that are not already compressed by design, namely Ogg and PNG files, are losslessly compressed using the Zopfli algorithm, which the README describes as a state-of-the-art DEFLATE encoder made by Google. It is tuned for very high space savings at the cost of performance whilst being compatible with every DEFLATE decoder. That last clause matters: the output is a normal ZIP, so anything that reads ZIPs can read it.

For even higher savings it is possible to compress already compressed files and increase the number of compression iterations, though this slows the process significantly. The other direction is also available: reduce the number of compression iterations, or skip it altogether, if lower savings are acceptable in exchange for faster execution. That is a single dial for the whole tradeoff, which is the right shape for it.

Then there are three capabilities that are disabled by default because the README says they require informed decisions to be made by the user.

The first is reusing previously generated ZIP files to skip compressing files that did not change between executions, which vastly speeds up incremental workflows where only a few files change each time.

The second is deduplicating identical files within the generated ZIP, so the contents of files repeated several times over are stored only once. That matters for real packs, where the same texture or model appears in many variations.

The third is protecting the generated ZIP files, making them harder to read by most ZIP manipulation programs, and some of the files stored inside them.

That last one deserves a note. The protection feature is described in terms of making files harder to read by most ZIP manipulation programs. That is a different kind of feature from the compression, and it is worth separating the two when you evaluate the tool: the compression work is about bytes, and the protection work is about discouraging casual inspection of the pack contents.

The other optional pieces are integrations. The README points to Nexo, a Minecraft server plugin for creating custom items, blocks and armor, which has a PackSquash integration, and to Git Pack Manager, a server mod for managing the server's resource pack using git.

The Rust implementation and the fork strategy

The Cargo.toml shows a workspace with resolver 3, edition 2024, and a workspace version of 0.4.1 under the AGPL-3.0-or-later licence, with publish set to false because the crates are internal to the application.

The lints are strict in a way that says something about the project's standards. missing_docs is denied, so every public item needs documentation. unsafe_code is denied outright. broken_intra_doc_links, invalid_html_tags and private_intra_doc_links are denied for rustdoc, so the generated API documentation has to be correct as well as present. The clippy configuration allows multiple crate versions with a comment that it introduces too much noise and is not better than cargo deny, and there is a deny.toml at the root for that purpose.

The patch section is the most interesting part, and it shows how the project handles upstream problems.

Three crates are patched to forks maintained by the project itself. The glsl-lang family, which is the GLSL parser, is replaced by a fork that allows it to parse the #moj_import directives, which are specific to Minecraft shader packs. The mmap crate is replaced by a fork to fix its dependency on unmaintained crates and to reduce duplicate dependency versions, with some changes authored by a contributor. And spng is patched to a newer commit that adds a high-level API for customizing the decoder's chunk CRC mismatch action, since spng is the PNG decoder underneath.

The mmap comment is worth pausing on. Fixing a dependency on unmaintained crates by forking it is a maintenance strategy with a cost: the fork has to be kept up to date with upstream by someone. It is also a strategy that only works for a project with a maintainer willing to carry that.

The release profile is tuned for a command line tool: opt-level 3, fat link time optimisation, one codegen unit and symbols stripped.

The Dockerfile is minimal, based on a distroless static Debian 13 image with a digest pin, copying the built binary to /usr/bin/packsquash and setting the entrypoint to packsquash. Pinning by digest rather than by tag is the safer choice for a container base.

Versions, licence and the shape of the project

The release history is sparse for a tool that is still referenced as current. The tags are v0.4.1 from 2026-01-01, v0.4.0 from 2023-06-25 and v0.3.1 from 2022-04-06. The last push to the repository was on 2026-10-19, so development continues even though the last tagged release is close to a year old.

That gap is worth understanding rather than assuming a problem. The workspace version in Cargo.toml is 0.4.1, matching the newest tag, so the main branch is working on what would become the next release. The README's own anecdotes about the tool are labelled with version v0.2.1, and it says it got better over time, which is consistent with a project where improvements land continuously and are tagged less often.

The licence is AGPL-3.0-or-later, which is the strongest copyleft in common use and the one with the most reach. For a command line tool that runs on the user's own machine and produces output files, the practical question is whether the tool is offered as a service or whether its output is distributed. The AGPL's network clause is what makes it unusual among pack tools, and it is worth a legal look if you intend to build a service around it. The README notes that as the licence says, the software is provided without any warranty, with the hope that you find it useful.

The repository layout supports a multi-part project: a common/ directory, packages/ for the workspace members, docs/, scripts/, a .cargo/ directory for cargo configuration, a .devcontainer/ for development containers, a Dockerfile, a rust-toolchain file, rustfmt.toml and clippy.toml.

The project is hosted under the ComunidadAylas organisation, with the site at packsquash.aylas.org, a Discord server, and the README ends by inviting constructive feedback.

Limits: lossy by design, and a fixed set of file types

The limits are visible in the README and follow from what the tool does.

The first is that several of the techniques are lossy and some of them are on by default. Colour quantization reduces the palette of a texture, which the README itself describes as pretty subtle or even unneeded for common texture sizes, and audio is transcoded and downsampled with the stated goal that most listeners will not find it distracting. The default settings are a judgement about imperceptibility, and for a pack where texture fidelity matters, for example a resource pack that is the point of the product, the quantization needs to be turned off. The README tells you it can be, which is the important part.

The second is the file type coverage. PNG, the audio formats, JSON, shaders, .nbt structures, legacy .lang files, and the two opt-in types. Textures in other formats, models in formats other than BlockBench, and data in other serialisations are not handled. A pack that uses them gets no benefit from them.

The third is the shader limitation, which the README flags directly and links to an issue about some shaders requiring tweaking. Minifying and expanding preprocessor directives is where the tool touches code it does not own, and shader packs are the least predictable input because they are hand-written and often clever.

The fourth is the validation limits. The JSON validation is described as strict, but the README says it does not catch all the possible errors that might confuse Minecraft, and the shader validation is described as basic. A pack that passes through PackSquash is not thereby guaranteed to work.

The fifth is that the output is not a source of truth. The pack produced is optimised for distribution, not for editing. Several of the transformations are not round-trip safe, so the workflow is to keep the sources and generate the distributable pack, which is fine for a pipeline but means the tool cannot be run in place on a working directory you also edit by hand.

The sixth is the licence reach of AGPL-3.0, discussed above, and the seventh is the sparse tagging, which means you should record the exact version you used if you distribute a pack built with it.

PackSquash against zipping by hand and against a build-pipeline image optimiser

Two comparisons make the choice clearer.

The first is against compressing the pack yourself with a zip tool. Any archive utility will apply DEFLATE, and the difference is that a zip tool leaves already-compressed PNG and Ogg payloads alone. That is the correct behaviour for a general tool, because recompressing JPEG is pointless. In a Minecraft resource pack, where the bulk of the bytes are PNG textures and Ogg audio, that correct behaviour is exactly where the savings are not. PackSquash's Zopfli pass and its imagequant and oxipng work are what produce a number like 118 MiB to 57 MiB rather than a few percent.

The second comparison is against a build pipeline that runs an image optimiser such as pngquant over your textures and packages the result. That approach gets most of the texture saving, and it has the advantage of being composed from tools you already know. The difference is that PackSquash applies the right treatment per file type in one pass, including the audio work, and it produces a ZIP that is directly usable by the game, with the deduplication and the incremental reuse built in.

What the pipeline approach gives up is the incremental behaviour. Re-running a full optimise over a large pack on every change is slow, and PackSquash's reuse of previously generated ZIP files to skip unchanged files is aimed squarely at that workflow, where a pack author changes a handful of files at a time.

The realistic recommendation is that if you distribute a pack at all, PackSquash is worth the configuration effort, because the file-type awareness is the part you cannot easily reproduce with a single tool. If you only need to shave a zip of a resource pack that is mostly text, a zip utility is enough.

Editorial conclusion

Adopt PackSquash if you distribute Minecraft resource or data packs and care about download size and load time, since the technique-specific configuration is where most of the saving comes from. Do not adopt it for a pack you need to keep editing as text, because several transformations are lossy and not round-trip safe. Verify first that the lossless-only settings are what you want for any texture the pack relies on, that the audio channel mixing option is left off unless you have checked the positional effects issue the README references, and that your licence obligations under AGPL-3.0 are acceptable for how you distribute the result.

Frequently asked questions

Official sources

1. ComunidadAylas/PackSquash on GitHub
2. License: AGPL-3.0
3. Project website
4. README
5. Releases