Mod creation tutorial

a plea to experienced mod creators here: how about making a nice, step-by-step tutorial on how to create a mod, say a town mod?

Don’t have a time, sorry. Take Cove mod and do like others do - replace content files by new files slowly step by step.

Using Cove as example is probably a better idea - this is town maintained by us so it will always be up-to-date with current state of modding system.

Writing mod from scratch is a huge amount of work. For example this is amount of lines of code in Cove mod:
town itself - 1185 lines
creatures - 1341 lines
heroes - 1518 lines
hero classes - 172 lines
total - more than 4000 lines.
Not to mention amount of graphics needed to make all this code work.

Editing existing mod using documentation on our wiki as reference is much better idea. Some guidelines/hints for novices would be nice to have though.

If you have any questions - feel free to ask. This will also help us with figuring out what needs improvements in terms of documentation or code improvements.

They could have 9 other factions to get inspiration from… just restating my point that SoD as mod would be a great baseline for tons of stuff.

Ivan, I can’t help noticing you are also using Linux. It seems that in the Ubuntu 13.10 installation you’ve put together there is only WOG and the WOG options button is deactivated. Is that how it is supposed to be?

My second question is how to get Cove in my Ubuntu install. Since y’all pointing me to Cove as a template for my mod I need to get it.

Finally, where are all the data files (the original homm3 lods and the like)? On my windows box the VCMI lives in the HOMM3 directory together with all native files but I can’t find those on my linux box.
Thanks for the help!

  1. VCMI acts identically on all systems - wog options are not implemented at this point.

  2. You can download it as well as other mods via VCMI launcher (vcmilauncher command in console). Or you can visit “mod list” page on wiki and download them manually.

  3. vcmibuilder copies all required H3 files into ~/.vcmi directory.

And about wog - right now vcmibuilder still installs it by default. You can either disable it or uninstall completely via launcher.

interesting - vcmilauncher does start on my ubuntu box, but not on my debian netbook install:
fedor@crunchbang:~$ vcmilauncher
bash: vcmilauncher: command not found
fedor@crunchbang:~$

Yeah. We’re using somewhat new library for launcher (Qt5). Older distributions like Debian Stable or Ubuntu Precise don’t have it. As result - on these systems vcmi will be built without launcher.

Theoretically you can install Qt5 manually and build VCMI yourself but I won’t recommend this unless you’re familiar with this already.

Hi,

since someone suggested here: I have some questions :slight_smile:

I have f.ex. a DEF of a pure decorative object. If i want to make a mod containing this, how? A pure decorative object is nit meant to be “visited”. So what about the “visitableFrom” tag in json? Could i simply eliminate it? Or do i have to include it and forbid visiting from any direction?

Next question: I have other DEF which i want to behave like a standard H3 object. Just to help your imagination: I’m talking about Freds objects. And here f.ex. those nude female prisoners. I’d like them to be prisons. Of course it would be advisable to put only female heroes “inside”. So what about the ID? Docu says ID is for the standard H3 objects only, and you can not use ID with own objects. So then, what would i have to do to add these as a standard H3 prison?

There you have old vcmi port with some fred objects. It is buggy, but studying jsons you’ll find answers for you all questions http://www.mediafire.com/file/bcocv2lmtsvn1ib/Fred’sObjectsPack_v1.0.zip

Thanks, got it, and already took a look at it. Still there are many questions.

  1. The decorative objects like f.ex. the cacti have all “visitableFrom” set, so that these objects are visitable:

“visitableFrom” : [ “—”, “+++”, “+++” ]

And they have mask set to:

“mask” : [ “VV”,“VB”]

So, visitable only at the upper 2 tiles and at the left. Why is a cactus visitable? Or is this part of the “bugginess” of that mod?

As far as i can see these cacti are 1-tile objects. So the “visitableFrom should be omitted or set to “—”,”—","—", and the mask should simply be [“B”]?

Next there is a question regarding objects format. The wiki says here:

