Guide to modding in Elemental (5/8 done)

By on January 6, 2011 9:29:57 AM from Elemental Forums Elemental Forums

Heavenfall

Join Date 07/2008
+436

 

 

 

Each of these sections will be divided into two areas: Basic and Advanced. Basic information is enough to get you started. Advanced information takes you all the way to the end of what I know (well, not all the way, but very close)

I will use the line "****************************" to indicate that I've removed significant parts from the quote. This is just so I don't have to keep quoting large examples with tags that you don't need right now.

I will also use large questionmarks like this ? to pose questions for you to solve. They are essentially exercises, to make sure you're on board. Yes, it's a bit childish, but if you can't solve the exercise, then you've misunderstood something in the tutorial and you'll have a hard time moving on.

1. Starting

2. Items

3. Improvements

4. UnitTypes

5. RaceConfigs

6. Abilitybonuses

7. Spells

8. Techs

 

If you are very eager to jump into the modding, I suggest you read only the first section. After that, you should be set to start copypasting various xml to create new things or modify existing content in the game.

Locked Post 45 Replies +3 Karma
Search this post
Subscription Options


Reason for Karma (Optional)
Successfully updated karma reason!
jshores
ArcElement2002
Wintersong
January 6, 2011 9:30:05 AM from Elemental Forums Elemental Forums

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.

    <UnitType InternalName="Kingdom_Pioneer">
        <DisplayName>Pioneer</DisplayName>
        <Description>Pioneers are equipped with the necessary materials to start new settlements.</Description>
       <ModelScale>1.3</ModelScale>
        <ModelPath>K_Male_Mesh_01.hkb</ModelPath>
        <InfoCardBackground>BG_GoodScene</InfoCardBackground>

        *************************

        <Equipment>PioneersKit</Equipment>
    </UnitType>

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

<GameItemType InternalName="PioneersKit">

                ************************

</GameItemType>

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.

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 9:30:10 AM from Elemental Forums Elemental Forums

2. Items

Basic

A new Weapon

Let's create a new weapon. For this, I have prepared a file here: http://pastebin.com/raw.php?i=TDnqNfEy

This is very nearly the exact same bow as one can find in game called Crude Bow. Putting that text inside a new xml file in your mod folder will overwrite the current crude bow in the game - but since it is almost exactly the same as the core file, there will be no difference from the standard game.

Let's go through the tags found in the weapon, in the order we see them.

<DisplayName>Crude Bow</DisplayName>
<Description>A crude bow made of driftwood and twine.</Description>

These are tags that contain string values read by the engine. The first one defines the name of the item. The second one defines the description of the item.

<Type>Weapon</Type>
<Type>Defense</Type>

<Type> tags inside an itemtype defines what slots the item occupies on the unit that equips the item. The type is Weapon, letting the engine know that if the unit equips this weapon, it cannot equip another item of the same kind. The type is ALSO Defense, letting the engine know that the unit cannot equip this item at the same time as a shield. If the player wanted a singlehanded weapon, he would completely remove the <Type>Defense</Type> value.

<WeaponType>Bow</WeaponType>

This defines what animations (how a unit moves and attacks) will be used in association with the weapon. Possible values are: Blunt, Spear, BluntTwo, Bow, OneHanded, TwoHanded. It is important to choose something that reflects the weapon you have, visually speaking. Using a crude bow as a Spear would look very odd!

<CanBeEquipped>1</CanBeEquipped>

This tag just lets us know that we can equip the item. If you don't have this tag, the item can be consumed like food.

        <EquipSFX>Equip_BowandArrow_01</EquipSFX>
        <EquipSFX>Equip_BowandArrow_02</EquipSFX>
        <EquipSFX>Equip_BowandArrow_03</EquipSFX>

        <AttackSFX>Hit_Arrow1</AttackSFX>
        <AttackSFX>Hit_Arrow2</AttackSFX>

These define what sound will be played when the weapon is equipped, and what sounds play when you attack with it. Note that the tag is used multiple times. We can assume that the engine chooses one of these values randomly. You will have to scrounge the current item files for SFX to use.

        <ShopValue>30</ShopValue>

This defines how much the item costs to purchase in the shop, if it is available. If this tag is not present in a gameitemtype, the game will estimate a value. If this value is set to -1, the item will not be available in the shop.

        <IconFile>Archer_Bow_Icon.png</IconFile>
        <TintR>0</TintR>
        <TintG>0</TintG>
        <TintB>0</TintB>

The first tag defines what icon you will see, when equipping the item. The Tint tags I think were meant to allow us to colour items, but appear not to function.

        <GameItemTypeModel>
            <ModelFile>Gfx\HKB\Items\Archer_Bow.hkb</ModelFile>
            <Texture_All>Gfx\HKB\Armor\K_Female_Armor_Archer_Texture_01.png</Texture_All>
            <Attachment>hand_Left_Lcf</Attachment>
        </GameItemTypeModel>

Note the container inside the container here - the <GameItemTypeModel> encompasses the other tags. This structure must be maintained.

First, the modelfile that is being used for the weapon is defined (.hkb). Then, the texture for the model is defined (.png). Not all models need a skin defined, some files have them pre-defined.

The <Attachment> tag is extremely important, as it tells the game where on the unit the item will be equipped. In this case, it tells the game the bow should go in his left hand (hand_Left_Lcf). All weapons except bows use "hand_right_Lcf".  Look in core files of items to find other Lcf points.

Items may have multiple <GameItemTypeModel> tags - for example, check out armors in CoreArmors.xml

        <ProductionRequirement>
            <Type>Resource</Type>
            <Attribute>Gold</Attribute>
            <Value>8</Value>
        </ProductionRequirement>

        <ProductionRequirement>
            <Type>Resource</Type>
            <Attribute>Materials</Attribute>
            <Value>4</Value>
        </ProductionRequirement>

