Server-required vs client-only mods

Status: Implemented for side (where a mod loads; dedicated servers skip client mods). The multiplayer handshake that enforces sync is Planned: today sync documents your intent (and the website shows it), but connections don’t compare mod lists yet.

Before you publish, decide who has to install your mod. That decision is the manifest’s side and sync, and it determines where your mod can be used.

The four kinds

Kind	side	sync	Who installs it	Works on
Client-only	client	client_only	Players	Any server: Celestial, vanilla, Paper, proxies, and older versions through the compat layer
Server-only	server	server_only	Server operators	Every client that can join, including vanilla 26.3 clients
Required on both	both	required	Both	Servers and clients with the mod
Optional on both	both	optional	The server; players optionally	Everyone; players with the mod get extra features

Singleplayer runs both sides in one process, so all four kinds work there. Choose the kind for the multiplayer experience you want. The website shows the choice on every version (“Client only”, “Server only”, “Required on both sides”, “Optional on the other side”).

Client-only mods

HUD info, zoom, chat tweaks, visual options, keybind helpers: the kind of features in Celestial’s own Client Settings.

• Use only client APIs and what the server already sends. The server doesn’t know your mod exists.
• Don’t register blocks or items: the server wouldn’t know them.
• Expect any server version. Through the compat layer you always see 26.3 packets, but features of newer versions may never arrive (Multi-version servers (the compat layer)).
• Visual changes must be off by default; the player opts in.
• Respect server rules: many servers ban automation and information that should stay hidden.

Server-only mods

Commands, chat formatting, shops, kits, minigames, protection, and data-driven content (Server plugins).

• Everything clients see must be expressible with vanilla packets: vanilla blocks and items (mod content shows as its base), vanilla menus, text, titles, sounds.
• Data-pack content (enchantments, damage types, recipes with vanilla items, loot) works as-is for every client.
• Mod textures and sounds reach vanilla clients only through a resource pack they install.
• Client-side prediction stays vanilla: a mod block’s friction or speed_factor is predicted only by Celestial clients with the mod, so vanilla clients get corrected now and then.

Required on both sides

Content mods whose client part matters: the mod’s block models, HUD layers, keybinds and screens.

• Until the handshake exists, players can join without the client part; design so that this is merely uglier, not broken (blocks show their base, items their base item).
• Keep client-only code in lifecycle.client_setup and client events, server code in server events.

Optional on both sides

The friendliest choice for many server mods: everyone can join, and players who install the mod get a better experience (a HUD, a screen).

• The server sends payloads to every player; clients without the mod ignore them.
• The client half must work (or stay quiet) on servers without the server half.

Planned

The configuration-phase handshake that refuses mismatched required mods with a readable list, telling the server which players have a mod (to send payloads only to them), and the vanilla_clients switch.