1. General notes on file locations and internalnames

Basic

The Game XML

The entire contents of the game are currently included in the installation directory, in XML format. Every unit, every spell, every building, every tech. This is an excellent source of information if you wish to look for it. You should get comfortable searching the file contents of this directory, as it will be very useful later to search for how the game currently uses tag values. It is important that you can search INSIDE files for the information that is there - searching just for filenames is not enough. Google "how to search file contents" to find out how, if you don't know how.

If you are running a 64-bit OS, you can find the installation directory here:
C:\Program Files (x86)\Stardock Games\Elemental

If you are running a 32-bit OS, you should be able to find the installation directory here:
C:\Program Files\Stardock Games\Elemental

Inside that 'Elemental' folder you can find the folders containing the XML for the game
...Elemental\data\English\

The XML found in this directory are generally called "core files" by modders. They should not be changed by a new modder.

Important: Note that some stuff inside the core files have been "commented out". This is when the XML is surrounded by these tags

This means that the information inbetween those markers are not currently in use by the engine. You can use the same markers in your own files if you wish to temporarily disable parts of the XML, but don't want to delete it. It is also a great way to leave comments about what you are doing in the XML. For example, you can write <!-- In this part, I will attempt to create a new shield --> and it will not interfere with the function of the file.

Words on modding

Generally speaking, the XML structure of the game is built around "types". These are basically XML containers that have a set internal name, and contain various tags that define their purpose.

For example, see the quote below. I've removed almost all the tags inside the container, just so you can understand the structure of the XML. In fact, a unittype container would contain many more tags, and what is in the quote is not nearly enough to make something happen in-game.

In the quote, we see the UnitType container. The UnitType container is used to define a unit and its characteristics. The internal name of that particular unit is Kingdom_Pioneer. These internal names are extremely important, as they are used as references between different types.

See the line <Equipment>PioneersKit</Equipment> inside the unittype. This is actually a reference to another type - the GameItemType - and the value inside the tag defines what the internalname of that GameItemType is. So, this tells us that somewhere in the game there is another file which contains something that looks like this

Of course, you might want to create a new item later on, in which case you'll have to come up with a new internalname for the item. A reference does not mean that something by default exists - you still have to create the appropriate type. However, since we are looking inside the game files right now, we can be sure that something like an item with the internal name "PioneersKit" exists.

Going back to the UnitType quote above, there are also other kinds of tags with values. See the line <DisplayName>Pioneer</DisplayName>.This tag, for example, contains only a string (or a value) that the game is set to read. The Displayname, for example, is the name of the unittype that will be displayed in-game. Also see <ModelScale>1.3</ModelScale> - this is a tag containing not a string but a value.

There are also tags that call for resources that aren't inside the xml. Icons, textures and 3d models are the most common. One such an example is the line <ModelPath>K_Male_Mesh_01.hkb</ModelPath>. This tag, for example, defines the filename of the model that is used for this unit. This model is not found inside the XML of the game, but rather it is a file that has been read into the game. If you search the installation directory, you will find a file named K_Male_Mesh_01.hkb. You can always tell whether a tag is referencing another type, or calling for a resource because resources always include file endings such as .hkb or .png or .dds. Note that core files often contain paths to the file - however, these are completely unnecessary.

There is also one last kind of tag that has information that indirectly creates a new type that can be referenced, but these are rare and I will deal with them on a case by case basis. I call them variables in-between files.

Edit: This chart should help you understand in-between files variables: http://img145.imageshack.us/img145/6599/35489618.png

So, how do you know the purpose of each tag? What does <InfoCardBackground> really do? You don't know. Unless someone has written a roadmap, there is no information and you will have to logically deduce what the tag is doing. Is it containing a reference to another type? Or is it a string value? Or a number value? This will give you a good start - if it's a reference, you can search the gamefiles for it.

Each type can only have specific tags. Some other tags will break when placed inside strange types, others will simply not function. For example, from an ImprovementType (defines building) we have <ReqCityLevel>1</ReqCityLevel> but if we place this inside a UnitType, it will not accomplish anything. Experimentation with what tags functions inside what types is an ongoing effort, but for almost every case so far - whatever way the core files use tags inside specific types will work, and nothing else will. My suggestion: stick with the tags as they are found inside types in the core files.