These tags define the cost if the item is equipped to a designed unit (remember champions use the <ShopValue> when buying from the shop). From this XML we can deduce that the item makes the cost of a unit increase by 8 gold and 4 materials. The <Attribute> is a reference to secondary internal names of resources. For a list of secondary internal names of resources, go to to the core file CoreResources.xml. The secondary internal name is defined in the <Type> tag, for example, there is a resourcetype with the <Type>Gold</Type> and another one with <Type>Materials</Type>.

        <GameModifier>
            <ModType>Unit</ModType>
            <Attribute>AdjustUnitStat</Attribute>
            <StrVal>UnitStat_Attack</StrVal>
            <Value>4</Value>
        </GameModifier>
        <GameModifier>
            <ModType>Unit</ModType>
            <Attribute>AdjustUnitStat</Attribute>
            <StrVal>UnitStat_Accuracy</StrVal>
            <Value>-2</Value>
        </GameModifier>

These tags define the bonuses the unit gains from equipping the item (or the bonuses it gains from consuming it if <CanBeEquipped> is nonexistant). The <StrVal> is a reference to a unit stat. For a list of the unit stats, go to CoreUnitStats.xml in the core files. Note that in the example, the wearer gains 4 attack but actually lose 2 accuracy.

        <GameModifier>
            <ModType>Unit</ModType>
            <Attribute>UnlockRangedAction</Attribute>
            <StrVal>BasicBowAttack</StrVal>
        </GameModifier>

This is a special modifier that tells the game that it is in fact a bow weapon (and makes ranged attacks available). It will need to be included in any bow or ranged attack type item. Note that the <StrVal> is a reference to a spelldef.

        <AdditionalTrainingTurns>2</AdditionalTrainingTurns>

A value describing how many extra turns it will take to train a unit with this weapon.

        <Prereq>
            <Type>Tech</Type>
            <Attribute>Archery_Amarian</Attribute>
        </Prereq>

This makes the weapon demand a technology before it is available. <Attribute> is a reference. The weapon will not be available to the player unless the tech has been researched.

<Prereq>
       <Type>BuildingRequirement</Type>

        <Attribute>Archery Range</Attribute>
</Prereq>

This makes a unit designed with the weapon require that the town it is being trained in has a certain building. The <Attribute> tag is a reference to a value that is created in-between files. In this case, it requires an ImprovementType with this tag: <SpecialBuildingType>Archery Range</SpecialBuildingType>. 

        <Prereq>
<Type>Race</Type>
<Attribute>Men</Attribute>
</Prereq>

This prereq makes the item available only to the race of Men. The <Attribute> is a reference to a value that is created in-between files. In this specific case, this tag demands that the faction has, in its raceconfig, the following tag: <RaceClassification>Men</RaceClassification>.

        <Prereq>
<Type>Allegiance</Type>
<Attribute>Kingdom</Attribute>
</Prereq>

This makes the item only available to Kingdom factions. As of Elemental 1.1, Allegiance is always either Kingdom or Empire for a faction.

<IsAvailableForSovereignCustomization>False</IsAvailableForSovereignCustomization>

This tag decides whether or not the item is available when designing a sovereign. In this case, the value is False telling us it is not available. Remove the tags completely if you want them to be available.

<TacticalRange>6</TacticalRange>

The range of the bow, in value, in tactical combat.

 

There is one more tag I find useful for weapons:

<HeroOnly>1</HeroOnly>

This makes the item unavailable for designing units, and that means its only available in the shop.

 

? Think about what reasons a modder may have for making an item unavailable in the shop, and unavailable when designing units, and unavailable when designing a sovereign.

 

? Try to figure out what this item is intended for.

    <GameItemType InternalName="Secretnewitem">
        <DisplayName>Secret New item</DisplayName>
        <Description>You didn't think it would be that easy, would you?</Description>
    <ShopValue>10</ShopValue>
        <IconFile>SecretNewItem.png</IconFile>
        <TintR>0</TintR>
        <TintG>97</TintG>
        <TintB>0</TintB>
         <SFX>TurnPageMagical_03</SFX>
        <SFX>TurnPageMagical_02</SFX>
        <SFX>TurnPageMagical_01</SFX>
        <GameModifier>
            <ModType>Unit</ModType>
            <Attribute>UnitStat_Attack</Attribute>
            <Value>3.0</Value>
            <Duration>5</Duration>
        </GameModifier>
        <UsableInBattle>1</UsableInBattle>
    </GameItemType>

 

 

Modeltypes

If you take a look at armor in CoreArmor.xml, you will find several of these references:

        <SupportedUnitModelType>IroneerMale</SupportedUnitModelType>
        <SupportedUnitModelType>KingdomMale</SupportedUnitModelType>
        <SupportedUnitModelType>MancerMale</SupportedUnitModelType>
        <SupportedUnitModelType>TarthanMale</SupportedUnitModelType>

for most armor items.

These tags are requirements for when designing units, or buying items in the shop, or trying to equip a hero. The string is an in-between files variable that is called from this tag inside an item type, and from <UnitModelType>KingdomFemale</UnitModelType> inside a UnitType. In essence, an item with <SupportedUnitModelType>KingdomMale</SupportedUnitModelType> will only be usable by a UnitType with <UnitModelType>KingdomMale</UnitModelType> (obviously multiple <SupportedUnitModelType> tags are allowed inside an item).

The function of this in the current game is to provide two different sets of items - one for normal-sized units, and one for larger units called Fallen.

You'll notice that shields completely lack any <SupportedUnitModelType> tag. This means the item can be worn by anyone.

 


 

Advanced

Making items available in the shop

Note that the shop has certain special requirements for items to appear. Obviously, the modeltype must match. The prereq tech must also be unlocked. And the prereq race and prereq allegiance must fit.

However, what if you have a starter item you wish to add that doesn't require any technology? It won't appear in the shop. The answer is that you need to include, in the "cityhub" improvementtype (more on this below) this tag: <UnlocksShopItem>SaltedPork</UnlocksShopItem>. The reference is to the internal name of the gameitemtype.

