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.

2 comments

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 platform 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 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

FAQ

Here is a common list of questions we get asked by developers, when considering whether to use mod.io.

Q: How do you monetize mod.io, I don't see any ads or business model

A: We offer two products. A licensed white label solution for studios that want a private mod.io environment branded with their users and games. It is typically used by AAA studios who want a mature mod platform that offers all of the benefits of an in-house solution, without the complexity, time and resources it would take to develop and run a comparable system. Pricing is available on request. The second product is the free mod.io platform you are using now. Developers using it can opt in to use patronage, monetization and marketplace functionality designed to allow players to back the creators of their favorite content. Any time a transaction takes place we take 10% of the gross with the game developer deciding how the remainder is split. We run no ads and have 16+ years of experience building community and serving over 1 billion mod downloads at ModDB.com - so rest assured we are in this for the long run and are big believers in the positive impact mods can have for games when utilized well.

Q: What size or type of mod do you support?

A: We support large and small mods from total conversions to simple cosmetics or scripts. The current upper limit for a mod file is 8gb, there is no lower limit. We realize today most mods are cosmetic or built in-game using simple editors. mod.io is designed to host large quantities of this type of user-generated content, and offers powerful search and sorting to help your players surface the best content. We recommend when configuring your game that you setup detailed tags, to allow your mod creators to properly categorize their content - making it easy to filter and browse.

Q: How do you differ from Steam Workshop?

A: Functionally we are very similar, in that our primary purpose is to enable 1-click mod installs in-game and solve all of the pieces of the puzzle that requires (submission, hosting, moderation, subscribing, rating, searching etc). We even support Steam Authentication. Key differences are:

  • Cross-platform - run 1 solution that works for your games on Steam, Epic Games, Discord, GOG, with console and mobile support in development.
  • Clientless - mod.io has no dependencies, it's designed to work behind the scenes so you can truly make it feel like part of your gameplay experience.
  • Portability - because we are the only mod platform with an API as well as a SDK, you can embed mod.io into your games launcher and homepage bringing you closer to your fans - and strengthening your engagement at key locations.
  • Open ecosystem - our community are continually building fansites and content consuming the mod.io API. Some cool applications of the API we've already seen and released (that you can use) include: a Discord bot which alerts your community when mods are released, and a web app that is less than 100kb and can be styled and embedded anywhere a web browser can run.
  • Business alignment - our sole aim is to build the world's best mod platform. We believe we've already accomplished this, we have an unmatched featureset, 16 years+ experience running ModDB.com and our platform is continually improving for your benefit. We don't have our own games or storefront to distract us, cloud our judgement or restrict our ability innovate.
  • Custom functionality - as a small fast moving team focused on mods, we see ourselves as enablers. We listen to our partners and will add your requirements to our roadmap provided those requirements are not specific to your game.
  • Revenue opportunities - we understand that every game is different. Workshop has to set rules globally, which restricts their ability to roll out functionality around paid modding. This is unfortunate because for some games (especially F2P) like TF2 and Roblox, the experience for creators and players was greatly enhanced when patronage, trading and marketplace concepts were carefully introduced. We will help you find a solution that maximises the outcome for you, your players and creators, and strongly believe that modding is only going to become more significant in a world where in-game interaction and content is what matters most.
  • White Label - if you need a private "mod support in a box" solution that gives you ownership and control over the complete experience - we've got you covered. Eliminate years of development and the cost of building an entire team to create (and maintain) a comparable service, and get the most comprehensive and battle-tested product up and running with our assistance. We can help theme the product and build out custom functionality to make mod.io a seamless part of your games experience.

Q: Can I run Workshop and mod.io side by side

A: Yes, we have developers that use both. The easiest approach is to have your mod submission tool upload content to Workshop and mod.io at the same time. We are exploring implementing a "sync" mechanism and can discuss on request, otherwise you can split your mod community, but we generally recommend you pick the solution that makes the most sense. In the case of mod.io we support Steam Authentication so the end-user experience in-game is identical, the only difference is you won't have a Steam Workshop page. With more stores opening (Epic, Discord, Google Stadia, WeGameX etc), shifting business models such as streaming and netflix-like subscriptions, the world's biggest games like LoL and Fortnite opting to go direct to the consumer, we believe "thinking cross-platform" is critically important, and being able to engage your players in-game with mods is one of the most powerful ways your game can stand out and succeed, no matter where your next player comes from.

Got a question for us? Ask on email or discord and we'll add it to the list.

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 three 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.

Steam / GOG / External authentication

If your game is running inside a popular distribution platform such as Steam or GOG Galaxy, you can use the external app ticket flow to authenticate your players via their encrypted session tickets which are accessible via the platform's SDK. mod.io offers the ability to decode this metadata from the respective client using a shared secret which is supplied to you by the platform.

ticketext

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.

2 comments

INtense!
INtense! @intense

As a consumer whether you use Steam Workshop, mod.io or something else - in order to access and play mods someone needs to put in the framework to host, moderate and manage the ecosystem. It's complicated - our aim is to uncomplicate it for everyone. Hope that helps!

#2
Guest @guest

What if I, as a consumer, don't want someone else to have complete control over the "modding ecosystem" of my games?