? See the line <InfoCardBackground>BG_GoodScene</InfoCardBackground> in the UnitType above. This is also a tag that references another type in the game files. What do you think the purpose of the tag is? Can you find out what file contains that referenced type? Can you figure out how it all connects? Look at the tags inside the referenced type.

Modded files and their placement

Modded files should be placed inside this directory (or something similar)

C:\Users\yourusername\Documents\My Games\Elemental\Mods

I suggest you make a new folder inside the \Mods\ folder to contain your files. For example ...\Mods\ExperimentalFolder\

That is where you will place all the XML files that you create to mod the game.

.png and .hkb files and other graphics resources should be placed inside the \Mods\GFX\ folder - suitably in their own folder as well - ex \Mods\GFX\ALsoExperimentalFolder\ . Graphics files will not be read into the game unless they are inside the \Mods\GFX\ folder or any of its subfolders.

It is VERY IMPORTANT that all files placed there have unique names. If two files have the same name, only one will be read. I don't know which one gets chosen.

Starting our first mod - new content or overwriting old?

So, we are ready to start our first as we now understand the basics behind the XML and we know where to place the files we are creating.

It is important to understand that there is a difference between creating new content and overwriting content that is already in the game. This is directly controlled by the internal name of a type. For example, if I want to create a NEW item, I would choose a unique internal name that has not been used before. However, if I am seeking to OVERWRITE something that is already in the game, then I need to use the same internal name as that type.

If I wanted to overwrite the GameItemType "PioneersKit" I would create a file that starts with <GameItemType InternalName="PioneersKit">. This will completely nullify the GameItemType called "PioneersKit" that has been defined in the core files.

However! Not all types can be overwritten like this. For example, the ImprovementType container (which defines buildings) CANNOT be overwritten like this. For more information about that, see the Advanced part of the Improvements section.

GameItemTypes, SpellDefs and UnitTypes can be overwritten. Abilitybonuses and ImprovementTypes and Raceconfigs and TechDefs cannot.

Advanced

Modifying Core files (total conversion mods)

So maybe you are trying to change something and there's just no way around it - the core files keep interrupting what you have planned. For example, you might be trying to remove the Altar faction (defined in a RaceConfig) but you can't remove it because you can't overwrite the type. 

When all else has failed, you can change Core Files. However, this is largely unknown territory.

What is known is that every time you change what is inside Core Files, the game will on startup have to go through all the core XML files and create a new "xml blob". This will take several minutes.

The obvious limitation of doing this is that it makes mods hard to share - users will generally not want to overwrite their corefiles.

The other limitation of doing this is that some core files - for example TerrainTypes.xml, have redundancy built into them. Even if you change it, and the game creates a new xml blob, the changes may not appear in-game because the file has redundancy checks inside the Elemental.exe file that will read XML beyond your reach if the current TerrainTypes.xml is not following specific standards.

Overwriting types inside modfiles with other modfiles

There is also a way to overwrite modfiles from other peoples mods without actually overwriting the file, but instead overwriting the type.

In that case, it is important that you choose a filename that begins with a letter near the end of the alphabet. For example, if there is a modfile that is called CPELF_weapons.xml and you want to overwrite a type inside it, you should name your file something that is found after the C letter in the alphabet ZZZ_cpelf_weapons.xml for example. This willl cause your file to be read after the CPELF_weapons.xml file has been read, and you can in that way overwrite the types inside it.

3. Improvements (buildings)

Basic

A new city building

Let's create a completely new building, also called improvement. In part 2, we created a weapon that would overwrite the current crude bow. For this part, we will create something entirely new. Take a look at this xml: http://pastebin.com/raw.php?i=wvZuRvfV 

Let's go through this building.

