May 2019 Update – How Modding Works

Welcome to the update! I had been hoping to show you giant mushrooms (which can be used as an alternate source of lumber) in this update, but it’s still not quite ready, though I don’t think it can be far away now.

A giant mushroom in the current mod tools – but how big is it?

Most of the work accomplished this month has been preparing the way for mod support, which is due to make up almost the entirety of Alpha 3. For this monthly dev update, I’m going to go into some detail on what mods in King under the Mountain actually are and how I expect them to work.

The Basics

One of the design goals of King under the Mountain is that it is data-driven, which is that most of the stuff in the game (i.e. items, terrain, jobs, professions, even some AI decision-making) are not “hard-coded” into the game engine but instead loaded in from data files. That could mean binary data like .wav sound effects, .png sprites for characters, items and furniture or, in most cases, a machine-readable text file which provides data to the game but is also easily understoo-editable by humans. In our case we use JSON as it’s a bit shorter and more readable then XML, although you lose the safety net of having a strict structure that you get with XML.

If you want to take a look in the /assets directory wherever King under the Mountain is installed, this is where all the game’s data files (except player-specific data like saved games) are stored and loaded when the game is launched. You’ll find a large selection of .json files containing all sorts of data for the game, music and sound effects, and perhaps most importantly, spritesheets in the “tilesets” directory. The largest and most important is diffuse-entities.png and here’s how it looks as of today:

There’s a few points of interest in this image. “Diffuse” refers to the fact there’s a matching normal-entities.png with the normal-mapped versions of the same set of sprites. You can think of the diffuse images as the colour version, and the normal is alternatively called bump-mapping to make the lighting system work. “Entities” is the term I’m using for things in the game, currently categorised into items, furniture, humanoids and plants (with animals likely to also be part of this list). You can see that some (mostly the different outfits currently in the game) are coloured, while the rest are in greyscale. This is because a lot of the entities are coloured in “on the fly” by the game engine, usually depending on which material they’re made out of – the different materials and which colours they are drawn as is specified in the JSON files.

2D games use spritesheets like this, which are all the images in a single image/texture, so that it can be loaded into the memory of the graphics card once and then accessed many, many times to draw different regions to different parts of the screen. Separately loading each sprite as a new texture, drawing it, unloading it from the graphics card and repeating the whole process would just be too slow in most cases.

The above hopefully explains what the assets used by King under the Mountain are. Most computer games ship with assets exactly like this, and a lot of the time they’re compressed and/or obfuscated, meaning they’re difficult to modify by the player. Usually this is to prevent cheating (particularly for multiplayer games where the integrity of the game’s files will be checked by an anti-cheat tool) or just to help protect the developer’s artwork and media from those who would copy and distribute it illegally. Still, that usually doesn’t deter some fans, who modified (or “modded”) game files to change how a game looks or plays, and its out of this that the modding scene was born.

Processing Assets

Most games now embrace modding and provide guides, tools and engine support for mods, and King under the Mountain will be no exception!

Armed with the above knowledge, you could go into the /assets directory and change things to modify the game, and this would indeed work. Modifying the spritesheets would be awkward  but possible, while the JSON files are relatively easy to manipulate. One or two members of the community have already done this in fact. To share their mods with others though, they need to keep and distribute the changes in the assets directory with others.

This works relatively well for when a single person has modded the game, but what if you wanted to add several mods to the game from different sources? You’d have to keep track of which files each mod changes, and attempt to put them all together without causing any conflicts – mods might want to change the same file, say one of the spritesheets, and at that point you’d have to pick one or the other to apply and lose some of the changes from the other, which might have poor or even disastrous results.

This is where mod support comes in. Alongside the /assets directory, there’s also a /mods directory in the game location. Currently this will only contain a single directory, “base”, which is effectively the source files for what gets processed into /assets. Looking in the “entities” directory, you’ll see JSON files defining what types of entities there are, several .png sprites for each of them, and asset descriptors (more JSON files) which describe how the entity sprites should be used.

The sprites for metal plates alongside their JSON descriptor

The different item types and other entity types are processed, and the image files are combined into the relevant spritesheet – coloured sprites into the diffuse spritesheet and the _NORMALS versions into the normals spritesheet. Similar processing happens for everything else in this base mod directory to produce the contents of the assets directory.

Example of the different file structures

The important point here is that the game’s data files, everything under /mods/base is treated as a mod itself. The upcoming work is to then allow for other mods to live alongside this which can be layered “on top” of the base mod to add new assets and behaviour, change existing assets or adjust settings and constant variables used by the game. This also solves the problem that would come from directly modifying the assets directory – multiple mods can be used at once and the mod system defines how they interact with each other – either additively providing more content or replacing the settings of previous mods.

Mod “Artifacts”

Until recently, every time a change was made to the game’s base mod – that is, whenever I’ve been adding more assets to the game – the entire /assets directory was deleted and re-created. It was a quick and dirty solution that was perfectly “good enough” throughout the early stages of development. Now that the entities spritesheet is getting quite large (see above) and complex, this has been taking more and more time, eventually becoming a bit of a drain on gamedev time, just waiting for the assets to be processed between minor changes.

The main progress this month has been designing and implementing a much better solution – mod “artifacts”. Simply put, an artifact is a single file or group of related files in the assets directory. Each set of entity type descriptors is one artifact, the entity spritesheets are another artifact, the terrain spritesheets yet another artifact and so on. Now, instead of deleting and recreating the entire assets directory, the mod processor checks for any changes in the “source” files (the files in the mods directory which feed in to each particular artifact) and only recreates the artifact if any changes are detected (by running a quick checksum on the contents of all the input files and checking them against what was last processed.

Diagram of single artifact processing

This also extends perfectly into layering mods on top of each other. As new mods are added to an installation of the game, a mod may only be made up of certain artifacts rather than all of them. The mod processor then knows it only needs to process these artifacts, massively speeding up the process of swapping mods in and out of the game. Here’s an example of how a mod which only changes the entity and terrain sprites would be applied:

Example of mod layering


And that’s how mods work in King under the Mountain! As I continue development of mod support, I’ll go into detail on how the mods will be packaged and distributed from modders to the larger playerbase. Of course there will also be much more in-depth guides and documentation covering how to add and change game assets. Most likely a wiki site will be launched soon. I’ll also be covering the current plans for code mods, in addition to data files as described above, which will allow for all-new in-game functionality.

If modding isn’t your thing, then don’t worry! There’s still a fairly big update coming as part of Alpha 2, wrapping up a lot of player-requested features and some new content additions. I’d hoped to have this released in May but as always, it’s been a very busy month! Finally, if you’re interested in modding the game or just want to get involved with the community, the best thing to do would be to join the Discord server. See you next month!


Leave a Reply

Your e-mail address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.