Getting Started

mod.io manages the searching, storage and distribution of mods, so you can focus on creating a game that delivers amazing content, and improves the experience for everyone.

Posted by on


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. The quick steps for you to get started is:

  1. Add your game to our test environment
  2. Read our API documentation for an overview of how mod.io works
  3. Use our engine plugins, API or SDK to integrate mod.io into your game and mod making tools
  4. Ready to launch? Add your game to our production environment then let's discuss promoting your release
  5. Need help? Our team is available on Discord to assist

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.

SDK diagram

Understanding mods

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.

Test Environment

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.

API SDK Tools/Plugins
Docs Here Here Available per tool
Usage For connecting directly to the mod.io REST API. Drop our open source C/C++ SDK (community made wrappers are also available) 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.

Authentication

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.

API key

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.

Email authentication

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.

Email authentication
API Key OAuth 2
Permission Read Read+Write
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.



Implementation

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.

Contact us

If you have any questions about using mod.io, please contact us, or speak to us on discord - we are here to help.

Comments