These tags reference what "tile design" this building will use. The first one is the finished state, and the second one is what the building will look like when it's under construction. These are tiles designed in the in-game forge. Tiles saved in there can be referenced using the exact same name as they were saved with. Tiles saved in the forge end up in /Documents/my games/Elemental/Tiles/. If you wish, you can move the tile out of this folder and into your own mod folder.

These tags also indirectly define how many in-game tiles a building will occupy (1 or 4) by checking the size of the tile design.

This tells the game what terrain an improvement may be built on. Land is actually a group of terrains, such as desert, rugged land and so on.

? Can you think of a scenario when buildings do NOT support the terrain Land? How can we use this to our advantage?

These are pictures shown for different parts of the building. The first is the picture shown in clothmap mode when the building is finished. The second one is shown in cloth map mode while under construction. The last defines what picture is shown in various places like when the icon it shows when in the building queue, or the icon shown in the large circular frame near the bottom middle when world resources are selected.

I'm breaking the format here a bit, the workshop in the link only has the first of these four choices, <IgnoreDuplicateImpLimit>. I quoted these 4 tags because they all impact how many of this building can be constructed. Only one of these tags should ever be included in a building.

The first one, <IgnoreDuplicateImpLimit>, used for workshops, tells the game that this building may be infinitely repeated in a city, if the player has free resources, specialists and Open tiles. If this is NOT set, only one building may be built per city level (a level 2 city would be able to build 2).

The second one, <AllowedPerCity>, is a value that tells the game the building may only be constructed a certain amount of times in one specific city. Values larger than 1 are valid, the number representing the upper limit.

The third one, <AllowedPerFaction>, is a value that tells the game the building may only be constructed a certain amount of times in total for a player. Values larger than 1 are valid, the number representing the upper limit.

The fourth one, <AllowedPerGame>, is a value that tells the game the building may only be constructed a certain amount of times in total in the world - ie by all factions put together. I do not think any other value than 1 is valid.

Edit: It appears that combinations of the following tags are possible: <AllowedPerFaction>, <AllowedPerCity> and <IgnoreDuplicateImpLimit>. Remember if <IgnoreDuplicateImpLimit> is not used, only one building may be built per city level. <AllowedPerGame> does not seem to work well these other tags.

This defines the picture of the building when shown in the hiergamenon.

This tag defines what level the city must be before the building can be constructed in it. In this case, the value is 1, meaning it is available in all cities (if it fulfills other requirements).

The only apparent function of this tag is to set if world resource improvements can, or cannot, be built without being adjacent to a city (adjacent meaning the next tile).

This is a very interesting modifier, because it tells us what the building is producing. In this case, it says it is producing 1 Materials per turn it is active. Notice the order of the tags, it must be maintained (modtype -> attribute -> value -> perturn). Deleting the PerTurn tag would cause the building to produce this only once.

The previous modifier told us what the building was producing, this modifier tells us what the building is consuming in upkeep cost. Note the minus sign in the <Value> tag, meaning it is draining gold. The game has built-in support for showing the player a building drains Gildar (gold) and mana, but I would recommend against using other types of upkeep for buildings.

This modifier tells the game that the building will continuously use up a certain amount of "used population", in the XML these are refered to as Specialists. Note that there isn't a need for the PerTurn tag here. This modifier can be modified and copied to make the building require resources when built as well, see this code for example:

[code]    <GameModifier InternalName="Consumption1">
      <ModType>ConstructionResourceCost</ModType>
      <Attribute>Materials</Attribute>
      <Value>-20</Value>
    </GameModifier>[/code]

This tag defines how many turns it will take to construct this building. Note that world resource improvements should always use at least 2, otherwise completing it may cause a rare bug where the improvement produces nothing.

This tag defines how the AI will think of this building. The AI chooses an area it thinks needs, then produces a building that supplies that. In this case, if it were to think that it needed a workshop, it would maybe produce this building. Note that these tags are shared between buildings. To keep the AI functioning, it is important to choose the right <AITag>.

Possible values are:
Workshop
Study
CommandPost
Housing
Farming
Arcane
Prestige

? How would you go about to create a building that gives you 3 mana per turn?

