ModsSynchronization

ModsSynchronization is a mod that helps you communicate with the server and fix errors in your mods.

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.zip on 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

  1. The server validates server_mods.zip: flat .jar entries only, reading each fabric.mod.json for mod id / version and computing SHA-256.
  2. While a player is in the configuration phase, the server sends the manifest.
  3. The client compares it with the local mods/ folder. Match → join. No match → request the archive.
  4. Chunked transfer → hash check → extract → compare again → a bilingual screen lists missing / wrong-version mods.
  5. "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:

  1. Put ModsSynchronization-<version>.jar into the mods/ folder on both the client and the server.
  2. Put server_mods.zip in the server root directory (next to server.properties). It must contain only the .jar files to sync, with no subfolders.
  3. 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): SMART sends the manifest first and transfers only what is needed; ALWAYS sends 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-.jar entry.
  • 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.

ModsSynchronization Team

profile avatar
  • 4
    Projects
  • 182
    Downloads

More from Hseisirs