SoD files mod like


I want to also add creature abilities to spells_info.json. Even the ones that have only an effect + sound and no school; stuff like Fammiliars mana channel. (ONce this done the amount of mana stolen can be added to config file also and we have a nice ability that can be configured/maintained outside of code.

Another part I want to do is get rid of the confusing spell to battleACToDef] mapping. Code is hard to follow/understand because it jumps from using spellID in one line to mappedID in the other. Add to this that one spell can have more than one entry in this map, some entries in map have no spell counterparts, and some stuff is simply hard codded without using the map at all.

Here a wip spell_info.json file. (Relevant part from ID 82 onwards) (5.04 KB)


The amount of mana stolen ALREADY can be configured via bonus system, not only for familiar, but also for every other creature, as well as artifact or hero ability etc. It is not hardcoded at all, where did you get that idea?
You are confusing two totally different things. This is not a spell, this is ability!

Well, you could move that to spell config indeed. But it makes sense only for spells and not many other things which are not spells. You will need to link many effects with abilities that do not even have any identifier - that’s why they are hardcoded.
However, this way we loose compatibility with AC format, which is at last established, and replce it with custom format that has just the same disadvantages. I see no benefit here.


My bad. I wanted to make an example about animations and somewhat sounds being hard-codded, then got over-carried and without thinking too much included the abilities bonus on the hardcoded list. Sorry for that.

I do not get it. We have in config a file called spell_info.json. In that file there are spells AND abilities. (But not all abilities). There is also a todo list in sp_sounds.json to add sounds for the rest of the abilities.

Entries 80&81 are for Acid Breath: "Acid breath is a creature special ability that reduces the target stack’s defense by 3, and the attack has a 30 % chance to do an extra 25 damage per attacking unit. The Rust Dragon has this ability."

Death Stare is also there. So why Drain Life would not be there? Something like this:

"drainLife" :
			"id" : 88,
			"name" : "Drain Life",
			"soundfile" : "DRAINLIF.wav",
			"effect" : 0,
			"anim" : -1,
			"graphics" : {
				"animation" : "C01SPE0.DEF"]
			"ranges" :  "0", "0", "0", "0" ],
			"immunity" :"UNDEAD", "NON_LIVING"] // Undead, elementals, golems, gargoyles

I do not know what this format is and noone seems to even know what AC stands for. I see it only as an array used in a dozen of places. And my proposal is to use an animation array from inside Spell and access entries seamlessly based on SpellID.


Because that’s how they are originally implemented. Some abilities EFFECTS (not the abilities themselves!) are described in SPTRAITS.txt They have specific spell level and thus can be resisted (or not) under certain conditions. They are also blocked by Cursed Ground, Orb of Inhibition and possibly others.

Also, they have very specific target. Drain Life has no target and cannot be resisted. Immunity the way you propose won’t work. It can’t be cast by hero, while other spells could (though they were not designed for that reason). Mana Channel has no target, regeneration has no target. It does not change with skill level, does no damage neither has any permanent effects. And no level.
The only thing in common it shares with spells is animation. But when considering mechanics, architecture or role of this ability, it is VERY different than any spell.

Spell effects are handled in CGameHandler::handleSpellCasting function and result in BattleSpellCast package applied.

Well, it’s bad if you don’t know. Check attachment. It’s good to keep thee formats in mind if we ever want to handle ERM for real.

If you find animation names confusing, use enum. But it has by NO MEANS anything to do with spells themselves.
ERM formats.txt (94.3 KB)


Personal opinion:

All these legacy stuff you want to keep in place did so in the past and will bite you in the future as well. The sooner you break loose from those the better this system will be. It is not like modding scene is something really thriving in original H3 (with 1-2 exceptions), and once VCMI is released that will diminish close to nothing. That is the whole purpose of the project: make original H3 obsolete.

Because of these legacies, ATM (and even more so in the past 1-2 years) for a not so experienced programmer and with incomplete knowledge of the whole system much of the code is percived as a series of “hacks” that are hard to understand and work on. And the restrictions “imposed” for keeping these in place create a frustrating experience.

So i would break loose of all that dead weight and thrive towards having a modern game engine that is easy to understand, work, maintain and improve upon.


