Architecture Choices
Start with an ordinary MelonLoader client mod. It is the primary SDK starter and does not need a source checkout. Choose an additional runtime boundary only when your feature needs it.
Peer client mod
Section titled “Peer client mod”A MelonLoader mod references Anomaly.Client.Api.dll and runs in the client process. Use it for local UI, accessibility, input, observation, rendering helpers, and other non-authoritative behavior.
It owns its commands, event subscriptions, Scheduler handles, input registration handles, Unity objects, and cleanup. Retain IDisposable handles and remove named event handlers during OnDeinitializeMelon. It should declare Anomaly SupportedGameVersion metadata so the Launcher can surface compatibility status. Unlike the signed official core and managed-module sidecars, a third-party peer declaration is advisory in v1.
Managed client module (advanced)
Section titled “Managed client module (advanced)”An IAnomalyMod is discovered from UserData/Anomaly/Modules with a validated sidecar. Use it when dependency resolution, typed owned subscriptions, context-scoped persistence/scheduling, feature health, and automatic fault cleanup are useful.
Managed ownership is lifecycle isolation, not a security sandbox. The Launcher inventories executable files before startup. The development launch policy permits local builds without per-build hash approval; managed-module sidecar validation still applies.
Server companion
Section titled “Server companion”A LabAPI plugin references Anomaly.Server.dll for authoritative state, moderation integration, custom-item registration, and server-side item logic.
Use the server whenever trusting a client value would be a security or gameplay bug.
Shared directional messages
Section titled “Shared directional messages”A client and server pair use one unchanged shared assembly containing bounded AuthenticatedClientToServerMessage and AuthenticatedServerToClientMessage types. Use this for small feature state that is not already represented by the items-only content flow.
Do not design custom messages as a file channel.
Decision table
Section titled “Decision table”| Requirement | Recommended shape |
|---|---|
| Local HUD, keybind, accessibility, or cosmetic view | Peer client mod |
| Client feature needing runtime-owned cleanup and dependency graph | Managed module |
| Authoritative gameplay or permissions | Server companion |
| Small authenticated state exchanged both ways | Client + server + shared messages |
| Custom item with text/icon and stock behavior/model/weight | Server custom-item API |
| Custom role, effect, model, weight, bundle, prefab, or generic spawn | Not supported in public v1 |
Continue to Environment Setup.