? How would you go about to create a building that gives you 1 "fireshard" resource that boosts the power of your fire spells?

? Using what you learned in part 2, how would you go about to make this building only available to Kingdoms? How would you make this building require a technology before it can be built?

Creating Buildings for World Resources

To create a building that can be built on top of a world resource, you'll need to put the following tags in the ImprovementType:

The first is needed to tell the engine this building needs a resource, then what type of resource is defined in the second tag. <SupportedResourceType> references an in-between files variable that is defined both here, and in a ResourceType. Check out CoreWorldResources.xml for examples.

This building can only be built on a ResourceType that contains this tag: <Type>Wargs</Type>

Note that each world resource can only have one building on top of it per player. With that I mean that there is no choice for the player, if multiple buildings are available on top of a resource. You need to make sure that the player always has only one building to construct on top of a resource. Using <UpgradesToImprovement> is a valid way to make sure only one type is available (for example, shard improvements that upgrade).

Creating buildings that upgrade

If you want a specific building to upgrade into another one at some point, you'll need this tag:

The tag references the internal name of another improvementtype.

Buildings automatically upgrade either
1) When a city levels up, or
2) When the player discovers a new technology that unlocks an improvement

Note that this tag disables the previous version in the build menu once the upgrade is available. City level and prerequisite tech may be used to limit the upgraded building so it is not available when the non-upgraded building is.

Creating buildings that "provide" something

Sometimes there's a need to describe what a building provides in text format.

Note the new tag <Provides>. This will fulfill that purpose. You should be aware that the frame in-game where the text is displayed is very small, so you'll need to be concise and you shouldn't have more than one <Provides> tag in an entire building.

Advanced

Creating buildings that require a previous building in the city

It is possible to create a building that requires that a certain building has already been built in the city.

Consider the Tower of Souls for empire, that has the following tags:

This means the city can only build a tower of souls, IF the city has one of these other improvements.

There is a big caveat: the building must be directly connected to the city (ie surrounded by the city walls). Otherwise, the building will never be available.

I strongly recommend NOT using these tags for a building that you are also using the <UpgradesToImprovement> tag with - it is possible for the player to end up in a situation where NONE of the buildings are available. In that respect, this tag is not handled correctly.

Modifying existing improvementtypes

One of the strengths and/or weaknesses of the current engine (depending on who you ask) is how the game handles overwrites of improvementtypes. I've previously mentioned that ImprovementTypes cannot be overwritten. This is a slight modification of the truth. In fact, ImprovementTypes can be added to, but not replaced.

Let's say you already have the workshop example used above as a mod. Now we want to change how that building functions. Then we do this, in a new file:

And that's ALL we add. This information is now added to the already existing improvementtype. This will increase the already existing +1 material production from the original improvement, to 2, using the modifier from this added xml. 

? How would you go about to make the workshop example above require NO upkeep?

Disabling an improvement without changing core files

Knowing that we can't overwrite, only modify, an existing improvementtype, we devised a way to disable buildings by tricking the engine. Consider the following XML:

Obviously, since there is no such Allegiance as Nonexistant, this prerequisite can never be fulfilled. If we add this prerequisite to a previously defined improvementtype, it will effectively disable the building (in the sense that it cannot be built). It will still appear in the tech tree when researching, however.

Cityhubs, the core of cities

There is a sub-set of tags associated with certain ImprovementTypes called Cityhubs. Cityhubs represent the actual "city" tile in a city - the first building to appear when you construct a city. A cityhub improvementtype always has <IsCityHub>true</IsCityHub>, and it is referenced from the raceconfig to decide which kind of city each faction will build.

Notable features of the cityhub improvementtype:

This allows the cityhub to change tile design depending on how many people are currently living in the city. Note that these tags are all found in ONE improvementtype.

This defines the zone of influence around the cityhub. The <ZOCMinRadius> defines what radius of influence is given on the turn after a city has been constructed.

<ZOCMaxRadius> defines what is the maximum zone of influence for this cityhub.

<ZOCRadiusTurnsBeforeUpdate> defines how many turns it will take until the current zone of influence increases for the cityhub.

