Modding Basics: XML 101

So you want to give Vikings Berzerker Axes instead of Berzerker Macemen?

As it happens, you can do this in Civ4. This is a simple tutorial on how to understand and read XML, and how to make a really simple XML mod.

I'm going to assume you have Warlords installed. If you don't, just remove the \Warlords\ part from the file paths, and most of the rest of the advice will work.

...

First, let's poke around.

Look in the following directory.
C:\Program Files\Firaxis Games\Sid Meier's Civilization 4\Warlords\Assets

There are a bunch of subdirectories in this folder.
Art, Python, res, Sounds and XML. In addition, there is a file called CvGameCoreDLL.dll.

Each of these can be modded -- but the easiest kind of mod is done purely in the XML.

Now, we don't want to break our copy of Civ4, so we shouldn't actually edit or open any file in this directory.

To play around, we are going to create a simple sandbox mod.

Go to the following directory:
C:\Program Files\Firaxis Games\Sid Meier's Civilization 4\Warlords\Mods

create a subdirectory called "PlayPen".

Congradulations, you just created an empty mod!

Now enter the PlayPen directory, and create a subdirectory called Assets.

Ok, now we are going to copy over the XML data from the core files into our playpen.

Go back to:
C:\Program Files\Firaxis Games\Sid Meier's Civilization 4\Warlords\Assets
highlight the XML directory, press ctrl-C to copy it.

Now go back to your Playpen/Assets directory (either go back to the window, or just press "back" on your current window).

Paste the XML directory here.

Chug chug chug goes your computer.

Currently, our mod does absolutely nothing!

Let's test it.

Launch Warlords. Select "advanced", then "load a mod", then select PlayPen.

Hold down the SHIFT key to prevent Warlords from using "cached" data -- this is important when you are changing a mod regularly, because otherwise warlords won't always load the changes! (you don't need to do it now, because this is a brand-new mod, but it is a good habit to get into when hacking away at a mod).

If it doesn't work, well, go back and try again from the start.

Shut down warlords. Your mod is pretty damn empty.

...

Ok, now we have a playpen. We can edit the XML files in our playpen without worrying about breaking your copy of warlords. This seems like a good plan!

Let's look inside our playpen:
C:\Program Files\Firaxis Games\Sid Meier's Civilization 4\Warlords\Mods\PlayPen\Assets\XML

There are lots of subdirectories, and two .xml files (GlobalDefines.xml and GlobalTypes.xml).

Let's take a look at one of the simpler XML files: Assets\XML\Units\CIV4UnitInfos.xml

Open it with notepad or your favourate text editor. Do not use wordpad, write, word, or other word processors to read and edit XML files.

Wait a second -- did you just double click the file? That isn't how you open these files for editing. If you double-click the file, you end up with internet explorer or mozilla... which isn't designed to edit XML files.

Right-click on the file, and select "edit". Now you have it open in notepad.

Notepad sucks, but it will do.

Let's look at what you see:

Code:

<?xml version="1.0"?>
<!-- edited with XMLSPY v2004 rel. 2 U (http://www.xmlspy.com) by Alex Mantzaris (Firaxis Games) -->
<!-- Sid Meier's Civilization 4 -->
<!-- Copyright Firaxis Games 2005 -->
<!-- -->
<!-- Unit Infos -->
<Civ4UnitInfos xmlns="x-schema:CIV4UnitSchema.xml">
	<UnitInfos>
		<UnitInfo>
			<Class>UNITCLASS_LION</Class>
			<Type>UNIT_LION</Type>
			<UniqueNames/>
			<Special>NONE</Special>
			<Capture>NONE</Capture>
			<Combat>NONE</Combat>
			<Domain>DOMAIN_LAND</Domain>
			<DefaultUnitAI>UNITAI_ANIMAL</DefaultUnitAI>
			<Invisible>NONE</Invisible>

etc. This is XML. Civ4 uses XML pretty simply.

A tag looks like this: <Tag>
An endtag looks like this: </Tag>
An empty tag looks like this: <Tag/>
A comment looks like this: <!-- Comment -->

So, right near the start of our file, we have a tag "Class", that contains the characters UNITCLASS_LION, and then ends..

Civ4 reads these XML files to determine huge chunks of the game content. The tech tree, civic stats, unit stats, difficulty levels, and a million other game features are all set in these XML files.

Now, let's test what we know. The first thing we want to do before editing it make a backup of our XML file. Go back to the directory, and make a copy of CIV4UnitInfos.xml.

Rename the backup copy to CIV4UnitInfos.xml.original. Windows will say "are you sure", and agree.

Now let's play. We are going to take Warriors and Scouts, and increase their combat strength to 100!

Why? Because we can, and it is easy to tell if we screwed up -- just start a game.

Go back to your notepad window. Press CTRL-F to open a FIND window. Type in UNIT_WARRIOR.

You should have part of <Type>UNIT_WARRIOR</TYPE> highlighted.

Now, the people who made this XML file where nice. They indenting things nicely. The Warrior unit data starts at the previous <UnitInfo> tag and ends at the next </UnitInfo> tag, and all of the warrior data is intented in one block.

Now for the hard part: search the data until you find <iCombat>2</iCombat>. You can do this by hand, or you can try using Find again.

If you use Find, make sure you are still inside the warrior unit definition.

Change the number 2 to 100.

Next, search for UNIT_SCOUT.

... wait, notepad just told you that it can't find it. Well, search for it again, but this time search upwards. Keep on searching until you are on the line with <Type>UNIT_SCOUT</Type>.

Now search downwards until you find <iCombat>1</iCombat>.

Change that to 100.

Now save the file. Close notepad.

Relauch warlords, advanced, load a mod, playpen, then start a game.

Is your scout and/or warrior now strength 100? Congradulations!

Shut down warlords. You just made your first working mod to the game. A rather silly mod, but a mod.

...

Ok, next step: clean up what you did. Delete your Civ4UnitInfos.xml, then copy (not rename!) Civ4UnitInfos.xml.original to Civ4UnitInfos.xml. You don't want to have a 100 strength warrior wandering around.

Now let's make a different change: make the viking berzerker into an axeman.

Search Civ4UnitInfos.xml for "BESERKER". When you find the <Type>UNIT_VIKING_BESERKER</Type> line, you are at the right spot.

Look above it. See the <Class> line? It says the BESERKER is a MACEMAN class. Change that to UNITCLASS_AXEMAN.

Our BESERKER is now replacing the AXEMAN.

We aren't quite done -- the problem is, our BESERKER still has strength 8 -- a bit too high for the era. Search down for the iCombat tag, and change the 8 to a 5 (from maceman strength to axeman strength).

Safe the file. Relaunch warlords and reload the mod. Remember to hold down shift.

Launch a game, and check out the civipedia entry on berserkers. They are now axemen, at least in the game-content, if not in the description.

Neat! But we aren't done learning yet. The playpen is useful for exploring and experimenting, but it isn't quite the right way to make a mod. You don't need nearly that many files.

...

Next, pruning your mod. You have a complete copy of every XML file in your mod. This is unnessicary.

Create a new mod directory in
C:\Program Files\Firaxis Games\Sid Meier's Civilization 4\Warlords\Mods\
called VikingAxes.

Create the subdirectories Assets\XML\Units.
Copy the Civ4UnitInfos.xml file from your PlayPen to your VikingAxes mod. Remember to copy it to the right location!

Now lanch warlords and load your viking axes mod. Check the civopedia -- did the change work? Congradulations!

The trick is, the game looks in your mod directory FIRST, then it looks in your CustomAssets folder, then it looks in the game assets folder, for each file. So files you don't modify you shouldn't place in your mod.

This keeps your mod size down, and reduces the amount of effort required to "update" your mod.

I would also advise keeping a copy of the "original" file around inside of your mod. By calling it "Civ4UnitInfos.xml.original", the Civ4 mod loader ignores it (it loads files ending in .xml, not .original), and it means when you download a new patch you can use "difference" utilities to figure out what you have to change to make your mod work.

But that is beyond XML 101. I hope this was a useful tutorial.

To figure out what a given tag does, I find it useful to look for a unit that has it set to a non-zero value. Then look at that unit in game. You can usually work it out.

Quite often when making changes warlords will give you errors. This is why you ALWAYS keep a backup copy of what the file was before you changed it.

Some common errors: duplicate tags. Misspelled tags. Forgetting a /, having an extra /, forgetting to close a tag, and the hard one: not being in sync with other files.

The name UNITCLASS_MACEMAN isn't just a magic name -- all of the UNITCLASSes are defined and described in another XML file -- CIV4UnitClassInfos.xml. If you want a new UNITCLASS, it has to be added there.

There are lots of such references -- all of the names of things in the game are in one XML file (so they have translations), the civeopedia entries are in another, etc. When you want to do more complex mods, you have to keep these linkages in mind.

Also note that adding a new tag will cause errors -- to add a new tag, you have to play around with schemas, and then write python/C++ code that understands the new tag data and makes it happen in the game.

Good luck on your modding!

 

Thank you for this post it has been very helpful, and I've been able to make a few changes that make the game more enjoyable for me.

My main question is how can I get some of the changes to work in MP?

For example, I play on a lan with a few other friends and we all would like Monty to have access to the Roman Prats as his unique unit and the Mongol Keshik's to have 3 movement and 8 strength. I modified the XML files and get it to work in single player, to get it to work in MP would I just copy the XML files over to their computers?

Just a note, currently I'm not launching as a mod, but I do have the orginal XML files saved in a separate folder.

 

First, never change the original XML files. Put them back.

Instead, place your changes into the CustomAssets folder. These "override" the original XML files magically. That is the approved way to do a "modless change" to Civ4, and has the benefit that when you patch civ4 your changes aren't deleted by the patcher. (they won't nessicarially work, but at least they don't just go away!)

One should leave the warlords/assets/xml folder alone, just copy from it. Instead copy the files you want to change to warlords/customassets/xml if you don't like launching a mod.

You can modify civ4 so that it auto-launches a mod. I like leaving my changes in a mod, so that if I stop playing and come back 1 year later my game won't be in a strange state.

..

Second, there are a few bugs in the above instructions, as you probably noticed. If you can get it to work, congrats.

Third, I believe if you are using the same mod and/or customassets as the other player, it should just work. I don't multiplayer much however.

From my knowledge of computer game architecture, Civ4 seems to follow the "every player simulates the world in parallel, with each players orders carried over to the other players" model. This is why it is careful with random numbers and has "sync" error issues.

So, each copy of civ4 has to have the same XML config files, or the games risk going out of sync.

 

Thanks for your post ... It really helps me get into Civ4 modding

 

This is by far the best Civ4 modding tutorial I have read to date.



Can you compile all your stuff into a handy downloadable pdf file?

 

This is a great tutorial, but do you mind if I ask a question? I can't find assets or mods, at all. Hidden files are being displayed, BtS and Warlord aren't installed. Mods is there, but I somehow created the file when I downloaded something, and instead of browsing for mods, I just typed. It might have given me a popup, but I really wanted to try the mod. If tihs belongs in a troubleshooting forum, just tell me.

 

Make sure you are browsing in the Program Files/FIraxes/Civ 4

Not My documents/My Games/Civ 4...

I was wondering if someone has a refrence on what all the xml files contain what. For example where are wonders and projects located?

 

oh my...what a help this tutorial has been!
Would anybody be able to point me to a similar tutorial regarding how to download and use someone else's unit graphics?

 

Great guide Yakk, very easy to follow. Just how would I increase the food, production, and gold gathering of a city along with researching faster for a civ? Maybe soemthing like being able to build a wonder and research a tech in one turn while the other civs take the normal amounts of time to build and research? I assume that I would have to edit the schemas and use C++ to create a mod like that.

 

Great Beginner tutorial! I'm not much of a modder myself, but I'm trying to get into it. This should be a sticky

 

i tried to save but it says it doesn't know the file path

 

I have the exact same problem black barron is having

"Cannot Create (insert file path here)

Make sure that the file path and name are correct"

However, I told it to save to desktop. Then I deleted the original file and moved the edited one into the CustomAssets were the Original copy was.

And It worked!

I think its a Vista Pet Peeve, you can't save it directly, you have to save a copy, then replace it. Rather annoying......, but at least there's a backdoor.

 

pet peeve....
any way
ill see if it likes that plan

 

sorry for double post but i need some help with another problem...
that is with the help from RandallS_1985 i tried adapting this tutorial to a civ mod but keep having the problem of when i start the game my civ won't show


never mind i found out the problem (although it really wasn't much of a problem)

 

Awesome tutorial, thanks for taking the time to make this, it is greatly appreciated.

 

Hello ppl,

Is there an easy way to find certain XML files? Some are easy to find since their name implies whats inside. Currently i am looking for the XML file where i can edit the way Permanent Alliances work. Can anyone point me in the right direction?

Thanks

 

Edit the way they work? Like how you share technologies, making it breakable, allowing more than 1? Not XML for any of those ones. Not sure there is XML for ANY of it except declaring which technology enables signing one.

As for how to search multiple XML files quickly, use Notepad++ or similar and it has the ability to search for text in all files and subfolders in any specified folder. Very handy for tracking things down in the XML

 

I'd like to edit the way research and commerce gets shared. As it seems it gets either stacked/doubled/multiplied and the effects are way to strong imo. But this is my first xp with PA's and i am playing with Rise of Mankind 2.3 MOD.

I am using notepad++ aswell its very usefull.

 

There is a penalty applied to research rates to compensate for that. It is found in the GlobalDefines (might have the name wrong, but one of the XML files in Assets/XML, no further sub-foldering). So while you gain another person worth of research, you start having to pay 50% more per tech or something like that.

 

Uh, my 'Assets' folder has the following: assets0.fpk, assets1.fpk, assets2.fpk, and assets3.fpk. No Art, Python, res, Sounds, XML, or CvGameCoreDLL.dll. And how do you create a subdirectory?