Mod and Plugin Support

Mod support extends the life of your game by letting the community create content, gameplay modes, and features you never planned. But mods also introduce complexity for hosting platforms that need to install, update, and manage them at scale.

Designing for mod support from the start makes this manageable. Retrofitting it later is significantly harder.

Directory Structure

Keep mods isolated from each other and from the base game:

• Directoryserver/

  • Directorymods/ or plugins/

    • Directorysome_mod/

      • mod.json Manifest: name, version, dependencies
      • …mod files
    • Directoryanother_mod/

      • mod.json
      • …mod files

Each mod lives in its own subdirectory with a manifest file that hosting platforms can read without loading the mod itself.

It is sometimes preferable for mods to be distributed as archives (e.g., some_mod.zip) that the game automatically inspects and reads at runtime. Hosting platforms can then do the same to inspect the manifest. The key is that mods are self-contained units that can be added, removed, and updated independently.

Mod Manifest

A manifest file (e.g., mod.json) for each mod should include:

{
  "id": "awesome-mod",
  "name": "Awesome Mod",
  "version": "2.1.0",
  "game_version_min": "1.2.0",
  "game_version_max": "1.4.x",
  "dependencies": [
    { "id": "core-library", "version": ">=1.0.0" }
  ],
  "author": "ModderName",
  "description": "Adds awesome features to the game."
}

This lets hosting platforms display mod info, check compatibility, and resolve dependencies without loading the mod code.

Mod Loading Order

If your game supports multiple mods at once, the loading order matters. Mods that depend on other mods need to load after their dependencies.

Your server should:

• Read all manifests and build a dependency graph
• Detect circular dependencies and report them clearly
• Load mods in dependency order
• Fail clearly when a required dependency is missing, naming the missing mod and version

Version Compatibility

Mods break when the game updates. Your server should check the mod’s declared compatible game version range against the current server version at startup.

• Compatible: load the mod
• Incompatible: skip the mod and log a clear warning ("Awesome Mod v2.1.0 requires game version 1.2.x-1.4.x, but server is running 1.5.0. Mod will not be loaded.")
• No version declared: load with a warning. Legacy mods may predate your versioning system.

Do not silently load incompatible mods. A broken mod that loads without warning causes mysterious crashes that waste everyone’s time.

Hosting Platform Automation

Hosting platforms need to install, update, and remove mods without manual intervention. Design for this:

• Mods exist in a single directory. No scattered files. This makes it easy for platforms to add/remove mods by copying/deleting a folder or archive.
• Mods are single archives, or a directory. Adding a mod = adding a folder/archive. Removing a mod = deleting a folder/archive. No registry, no database, no global state that must be edited.
• Manifests are self-describing. The platform reads mod.json to know what’s installed without executing any mod code.
• Config is per-mod. Each mod’s configuration lives in its own directory, not in a global config file.

Mod Validation and Sandboxing

Mods are third-party code running on your server. Consider:

• File system access: Can mods write anywhere on disk, or only to their own directory?
• Network access: Can mods make outbound network calls?
• System calls: Can mods execute system commands or spawn processes?

The more you sandbox mods, the safer your server is. At minimum, document what mods can and cannot do so server admins understand the risk.

Distribution Platforms

Mods need a place to live where players and hosting platforms can find, download, and update them. See the platform-specific guides:

Steam Workshop

Mod.io

Curseforge

Each platform has different strengths. Steam Workshop integrates directly with Steam’s infrastructure. Mod.io works across platforms. CurseForge has a large existing modding community. You can support more than one.