By reading all 3 tags, we can say for certain that the cityhub will take 20-21 turns to exert its full zone of influence, and after that it will stop.

<BuildableTiles> defines how many "open tiles" a cityhub has.

I'm not sure how <CitywideDuplicateImpLimit> functions. I believe it decides how many buildings may be built of a building, if it is not set to <IgnoreDuplicateLimit> or any other limiter. The tag, I would guess, works like CityLevel * Value = max amount of building in city.

This modifier tells the game how many people can live in the city if it has no other places for people to live. 10, in this case.

This modifier tells the game when the city will upgrade. As we can see, the city will upgrade to the referenced cityhub improvementtype known as 'F_Capital_L2' as soon as this city reaches 15 population.

This modifier allows us to automatically adjust the stats of every unit inside the city.

These tags reference gameitemtype types, and is used to unlock goods in the item shop in the city, that do not require technology to unlock.

Workaround for making buildings mutually exclusive

See this thread. https://forums.elementalgame.com/404727

5. RaceConfigs

Basic

What are they?

Each raceconfig represents a faction. A raceconfig defines everything special about the faction. I've gone ahead and uploaded a raceconfig of a modded faction, as that is what you are most likely to want to do. See here: http://pastebin.com/raw.php?i=zVdE4d8F

Let's go over what each tag accomplishes.

The first tag appears not to be in use.

The second tag appears not to be in use.

The third tag defines the name of the faction, but it also automatically adds "Kingdom of" or "Empire of" depending on which allegiance the faction belongs to (see <FactionAllegiance> below).

The fourth tag appears not to be in use.

The first tag is a string value telling the history of the faction, as seen by the player when selecting what faction to play.

The second tag appears not to be in use.

The first tag defines "Alignment". This must be Evil for Empires, and Good for Kingdoms. Any other value will cause the faction to not appear as a choice for enemy faction, but can still be chosen to be played by the player.

The second tag defines if the faction is an Empire or a Kingdom.

References a unittype. This unit will be chosen as sovereign. The referenced unittype must have <IsSovereign>1</IsSovereign>

These define faction strengths and weaknesses. More on this in the section about AbiiltyBonuses. The tag references an AbilityBonusOption.

This is a reference to a sheet of music to be played. See CoreLayeredMusic.xml for a list of the types.

This defines what default set of walls will surround a city. It is a reference string to a type called CityWallSet. See CoreCityWalls.xml for options and examples.

These reference cityhub improvementtypes (see the Advanced section on improvements).

The first tag is a reference to an improvementtype that must have <IsCityHub>true</IsCityHub>. This improvement is the one that will be created whenever a pioneer builds a city.

The second tag is a reference to an improvementtype that must have <IsCityHub>true</IsCityHub>. This improvement is the one that will be created whenever a sovereign builds a city.

This is an extremely important tag, as this references an in-between files variable that can be used in prerequisites. See the example below

[code]        <Prereq>
            <Type>Race</Type>
            <Attribute>White Golems</Attribute>
        </Prereq>[/code]

Including that code in an item or an improvement would cause it to be ONLY usable by a faction whose <RaceClassification> equals "White Golems".

The first tag appears not to be in use.

The second tag is a reference to something called a racetype. Racetypes are essentially schematics for allowing the user to construct custom factions and sovereigns from that particular racetype. In this example, I've referenced a racetype that doesn't exist, and this is perfectly valid.

These tags all define unittypes.

The first two tags are references to unittypes that the AI will use to select spouses for the AI automatically. In this example, I've been lazy as you can see. The golemking AI will spawn with a wraith spouse.

The third and fourth tags reference unittypes that are StartingType units. These unittypes must have the <IsStartingUnitType>1</IsStartingUnitType> tag. In addition, their <Gender> tags must equal the use of the unittypes in the raceconfig tags. <GenericUnitType_Male> must reference a unittype with the <Gender> set to 'Male'.

The first tag references a unittype that will function as a trader. For information on what a trader is, see the UnitTypes section.

