SoD files mod like


the 2 files named enchantress.json will just reside in 2 different places in hierarchy. one in factions/castle/creatures/enchantress and the other in factions/cove/creatures/enchantress (or whatever location the modder wants, just not in the castle path, unless he wants to override). (On hard drive they will exist in Mods/SoD/factions/castle/creatures/enchantress and Mods/HotA/factions/cove/creatures/enchantress respectively).

How this is translated into engine resources without conflicts… I do not know, but I think that is already solved. (we have hota as mod).

Modder can do whatever he wants inside his mod in my variant too. With the exception when he overwrites something but then he does not need an additional folder (this overrides/).


Except that here Ivan does not propose 2 folder from which only 1 is modifiable. He proposes 2 folders both to suffer modifications. EG: I want to make an artifact set. I invent 1 new artifact and modify 1 from SoD. With his solution I will have to go to <my_mod>/Overrides/artifacts/ and <my_mod>/Files/artifacts/ 2 different locations.

Now that is simple for artifacts but imagine a path for creatures or town files…

The proposed workaround was for the modder to decide not to use Files, but put everything under Overrides. And that is exactly “my” variant.


I just re-red this…

Just wanted to point out that in my variant you will not need this extra level at all. Every mod will write into the “root” mod structure. I stress it again, the engine will not know what mods created the 16 factions he sees. He just sees a “virtual” folder/path called "factions: with 14 entries.


I think you got it a bit wrong - all files from one mod are in one directory - there is no way for one mod to replace files from another mod physically, in real filesystem. The question is how to handle interaction of mods in virtual filesystem generated on vcmi start.

I don’t see any issues related to mods that will be specific to Linux systems neither in my system nor in one proposed by krs.

And what about string ID that will be accessible at some point via scripting? Different creatures must have different ID (currently achieved by prefixing ID with mod name)
What about such objects like artifacts which don’t have anything like faction name in path?
What about two neutral (same faction) creatures with same name?

The problem is that he may accidentally override file from another mod without even knowing that.

Imagine number of modders that will create folder (or ID) named “castle” or “town” and put all files specific to their mod in it? Or something even more generic like “icon.png”? Their mod will work correctly for them but after releasing it they will end up with broken mod on user side.

My approach to edit and add 1 creature:

Your approach:
/factions/<faction 2>/content/creatures/<creature name 2>

IMO mine is actually simpler. At least in this case :wink:

Then how can engine differ between object added by mod and object replaced by mod? What if same name is just an accident and game should add two objects instead of one? This is probably my biggest complain against your proposition. Saying “just use unique names” is not an answer.


Without quoting you I think the biggest issue is same name-handling. Frankly I do not know how they handle it in code in other games but this is how they work but they have a solution for 2 resources with same name (but different paths) with game engine having 0 clue about your mod.

In my approach you can as-well override like this:

/content/creatures/. <- override
/content/creatures/HotA/ < no override.

I use factions/ because with 100+ creatures I find it more organized to separate them into factions. And then the chances of having 2 creatures with same name will be 0 (unless you have in same faction 2 creatures named Wolf Rider, but who would be that stupid? :slight_smile: ).

How the engine will differentiate between the 2 identical creature names?.. I do not know for sure but seems to me like same solution for both variants. (use somehow folder name).


Engine should not care if it is a new resource or overwrite. It just loads what is in that “virtual path”. (mod order resolves for same name under same path)

If you use same name under same path … it WILL overwrite! Your mistake. (Here a more elaborate hierarchy comes to use (factions/<faction_name>/… )). Nevertheless your mistake. If you do not want it overwritten and still want same name, place it under a separate folder.

/Creatures/<other_pirates> or better yet! bring the pirate under /Creatures/HotA/

But this is only for same name resources!!! No need for this extra “indentation” otherwise.


Usually they don’t. Thus forcing modders to invent naming conventions used only by some percent of mods and spend hours to figure out source of conflict.
Some mod systems avoid such situations by allowing no more than one mod to run at once or blocking any interaction between mods.

But we can do better than that, don’t we?

This will work in case of creatures (or any other objects inside a faction). But what about this:
<mod 1>/artifacts/coolSword.json
<mod 2>/artifacts/coolSword.json
What is this? One mod that edits another or two independent mods? Because after loading this will turn into one object, no matter what authors expected to have.

