We have put a lifetime of experience into mod.io that begun in 2002 with ModDB.com and have a team dedicated to improving the product daily. This guide helps you understand the steps to begin using the mod.io API in your game, to unlock the power of modding.
How it works
Compatible with all builds of your game, mod.io operates silently in the background (without requiring your users to install another client), giving you complete control over your modding ecosystem.
Before you begin implementation, it's important to consider the kind of mods you want to enable. For example many multiplayer games allow cosmetic mods and maps only, to keep gameplay balanced and even. While many singleplayer games allow total conversions that change characters, weapons and content - allowing creators complete freedom. In some cases a mod might need to alter key gameplay settings, such as a weapons range and damage. mod.io supports metadata and customization to handle all of these usecases.
We offer a private test environment which replicates all production features, so you can begin using mod.io functionality immediately and obligation free, and perfect your implementation before going live.
Connecting to mod.io
You have 3 options to connect to the mod.io API which you can use interchangeably depending on your needs.
|Docs||Here||Here||Available per tool|
|Usage||For connecting directly to the mod.io REST API.||Drop our open source C/C++ SDK into your game to call mod.io functionality.||Use tools and plugins created by the community to make implementation in various engines easy.|
|Suited for||Web apps that need a JSON REST API, or game developers that like a challenge and want control over their implementation.||Developers that want a SDK that abstracts the uploading, downloading and unzip flows behind easy to use function calls.||Game developers that want a pre-built modding solution for their engine of choice.|
There are two ways to authenticate with the mod.io API described below. Both are designed to be easy for you and your users to use. A custom solution which connects to your OAuth endpoints can be added on request if neither is suitable.
To access the API, authentication is required. All users and games get a private API key. It is quick and easy to use in your apps, but limited to read-only GET requests, due to the limited security it offers.
To perform writes, you will need to authenticate your users via OAuth 2. To make this frictionless in-game, we use an email authentication flow, similar to what Slack and others pioneered. It works by users supplying their email, which we send a time-limited 5 digit security code too. They exchange this code in-game, for an OAuth 2 access token you can save to authenticate future requests. The benefit of this approach is it avoids complex website redirects, and doesn't require your users to complete a slow registration flow.
|API Key||OAuth 2|
|Generate||Global, unique to your application via your API key page.||Per user, created by the email authentication flow (or manually).|
|Usage||Easy to implement for low security read-only requests to browse and download mods.||Authenticate users, to download their subscribed mods. Required to create, edit and rate content.|
What to create
mod.io works best when implemented in-game to browse and download a users subscribed mods automatically. This way users can subscribe to mods via the mod.io website and have them magically installed in-game. It should also be implemented in your mod creation tools, so you can guarantee a mod is compatible with your game and tag its features appropriately during the submission process.
Alternately if you prefer a simpler implementation, you can allow mod submissions via the mod.io website, and use the mod.io API to browse and download mods in a read-only manner.
The implementation is flexible to your needs and can be used alongside other modding systems. We also encourage our users to create tools, SDKs, plugins, websites and platforms built ontop of mod.io.
Here is an example implementation, to show how everything fits together.
- Mod upload tool: You will need to create a tool that creators can use to upload mods. Some games will integrate mod uploading into their mod making tools, while others will create a standalone application that does it. This tool will be responsible for validating the mod works and includes metadata, tags, screenshots and information about the mod. This is important because your game will need to use the information you saved, to run the mod and change any gameplay settings as appropiate.
- Loading mods: mod.io stores each mod in it's own folder. Your client will need to see which mods a user is subscribed too, and load the relevant folders and associated mod metadata when playing the game. Your client will be responsible for moving and overwriting any files, if necessary for a mod to run. We also recommend you have a staging environment for mod creators to use, that you can load mods from and is separate from the mod.io folder.
- Multiplayer mods: In some cases multiplayer games will need mods to be loaded by all players and the server to properly run. For example if a user has a custom player character, other users playing with them will need to connect to the mod.io API and download that character in order to be able to see it. Or a server might distribute a custom map loaded by a user, to other users before joining that server.
If you have any questions about using mod.io, please contact us - we are here to help.