{
“myCoolObjectGroup”:
{
//numeric ID, mandatory for h3/wog objects, shall be unique if not defined
//used only for H3 objects, mods can not be used by mods
“index”:123,

So this seems to be the ID of the object. Let’s take for example the subterranean gateway from the original H3 objects, assuming i would have to put it into a mod. The ID of the simple subterranean gate is 103. So far so good. The sub-ID of this object is 0. Now where to put this sub-ID?

There is another subterranean gate, the snow covered one. This has the same ID, but sub-ID is 1. So they obviously belong to the same objectGroup. There is a second ID in the object type format. What ID is this? It can not be the sub-ID, since the object type format is not associated with any DEFs. So what is this “index”?

Now there is the “template” format section. This contains all the DEFs. But there is no ID. I’m quite confused.

The goal is: Take the Era editor, make a map with those objects from Fred, and then play that map with vcmi. How is it ensured that those additional objects show up correctly in vcmi?

Just to clarify this a bit more: I used to experiment quite a little with erm. So once i tried to add a script that adds a terrain overlay patch after battle. I was quite surprised, that i could only place one of these patches. To place such an object with erm, you need to give the ID and the sub-ID. I investigated the ZEOBJTS.txt and found they all had the same ID and the same sub-ID. So i changed that, gave them all distinct sub-IDs while keeping the ID. Result was, i could place exactly that patch that i wanted to place. That change had no impact on gameplay. The patch still was the same patch type, giving still the same bonus.

So the ID seems to be somewhat related to what vcmi calls “handler”. It would be extremely useful to have a full list of available handlers. And the sub-ID seems to identify the DEF. To make such an object into vcmi, there should be somehow a possibility to put this sub-ID into that templates section.

Yes, you must experiment with object configuration. You know, it’s hard to learn to add objects to the game without map editor. I’ve made this mod (based on marcron1 works) some times ago and test only luck of random maps:) And yes, visitableFrom is not needed for non-visitable objects.

  1. The decorative objects like f.ex. the cacti have all “visitableFrom” set, so that these objects are visitable:

“visitableFrom” : [ “—”, “+++”, “+++” ]

This command is not needed for non-visitable objects. For other objects - you must use “core:” command, so “visitableFrom” is set from the h3 object you’re ‘core-ing’.

And they have mask set to:

“mask” : [ “VV”,“VB”]

Mask must be set and is based of your def - it’s yellow and red squares of the object in map editor

So, visitable only at the upper 2 tiles and at the left. Why is a cactus visitable? Or is this part of the “bugginess” of that mod?

Yes, it is my attempt to understand object format - that’s why this mod is not public.

and the mask should simply be [“B”]?

How to set masks I wrote in this forum elsewhere. Masks are important. Very important.

So this seems to be the ID of the object. Let’s take for example the subterranean gateway from the original H3 objects, assuming i would have to put it into a mod. The ID of the simple subterranean gate is 103. So far so good. The sub-ID of this object is 0. Now where to put this sub-ID?

Now VCMI allows you to create non-visitable objects. In such objects ID is not needed. And you can “core” existing objects, so ID is taken from core-ing object. About sub-ID I don’t know.

So what is this “index”?

I think ‘index’ is connected with object ‘index’ in oryginal h3 game. Check config/objects/generic.json for example.

Now there is the “template” format section. This contains all the DEFs. But there is no ID. I’m quite confused.

Template is for many defs connected with the same handler. So you can have various defs working as War Machine Factory for example. Or one def can be spawn on snow, second one on grass, third on rock etc. Check config/objects/generic.json and look at redwoodObservatory config.

The goal is: Take the Era editor, make a map with those objects from Fred, and then play that map with vcmi. How is it ensured that those additional objects show up correctly in vcmi?

No need to. All we need is stable map editor without some tricky ways to launch it properly.

So the ID seems to be somewhat related to what vcmi calls “handler”. It would be extremely useful to have a full list of available handlers.

Such list exists. Study jsons in config/objects folder.

You mean the system-wide folder? /usr/share/vcmi?

I’m windows user. Don’t know where this folder is located in linux. But should be in your main h3-vcmi folder.

And here’s my ‘tutorial’ how to write masks.

I do it in a similar way :slight_smile: I’m using the Era editor and its “advanced properties” for that. But the idea is nearly the same.

I found an interesting part in the config/objects/generic.json:

"subterraneanGate" : {
	"index" :103,
	"handler" : "subterraneanGate",
	"base" : {
		"sounds" : {
			"ambient" : ["LOOPGATE"],
			"visit" : ["CAVEHEAD"]
		}
	},
	"types" : {
		"object" : {
			"index" : 0 },
		"objectWoG" : { "index" : 1 } // WoG object? Present on VCMI Test 2011b
	}
},

The subterranean gate, index 103, subindex 1, is not a special WoG object. It is just the snow covered variant in the standard H3 objects.
So: would it be o.k. to replace the variant here with:

“object” : { “index” : 1 }

?

Ok, enough for today. I’m having my evening beer, and after that i’ll go to sleep. I hope i have some minutes tomorrow. Thanks so far.

Frankly, I don’t know. I’ve never messed with subterrean gate yet ;[ You must test it and teach us…

I’ll do. But not today :slight_smile:

There are WoG objects that are much better subterranean gates than the original ones. The so called “adventure caves”. They fit much much better to the environment. I tested that in WoG (with altered ZEOBJTS.txt) and with Era, and it works out of the box. Let’s see if that is possible with vcmi too.

It just seems the json format is somewhat different to what is dokumented in the wiki :frowning:

BTW, i’m a software developer, since some years mostly doing Java. I took a look at the Java json support and found it quite impressive. May be out of these studies some day there will be a Mod designer in java. But i already found one issue: In vcmi everything is quoted. Even numericla values (like f.ex. this “index”). But json specification puts numbers without quotes.

Replacing existing defs via mod is childish thing in vcmi. But ‘templates’ should do something diffirent. Your ‘adventure cave’ def should appear in map editor next to standard ‘subterrean gate’. So mapmaker should put new defs on the map and this graphic should work as standard gate. Placing such defs in random maps is another thing. But best way to understand this mechanic is… experimenting. It’s fun after you solve all reasons that gam crashes at start ;]