This is how it works right now - modders have to place own files into some subdirectory (HotA in your example). Unfortunately not everyone does this.

This also results in weird-looking directory structure, e.g.
Engine already knows that this is HotA mod. Why it has to be specified twice? Of course this has an explanation but not all modders (especially novice) know about it.

Or even better:
Subdirectory named Cove but it does not matches name of the mod! This goes into dangerous field where somebody creates mod with such name and start getting conflicts despite placing files into separate directory.

And yes - I’m criticizing system made mostly by me and mod made mostly by me :stuck_out_tongue:

And offended modder who wanted to make mod for VCMI goes away. We don’t want that.

Such situation is something that can be handled. We shouldn’t just say “fix it yourself” - this should be one of the features of modding system.

And how such “same name resources” can be detected? Imagine large number of mods, without any interaction between most of authors. Unless I check every other mod I can’t be sure that such name is not used somewhere else.


Here you got me. Up to now I thought my solution is better because it was simpler, but because of that, with my solution you cannot solve this automatically. My solution for such collision would have been release->if conflict->report->fix.

It all depends on how many conflicting mods there will be.

I yield! I find your solution better. I would very much prefer my “simpler yet not complete” solution but most likely the time spent solving inter-mod conflicts will be much higher than dealing with 2 separate folders or doing extra indentations.

so how will mod.json change for a mod? Instead of having contents/… we will have to put the appropriate Files or Overwrites?


mod.json itself will remain same (or at least there won’t be changes related to this).
See this page to check what I’d like to change in mod format: … ion_format
(wiki talk page is probably better place to discuss than this thread)

As for files location - I’m not yet sure when I’ll implement this. First I’d like to finish mod manager + zip support. After this I can work on improving mod structure (including submods support).

Most likely it will look like this:

  Mods/ <- directory for submods.  
  Files/ <- files added by mod. Unless I'll come up with better name
  Overrides/ <- files replaced by mod
  Content <- current directory for compatibility purposes


  • By this time we’ll have .zip support meaning that both Files and Overrides can be replaced by archives. Mods is likely to remain uncompressed
  • All submods must be placed directly in Mods/ - vcmi will not perform deep search.

I also not sure how Overrides should look like.

  <modname 2>/



A) may sound more logical from modder point of view. However it does not represents our internal structure ( = more complicate to implement) and does not have clear way on how to replace H3 files

B) Is trivial to implement but may not be as obvious as A) for modder


I just want to say this. A)is logical B) is ugly.

And I also want to say that it seems to me more logical to place all images in a /images subfolder, like all defs are in /sprites folder. This way Data will remain for everything else. Fonts, pals, whatever.


Yeah… But there are some problems with implementing A:

  1. How replacing files from H3 will work in this case? Hardcoded “core” mod?
    <replaced H3 files
  1. Implementing this is not straightforward using current filesystem functionality.

Perhaps. But this raises another issue. Are icons also “images” or they’re animation files (.def)? Because internally all icons are just one frame in animation file. Even if they’re stored externally. Town hall icons are even more obvious - they can be stored in .def or as set of bitmaps. What is correct location for them?

Same goes to “real” animation - in future we’ll have support for 32-bit, def-free graphics. Meaning that animation will consist from 1 json file and set of bitmaps (e.g. .png files). What is a proper place for these files?


I cannot answer for future 32 bits. But in my laymen mind everything that needs a .def program to open is a sprite. If I can open it with windows image viewer then its an image.

As you’ve mentioned it does not for the packed icons…but there are ~5000 images compared to ~15 packed icons. And out of those 6 concerning icons for factions I’ve splitted already… (maybe some more for interfaces)


Maybe rename /Files to /Resources? So you have /Resources, /Overrides, /Mods?


What exactly a problem is when “images” meet “animations” because my idea is to gradually replace .def files with set of images (at least for mods).

What you have is:
Sprites/myCreature/animation.json <- json file that lists paths to images that compose animation. Placing this file into Sprites directory is completely logical.

Now - where should these images go?
Placing them into Images directory will result in somewhat weird situation because logically connected files are in completely different locations.

Placing them into Sprites, alongside with json results in images that are not in Images directory.

Perhaps just merge Images directory into Sprites? In this case all graphical files will be in one place, both images and animation - keeping them separate will make situation even more strange with time.

Sounds good.


