HOW TO: Add a Civ/Unit/Building in BTS (Modular XML Modding)

[Teg_Navanis]

Since people seem to want a concise tutorial that helps them to add civs, units or buildings to BTS, I'll try to write one. I'm taking most of my infos from another tutorial, the Modders Guide to Beyond the Sword by Kael, Impaler[WrG] and Solver.

Purplexus will publish a more detailed guide soon. Check his Plug and Play Project for more.

This guide is purely concerned with how to make a mod work with BTS. To see how to make the art or what the XML entries mean, check the existing Vanilla or Warlords tutorials.


Modular Modding

Until now, the most common way to add a unit, civ or building (I'll just say custom content from now on) to the game was to take the original files, copy them to a mod folder and add your custom content there.

With BTS, there is a new, cleaner and easier way to add your custom content. It's called Modular XML Loading. You find a more detailed instruction in the guide mentioned above, I'll just give a step-by-step guide how to use it.

Step 1: Enabling Modular XML Loading

Modular mods only work if the setting "ModularLoading" in your mod config file is set to 1. The config file is created automatically in your mod folder when you start your mod.

Step 2: File structure

This is a classical file structure for a Vanilla or Warlords Mod:

Assets\XML\Art\CIV4ArtDefines_Civilization.xml
Assets\XML\Art\CIV4ArtDefines_Leaderhead.xml
Assets\XML\Civilizations\CIV4LeaderHeadInfos.xml
Assets\XML\Civilizations\CIV4CivilizationInfos.xml
Assets\XML\Units\CIV4UnitInfos.xml
Assets\XML\Text\CIV4GameText_AnyName.xml

This is the same structure for a modular BTS Mod:

Assets\Modules\Switzerland_CIV4ArtDefines_Civilization.xml
Assets\Modules\Switzerland_CIV4ArtDefines_Leaderhead.xml
Assets\Modules\Switzerland_CIV4LeaderHeadInfos.xml
Assets\Modules\Switzerland_CIV4CivilizationInfos.xml
Assets\Modules\Switzerland_CIV4UnitInfos.xml
Assets\Modules\Switzerland_CIV4GameText.xml

+

Assets\Modules\Switzerland_CIV4UnitSchema.xml
Assets\Modules\Switzerland_CIV4CivilizationsSchema.xml
Assets\Modules\Switzerland_CIV4ArtDefinesSchema.xml


There are four important changes:

1. Everything is in a folder called Modules, not XML. You can make subfolders, but they are no longer needed for the game, so I would advise to maybe use one folder per civ instead of splitting up the ArtDefines and CivilizationInfos that belong together.

2. Every modular file needs a "*_" at its beginning. In my example case, I used "Switzerland_". You could replace "Switzerland" by anything you want, but I suggest you use something that is a good description of your module.

3. Every modular file needs to have its schema in the same folder. If you want to know what schema a file needs, look up its first line (except for the comments). It will look something like this:

<Civ4ArtDefines xmlns="x-schema:CIV4ArtDefinesSchema.xml">

The file I looked up (CIV4ArtDefines_Unit) uses the CIV4ArtDefinesSchema, hence this schema needs to be in the same folder as the file itself. It is recommended to rename all schemas to Switzerland_* to prevent file conflicts when different modules are merged. To make sure that all files find the renamed schema, change

<Civ4ArtDefines xmlns="x-schema:CIV4ArtDefinesSchema.xml">

to

<Civ4ArtDefines xmlns="x-schema:Switzerland_CIV4ArtDefinesSchema.xml">

(or whatever your new name is).

4. Notice that most GameText files will be called something like CIV4GameText_AnyName in non-BTS mods. However, you can't call your modular GameText file Switzerland_CIV4GameText_AnyName.xml. Just remove everything after CIV4GameText and you will be fine.

Modular Art

You can freely change the path of your art files as well, as long as you change all the references to them in the corresponding XML files. If you want to make a module that can easily be deleted (including all art files), it is recommended to put them all into a single folder. Here is a slightly modified version of the Switzerland Civ for BTS as an example.

Before:

<Button>,Art/Interface/Buttons/Units/Hellebardier.dds</Button>

After:

<Button>,Modules/Switzerland/Hellebardier.dds</Button>

The disadvantage is that you cannot change the folder structure without adjusting all the references to the art files.

Step 3: File content

A modular file will look like this:

<?xml version="1.0"?>
<!-- edited with XMLSPY v2004 rel. 2 U (http://www.xmlspy.com) by Firaxis Games (Firaxis Games) -->
<!-- Sid Meier's Civilization 4 -->
<!-- Copyright Firaxis Games 2005 -->
<!-- -->
<!-- Civilization art path information -->
<Civ4ArtDefines xmlns="x-schema:CIV4ArtDefinesSchema.xml">
	<CivilizationArtInfos>
		<CivilizationArtInfo>
			<Type>ART_DEF_CIVILIZATION_SWITZERLAND</Type>
			<Button>,Art/Interface/Buttons/Civilizations/Switzerland.dds,Art/Interface/Buttons/Civics_Civilizations_Religions_Atlas.dds,5,7</Button>
			<Path>Art/Interface/TeamColor/swiss.dds</Path>
			<bWhiteFlag>1</bWhiteFlag>
		</CivilizationArtInfo>
	</CivilizationArtInfos>
</Civ4ArtDefines>

Notice that you no longer have to include all the original civilizations, but just the one you wish to add. This is the beauty behind modular modding. Take either an original file and delete all entries but one, or use another modular mod (like the BTS Switzerland Mod) as your basis. After changing the file structure according to Step 2, you can then edit this single entry to create your own content (unit, civ, building, leaderhead etc.).

Please tell me if you still have problems using modular modding, I'll be glad to expand this tutorial if you do.

 

[Aeven]

Very good guide, thank you

 

[Flamegrape]

OMG! If this works then modding will be a BILLION times easier!!!

 

[Sabio]

Yeah Men! it works.
I'm working on Brasil Civ with 3D LH right now.

Thanks Dude! You're the Best!

 

[earthwulf]

Thanks! Now for an even more basic question... I've downloaded & played around with it, but can't figure out how to get it to load in game. I have it in my BTS assets folder, and created a folder called Modules to put it all in, but I don't see switzerland or my civ in the single player games (custom & play now).

Did I put it in the wrong folder?

EDIT: put it in the Mods & got it mostly going... Switzerland seems to work fine, but the one I did keeps crashing... says that imperialistic is not a alid civ trait. Grrr.

 

[Teg_Navanis]

I don't think the game searches for modules in the game's Assets folder. Try the CustomAssets one (C:\Documents and Settings\Owner\My Documents\My Games\Beyond the Sword\CustomAssets) or load it as a mod (C:\Documents and Settings\Owner\My Documents\My Games\Beyond the Sword\Mods\Switzerland\Assets). And don't forget to set ModularLoading to 1.

 

[earthwulf]

Thanks for the info, by the way... and your civ works, mine is having difficulties.

 

[Flamegrape]

What's the difference between Switzerland Mod.ini and Switzerland.ini?

 

[Teg_Navanis]

You can delete both if you want. They are generated automatically when you start a mod for the first time, and I renamed the mod once - that's why there are two config files.

 

[Sabio]

How do I do to put original leader music and speaches for units??

 

[Teg_Navanis]

I have never done that. Does another tutorial cover sounds? There is one problem though:

Unfortunately there is one class of files that don't work with MXMLL, any that deals with Sound and Audio data. These have not been made compatible, also several file types like MissionInfos.xml and CommerceTypes.xml are linked with Enums in the SDK thus any extensions of these files would have no effect without a corresponding modification in the SDK. It's recommended you not try to make Modules with these files.

 

[Flamegrape]

Is there a schema file needed for Civilopedia text?

 

[Flamegrape]

Teg, your Civilopedia text doesn't work.

 

[Teg_Navanis]

No, the GameText XML files don't need a schema.

Thanks for pointing out that the Civopedia didn't work. Apparently, you can either call your GameText file GameText_bla or bla_GameText, but not bla_GameText_bla. I corrected the Switzerland Mod.

 

[Impaler[WrG]]

Teg please advise others to rename the schema with the name of the module and update the reference on the necessary files, though not strictly necessary its considered good practice as it isolates the schema to that module alone preventing the possibility that it will 'pollute' other modules that have modified schemas. These errors are especially onerous to track down so taking a few seconds to prevent them is advised.

P.S. Purplexus can answer questions and is working on a detailed guide at this time, here is a link to the new plug and play forum http://forums.civfanatics.com/forumdisplay.php?f=255

 

[Teg_Navanis]

OK, done. Fantastic work BTW, love it

 

[Flamegrape]

As I understand it so far, modular elements are combined together into one mod. They cannot be easily removed from the mod.

When I first learned of this method of modular mod elements, my impression was that these elements could be removed or replaced as needed. I think that this is not the case.

Sure, it's easy to simply delete the XML files from the Modules folder. Especially if their file names include the name of the modular mod element. (For example, in the case of the Swiss civilization that Teg has provided for us, all the XML files have a name that contains the word, "Switzerland.") This is extremely useful for mod construction.

But what about the files in the Art folder?

Let me try to discuss this in terms of a hypothetical mod that I might create. I'll call it GRAPE, named after my user name. And suppose I want to add two civilizations to my mod, Switzerland and Phoenicia (a modular civilization that I am actually working on right now).

As I understand it, if I wanted to add Teg's Switzerland modular civ to my GRAPE mod, the Switzerland modular XML files are placed into GRAPE\Assets\Modules and the Switzerland art files are placed into GRAPE\Assets\Art. Then I put my Phoenicia modular XML files into GRAPE\Assets\Modules and the Phoenicia art files into GRAPE\Assets\Art, just like I did with Teg's Switzerland files.

But what if I decided that including the Phoenicia civ was a bad idea? What if I wanted to remove Phoenicia from my GRAPE mod? Removing the modular XML files from GRAPE\Assets\Module is easy. All of those text files are in one directory and are clearly labeled with the word, "Phoenicia." But removing the Phoenicia-related art files from the GRAPE\Art subdirectories is not as easy.

Don't get me wrong. I know that it only takes a minute or two to pick through the subdirectories of GRAPE\Art and delete files that I know are components of my modular Phoenicia civ. No problem for me. But what about other people who download my modular Phoenicia civ? Unless they are familiar with the ancient Phoenicians, they might not recognize file names containing the word "Hiram" or "bireme." Someone attempting to remove my modular Phoenicia civ from their own mod would easily recognize art files named with the word, "Phoenicia." But files related to the leaderhead, Hiram, or the Unique unit, bireme, might be left behind.

When I first learned of modular mod components, I was under the impression that properly-constructed mods could be somehow combined together and removed at will. I had it fixed in my mind that a "parent mod" would contain some sort of script that would "include" modular mods. Perhaps lines of code would be added to the parent mod's .ini file. But as far as I can tell, this is not the case.

I've taken a look at the Purplexus' Plug and Play Project forum. From what I generally understand, that requires the use of some programs that properly install modular mod elements. I'm willing to learn more about this but I'm not sure I like it. On the surface, it seems rather complicated. It isn't immediately obvious to me how it works. Perhaps it seems simple to others, but for some reason it reminds me of the flawed file registry system that has plagued Microsoft Windows from day one. To me, the term "plug and play" simply means adding one file or directory with the ability to delete or remove it at will. Not the installation of a third-party public domain program that is relied upon to properly install modular mod components. I could be absolutely wrong about the Plug and Play Project so I'm not rejecting the idea altogether.

However, I have an idea that might work. (I haven't successfully tested it.) I've noticed that Civilization IV and a few of the extremely popular mods employ the use of .pak files. Could a modular mod have all of it's art assets stored in one .pak file? Could all of the individual modular mods have their art .pak files stored in one folder for easy removal?

I still have much to learn but I wanted to express some of these thoughts and ideas.

 

[Teg_Navanis]

You can also put your Art files into the Modules folder. You have to change the references in your XML files though.

<Path>Art/Interface/TeamColor/swiss.dds</Path>

would then become

<Path>Modules/Switzerland/swiss.dds</Path>

, for example.

It is probably not a bad idea to do explain this in the tutorial, since this is actually the recommended way of doing things. I just left it out for simplicity's sake.

 

[Flamegrape]

Holy cats! This is amazing!

The idea of putting the art files in the Modules directory hadn't occurred to me.

As for using PakBuild, I just tried it out and it works like a charm. In fact, I'm able to combine everything together into one FPK file. If people were to make modular mods and put them into FPK files, in my humble opinion, this would truly make them "plug and play." Just don't include the Schema files in the FPK otherwise it would create redundancy when combined with other modular mods. If all possible Schema files are placed in a "parent" mod's Modules directory, then it's just a matter of adding and removing ONE file.

Going back to my GRAPE mod example, I put all of my Phoenicia mod into one file, Phoenicia.FPK and put it in GRAPE/Assets. When I run my GRAPE mod in Civ4, all of my Phoenicia components work normally. If I decide to remove the Phoenician civ from my mod, all I have to delete is that one file!

Brilliant! This is fantastic! With carefully crafted modular mod elements, this makes things so much easier!

 

[Flamegrape]

I found Kael's tutorial on how to use PakBuild:

http://forums.civfanatics.com/showthread.php?t=187699

I'm convinced that using PakBuild could be the best way to employ the use of modular mods.

Perhaps-- and this is only a suggestion-- all of the Schema files could be put into one FPK file. Anyone who wants to use modular mod components could just flip that switch in the CivilizationIV.ini file, place a ModuleSchema.FPK file in a mod/Assets directory, and then the mod would be ready to use modular mod components that can be added or removed as needed!

There are a million ways all of these modular file components could be configured. The trick would be getting the entire Civ4 mod community to agree upon a convention.

Or has someone else already thought of all this and I'm just reinventing The Wheel?