Skip to content

Sides Threads and Lifecycle

Gugas749 edited this page Nov 5, 2026 · 1 revision

Sides, threads and lifecycle: read this first

Most bugs with this API come from one of these rules.

Rule Why
Create channels and register synced attachments while your mod is being constructed. A static final field that your mod constructor touches is enough. NeoForge registers payloads and attachment types in early mod-bus events; Forge needs the channel before the registries freeze.
Run packet handler work inside ctx.enqueueWork(...). Packet handlers run on the network thread, not the game thread.
Never trust the client. Re-check permissions on the server in every C2S handler. AbyssClientPermission and AbyssPanelScreen.requiredLevel() are only for the user experience; a modified client can fake them.
Keep client-only classes (Minecraft, screens) out of common/server code paths. Use the Supplier in r.s2c(...). A dedicated server has no client classes. Loading one crashes it.
Use immutable values (records, Integer, String) in synced attachments. set() is the only way the client hears about a change.
Add new packets at the END of the registrar, and bump the version string when packets change. Forge numbers packets in registration order.

Which side each call runs on

API Server Client Notes
AbyssPermissionHandler.* ✅ ❌ Uses the server's permission file
AbyssClientPermission.* ❌ ✅ Last level the server sent
AbyssChannel.sendToPlayer/All/Tracking/TrackingAndSelf ✅ ❌
AbyssChannel.sendToServer ❌ ✅
AbyssSyncedAttachment.get ✅ ✅ Client: the local player's value. Other players read as the default.
AbyssSyncedAttachment.set/setSilently/sync ✅ ❌ Takes ServerPlayer
AbyssCorruption.get/data ✅ ✅ Same as above
AbyssCorruption.set/add/reset/addProgress ✅ ❌
AbyssDamage.deal ✅ ❌
AbyssEffectHandler.* ✅ — Register on the server (refreshing only runs there)
AbyssScreenOverlay.bindEffect/unbindEffect ✅ ✅ Call on both sides. The client draws it.
AbyssDamageSources.* ✅ ✅ Needs a Level (the damage itself is dealt on the server)
AbyssScreenOverlay.bindDamageType ✅ — Server-side trigger; calling it on both sides is harmless
AbyssScreenOverlay.show/clear ✅ ❌ Sends a packet
GUI toolkit (api.gui.*) ❌ ✅ Client only

Clone this wiki locally