I don’t want to keep this stuff only because it’s “legacy”. I want to keep it because it actually works and is still much better organized that it was one, two or three years ago. Also, hopefully I explained clearly that each of these solutions serves a purpose and was chosen to either make game work better or the code look clearer. Breaking it just for the sake of breaking it making anew is not a good idea.

I fail to see why you actually want to rewrite anything. You didn’t prove that the code is incorrect or badly organized, but only that YOU can’t understand it or all the mechanics. This is a fundamental difference.

The code is complex and convoluted not because I wanted it to be so, but just because game mechanics are very complex in first place. There are hundreds of issues, quirks, exceptions that need to stay there for maximum game compatibility.


krs, perhaps keep spells as it but also create “spell effect” entity? It exists right now but in quite unorganized state.

So spells will contain all mechanics-related data (as they do now).
And spell effects will contain all UI-related data: filename(s) with animations, how and where to display it, in future - list of effects to apply to creature image (e.g. red bloodlust).

All spells will have one (or may be several?) spell effects assigned to it. And there will be several “spell effects” like morale that can be triggered without any spell.

I think something like this should work quite well with H3 data and will be more-less mod-friendly.

I fail to see why you actually want to rewrite anything. You didn't prove that the code is incorrect or badly organized

By rewrite I mean that there are still tons of stuff that should be moved to .json configs. (parts of spells is just an example). By no means I intend to rewrite the mechanics. Maybe If I show you and example of what I am doing then we will talk about the same thing. (see attachment).

@ivan Basically that is what I want to do but I thought adding that stuff into the spells and abilities config. So do I understand you correctly? You want an additional file like below?

"drainLife" :
	"id" : 88,
	"soundEffects" : "DRAINLIF.wav", xxxx.wav],
	"animations" : "C01SPE0.DEF", "xxxx.def"]
  • Where would mechanics for drainLife stay? (or deathBlow for example).
  • Can effects for spells have same format but be kept in spell_info.json? So we do not have redefinitions?
  • What about the deal breaker AC format/mapping. Keep it? (2.83 KB)


Yes. Something like that. Two separate entities, spells and effects.

Abilities currently implemented in bonus system will stay where they are now, with hardcoded ID for effect. In future - some field like “additionalInfo” can be used to specify effect.

There won’t be redefinition except for specifying string ID multiple times. AC mapping will be replaced by string ID’s.
Internally mapping will remain but mot of usages of ID’s should be replaced with pointers to either spell or effect. (pointers have type so you won’t mistake spell ID for effect ID)


"spells" :
	"mySpell" :
		"animation" : // because "effects" is used below. Better name?
			// String ID of effect that will be displayed when spell is casted
			"onCast": "mySpellEffect",

			// effect that will be displayed until spell duration runs out
			"passive" : "myPassiveEffect"
		"ranges":  "0", "0", "0", "X" ],
			... // all spell-related icons are here
		"effects":  ... ],
		"immunity":  ... ]
"effects" :
	"mySpellEffect" :
		"animation"  "aaa.def" ,"bbb.def" ,"ccc.def" ],
		"sound" : "sound.wav", // any reasons to use list here?

		<any other options>

Note: passive effect may be needed for such spells like land mines, firewall, clone.


1 remark: you have onCast and passive. I think a third option should be there called onExpire or something like that (EG: Land mines, quick sand).

2’nd remark. Sounds so far do not need an array. Mana channel is the only spell so far that has 2 sound effects. But since it is composed of 2 parts (steal from enemy, then give to your hero) it will just have 2 separate effects.


So it seems that for any work to be done/accepted it is better to separate it into chunks. Seems a pitty to have all that work gone to waste…

First chunk SoD FACTIONS as mods:
Question (mainly @ Ivan since hes familiar with what I’ve done up to now). Will you add to the game the changes for SoD factions as mods? If so I just need to update the .jsons with the changes from the last month and send them to you as a patch.


Sorry for question but what work? I do remember some changes by you like merge of spell configs but can you (re-)post all of them in one place?

IIRC the only missing piece was submods support? I am interested in this feature but right now I don’t have time for anything other than bugfixing.