Keep in mind that this applies only to the shop, not when designing units.


 

    <GameItemType InternalName="Mushroom">
        <!-- Item Display Name/Description -->
        <DisplayName>Mushroom</DisplayName>
        <Description>A rare type of mushroom that works wonders for the world-weary traveller.</Description>
    <ShopValue>10</ShopValue>
        <!-- Item Graphics -->
        <IconFile>gfx\items\Mushroom2.png</IconFile>
        <TintR>0</TintR>
        <TintG>97</TintG>
        <TintB>0</TintB>
        <!-- Item Sound FX -->
        <!-- Item Sound FX -->
        <SFX>TurnPageMagical_03</SFX>
        <SFX>TurnPageMagical_02</SFX>
        <SFX>TurnPageMagical_01</SFX>
        <!-- Item Modifiers -->
        <GameModifier>
            <ModType>Unit</ModType>
            <Attribute>CurHealth</Attribute>
            <Value>3.0</Value>
        </GameModifier>
        <UsableInBattle>1</UsableInBattle>
    </GameItemType>
Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 9:30:16 AM from Elemental Forums Elemental Forums

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.

    <DisplayName>Workshop</DisplayName>
    <Description>Workshops increase the Materials produced by the settlement by 1.</Description></Description>

Again, these tags are simply string values read into the game. The first tag defines its visual name, and the second tag its description. In this case, the description is showed in the tooltip when choosing a building to construct in a city.

    <TileDesign>K_Workshop_01</TileDesign>
    <ConstructionTileDesign>K_Workshop_Build_01</ConstructionTileDesign>

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.

    <SupportedTerrainType>Land</SupportedTerrainType>

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?

<DrawnIcon>Gfx/TacticalIcons/K_WorkCamp1.png</DrawnIcon>
    <DrawnIconConstruction>Gfx/TacticalIcons/K_WorkCamp1_C.png</DrawnIconConstruction>
    <Thumbnail>K_Workshop_Thumb_01.png</Thumbnail>

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.

    <IgnoreDuplicateImpLimit>true</IgnoreDuplicateImpLimit>

OR
   <AllowedPerCity>1</AllowedPerCity>
OR
   <AllowedPerFaction>1</AllowedPerFaction>
OR
   <AllowedPerGame>1</AllowedPerGame>

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.

    <Medallions>
      <All>K_Workshop_Thumb_01.png</All>
    </Medallions>

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

    <ReqCityLevel>1</ReqCityLevel>

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).

<RequiresCity>True</RequiresCity>

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).

    <GameModifier InternalName="Production1">
      <ModType>Resource</ModType>
      <Attribute>Materials</Attribute>
      <Value>1.0</Value>
      <PerTurn>1</PerTurn>
    </GameModifier>

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.

    <GameModifier>
      <ModType>Resource</ModType>
      <Attribute>Gold</Attribute>
      <Value>-1.0</Value>
      <PerTurn>-1</PerTurn>
    </GameModifier>

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.

    <GameModifier>
      <ModType>ConstructionResourceCost</ModType>
      <Attribute>AvailableSpecialists</Attribute>
      <Value>-5</Value>
    </GameModifier>

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]

    <LaborToBuild>5.0</LaborToBuild>

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.

    <AIData AIPersonality="AI_General">
      <AITag>Workshop</AITag>
    </AIData>

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:

        <RequiresResource>True</RequiresResource>
        <SupportedResourceType>Wargs</SupportedResourceType>

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:

<UpgradesToImprovement>F_Shanty</UpgradesToImprovement>

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.

    <GameModifier InternalName="Production1">
      <ModType>Resource</ModType>
      <Attribute>Materials</Attribute>
      <Value>1.0</Value>
      <PerTurn>1</PerTurn>
      <Provides>Creates 1 material per turn</Provides>
    </GameModifier>

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:

    <RequiresCityImprovements>1</RequiresCityImprovements>
    <RequiredImprovement>E_Earth_Shrine</RequiredImprovement>
    <RequiredImprovement>E_Air_Shrine</RequiredImprovement>
    <RequiredImprovement>E_Fire_Shrine</RequiredImprovement>
    <RequiredImprovement>E_Water_Shrine</RequiredImprovement>
    <RequiredImprovement>E_Greater_Earth_Shrine</RequiredImprovement>
    <RequiredImprovement>E_Greater_Air_Shrine</RequiredImprovement>
    <RequiredImprovement>E_Greater_Fire_Shrine</RequiredImprovement>
    <RequiredImprovement>E_Greater_Water_Shrine</RequiredImprovement>

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:

  <ImprovementType InternalName="tutorial_Workshop">

    <GameModifier InternalName="Production1">
      <ModType>Resource</ModType>
      <Attribute>Materials</Attribute>
      <Value>1.0</Value>
      <PerTurn>1</PerTurn>

    </GameModifier>
  </ImprovementType>

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:

    <Prereq>
      <Type>Allegiance</Type>
      <Attribute>Nonexistant</Attribute>
    </Prereq>

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:

        <TileDesign>F_Outpost_02_v2</TileDesign>
        <TileStagePopulation>2</TileStagePopulation>
        <TileStageDesign>F_Outpost_03</TileStageDesign>
        <TileStagePopulation>4</TileStagePopulation>
        <TileStageDesign>F_Outpost_04</TileStageDesign>
        <TileStagePopulation>7</TileStagePopulation>
        <TileStageDesign>F_Outpost_05</TileStageDesign>
        <TileStagePopulation>10</TileStagePopulation>
        <TileStageDesign>F_Outpost_06</TileStageDesign>
        <TileStagePopulation>14</TileStagePopulation>
        <TileStageDesign>F_Outpost_02</TileStageDesign>

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.

        <ZOCMinRadius>1</ZOCMinRadius>
        <ZOCMaxRadius>3</ZOCMaxRadius>
        <ZOCRadiusTurnsBeforeUpdate>10</ZOCRadiusTurnsBeforeUpdate>

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>50</BuildableTiles>
        <CitywideDuplicateImpLimit>1</CitywideDuplicateImpLimit>

<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.

    <GameModifier InternalName="L1_Storage_Population">
      <ModType>ResourceStorage</ModType>
      <Attribute>Population</Attribute>
      <Value>10.0</Value>
      <Cumulative>true</Cumulative>
    </GameModifier>

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.

   <GameModifier InternalName="L1_LevelCap">
      <ModType>LevelBarrier</ModType>
      <Attribute>Population</Attribute>
      <Value>15.0</Value>
      <CityUpgrade>F_Capital_L2</CityUpgrade>
    </GameModifier>

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.

    <GameModifier>
        <ModType>City</ModType>
        <Attribute>AdjustDefendingUnit</Attribute>
        <Value>5</Value>
        <Operator>+</Operator>
        <StrVal>UnitStat_HitPoints</StrVal>
        <PerTurn>1</PerTurn>
    </GameModifier>

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

        <UnlocksShopItem>GnarledClub</UnlocksShopItem>
        <UnlocksShopItem>Staff</UnlocksShopItem>

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. http://forums.elementalgame.com/404727

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 9:30:22 AM from Elemental Forums Elemental Forums

