ModsSynchronization
EN: One Fabric mod is all it takes. The server delivers the whole modpack to your local mods/ folder before you enter the world.
Platform: Minecraft Java 26.1 · Fabric Loader ≥ 0.19.3 · Fabric API 0.145.1+26.1 · Java 25 License: https://license.hseisirs.top/
What it is
ModsSynchronization turns "install a pile of mods before joining" into "join and get them automatically".
The server reads server_mods.zip from its root directory and sends a mod manifest to the client while the player is connected but still in the configuration phase — before entering the world. The client compares it against the local mods/ folder, fills in what is missing, corrects what is outdated, and asks you to confirm a restart.
Mods you installed yourself — cosmetics, shaders, performance tweaks — are never inspected, never listed, never touched. Synchronization only completes and corrects. It never cleans.
Why use it
- One jar, both sides — client and server use the same file, so server admins cannot install the wrong one.
- No extra ports — custom payloads ride the game connection during the configuration phase. No public HTTP endpoint, no port forwarding.
- Before you enter the world — comparison, download and repair all happen before play starts.
- Zero bytes when everything matches — the manifest goes first; if mod id + SHA-256 all match, nothing else is transferred.
- Hot-swappable pack — replace
server_mods.zipon a running server, no restart. A pack overwritten mid-transfer is detected and safely retried instead of handed to the player corrupt. - No game-thread stalls — local jar hashes are cached in
mods/.mods-synchronization/index.json(keyed by size + mtime); only changed jars are re-hashed, in parallel. Even a full modpack joins in milliseconds and will not time out. - Bilingual, light & dark — the in-game screen follows your language and has a one-click theme switch.
How it works
- The server validates
server_mods.zip: flat.jarentries only, reading eachfabric.mod.jsonfor mod id / version and computing SHA-256. - While a player is in the configuration phase, the server sends the manifest.
- The client compares it with the local
mods/folder. Match → join. No match → request the archive. - Chunked transfer → hash check → extract → compare again → a bilingual screen lists missing / wrong-version mods.
- "Fix mod errors" → back up → write / replace in place → re-verify → close the game automatically (mods cannot be hot reloaded).
Installation
Client and server use the same jar:
- Put
ModsSynchronization-<version>.jarinto themods/folder on both the client and the server. - Put
server_mods.zipin the server root directory (next toserver.properties). It must contain only the.jarfiles to sync, with no subfolders. - Start the server, start the client, join.
Requires Java 25. Fabric Loader and Fabric API must be installed on both sides.
Configuration
Server config/mods-synchronization-server.json:
syncMode(SMART):SMARTsends the manifest first and transfers only what is needed;ALWAYSsends the full zip on every join.zipName(server_mods.zip): relative to the server root.enabled(true): when false, the mod does not touch connections at all.strictJarOnly(true): logs an ERROR if the archive contains a non-.jarentry.allowClientsWithoutMod(true): lets players without this mod join.serverName(empty): name shown to players; empty uses the address they entered.maxZipSizeMb(1024): archives larger than this are not sent.chunkSizeKb(256): chunk size, 16–512.handshakeTimeoutSeconds(60): how long to wait for the client to respond.
Client config/mods-synchronization-client.json: theme is DARK or LIGHT, also switchable in game.
Security
Jars sent by the server are loaded and executed by the client — only connect to servers you trust, just as you would trust any mod download source.
Every replaced local jar is first moved to mods/.mods-synchronization/backup/<timestamp>/ and recorded in mods/.mods-synchronization/last-sync.log. If the sync pack is missing or damaged, the default is to let players in and log a warning rather than lock them out.
FAQ
Q: Will it delete my own mods? A: No. Mods present locally but absent from the server manifest are ignored. Cosmetic, shader and performance mods are never inspected, listed or touched.
Q: Why do I have to restart after a fix? A: Fabric cannot hot-reload new jars at runtime. A restart is the only way to guarantee correct load order and dependencies.
Q: Do I need to restart the server after updating the pack?
A: No (since 1.3.2). Just replace server_mods.zip; the server detects the change and rebuilds the manifest in the background.
Q: Which Minecraft version is supported? A: Minecraft Java 26.1 / Fabric Loader ≥ 0.19.3 / Fabric API 0.145.1+26.1 / Java 25.