I am talking mainly about .json work. I’ve spent some 100+ hours for that and I would be sad if it will see no usage :(.

The other part was merging spell configs and adding unit skills. That was the part that cut all my enthusiasm. Some spells have bugs, some are incomplete, many creature abilities are missing, there is that ugly AC mapping and on top .json files get updated in trunk frequently making diffs quite hard.

So what I want to do is have in repository at lest the biggest chunk of those .json config files (the factions) and the script for extracting and moving files. Then see if I continue from there.

Personally I would very much like to continue working on making SoD as mod happen and then go implement H3 with H2 graphics. But I have to recognize in some places I was at the end of my knowledge of the VCMI-project. That means that I will have to wait in some parts for work to be done by people with more knowledge of the whole system.

" submods support? I am interested in this feature but right now I don’t have time for anything other than bugfixing."

Maybe I bring this up here once more. I think maturing the modding system should be no1 priority at least for one developer. There is a lot of work that could be done in parallel by guys with not so much skill in coding the whole thing. A lot of testing will go to waste/will be redone once features start moving from full/partially hardcoded to configs. Tons of code will get so much cleaner once that is done. Partially because of moving stuff out and partially because of the implied review those parts would get.

That being said, you the team are doing all the work. I for one am just buzzing around from time to time. But I really am interested in helping with those 2 parts I’ve mentioned earlier.


Considering that I’ve spent most of my coding time was spend on modding system this year it can be called as #1 priority for me. The problem is that we have more systems that must be taken care of than developers.

I’ll happy to implement submods but I just can’t do everything. Campaigns, unicode support/i18n, launcher, 32-bit graphics, submods - can you say that something from this list is unimportant? And all of these are needed for fully-functional modding system (including campaings - I’d like to have Chronicles mod at some point).

So all I can do right now is to promise to look into submods when I’ll get some time to do it. When this will happen? Frankly I have no idea.


Ty for your answer. You do not have to answer for below, it’s just my rant…

I try to be as objective as I can, but I still see submods as priority no1 over any of the others. (Unless I am missing something and something is really screaming for unicode). Campaigns should be on your 2014 :D, and 32-bit should come after SDL2? maybe?

There I’ve took care of your schedule, get back to work :D.

Now seriously, many will flock here around X-Mas vacations. “Coders” and “testers” alike. With the current VCMI state I do not think campaigns or 32 bit will be needed at that time.


“campaigns or 32 bit will be needed at that time”

So Unicode also.
I proposed earlier easy way to turn off standard towns. But it was rejected.
I think if we just turn off standard towns, then they will be accessed through mods.
And everyone will be happy.
PS So there will be no need to clean up hardcoded standard towns stuff right now.


Campaigns - one of biggest missing features for H3, requested a lot by players who are not interested in mods.
unicode support/i18n - needed for better support for localized versions of H3. Including mods. Right now it is impossible to (for example) install Russian mod into Polish version of H3.
launcher - needs some internal improvements, probably smallest feature from this list.
32-bit graphics - SDL 2.0 or not code majority of code that assumes that all images are 8-bit still needs rewrite/fixes, most notably - battles.

There would never be a single opinion on what feature should have highest priority - you want submods, some H3 players want campaigns, artists want 32 bit, on bugtracker there is request for unicode from Chinese players.

How many times I should repeat this: implementing even “special” field is far from trivial. Simplest example: random town was set to Castle or Rampart in editor. Now you made this factions “special”. How such situation should be resolved? This is most trivial example that I can think of even without looking in code.
If somebody will make bug-free patch that implement this then I’ll commit it. But othervice I’m not interested in working on this feature at this point.


As I said earlier, if town is written in editor, it must stay as placed. So are creatures.
There is no change.
Only change for “special” - is that town is not proposed to choose on game options selection, and not placed on map, if random town without limitation is there.
Submods will not change this behavior (as I understand Krs). Creatures, heroes and towns will be named the same.


Winter is coming, so is free time. How is the progress/mood on sub-mod support?


Right now I’m finishing another feature: … ements.png

As for what to do next - either submods or victory conditions for campaigns.

For campaigns - base system is already mostly done & tested as part of extended building requirements so implementing campaigns is a logical continuation.

For submods - recently I made some changes that should make implementing submods easier. I’ll take a closer look on this - if there won’t be any unexpected obstacles then it should be possible to implement them as next feature.