Dev Diary: Mods

What's happening / TLDR: Developer diaries introduce details of Espiocracy - Cold War strategy game in which you play as an intelligence agency. You can catch up with the most important dev diary (The Vision) and find out more on Steam page.

Vocabulary intro for beginners: a "mod" is a set of modifications of the game, prepared and shared externally by the players themselves (not the developer), changing anything from small details to entire game world. "Modding" means making mods. "Moddability" refers to technical ability of modding a particular game, from "low moddability" (games with hardcoded closed content which are difficult to change) to "high moddability" (games intentionally exposing their internals to modding, that's us!). This diary is mostly about moddability.

Grand strategy games are famous for their fantastic mods. Espiocracy, as a game in this genre, will be moddable - it will have a mod manager, Steam Workshop integration, and it will also detect mod files dropped into game directory.

However, the extent of moddability will be different from most famous grand strategy games. In many areas it will be more shallow (eg. event modding), in some areas it will be more difficult (eg. map modding), while other rare areas will offer greater depth (eg. potential code modding). This is a product of many conscious choices during 5 years of development, and it's tied to the plan for more years of development after the release.

From the big picture perspective, high moddability is generally a multiplier of code complexity, and therefore a multiplier of required development time. As a small developer, I'm trying to cleverly pick my battles (which, as you can tell from long development time, suggests that I'm not very clever). Some of these battles were postponed, as I intentionally left particularly hairy features to be opened to modding in the future. This developer diary describes the current state of moddability, relevant to the incoming release, but be aware that we have a plan to expand moddability later.

Naturally, this diary just introduces the topic. Detailed documentation for modders with precise instructions and all available options will be released with the game.

XML Philosophy

Primary vehicle of moddability in Espiocracy is XML format.

The game will be shipped with a bunch of XML files which contain majority of historical (and alt-historical) data that makes up the game world: actors, countries, intelligence communities, wars, views, ideologies, events, population groups, and technologies (paradigms).

Here's a quick walk through their examples:

For personal micromodding, you can just open and directly modify any of the files. Here, I modified Tito to actually be a friend of Stalin:

To create a mod that can be easily shared with other players, you can create a new XML file (or multiple files). The game will automatically load them if they exist in one of the subdirectories inside "mods" directory (every subdirectory equals a separate mod). In these files you can overwrite any existing data, add new data in any way or order, or even suggest ignoring previously loaded data.

Since multiple mods can overwrite the same state, you can manage mods directly inside the game, and even for particular campaigns - turning mods on/off and changing the order of loading.

Nerdy technological detour: why XML, instead of JSON, Lua, or custom format? Out of the all options, XML has the most robust and the most mature loaders that can gracefully handle anything you throw at them...

...thanks to solid tag-based syntax. The syntax also makes searching and regexing across thousands of lines actually viable. It also has a few very useful features, such as attributes inside tags or ability to leave comments. Even its main disadvantage in comparison to other formats - that it is less aesthetically pleasing (less concise) - can be resolved simply by using one of the dozens of XML editors that were developed over three decades of existence of this format (and anything more advanced than Windows Notepad already assists you in editing XMLs, for instance by automatically finishing tags).

That being said, XML has one disadvantage that cannot be resolved: it is not suited for bulk data. Therefore, in cases where the game needs dozens of thousands of records, we are using instead small databases (SQLite), which can be replaced by mods in full (if they provide another DB file with the same name and structure). For instance, DB files are used for names, and therefore all names are moddable:

PNG Philosophy

Spatial data in the game is usually stored in PNG files which you can edit in any image editor.

Data is coded in RGB (red green blue) of pixels. Usually, XML files assign chosen RGBs to chosen entities, for instance tying a region inside a country to specific RGB value, and then PNG files define its distribution on the map:

For basic map data, such as land mass or borders, RGB coding is even simpler: it's just "binary" color-or-transparency.

Similarly to XML files, you can modify PNG files in place or drop new files inside "mods" directory. You can prepare new full replacements for original PNG files (then they just should have the same name as the original file in game files), or tap into overwriting/replacing/ignoring data by appending the intent to the file name:

In addition to spatial data, visual files such as actor portraits or icons are also stored as PNG files (and JPG in case of larger files, particularly prerendered map tiles) and follow the same modding rules.

Towards Total Conversion Mods

During development, we assumed and maintained ability to develop four examples of total conversion mods: changing entire game world into WW2 world, into modern world, into X-Files-like world, or into Star-Wars-like world.

As such mods require, first, ignoring majority or even all of the original files, in mod configuration file you can define in bulk the names of original files to be ignored (eg. "IGNORE:Actors_*" to ignore all actors from the original game).