4. UnitTypes

Basic

UnitTypes

Generally speaking, unittypes are used to define a particular unit in-game - such as a monster, a champion, a summoned monster and so on. I will begin with a general overview of the unittype container, then I will describe how to differentiate these different groups from each other - each different sort of unittype will need different tags.

First, I've posted the xml of a unit here: http://pastebin.com/raw.php?i=CUwX44qS .

Let's go through the tags from the top.

        <DisplayName>Guardian</DisplayName>
        <BackStory>Hiergamenon entry</BackStory>
        <Quote>'Any invading force will dine upon my blade.'</Quote>

These are all string values read by the engine. DisplayName dictates the name of the unit. BackStory dictates the Hiergamenon entry for the unit (listed as "history"). The Quote is the quote seen on the infocard of the unit.

        <ModelPath>Gfx\HKB\Units\K_Male_Mesh_01.hkb</ModelPath>
        <SkeletonPath>Gfx\HKB\Units\K_Male_Skeleton_01.hkb</SkeletonPath>

These define the modelpath and the skeletons used for the unit. Note that these must "match", in the sense that the model must be built specifically for the model. Unless you are tampering with making new models, simply gather the information you need from the core files.

        <EyeTexture>gfx\eyes\blinks\eyeblink_m4_blk.png</EyeTexture>

This defines the eye texture of the unit. Note that not all units have eyes, but this tag must nevertheless be included in all unittypes.

        <AnimationPack>SoldierAnimationPack</AnimationPack>

This defines the animationpack used by the unit. If you are copying a monster or a mount or anything non-humanoid, you'll want to copy what animationpack to use as well. For a list of all the animationpacks, visit your installation directory and navigate to ...\Elemental\data\Animations\. If you simply wish to find an appropriate animationpack for a unit, I suggest you create a new sovereign, choose a cool animationpack and then copy the tag reference from the sovereign xml.

        <ShowAsSingleUnit>false</ShowAsSingleUnit>

This tag lacks purpose.

        <ModelScale>1.0000</ModelScale>
        <EquipmentScale>1.0000</EquipmentScale>
        <ClothMapScale>1.2000</ClothMapScale>

These tags define certain scales used to make things larger or smaller. However, they can be quite troublesome to use.

First, if a unit has a <ModelScale> OTHER than 1, any <gameitemtypemodel> (used to define models for items, remember?) that requires the tag <AttachmentType>Skinned</AttachmentType> will render incorrectly. This fact means that most humanoid unittypes can not simply be increased in size, because their heads are in reality gameitemtypemodels with the tag <AttachmentType>Skinned</AttachmentType>.

Secondly, <EquipmentScale> seems to scale inversely with the ModelScale used. If I were to give a unit ModelScale 2.0, I would then be forced to give it an equipmentscale of 0.5.

<ClothMapScale> appears to tell us the upper limit of the size of the unit on the cloth map. Let's say I assign a unit a ModelScale of 4. This unit would be insanely large. However, we might not want it to appear that way on the cloth map. We can then use <ClothMapScale> to override that value.

        <MovementType>land</MovementType>

Tells us where the unit can move. Values are land, air or water. Air units may cross any tile, and may carry any unit with them while doing so. Water units may cross any water tile, and beaches, and carry any unit with them while doing so. Land units are the default type, and may not cross water or cliffs or mountains. Note that Air units still suffer movement penalty while moving through forest tiles.

        <BobbingFrequency>0.0000</BobbingFrequency>

Unknown. Bobbing in units is usually associated with a first person view. Possibly a hint that at one point players would be able to view the game through that perspective.

        <ClothPoseIndex>0</ClothPoseIndex>
        <InfoCardBackground>BG1_Sunset</InfoCardBackground>
        <InfoCardBackgroundFlipped>0</InfoCardBackgroundFlipped>

These tags all define what the tooltip and infocard of a unit will look like. ClothPoseIndex seems to reference a list, but I haven't found it in the game XML. Values can vary from 0 to 16 (possibly higher), or up to 3 for mounted units. ClothPoseIndex essentially defines what pose the unit will have on its infocard.

<InfoCardBackground> tells the game what background the unit should have on tooltips and its infocard. It is a reference to types found in CoreInfoCardBackgrounds.xml.

<InfoCardBackgroundFlipped> is a simple 0 or 1, depending on if you want the <InfoCardBackground> flipped horizontally or not (0 = not flipped).

 

        <MovingSFX>TEMP_KnightMarching1</MovingSFX>

What sound the unit plays while moving.

        <LevelMilestone InternalName="">
            <Level>1</Level>
            <UnitStat_Charisma>10.0000</UnitStat_Charisma>
            <UnitStat_CombatSpeed>2.0000</UnitStat_CombatSpeed>
            <UnitStat_Constitution>5.0000</UnitStat_Constitution>
            <UnitStat_Essence>0.0000</UnitStat_Essence>
            <UnitStat_ExpToNextLevel>20.0000</UnitStat_ExpToNextLevel>
            <UnitStat_Experience>5.0000</UnitStat_Experience>
            <UnitStat_HitPoints>0.0000</UnitStat_HitPoints>
            <UnitStat_Intelligence>10.0000</UnitStat_Intelligence>
            <UnitStat_Sight>3.0000</UnitStat_Sight>
        </LevelMilestone>

Note that the LevelMileStone is a sub-container of the unittype container. It contains tags of various unit stats. These milestone tags can NOT be used to define how a unit will change as it levels up - a trained unit always assumes the stats of level 1.