The <StartingUnitType> tag references a unittype that will be automatically available to the player when he starts up the game. The default here is to include a pioneer and a basic peasant. These unittypes require the <IsStartingUnitType>1</IsStartingUnitType>.

The last tag references a unittype that will act as the shopkeeper for the faction. A shopkeeper is the model shown when the player browses the item store in a city.

Chooses the background for the faction, to be displayed behind the sovereign and the StartingType units when the player chooses a faction.

These tags are all inherited by StartingType units automatically, so when the player (or AI) designs a "new" unit, these values are automatically included in those unittypes.

The first tag defines the underlying skin-colour, that will appear underneath the skin texture of these models.

The second tag defines the underlying hair-colour that will apear underneath the texture of the hair model, if there is one.

The third tag appears not to be in use.

<UnitClothing1Color> and <UnitClothing2Color> defines various colours appearing on cloth items.

<UnitMetalColor> defines what colour will be used underneath weapon and armor textures for the unittypes.

These three tags further define how the cities of the faction will be coloured. I suggest you visit the in-game workshop -> Builder's forge and load up K_Study_01 and play around with the colours to get an idea of what these tags accomplish.

This defines the colour used for the "borders" of a faction's zone of influence. This colour also defines the colour of the "ring" around the crest when selecting factions, and the colour behind the name of the faction when choosing a faction to play. In addition, this colour will appear in your diplomatic efforts in the menus.

These tags appear not to function.

This tag defines what kind of environment the faction will spread. Possible values are 0, 1, 2, 3, 4. These represent, in order, the following environments: none, dead(empire), grassland(kingdom), desert, arctic.

Note that regardless of what is defined in the raceconfig in this tag, factions suffer and gain bonuses in environments based on their <FactionAllegiance>, not the <EnvironmentTerrainType> tag.

Unknown functions.

References a LogoType type. See CoreLogos.xml. This is the "crest" of the faction.

Unknown function.

This tag references a techdef (a technology) that is instantly available to the player. The techdef in question MUST be a part of the faction's tech tree. I never use this tag for anything, as there is a way to use AbilityBonuses to give factions techs that aren't part of their tech tree - see AbilityBonuses section for that.

This defines what spellbook will be automatically granted to sovereigns that play this faction. The tag contains a reference to a spellbook  - see Spells section for more on that.

This tag references a TechTree type. This effectively decides what tech tree a faction will have. More on this in the Techs section.

7. RaceConfigs

This will allow a Modder to have an object be placed and findable only on the Map via Goodie hut and or Quest?

Also think back on what tags you saw in part 1.

Added the third part. No, I've not teached.

You can discuss the answers here, full answers is ok (but you won't get them from me)

? See the line <InfoCardBackground>BG_GoodScene</InfoCardBackground> in the UnitType above. This is also a tag that references another type in the game files. What do you think the purpose of the tag is? Can you find out what file contains that referenced type? Can you figure out how it all connects? Look at the tags inside the referenced type

I found it in CoreInfoCardBackgrounds.xml,

From what I can guess, BG_GoodScene seems to access an image stored in gfx/BarracksBackground.png.  I would hazard a guess that the tag's purpose is to make it faster to access by calling BG_GoodScene instead of going to gfx/BarracksBackground.png?

Thanks for the tip on disabling the default buildings! As far as you know, does the game always take the modded version of the improvement when there are conflicting tags? I would have guessed that it would try to 'add' those tags as it does with resources (and thus cause problems).

Also I have a question about this part:

Does the value in the <PerTurn> tag have to be the same as in the <Value> tag? Because I believe I've seen it be different, and I couldn't figure out what that did..

Unfortunately, where possible, the game applies both, as in the case with production costs, etc. If it can't, sometimes the modded info will take precedence. But, occasionally, it will load both and randomly apply one or the other.

I thought that this was a binary value. If it's 1, it applies the Value each turn, if it's any other number, it doesn't. Has anyone seen behavior other than this?

It can have other values, I've seen 1, 2, and 3, both positive and negative..

Thats why I was confused, I thought it was a boolean as well, and the other values don't seem to do anything special as far as I can tell..