Then, a total conversion mod has to provide:

• New XML files with actors, countries, intelligence communities etc

• New PNG files with spatial data on land mass, borders, populations etc

• New PNG and JPG files for visuals, especially actor portraits and map tiles

For larger map changes (especially remaking the map from zero), the game initially has to perform complex calculations, for instance flood fills between borders to define country shapes. The original version of the game will be shipped with these calculations already finished offline, significantly shortening the loading time. You can also implement this offline calculation for map-changing mods, by pressing F1 to access development console inside the game, and then running one of the modding tools. The console provides also other basic modding tools such as live error logger.

This is a good place to understand the limits of moddability as of now. Modding is generally limited to the game world and it does not extend to gameplay/activities/mechanics. There are a few exceptions, following the assumption described above. For instance, you can partially mod actor actions (eg. mod in cow abductions for an X-Files mod) or mod operations (eg. mod in light saber fights as an operational step in assassination operations for a Star Wars mod). However, many other mechanics of the game are for now closed for modding because opening them would be too costly in terms of development time. These parts of the game can be, for now, simply shut down in mod configuration file. As an example, the game features numerous rather-Cold-War intelligence programs. If you deem that, say, "Covert Airline" program doesn't really fit Star-Wars-like mod, you can add "TURNOFF_PROGRAM:Covert Airline" to mod configuration file (or even "TURNOFF_PROGRAM:*" to turn all of them). This is a temporary measure until more mechanical parts of the game are be exposed to modding as well.

Potential For Other Modifications

Espiocracy uses Godot Engine for user interface. The game comes with large PCK file that contains inside all the Godot files, such as interface scenes. You can inspect and modify them in Godot Editor, which is a free open source software. For now, there is no special system for detecting and loading such mods (integration with current interface system, error-handling, and scripts is rather complex) but there's a potential for very deep interface mods in the future.

The game is coded in C# - which means that its code can be inspected and expanded. We won't be obfuscating the code to keep the game open for such moddability. However, for now we decided that for security reasons we won't be supporting "code mods" from in-game mod manager. In the last few years, there were a few harmful cases of hackers using code mods to plant malware. A game about espionage obviously would be a huge target for such attempts. Alternatives either do not work well enough (eg. running code mods in sandbox environment can be broken because sandbox similarly to the rest of the code is also known) or would take away a lot of development time (eg. using Lua for code mods requires a lot adjustment & exposing work). That being said, many C# games have (whether developers wanted it or not) code mods "in second circulation", so such modding is generally possible - we just made it a little bit less convenient, so that it occurs between people knowledgeable enough to understand what they are downloading.

One specific modding-like activity - modifying save files - is also possible. Saves are in ordinary binary format which you can edit with any binary editor:

Last but not least: algorithms of AI players are very important for strategy games, and as we indicated in DD#39 they will be moddable - we will dedicate entire separate dev diary to their moddability.

Behind The Scenes

► While in a developer diary we are discussing features from developer's perspective, we cannot ommit external - community - side of modding. A lot will depend on game's quality and appeal (measured in number of sold units) but even if everything works well in this department, there are many other external factors affecting the existence and strength of modding community.

And then the largest factor is time

it takes many years for a robust modding community to form. In the case of popular grand strategy franchises, the community is already there, very strong, and used to specific technical solutions of the same/similar engine - hence, even a new game has immediately hundreds of mods, and then a few strong total conversion projects after a year or two. In the case of Espiocracy, my honest assessment is that I will be happy with 1/10th or 1/20th of number & quality of mods in comparable time after the release. This stems from comparison of actual releases of other moddable games and how their communities form over time. It also takes into account other underappreciated factors, such as changes between generations of gamers (it's no coincidence that many games released in mid-2010s grew excellent modding communities, while games released after 2020 very rarely do so).

So to summarize this angle

we are leaving the door open for modding but as a player, you won't probably see many/rich/deep mods in reasonable time, and it won't be anybody's fault. Online communities are a complex phenomenon.

Final Remarks

The next dev diary will be posted on March 6th.

If you're not already wishlisting Espiocracy, consider doing it

https://store.steampowered.com/app/1670650/Espiocracy/

There is also a small community around Espiocracy:

---"Usually a tech required access to the telephone to make the modification but if the make and model of the targeted telephone could be obtained, a hook-switch bypass modification to an identical instrument could be made. Then, similar to a quick-plant operation, a cleaning person or service personnel could covertly exchange phones"- Robert Wallace, CIA officer, on real life modifications in the field