Like I’ve said before, I guess my biggest “problem” is still this usage of /Data like structure for mods… While in json hierarchy things are aranged after their meaning(faction, heroes, creatures, artifacts) Please indulge me once again :).

You have this in place:


This seems more natural: (to me)


I did a quick mockup of the 2. (Have to say that after working with the inplace Data./ based structure for ~40 hours, where I had to continuously “fight” my way through the hierarchy, this “natural” organization of resources felt like a breeze).

I do not know/see what the probles are with this structure but it solves the sprites/images problem by not using any of them :). You will use meaningful folder names that can contain both types inside. (EG: towns will have a folder /townScreen that will have subfolders for /animation(defs) /area(images) /border(images)) all contingently located in one place.

The path to resources in config files will have 2/3 less levels of indentation.

In case of ./Overwrites folder you will need to specify the mod name only once.


  <modname 2>/

I find this C) more closer to how people organize things and to json hierarchy.

  • all resources for an entity are in 1 place
  • natural way of organizing things (entity based, just like json hierarchy)
  • you indirect your mod only once (easy to understand, 0 danger of overwriting files in other mods)
  • paths to resources loose 2/3 indentation levels.
  • there is no need for auto-detection of resource folders.

Here the 2 structures for castle faction to compare. (everything is in its right place for the non_data_mod, except I did only 1 creature: angel.json and one hero adela.json). (37.1 KB) (37 KB)


Here we again disagree :slight_smile:

IMO files organization should help with most common operations on them. Your structure is “optimized” towards copying/removing whole object at once. This is relatively rare operation.

Grouping files by type here would be more logical - it is more likely that modder will want to make change into (for example) config of multiple objects than changing config and dome of images in the same time. In the same time artist may be interested in having access to all icons at once and not interested at all in config files.

Although I agree with you townScreen propositions.
I made list of files needed for various objects. What do you think about placing files in such format?
(towns have too many files - will finish it later)

A) More-less similar to current organization, except all images are now in Sprites directory. Will also fix your complain with town screen.





Hero class




B) Pushing it further, all images are located according to their “type” - where they’re used





Hero class




Optionally - replace “sprites/icons” with “icons”, turning them into one more “root” directory.


I do not see how is “my” organization hampers any of the above. You want to change all icons for all creatures of a faction you go in /creatures/icons/ and you have all of them there. Same for configs, go to /creatures/configs and change as many as you want.

I cannot imagine a mod that will benefit from the “awkward” Data structure. Last time you convinced me with a “real” use case example. I have pointed some advantages the entity grouping would have, can you point out shortly 1 or 2 for Data here?

I say the on the contrary people who do mods will change “logiclal” grouped objects like towns, creatures, artifacts, spells, interface. Usually they change more than 1 stuff in an entity and even for 1 stuff they would like the configs where they specify where resources are stored close to the resources and not 5-9 folders away.


Nevertheless all games I know about separate data by usage location. This includes commercial games as well as open-source games.

Reasoning for this is:

  • Loading speed. Files in one directory are often placed in the same block/sector on hard drive (or on SSD). Meaning that loading files in one directory is faster. Much faster. And in archives they are always near each other.

  • split by type is useful for big teams where one person usually only works with data of one type - all changes on config files will be done by “scripter”, all changes to graphics are done by artist, etc. For small teams/solo projects this is not a problem since size of mod is usually small.

Anyway - I propose to delay it for later. I doubt that I’ll have time to work on this before 0.94 release. At most I’ll implement Resource/Overrides split and/or submods. But definitely not this one.


Maybe leave original LODs as they are, in mods of standard factions etc will be only filenames from original LODs?

Or keep LOD along with sorted files?
I have some towns, that use files from town siege, for example, from standard resources.
If they all will be externationalized, it will leed to paths corrections and etc.
So standart LOD data will be used in mods like now.


I have seen both but of late games got bigger and the “logical” organization seems to be more in use (at least in my games). As for performance I do not know, I would guess that if mods will be zipped anywayz it wont be relevant.

Nevertheless… I brought it up as an idea and an answer like: looks good but not for now, or looks bad, would suffice.

What I want to achieve ATM is to come up with a “common” solution for a factions folder structure, so that one we agree on all details for castle, I will update the rest (and the moving script) to the latest stand.

Will send this evening an update with the latest structure.