Making Mod-friendly Games
Many games are technically moddable, but doing so is difficult. Creating even a basic mod is an achievement, and for anything complex you basically need to be a developer.
Modding is one of the most powerful tools for building a community around your game, and improving the modding process — even with small changes —can make a huge difference in the way your mod-makers and players interact with the game and each other.
Topics discussed:
- Player access — make it easy to find and install mods
- Modder onboarding — make it easy to start making a mod
- Documentation — make it easy to find what things can be added to a mod
- Clarity — make it obvious to end users what a mod does
- Debugging — make it easy to find problems in a mod
- Community Management — Modders are a subcommunity, make them feel at home!
- Multiplying Effects —Separate effects into buildings blocks to exponentially expand possibility space
- Putting it all together
In all cases, I will bring examples for how we handle these issues in Unciv
Player Access
A player has 2 major hurdles to go through before they can play a mod:
- Finding a mod that looks cool
- Installing and uninstalling said mod
1. Finding a mod
You will want a centralized location where people can search for mods, and where modders can upload the latest versions to account for updates.
At the simplest level, this can be handled by the community itself — say, a Discord Forum Channel where people can upload their mods. Beyond the regular textual search, you can add tags to posts to specify what kind of mod it is for even better searchability. The “number of emojis” that Discord shows you is a great indicator for how well liked it is!
2. Installing and uninstalling a mod
Here, the idea is to minimize steps required. Any additional step cuts the number of players who will install the mod!
Many games have “Put file X in folder Y”, and that’s great! Simple clean instructions.
However, if that file is overriding another file, that makes it difficult for the user to go back to the previous state without the mod. “rename X to X_old, put X in file, when uninstalling delete X and rename X_old to X” is more complex and harder to remember when the user wants to uninstall.
Example — Unciv
The way we handled this in Unciv is to handle both points — search and mod installation/deinstallation — within the game itself
- All mods are Github repos — you can search for them outside the game using Github’s UI
- In-game, you can search mods by type (ruleset, graphics, maps, etc) and by text. Mods are sorted by number of Github stars, so that the more popular mods are at the top, so new players get the best experiences
- When you select a mod, you see basic information and can choose to download
- Downloaded mods are displayed alongside, and can be deleted or updated
Modder onboarding
Getting players to download a mod is only one half of the problem. The difficult half is getting modders to make them.
Just like for players, minimize steps required to having a Minimum Viable Product. This is a continuously improving process — as your documentat1ion and process improves, this time will go from days to hours to minutes
I suggest you start with clear, step-by-step instructions for creating a minimal mod that can be installed by users.
Then, create a template mod for modders to start with.
Once they have something to their name, then you can start with the deep-dive into the documentation of what is possible.
Example — Unciv
We started off with a list of written instructions for creating a mod ‘from scratch’ — but experience showed that lots of modders were getting stuck at relatively simple stages. Creating a template repository for new modders to copy supercharged this process and made creating new mods fast and simple
Documentation
Modders are frequently ingenious and can reverse-engineer your entire code, but even so, it’s much better to clearly state what can and can’t be done. Documentation — don’t get me wrong — is a hassle, but this can be made much simpler by 2 tricks:
A. Let modders improve your documentation
If your documentation is open to changes or suggestions, this provides a way for your community to improve it if something is misunderstood or simply incorrect.
It’s important to note that they will often improve existing documentation but very rarely add new subjects — this means that it’s in your best interest to write a ‘minimal documentation’ about something even if it only covers 10%, since that will be gradually expanded by the community over time.
B. Auto-generate documentation
Your game is code, and much of what modders can change is already defined in-code. You can use that to create the documentation whenever a change is made, or whenever you release a new version.
As your game gets bigger and the possibility space for modders expands, this is a massive time-saver as it enables you to quickly iterate on changing that space while keeping your modder’s source of truth up to date.
C. Schemas
You’re probably using a well-known file format for the mod’s data — json, yaml, xml, etc. Well-known file formats have data schemas to match them, so you can make your own schemas so modders (and you!) have an easier time filling in the objects. Of course, you need to assume modders don’t know what this is about, meaning — provide instructions on how to set this up.
Example — Unciv
We used to have all of the ‘special effects’ that you can add to an object be hardcoded strings, so there was no central list for available options — modder documentation was done by hand. It took us nearly 2 years (open-source being what it is) to fully convert those strings into an Enum containing all possible values, but that conversion lead to massive benefits down the line that we couldn’t have even imagined:
- Defining variable types for these effects (for documentation)
- Checking these variable types when loading a mod (for debugging)
- Auto-Converting effects in format A to format B (for deprecation of old effects)
Clarity
We discussed how modders can know what they can implement. But how do users know?
The simplest way is to allow modders to write it up — after all, they would know! But like all hand-written documentation, this can both be non-comprehensive and get out of date quickly.
Since our behavior is well-defined for modders anyway, reflecting the information on each modded object to users should be a relatively simple task.
This also serves a secondary purpose for modders, to allow users to quickly grasp what the mod is all about, and how it should work — i.e., what is a bug vs. working as intended.
NOTE: This does NOT apply to mods that include custom code, which by definition are irreducible to a set of known behaviors
Translation
Even if your game is translated, that doesn’t necessarily mean that your mods can be! Assuming that you’ll want to retain the same methodology for translating mods and the base game, the ease in which your regular translations can be conducted directly impacts the way that your modders can translate their mods.
Assuming that your modders don’t know all languages, the ability for collaboration in general becomes a sticking point for translations as well.
Debugging
There are 3 distinct types of problems you can encounter, which need different solutions.
- Mod is not installing / activating
- Specific functionality within the mod is not working
- Conflicts between mods
Here, I have no “one size fits all” advice. All of these require explicit treatment within the code. Ask yourself:
1. What happens if a mod is incorrectly defined (text should be an X but is not an X)? Not parseable? Has extra bits that are not defined (is json/xml but contains unknown fields)? Do we want to ignore the extras or declare this illegal?
2. Is there such a thing as a mod that is correctly defined but still “not valid”? How can you check such invalidity?
3. Is there such a thing as mods that conflict with each other? If so, can you check the final product of a bunch of mods together to check for these conflicts? Is this the same, or different from, a single mod that is invalid?
If you can recognize these problems in-game, you can reflect them to the mod maker!
How do players report errors to modders?
Users may encounter situations different to the mod creator, where the mod doesn’t behave as expected. Similarly, they may have suggestions on how to improve the mod.
At minimum, you would want users to be able to one-sidedly report such problems to the mod creators. Better still is the ability to talk directly to the modders, which leads into our next point of Community Management.
Personally, our decision to host all mods as Github repositories yielded a truly welcome surprise. Sufficiently motivated users could both locate the errors — since the ‘mod error detection’ is part of the base game — and suggest the required change as a PR, so the mod owner has only to accept the suggested change to fix the problem for everyone :)
Example — Unciv
In Unciv we have an in-game mod checker, with several features that might trigger your imagination for what you could do for your modders :)
- Since we mark deprecated features within the code, we can also mark what the new replacement feature is. By parsing the old one and taking its parameters to fill the new one, we can suggest the new replacements — and if we already know what needs to be replaced with what, we can do it ourselves! Modders only need to press a button to ‘autoupdate’ all of the deprecated parts of their mod!
- Since our mods are all hosted on Github we can go one step further and provide a Github Actions pipeline to do this automagically — mod owners only have to accept a PR every time features are deprecated and replaced :D
- Improve user experience by checking color contrasts — see here for details
- Locate spelling errors — if you already have a list of possible values you’re checking against, you can also check if it’s similar to something that is acceptable
Community Management
Like any other subcommunity, providing a safe environment to share ideas and host discussions will improve the health of your community, and — if you take note — your game.
In a way, though, the creative parts of your community — like modders and artists — are the MVPs of your community, because they are users that generate other users. Not only is their work actively increasing the assets of the community, their work as creators gives them a much better perspective on the technical and design decisions of your game.
Thus, it is extra important to stamp out any toxic behavior in this part of the community, even if this is behavior you tolerate in the general community. No modder, talented as they may be, is worth corrupting the comfort of the community space. A friendly modding community vastly increases the ramp up of new modders, and they build of each other’s ideas to create truly amazing works!
The Developer’s place in the Modding community
As a community, modders will create their own guides, guidelines, and workarounds when creating mods. These indicate a need of the community — these can indicate missing documentation, difficult processes, or simply something that is impossible to do ‘the normal way’. These are an excellent place to start if you want to improve the mod-making process.
For example, documentation. Even if you just restate what has already been said in the community, the fact that you are one saying it makes it a Source of Truth, and as long as you’re around to change the game — you’ll be around to change the docs.
Not all modder needs are possible, or even a good idea, to fulfill. But many trivial changes for a developer can save hours of work for modders, and these incremental changes in modder’s QOL build on each other.
If you’re unsure of the prevalence of a request, polling the community — being part of that shared space — can help understand if something is a niche request, or a common usecase.
Modders are people who are passionate about your game, so taking the time to consider their ideas can help you discover the limits your game has — or doesn’t have. Taking the time to explain why something won’t work builds trust in the developer-modder dynamic, and can help uncover other paths to the same goal.
Example — Unciv
In Unciv, we have 2 spaces for mod-related discussions: One for general discussion (asking questions, opening threads for specific subjects), and a separate area for mod-specific discussions.
The mod-specific channels (done again with Discord’s Forum Channel feature) are one of the most surprising successes of the Discord server, are serve as sort of mini-servers for the mod owners within the larger server
Multiplying Effects
Games are made interesting by interesting decisions, flavor (or theming), and interacting systems.
Flavor is by far the easiest thing to mod — allowing modders to take your game and make it a fantasy setting, or scifi, or Wuxia. But that’s just a thin veneer over the existing game.
Interesting decisions are something you can craft as a game maker — but how do hand your modders the ability to make these interesting decisions for their users?
A. Templates for effects
The simplest way is to create systems that already interact with each other, and give the modders the ability to create things within that system. For example, creating a “Does +2 damage to Fire creatures” modifier that you can add to a weapon. But this is inherently limited.
A far more powerful way is to give the modders the ability to create systems that interact with each other. For example, “Does [amount] damage to [creatureType] creatures”, “take [amount] damage in [tileType] tiles”.
That already gives us a large number of possible effects, and they can result in interesting trade-offs. For example — if a weapon does +2 damage to fire, but -2 to water, do I still want it? Depends!
C. Effects under certain conditions
But to really supercharge this, we can go one step further — and separate the condition from the effect. Now, if I have effects — “Does [amount] damage”, “take [amount] damage” — and conditions separately — “in [tileType] tiles” and “to [creatureType] creatures” — you can mix and match in any way you want!
And why restrict to only one condition? Allow modders to add as many conditions as they want for specific cases!
D. Separate cause and effect
Similarly, cause-and-effect can be separated — “do X” “when Y happens” can allow you to pair any X with any Y. If you allow the previously mentioned conditions as well, you’ll get a statement like “Do X | When Y | If Z” and a truly combinatorical explosion of possibilities!
A possible next step — which I have not yet had experience with — is to allow chaining of effects. “If A happens trigger B if C”, and then B can have its own “If B happens trigger D”. This is what card combo games like MTG live on :)
E. Object Tags and meta-modifiers
Since we can filter effects to only apply on certain conditions, how can we allow those conditions to happen?
- They can be part of the object itself (defined by the modder)
- They can be applied globally as a rule (e.g. “All metal objects are conductive”, a la BOTW)
- They can be applied by user decisions in-game — this requires “meta-modifiers”, ways to add or remove ‘tags’ from objects. These too can be subject to conditions!
Another powerful tool is applying these tags for a limited time — for example a “burning” effect applied by an attack, or a buff/debuff, effectively give effects temporarily which can stack with the rest of your system (‘wet’ characters hit by ‘freezing’ attacks get ‘frozen’ status, etc).
Meta-modifiers can also include things like “hidden from user”, or other custom changes for specific effects.
The Dilemma — modder freedom vs AI programming
Emergent gameplay is fantastic for players, but the exact combos that make a player feel brilliant make the AI feel dumb, when it can’t take advantage of it.
For games that feature both PvP and PvE, there is a built-in conflict between optimizing mods for one vs the other. More power to players means it’s harder to write AI to account for these changes, so your modders need to be aware of the limitations of the AI so they can make informed choices regarding content. Do they want a simpler mod where the AI can compete? Or a more complex one geared towards PvP? This is a design choice that can drastically change the direction of a mod.
Putting it all together —Effects in Unciv
Mods are comprised of json files and images / audio files — the json files are schemafied for modder ease.
In retrospect json files are finnicky, requiring all brackets to be closed etc, and do not natively support comments — we would have been better served making them yaml files, and allowing both is not off the table for us.
Objects’ special effects are determined by Uniques. These are a set of known effects, with known parameters, that we can reflect to modders.
These are human readable so that we can take the unique as the modder wrote it, and display it to users. The unique templates are already translated in the base game, so to translate the mod we only need to translate the object names — this we do by allowing mod creators to create their translation files in-game. Since mods are hosted on Github (example), they’re available for translators to add their own changes via PR.
Modifiers for these abilities are also human readable, which means that the entire ability can be expressed as a single string, e.g. “[+1 Gold] [in this city] <after discovering [Flight]>”.
These can then be translated piecemeal and rejoined to be displayed to users in their language. We have a button that generates translation files for mods, by scraping the mod object’s names and new texts (e.g. introduction texts, descriptions).
In addition to permanent effects, one-time effects exist as Triggerables, which can be activated by constructing buildings, researching techs, activating unit actions, or upon some other condition.
All Uniques have specific objects they can be placed on, and the parameter name determines the values that can be put there. This means that we can check Unique validity in-game for modders, and block incorrect mods from users to avoid crashes.
We have meta-Uniques to determine mod dependencies, and versioning and scoring is handled via Github’s existing capabilities.
Honorary Mention — Mod.io
Special shout-out to https://mod.io/ who have an extremely good understanding of the modding process — probably better than me! I’m not affiliated (I wish…) nor do I use their service, but if you’re a professional game dev and are working in Unreal / Unity, check them out!