Milestones can be used to increase difficulty of world monsters, however. See CoreMonsterUnitTypes.xml for examples on how to make higher level monsters have different stats compared to the level 1 version.

        <Equipment>F_Head_Wraith_Mesh_01</Equipment>
        <Equipment>Broadsword</Equipment>
        <Equipment>MasterHeavyPlateHelmet</Equipment>
        <Equipment>MasterHeavyPlateBreastpiece</Equipment>
        <Equipment>SoldiersCloak</Equipment>
        <Equipment>MasterHeavyPlateArmlets</Equipment>
        <Equipment>MasterHeavyPlateGreaves</Equipment>
        <Equipment>BasicHorseMount</Equipment>
        <Equipment>BandOfTheStalwart</Equipment>
        <Equipment>AmuletOfWarding</Equipment>
        <Equipment>ScoutsPack</Equipment>
        <Equipment>WardOfDefense</Equipment>
        <Equipment>MasterHeavySteelShield</Equipment>

The equipment tag defines what items the unit is wearing. Notice how the head is treated as an item, and not part of the body. If an item has a prerequisite for technology before it can be built, this is inherited by the unittype (you cannot train a legendary plate helm wearer until you've researched legendary plate helm). If the unit had hair, it would also be listed as a piece of equipment.

        <Color_Hair>160,115,80,255</Color_Hair>
        <Color_Skin>202,137,87,255</Color_Skin>
        <Color_Clothing1>120,25,20,255</Color_Clothing1>
        <Color_Clothing2>78,60,55,255</Color_Clothing2>
        <Color_Metal>145,145,145,255</Color_Metal>
        <Color_Primary>165,145,130,255</Color_Primary>
        <Color_Secondary>75,60,50,255</Color_Secondary>
        <Color_Roof>90,15,10,255</Color_Roof>
        <Color_TerrainBlend>255,255,255,255</Color_TerrainBlend>
        <Color_TerrainOnly>255,255,255,255</Color_TerrainOnly>
        <Color_Trans>255,255,255,255</Color_Trans>
        <Color_ScrollTransMask>255,255,255,255</Color_ScrollTransMask>
        <Color_Eyes>255,255,255,255</Color_Eyes>
        <Color_Crest>255,255,255,255</Color_Crest>

These tags define underlying colours of models used inside the unittype. The values are in RGB format, and the fourth value lacks apparent purpose. For a unittype, the only important things here are <Color_Hair>, <Color_Skin>, <Color_Clothing1>, <Color_Clothing2> and <Color_Metal>.

If you wish to test colours in-game, I suggest you create a custom sovereign and play around with his colours.

        <Texture_Skin>K_Male_Groomed_Texture_01.png</Texture_Skin>
        <Texture_Eyes>gfx\eyes\blinks\eyeblink_m4_blk.png</Texture_Eyes>

The first tag defines what texture will be used on the body and head of a unit. For a list of valid textures, see CoreSkins.xml. If you are designing monsters, copy the skin file call from the core files.

The second tag, again, defines what texture will be used on the eyes of the head of a unit. I suggest that you give this the same value as you gave <EyeTexture>.

        <Gender>Male</Gender>
        <UnitModelType>KingdomMale</UnitModelType>

First, the gender is telling us what the gender of the unittype is. This is used for two things - champions being eligible for marrying, and StartingType units (see below).

Second, the UnitModelType has already been covered in the Items section of this guide. The unitModelType helps define what pieces of clothing it can and can't wear. In addition, the UnitModelType helps assign random skins, heads, hair and clothes to a unit (see advanced section for more on this).

 

Those are all the "default" tags, you'll need them for any unittype. The rest of the tags are actually used to tell the engine what kind of unit this is. Now I will describe how to differentiate between the unittypes.

 

 

Treating a unittype as if it was designed by the user

        <CanBeDesigned>1</CanBeDesigned>
        <UserDesigned>true</UserDesigned>
        <CreatorFactionName>KingdomOfAltar</CreatorFactionName>

<CanBeDesigned> tells us that this unit can be put in the training window - it can be trained. In addition, the tag is telling the engine that if this unit is available, it can be used to design other sorts of units based on this unittype - essentially Upgrading them in the unit design window in-game.

<UserDesigned> lets the engine know that this unittype has been designed by the user. This means it can be deleted using the Retire Button.

<CreatorFactionName> references a RaceConfig (a faction), and the unit may only be built for this faction.

 

 

Treating a unittype as if it was a champion

Take a look at CoreNPCunits.xml. I have no experience with this.

 

 

Treating a unittype as if it was a monster

<CanBeDesigned>0</CanBeDesigned>
<SpawnRating>5</SpawnRating>

The first tag tells the engine this unit can't be trained.

The second tag appears to be the only tag that defines what a monster is. The spawnrating value is defining at what research level the unit will start spawning. Note that the <SpawnRating> tag is used for champions as well, but champions have additonal tags to separate them from monsters.

 

 

Treating a unittype as if it was a sovereign


<CanBeDesigned>0</CanBeDesigned>
<IsSovereign>1</IsSovereign>

The first tag tells the engine this unit can't be trained.

The second tag defines the unittype as a sovereign, allowing it to show up when the player is choosing a sovereign to play the game with. Some unittypes will contain an <IsSovereign> tag with a value of 0. This seems to serve no purpose.

 

 

Treating a unittype as if it was a diplomacy unit

    <IgnoreItemTrainingCosts>1</IgnoreItemTrainingCosts>

   <ProductionRequirement>
      <Type>Resource</Type>
      <Attribute>Gold</Attribute>
      <Value>50.0</Value>
    </ProductionRequirement>

    <RequiresCityUnlock>1</RequiresCityUnlock>
    <Prereq>
      <Type>BuildingRequirement</Type>
      <Attribute>DarklingRecruiting</Attribute>
    </Prereq>

    <CanBeDesigned>1</CanBeDesigned>
    <IsUniqueButBuildable>1</IsUniqueButBuildable>

The first tag is a switch that lets the engine know this unit should ignore the additional training time associated with a certain weapon. The weapon still causes the unit to cost resources.

The <ProductionRequirement> set of tags is the same as seen in improvements or items. In this case, the unit costs 50 gildar to train.

<RequiresCityUnlock>1</RequiresCityUnlock> defines the unit as something that needs to be unlocked by a particular building in a city before it is available. What building is needed is defined in the following <Prereq> set of tags.

<CanBeDesigned> defines the unit as something that can be trained and <IsUniqueButBuildable>1</IsUniqueButBuildable> lets the engine know that this unit cannot be upgraded by the user in the unit design window.

Note that the game gathers information from the improvementtype containing the BuildingRequirement attribute, in the example DarklingRecruiting. If the improvementtype is available only when built on a world resource, the unittype will only appear in a city once it is connected to that improvementtype. However, if the improvementtype does not require a world resource to be built, the unittype will be available in every city but greyed out - for an example of this, see the Empire Sion unit.

 

 

Treating a unittype as if it was a startingtype unit

A startingtype unit is a unit that is a schematic unit that is visible when selecting a certain faction

Note that the RaceConfig defining a faction is ultimately responsible for how these units are treated, depending on what tag the raceconfig references the unittype from. More of this in the raceconfig section.

These tags are necessary for a startingtype unit:

    <CanBeDesigned>1</CanBeDesigned>
    <IsStartingUnitType>1</IsStartingUnitType>

In addition, a startingtype unit should NOT include ANY of the colour tags as listed above for all unittypes. These colours are instead inherited from the raceconfig.

These startingtype units are what the game draws from, for a faction, when the player opens up the unit design window and clicks "new unit". These startingtype units are similarly used by the AI when it automatically designs units to use.

 

 

Making a unit cost "used population"

    <ProductionRequirement>
      <Type>Resource</Type>
      <Attribute>AvailableSpecialists</Attribute>
      <Value>1.0</Value>
    </ProductionRequirement>

The same use as in improvementtypes. Values may vary.

 

 

Inheriting tags

It is important to note that when you "upgrade" a unit, the tags within that unittype are all inherited to the new unittype created. This can be used to, for example, create a line of units that all have a certain skin colour. Of course, if the player upgrades a unit, then randomizes its appearance using the randomize button, the random things (discussed in the advanced section) will all be rerolled according to UnitModelType.

 

? If I wanted to make a startingtype unit cost 1 food, how would I achieve that? How do you think the AI would react to this?

? I have not covered how to create a unittype intended for summoning. Why do you think that is?

 

 

 


 

Advanced


Making a unit "unique"

<AllowGrouping>0</AllowGrouping>

This will prevent the unit from being trained in groups. Dragons and demons are examples.

 

 

Making a unit stay in the center of the tile

    <AlwaysInTileCenter>1</AlwaysInTileCenter>

This will prevent a unit from leaving the center of a tile in tactical combat. Units will by default "move to the edge of the tile" when attacking or defending. This makes them always stay in the center of the tile. It is suitable for "unique" units, or for very large units.

 

 

Making a unit cost extra turns to train

        <AdditionalTrainingTurns>0.0000</AdditionalTrainingTurns>

0 by default, this value can be both positive and negative. Units cost 3 turns, which is defined elsewhere, to train by default in the game. If the value of this tag was 2, the unit would take 5 turns to train.

 

 

Wage override to a value

<WageOverride>0.0000</WageOverride>

This tag can be used to override the wage assigned to a unit when it is trained. If this value is 0, the tag is not in use. If this value is above 0, the value automatically replaces the wage cost of the unit. If I wanted to design a unit that would appear to have no wage, but still defect if there were no gildar in the kingdom/empire, I would give this a value of 0.00001.

 

 

Wage override to nothing

    <HasWages>F</HasWages>

This tag overrides any wage the unit will be assigned when trained, and the unit will permanentally cost 0.0000000 gildar per turn in upkeep.

 

 

Making a unit's attacks use an in-game effect


    <OnAttackParticleName>referencetoeffect</OnAttackParticleName>

With this, a unit will display an effect on an enemy whenever it attacks in tactical combat

 

Making a unit display an effect when attacked

    <OnHitParticleName>referencetoeffect</OnHitParticleName>

Similarly, this will display a certain effect on the body of the unit if it is attacked in tactical combat

 

 

Overriding the auto-generated tooltips and infocard pictures

If you don't want to show an autogenerated picture for a unit, you can include this:

    <Medallions InternalName="">
      <All>M_Golem_Card_01.png</All>
    </Medallions>

 

 

 

Randomized clothes, heads, hairstyles and skins

Now that you've learned what a <UnitModelType> is, and what a StartingType unit is, let's talk about how skins, clothes, hairstyles and heads are randomly chosen when designing a "new" unit.

This is an example of a head:

  <GameItemType InternalName="K_Female_Head_01">
    <Type>Face</Type>
    <DisplayName>Kingdom - Sovereign Female Head 1</DisplayName>
    <SupportedUnitModelType>KingdomFemale</SupportedUnitModelType>
    <SupportedUnitModelType>IroneerFemale</SupportedUnitModelType>
    <SupportedUnitModelType>AmarianFemale</SupportedUnitModelType>
    <SupportedUnitModelType>MancerFemale</SupportedUnitModelType>
    <IconFile>K_Female_Head_Icon_01.png</IconFile>
    <CanBeEquipped>1</CanBeEquipped>
    <RandomPeasantUnitLiklihood>50</RandomPeasantUnitLiklihood>
    <RandomMerchantUnitLiklihood>50</RandomMerchantUnitLiklihood>
    <RandomHeroUnitLiklihood>50</RandomHeroUnitLiklihood>
    <!--Item Graphics-->
    <GameItemTypeModel>
      <ModelFile>Gfx\HKB\Units\K_Female_Head_Mesh_01.hkb</ModelFile>
      <AttachmentType>Skinned</AttachmentType>
    </GameItemTypeModel>
  </GameItemType>

Note the <SupportedUnitModelType>, defining what modeltypes this face may be randomly assigned to. Note the <RandomPeasantUnitLiklihood> tag and its other formats, defining the likelihood of this particular face appearing. Lilklihood tags are weighted against each other - if three faces each have 50 liklihood, then they have a 33% chance of appearing. However, if two faces have 50 and one head has 100, the last head has a 50% chance of appearing.

Hairstyles are generated the same way

  <GameItemType InternalName="Sovereign_Short_Hair_01">
    <Type>Head</Type>
    <Subtype>Hair</Subtype>
    <DisplayName>Short Peasant Hair</DisplayName>
    <SupportedUnitModelType>KingdomMale</SupportedUnitModelType>
    <SupportedUnitModelType>MancerMale</SupportedUnitModelType>
    <SupportedUnitModelType>AmarianMale</SupportedUnitModelType>
    <SupportedUnitModelType>EmpireMale</SupportedUnitModelType>
    <IconFile>Hair_PeasantSHORT.png</IconFile>

    <!--Item Equip Information-->
    <CanBeEquipped>1</CanBeEquipped>
    <HeroOnly>1</HeroOnly>
    <RandomPeasantUnitLiklihood>80</RandomPeasantUnitLiklihood>
    <RandomMerchantUnitLiklihood>30</RandomMerchantUnitLiklihood>
    <RandomHeroUnitLiklihood>5</RandomHeroUnitLiklihood>

    <!--Item Graphics-->
    <GameItemTypeModel>
      <ModelFile>Gfx\HKB\Hair\K_Male_Hair_Short_Mesh_01.hkb</ModelFile>
      <AttachmentType>Skinned</AttachmentType>
      <Texture_Hair>Gfx\HKB\Hair\K_Male_Hair_Texture_01.png</Texture_Hair>
    </GameItemTypeModel>

  </GameItemType>

And so are clothes.

But these gameitemtypes appear to have nothing special about them, except the liklihood tags. This is not enough to make clothes and such be automatically generated when you are designing a new unit.

In fact, the engine is hardcoded to look for certain <Type> and <Subtype> tags in gamefiles. For example, clothes all have the <SubType>Clothes</SubType> tag.

 

Skins are handled differently. When designing a new unit, the game draws skins from a series of UnitSkinTextureDef such as this:

  <UnitSkinTextureDef InternalName="Unit_Skin_Texture_Sovereign_Plain">
    <DisplayName>Male Sovereign Skin - Default</DisplayName>
    <Icon>K_Male_Default_Icon_01.png</Icon>
    <SkinTextureFilename>K_Male_Default_Texture_01.png</SkinTextureFilename>
    <SupportedUnitModelType>MancerMale</SupportedUnitModelType>
    <SupportedUnitModelType>AmarianMale</SupportedUnitModelType>
    <SupportedUnitModelType>EmpireMale</SupportedUnitModelType>
    <RandomPeasantUnitLiklihood>50</RandomPeasantUnitLiklihood>
    <RandomMerchantUnitLiklihood>50</RandomMerchantUnitLiklihood>
    <RandomHeroUnitLiklihood>50</RandomHeroUnitLiklihood>
  </UnitSkinTextureDef>

If a modeltype has NO UnitSkinTextureDef assigned to it, it will always default to the <Skin_Texture> the unittype has. However, if it HAS a UnitSkinTextureDef or more assigned to it, it will always randomly change out the skin of the StartingUnit.

 

 

Caravans, traders and shopkeepers

There are more tags that will make units show non-standard behaviour.

Caravans are not referenced in the raceconfig, but traders and shopkeepers are.

A caravan will have the following tag

<IsCaravan>1</IsCaravan>

This tag has two functions: first the unit may not be grouped with any other unit. And in addition the unittype automatically costs "available caravans" from a city.

A trader will also have the <IsCaravan> tag. A trader is a unit that automatically replaces the caravan once it has established its route (when it reaches a city it wasn't built in).

A shopkeeper unittype is the unit that will show when the player visits the item shop in a city. It has no special tags, but is uniquely identified in the raceconfig.

 

? Knowing that heads are in fact randomized gameitemtypes, how can we use this to give units designed by the AI random bonuses? Why is it a bad idea to do the same for clothes and hairstyles?

 

 

 

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 9:30:30 AM from Elemental Forums Elemental Forums

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.

    <DisplayName>Empire of the Golem King</DisplayName>
    <Capital>Teza</Capital>
    <ShortName>the Golem King</ShortName>
    <LeaderName>Emperor Stormlord</LeaderName>
    <PopulaceName>White Golem</PopulaceName>

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.

<Description>*********************
    </Description>
    <BonusesDesc>
    </BonusesDesc>

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.

    <Alignment>Evil</Alignment>
    <FactionAllegiance>Empire</FactionAllegiance>

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.

    <SovereignUnitType>expandedfactions_golemking_sovereign</SovereignUnitType>

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

    <SelAbilityBonusOption>expandedfactions_golemking_noterritoryBonus1</SelAbilityBonusOption>
    <SelAbilityBonusOption>expandedfactions_golemking_noterritoryBonus2</SelAbilityBonusOption>
    <SelAbilityBonusOption>expandedfactions_golemking_EgalitarianBonus2</SelAbilityBonusOption>  
    <SelAbilityBonusOption>expandedfactions_golemking_EgalitarianBonus4</SelAbilityBonusOption>
    <SelAbilityBonusOption>expandedfactions_golemking_EgalitarianBonus5</SelAbilityBonusOption>
    <SelAbilityBonusOption>expandedfactions_golemking_EgalitarianBonus3</SelAbilityBonusOption>

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

    <MusicTheme>EasternWardrums</MusicTheme>

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

Quoting ,

    <DefaultCityWallSet>CityWalls_Fallen_Fence</DefaultCityWallSet>

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.

    <NewCityHubType>F_Outpost</NewCityHubType>
    <CapitalHubType>expandedfactions_golemking_F_Capital</CapitalHubType>

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.

    <RaceClassification>White Golems</RaceClassification>

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".

    <RaceDisplayName>White Golems</RaceDisplayName>
    <RaceInternalName>expanded_factions_golemking_racetype</RaceInternalName>

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.

    <MaleUnitType>Wraith_Sovereign_Male_Basic</MaleUnitType>
   <FemaleUnitType>Wraith_Sovereign_Female_Basic</FemaleUnitType>

    <GenericUnitType_Male>expandedfactions_golemking_GenericBaseUnit_Male</GenericUnitType_Male>
    <GenericUnitType_Female>expandedfactions_golemking_GenericBaseUnit_feMale</GenericUnitType_Female>

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'.


    <TraderUnitType>expandedfactions_golemking_TraderTest</TraderUnitType>
    <StartingUnitType>Expandedfactions_golemking_Soldier</StartingUnitType>
    <StartingUnitType>expandedfactions_golemking_Pioneer</StartingUnitType>
    <ShopkeeperUnitType>expandedfactions_golemking_Shopkeeper</ShopkeeperUnitType>

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.

    <ChooseFactionBack>BG23_White.png</ChooseFactionBack>

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

    <UnitSkinColor>200,200,200,255</UnitSkinColor>
    <UnitHairColor>50,50,65</UnitHairColor>
    <UnitScale>1.0</UnitScale>
    <UnitClothing1Color>30,65,100</UnitClothing1Color>
    <UnitClothing2Color>50,50,60</UnitClothing2Color>
    <UnitMetalColor>150,150,150,255</UnitMetalColor>

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.

    <BuildingPrimaryColor>200,200,200</BuildingPrimaryColor>
    <BuildingSecondaryColor>200,200,200</BuildingSecondaryColor>
    <BuildingRoofColor>200,200,200</BuildingRoofColor>

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.

    <ZoneOfControlColor>159,181,207</ZoneOfControlColor>

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.

    <BuildingStyle>
    </BuildingStyle>
    <UnitStyle>
    </UnitStyle>

These tags appear not to function.

    <EnvironmentTerrainType>4</EnvironmentTerrainType>

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.

    <NonBuildableEnvironmentType>GrasslandEnvironment</NonBuildableEnvironmentType>
    <PreferredLeader>Mr. Athos</PreferredLeader>

Unknown functions.

    <PreferredLogoType>GenericCrest32</PreferredLogoType>

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

    <WorkerName>Captain Jack</WorkerName>
    <WorkerName>Roger</WorkerName>
    <WorkerName>Wilhelm</WorkerName>

Unknown function.

<KnownStartingTech>K_Civilization_General</KnownStartingTech>

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.

    <Spellbook>LifeSpellbook</Spellbook>

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.

    <TechTree>expandedfactions_techtree_golemking</TechTree>

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

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 9:30:36 AM from Elemental Forums Elemental Forums

6. UnitTypes

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 9:30:44 AM from Elemental Forums Elemental Forums

7. RaceConfigs

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 9:30:51 AM from Elemental Forums Elemental Forums

8. Who knows

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 3:29:33 PM from Elemental Forums Elemental Forums

? Think about what reasons a modder may have for making an item unavailable in the shop, and unavailable when designing units, and unavailable when designing a sovereign.

 

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

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 4:36:56 PM from Elemental Forums Elemental Forums

Following... Thanks Heavenfall!

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 5:11:08 PM from Elemental Forums Elemental Forums

Quoting John_Hughes,
? Think about what reasons a modder may have for making an item unavailable in the shop, and unavailable when designing units, and unavailable when designing a sovereign.

 

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.

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 5:49:19 PM from Elemental Forums Elemental Forums

Good work Heavenfall!

Have you done technical writing or teaching? It is not easy to pitch technical info in a way that informs the reader so well.

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 6:24:40 PM from Elemental Forums Elemental Forums

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

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 6:55:17 PM from Elemental Forums Elemental Forums

WOW, thanks so much!  This is incredibly useful!  Do we post answers to questions here, or would you prefer we just answer it ourselves so that other people can have a try at answering?  Thanks!

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 7:04:22 PM from Elemental Forums Elemental Forums

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

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 7:14:47 PM from Elemental Forums Elemental Forums

Wonderful!

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 7:50:08 PM from Elemental Forums Elemental Forums

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,

Code: xml
  1.   <InfoCardBackground InternalName="BG_GoodScene">    
  2. <Image>gfx/BarracksBackground.png</Image>  
  3. </InfoCardBackground>

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?

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 7:59:03 PM from Elemental Forums Elemental Forums

Quoting Heavenfall,


? Think about what reasons a modder may have for making an item unavailable in the shop, and unavailable when designing units, and unavailable when designing a sovereign.

 

? Try to figure out what this item is intended for.


    <GameItemType InternalName="Secretnewitem">
        <DisplayName>Secret New item</DisplayName>
        <Description>You didn't think it would be that easy, would you?</Description>
    <ShopValue>10</ShopValue>
        <IconFile>SecretNewItem.png</IconFile>
        <TintR>0</TintR>
        <TintG>97</TintG>
        <TintB>0</TintB>
         <SFX>TurnPageMagical_03</SFX>
        <SFX>TurnPageMagical_02</SFX>
        <SFX>TurnPageMagical_01</SFX>
        <GameModifier>
            <ModType>Unit</ModType>
            <Attribute>UnitStat_Attack</Attribute>
            <Value>3.0</Value>
            <Duration>5</Duration>
        </GameModifier>
        <UsableInBattle>1</UsableInBattle>
    </GameItemType>


 

I think I finally figured out how to use quotes.  For the first question, I didn't have an answer, but John_Hughes answer seems right.  For the second... It's an item you can buy at the shop for 10 gildar and is a consumable potion-like item you can use in tactical battle (maybe only usable in tactical battle) that increases attack by 3?

edit: increases attack by 3 for 5 turns?

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 9:10:11 PM from Elemental Forums Elemental Forums

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:

<GameModifier>
      <ModType>Resource</ModType>
      <Attribute>Gold</Attribute>
      <Value>-1.0</Value>
      <PerTurn>-1</PerTurn>
    </GameModifier>

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..

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 9:14:05 PM from Elemental Forums Elemental Forums

Core files are always read before mod files, so mod files are processed after core files.

It can be any number it seems, I would guess it can't be 0.

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 9:20:14 PM from Elemental Forums Elemental Forums

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).

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.

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..

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?

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 9:24:46 PM from Elemental Forums Elemental Forums

So the <PerTurn> tag is really just a boolean that when included adds or removes whatever is between the <Value></Value> tags, and what is between the <PerTurn></PerTurn> tags doesn't matter (as long as it is not 0)?

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 9:27:48 PM from Elemental Forums Elemental Forums

Quoting LightofAbraxas,

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..

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 9:28:38 PM from Elemental Forums Elemental Forums

Well, I know that a PerTurn of 1 does apply the value and 0 doesn't, but I haven't tested any other values. I just assumed that it was a Boolean.

Huh. Do these other values do anything special?

Reason for Karma (Optional)
Successfully updated karma reason!
January 6, 2011 9:39:51 PM from Elemental Forums Elemental Forums

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..

Reason for Karma (Optional)
Successfully updated karma reason!
Stardock Forums v1.0.0.0    #108433  walnut3   Server Load Time: 00:00:00.0001438   Page Render Time: