A Brief Guide to Modding Galactic Civilizations 2: Dread Lords

This guide is current for version 1.2 of GalCiv2. I will try to keep this guide updated as changes are made that might affect modding. I’ve tried to group related topics as much as possible.

While the mods folder is mostly functional, there are a few things that you still cannot mod by putting a file in the mods folder. Also, I have tested it, but I'm a programmer and not a modder, so you may have some feedback on what would make modding GalCiv2 easier. As I update the mods code, I'll update this documentation. It's taken me awhile to write these docs, so if you do find something that is incorrect, please e-mail me at carielf@stardock.com. Just be nice about it, ok?

One thing to keep in mind is that the AI will often use a mod that you create, so you may not be giving yourself an advantage by making a crazy powerful mod.

Also, I didn't do a lot of testing with the mods folder and the Metaverse. If you want to make sure that your Metaverse games are not disqualified, make sure that mods are disabled before starting GalCiv2.

There may be a few places where I paste source code. If so, I will try to give a verbose description of what the code is doing. The symbol // means that whatever follows on that line is a comment, that it doesn't actually do anything.

I am aware that there are spelling errors in some of the field/tag names. It’s generally better not to ‘fix’ these things after a certain point, because there is the possibility of breaking something. We generally go with the maxim “If it ain’t broke, don’t fix it.” Also, our formats and naming conventions are not consistent because at least four different people were working on the data files. In future games, I would like to have a consistent format and naming convention, but for now, we’re stuck with what we have.

Other contributors to this guide are Paul Kerchen, Jesse Brindle, and Scott Tykoski.

The Mods Folder

The purpose of the mods folder is to allow you to apply your mods to GalCiv2 without having to worry about corrupting your installation of GalCiv2, and without losing all of your mods if you need to re-install. Its folder structure is very similar to the GalCiv2 folder structure, so you can take a file from the GalCiv2 folder, modify it, and save it to the corresponding mods folder. Some people might have preferred just a folder without any subfolders, but having the subdirectories makes it easier to replace a specific graphic without having to worry about if it has the same name as a graphic in another subfolder of the GalCiv2 folder. It also means that I don't have to parse the file to determine what is stored in it, which saves loading time.

For version 1.2, we are including an interface to change your mods directory. On the options menu, there will be a control with the current mods directory and a button to change it. Clicking on the change button will bring up a dialog that will let you browse to a different directory, or you can create a new folder by modifying the path and then clicking the + button. It's not a true windows browse dialog because that would have caused compatibility issues. It would have taken too long to show a tree structure well, so it simply lists the subfolders of the current directory. You can click on a subfolder to choose that folder, or click on the up arrow button to go up a level. Changes are not saved until you hit the Done button, or you can reset to the default mods directory by clicking on the Default button. You can also change the directory used for the mods folder by editing your prefs.ini file in your My Documents\My Games\GalCiv2 folder. Being able to change the mods directory should make it easier for you to switch between total conversion mods and more casual mods, or to just store your mods on a different hard drive. When GalCiv2 loads and mods are enabled, it checks the prefs.ini file for the path and creates the necessary subdirectories in the mods folder if they do not exist. If you create a new mods folder or clear out the existing one, it will automatically create all the subdirectories for you. You still have to move the files in yourself, though.

If you're making a mod, a good way to test it would be to create a new mods folder just for it and put your files in it. When you're ready to submit it to the GalCiv2 mods library, you can just add all the contents of your mods folder to a zip file and the folder structure will be intact. Then, when a person downloads the mod, they can just extract it directly to their chosen mods directory.

The mods folder has a structure similar to the folder structure of the GalCiv2 install folder. Its main subfolders are Data, EventMusic, Gfx, Music, Screens and Sfx. The Data directory and its subdirectories store the data parts of the mods. The Gfx subfolder contains all of the non-interface graphics: textures, still images, etc. The Screens folder contains the .dxpack files which are used to display the game's interface. The EventMusic and Music folders only allow replacement modding because we specify what music is played in the code, not in a data file. Most of the sfx are also specified in code, but the weapons sfx are specified in their component definitions so you could add new sfx with new components.

Modding GalCiv2's Data

There are about 30 abilities that affect your entire empire: how good your economy is, how fast your population grows, etc. These are modified by a lot of the various files that I talk about, so I'm going to list them here. Note that it IS possible to get negative bonuses and have penalties instead of bonuses. Below, I'm going to list what they do as if their value is greater than zero.

0	Economics	Increases how much money your colonies produce.
1	Weapons	Increases the effectiveness of your weapons.
2	Defense	Increases the effectiveness of our defenses.
3	Speed	Increases the amount of moves your ships get each turn.
4	Morale	Increases the happiness of your people, giving you a higher approval rating.
5	Population Growth	Increases how quickly your population grows.
6	Social Production	Makes your planetary improvements build quicker.
7	Military Production	Makes your ships build faster.
8	Research	Makes your techs research faster.
9	Influence	Increases your cultural influence in the galaxy; this gives you more votes in the United Planets and makes it more likely that colonies belonging to other races will "flip" to you.
10	Trade	Increases revenue from trade routes.
11	Diplomacy	Affects your relations with the other civilizations. A higher diplomacy can help your relations and helps you when trading.
12	Hit Points	Increases the hitpoints for your ships.
13	Repair	Makes your ships repair faster.
14	Sensors	Increases the area around your ships and planets that is "visible".
15	Espionage	Gets you more for your money when spying on other races.
16	Soldiering	Helps your soldiers when invading a planet.
17	Interest Rates	Higher interest rates help you when you are purchasing a planetary improvement or a ship.
18	Planet Quality	If high enough, will increase the class of all the planets you have colonized.
19	Trade Routes	Determines the number of trade routes you can have.
20	Crime	Unused.
21	Cabinet	Unused.
22	Range	Increases the distance a ship can travel from your starbases and planets.
23	Luck	Increases the likelihood that something good will happen to you.
24	Courage	Helps your ships in battle.
25	Creativity	Increases the likelihood that you will randomly research a tech.
26	Government	Unused.
27	Loyalty	Makes your citizens less likely to revolt and culture flip.
28	Logistics	Determines the number of ships in a fleet.
29	Miniaturization	Reduces the size of the components on a ship and increases hull size.
30	Home Planet Quality	Makes the planet with your initial colony a higher class planet.

There are still some places in the various data files that require an integer value for a race ID. These are the values for the races:

0	Human
1	Drengin
2	Altarian
3	Arcean
4	Torian
5	Yor
6	Korx
7	Drath
8	Thalan
9	Iconian
10	Custom Race

You'll notice that there are a lot of places where we start counting at 0. This is useful to us because of the way data is stored in C/C++, but I know that it's confusing to non-programmers and programmers who use languages that start counting at 1. Because 0 is often a valid value, we often use -1 for an invalid value.

Anything higher than 10 is considered a minor race. Minor races behave differently than the major races, but in the case of the Dread Lords, they are not necessarily weaker. The minor races use offsets from 11 so they could feasibly change in an update or expansion pack. I think that the Dread Lords are currently Race 16 (remember, counting from zero), but since they are a special case, they will sometimes use the value 11 in data files (like in the scenarios and custom maps) because they are the last race that can be affected by whatever is in the data file, whereas the other minor races are ignored. You can change the characteristics of the Dread Lords and the first 9 minor races that can show up at the start of the game in the RaceConfigXML file. Sorry, you can't mod the pirates or monsters (monsters are currently disabled).

Most of our data is now stored in an xml format instead of a custom data format that has to be parsed. You should be able to open up most of our files in notepad and edit them there, although at some point we may release editors with an expansion pack to make it easier. The scenarios are really renamed .ini files and so are the .shpcfg files. The .str files are a custom format, but it's fairly straightforward. One thing to keep in mind: don't edit any of the data files in a rich text editor, not even to spell check them. Rich text formats like Word store hidden characters that will cause errors when the file is read into GalCiv2.

The .str files are what we call string tables. The tables start with the tag [TABLEALIAS tablename] and end with the tag [TABLEEND] where ‘tablename’ is the name of the table. In the case of screens.str, the table name generally corresponds to a specific screen, and generally uses the name of the dxpack. The strings in the table all have tags between the square brackets, [ ]. The strings in these tables are not a 1 to 1 relationship with the objects in the dxpacks because they often change. So the strings are called by the code by their tag and set in the object. Some of the strings may have %s or %d in them. These are format delimiters for the C function sprintf, which we use to make dynamic text. You don't ever want to change these parameters or change the order they appear in the string. At best, you'll get funky looking strings. At worst, you'll create a parsing error that causes crashes.

Ini files use a similar format. They have a section name that is in square brackets [SectionName] and they have keys that are set equal to their value. So bMods=1, bModsDir=C:\MyMods. This is a format used before the registry became popular, but it's not used quite so much now. They are limited to 64 kb on Windows ME and Windows 98. They're convenient for saving options and settings and are supposed to be fast, but not ideal for storing large amounts of data.

XML files are also like tables, but you can get a bit more complex and have tables within tables, which I actually did in the CustomPlanets files. In Visual Studio, you can view an XML file as a spreadsheet. The values for a given field are in between tags like this <Value>0</Value>. We’re using utf-8 format, but most of our code doesn’t actually support Unicode, so to avoid funky looking characters, save your xml files as an ANSI (ASCII) format. Comments in XML files (text that is ignored by parsers) look like this: .

Most of GalCiv2's data types support adding additional kinds rather than just replacing them, but there are a few files that only use replacement: AbilityBonuses.xml, CustomPlanets.xml, RaceConfig.xml, and the .str files. The .str files you can have a file with just the table you're modifying in it and will replace just the strings that you're modifying. The other files will be used instead of their counterparts; this means if it's not in the file, it won't exist, and bad things might happen. Eventually, I would like to add support for replacing just one custom race definition, etc, but for now you'll just have to copy the existing file into the mods folder and modify the parts that you want to modify.

At the moment, you have to replace an item completely in order to mod the existing item. So you can't just change the name of an anomaly, or tech, etc. and have the stats pull from the standard files. This is something that I would like to get in, but it would take some re-working of the way that the data is read in and that might end up being somewhat complicated. The other problem with this method is that it would be easy enough to add or replace data in the files, but not remove it. So you couldn't necessarily remove an engine from the ColonyShip to make more room for something else. The engine would still be there, plus whatever you added, which would put you over the capacity limit, which would probably make it not show up in the list.

There are two main differences between the Mods\Data folder and the GalCiv2\Data folder. The first is that there is no folder for localized files. You have control over which files you put in your mods folder, so I figure that you'll put ones that you can read in there. The second is that there's a lot more subfolders. Knowing what kind of files they are makes it easier and faster to load them, and it allows me to control in what order they are loaded. In GalCiv1, we had a lot of files that were text files that were renamed with different extensions, but if you go to edit an xml file with a different extension, editors treat it just like a text file instead of an xml file so it's not as convenient.

Modding Civilizations

At the moment, the default race configs can only be modified by replacing the entire RaceConfigXML.xml file so that the race configs are loaded in a specific order to correspond to their AI personalities. In the future, I may add functionality for partial replacements. The main advantage to having to replace the entire file is that I only have to read in one file for the races, which is quicker than constantly accessing the hard disk. Also, assuming that you don’t make an error while editing the raceconfig file, you’ll have the correct number of races in the file. For 1.2, we added an Ignore field so that we could disable races without throwing off the indices of the races. To disable races from being selected as the player’s race or as opponents, add the field <Ignore>1</Ignore> to a race definition.

<DisplayName>Barbian Empire</DisplayName>

<ShortEmpireName>Barbian Empire</ShortEmpireName>

<RaceLeader>Barbie</RaceLeader>

<Homeworld>Barbie World</Homeworld>

<Homestar>Barbie Star</Homestar>

<Description>I'm a Barbie girl, in a Barbie world...</Description>

<Portrait>Gfx\Race\RaceImage_GaladrielBarbie.png</Portrait>

<DefaultTradePortrait>Gfx\Race\RaceImage_GaladrielBarbie.png</DefaultTradePortrait>

<Logo>Gfx\Race\Logos\RaceLogo_Barbie.png</Logo>

<Tech>HyperDrive</Tech>

<Tech>UniversalTranslator</Tech>

<Tech>Xeno Communications</Tech>

<Tech>Xeno Engineering</Tech>

<Tech>StellarCartography</Tech>

<Tech>XenoResearch</Tech>

</Race>

The Name field is the unique identifier for this race, but when replacing the RaceConfigXML file, it matters what order you put the definitions in to depend on what race you're replacing. The display name is what is actually displayed in game. Alignment is the initial alignment that a race starts out with, from 1-99. These are the possible values for alignment:

Pure Good	76 - 99
Chaotic Good	60 - 75
Neutral	50 - 59
Chaotic Evil	40 - 49
Pure Evil	1 - 39

ShortEmpireName is the shorter version of the DisplayName; i.e. The Terrans instead of The Terran Alliance. There is currently no way to set this in game. RaceLeader is the name of the leader of your Empire, aka the Player Name. The Homeworld is the name of the race's starting planet, and Homestar is the name of the star system the home world is in. The Homestar value can correspond to a custom star system definition so that the race has a unique star system that it will always start with at the beginning of a game (see Custom Planets). The Description field is another field that cannot be edited in game; it's just a short description of the race.

Portrait and TradePortrait are the pictures used by the game when you talk to the race, but the TradePortrait should have a wide aspect ratio so that it doesn't look funny on the Trade screen. The Logo field is the image used for the race's logo on the starmap and various other places in game. The Portrait, TradePortrait and Logo filenames should always have the relative path, not the full path. You should probably use the same sizes that we do for the best results; the Portrait should be 256x256, the TradePortrait should be 393 x 256, and the logo should be 128x128. These Images should always be no larger than 256x256.

PoliticalParty is the ID of the political party that the race uses by default.

The various color fields contain the R, G, and B values for an RGB color value, separated by commas. RaceColor is used for trade route lines, auto pilot lines, and various graphs and charts. ShadowColor is unused. UndefendedStarColor and DefendedStarColor are used to draw the population or manufacturing circles on the minimap, depending on if the planet is defended or not. By default, these are the same as the interface color. The sector color is used for the influence lines on the starmap, and defaults to the race color. BaseColor, TrimColor and EngineColor are used by the ships. InterfaceColor is the color that the interface is tinted.

ShipStyle is a number between 0-5 (inclusive) that identifies the ship style used by the civilization, which mainly affects the hulls available to the civilization. ModuleStyle is currently unused. Originally, we intended to make the races use different module styles if they had the same ShipStyle, but we didn't have time to do that. The ship styles are listed in the Modding Ships section.

You can specify multiple starting techs with the Tech tag. Your civilization will know these techs at the start of the game.

The rest of the tags are for the racial abilities that your race has by default. If the value for a given ability matches the ability on the race customization screen, it will count towards the total amount of ability points being used. Otherwise, they're free. The tags listed in the example are the only abilities that are recognized by the RaceConfig parser.

Modding Ability Bonuses

In order to modify the abilities that you can select at the start of the game, you have to create your own version of the AbilityBonuses.xml file. Most of you will probably just want to add Logistics and Miniaturization, so it’s a simple matter of copy and paste.

<Option0Text>Advanced</Option0Text>

<Option1Text>Gifted</Option1Text>

<Option2Text>Master</Option2Text>

</Ability>

The name of the ability isn’t actually used in the game; it’s pulled from one of the .str files. It’s mainly in the file for easy identification of the ability. The AbilityIndex is the important value, which corresponds to the Ability ID which I listed in the Abilities Table. Next, you list the number of available options, which should be a value 1-6 as 6 is the maximum number of options that you can provide. First you list the option text, which is the short description of the level of ability or what it does for you. Next you list the actual value of the bonus. In most cases, this will be an integer representing a percent although Sensors, Trade Routes, Range, and Speed (listed as propulsion in the abilitiesbonus.xml file) use values that actually represent what they are in game. Finally, you list the BonusUnits, which is provided so the game can parse together a string intelligently. As you can see in the example, there are 3 options and the fieldnames for the text are Option0Text, Option1Text and Option2Text. Be careful when you are copying, pasting, and editing to make sure that you keep the options in order, that you don’t overwrite some and leave others blank.

Political Parties

Political Parties give you bonuses as long as you remain in control of the Senate. You don't have to worry about losing control of an Imperial Senate, which will always be 100% behind any decision you care to make. However, you get really nice bonuses for the other forms of government in addition to the bonuses from your political party. If you lose control of the Senate, however, you will get penalties until you can gain control of the Senate again. Here's an example, my favorite political party:

<DisplayName>Industrialist</DisplayName>

<Description>The Industrialists are the antithesis of Technologists. Industrialists receive a bonus to production capacity.</Description>

<Model>gfx/Government/Industrialist.png</Model>

<OpposingParty>Technologists</OpposingParty>

</PoliticalParty>

As always, the internal name is the unique identifier of the political party. The ID is supposed to be unused and set as they are read in, but apparently they are not, and they are used for quick identification in game, so they also need to be unique. This is something that I will have to fix, but in the meantime, make sure that you use an ID bigger than the ones in the standard file. This number will also be used by the raceconfig, which could make it tricky to change. DisplayName is the value used to display the name in game text, and the description is pretty obvious. Model actually refers to the png file that is the logo of the political party. It should include gfx/government in the path, as the mod code is smart enough to pick it out of the mods folder if it's there, but it still needs that part of the path. The opposing party is the internal name of the party that is directly opposed to this party. For example, Democrats directly oppose the Republicans. Parties always have to have an opposing party, or crashes will happen. If the opposing party gains control of the senate, you also incur their bonuses as penalties. Bonus and Penalty can contain multiple values in the same string. The first number in the bonus or penalty is the Ability ID, and it precedes the colon. The number following the colon is the value of that bonus or penalty. Bonuses and penalties are separated by a space. I don't know how well the parsing code works so try not to add extra spaces or tabs. The ColorRed, ColorGreen, and ColorBlue values are the RGB values for the color of your political party. White is 255,255,255 and black is 0,0,0. Most paint programs will let you mix colors, so you can use them to mix a color you want.

Modding Planets and Star Systems

I’m going to tell you how to create your own custom home star system, but I think that you can also just make a few new height maps or color schemes if you want.

Star Types

This folder is for entries like in StarTypes.xml, which tell the game which colors and textures to use for a star of a given type. I'm not sure how well this will work for adding additional types, but you should be able to at least replace the existing ones. I think.

<Texture>BlueStar.png</Texture>

<Halo>BlueStarHalo.png</Halo>

<F_StarColor>0.0, 0.2, 0.5, 1.0</F_Color>

</StarType>

Basically, this just gives some basic information about the star. Type is a unique identifier, and it should always be less than the number of StarTypes since it starts counting from 0. Star systems with habitable planets always have star type 2, and if the star system has a special planet, it will have type 5. For examples of the textures used by the star (as indicated by Texture and Halo), check the GalCiv2\Gfx\Stars folder. F_StarColor holds the values for the D3DXCOLOR of the star; in terms of the game, it’s the color the star appears on the map. A D3DXCOLOR is a structure containing 4 floating point numbers representing the R, G, B, and A values of the color. A stands for Alpha channel, and it controls the transparency rather than a hue. A value of 0 for the alpha channel is completely transparent, and 255 is completely opaque. In a D3DXCOLOR, the R, G, B, and A values are represented by floating point numbers from 0.0 to 1.0 instead of from 0 to 255. This allows a little more variation in colors. To convert from the R, G, B, or A value represented by a byte, just divide it by 255. For example, the color in the Blue star can also be represented by 0, 51,127, 255. As you can see, dividing each value by 255 gets 0.0, 0.2, 0.5, 1.0. The color of the star was hard-coded based on the texture name before 1.2, so I moved it into the file.

Height Maps

A height map is a black and white 256 grayscale image, exported in .RAW format. Whiter areas are more elevated than darker areas. Height Maps should be 384x192. This is what Earth.raw looks like:

Terrain Color Schemes

A Terrain Color Scheme defines how a planet is colored. Each scheme has one or more ColorDefs which, along with other information, completely describe how a planet is colored. This is an example of an Earthlike planet’s color scheme:

<SchemeName>Earthlike</SchemeName>

<InvasionGroundTexture>Gfx\Invasion\Invasion_Ground01.png</InvasionGroundTexture>

<InvasionHorizonTexture>Gfx\Invasion\Invasion_Horizon01.png</InvasionHorizonTexture>

</InvasionTextures>

<InvasionGroundTexture>Gfx\Invasion\Invasion_Ground01.png</InvasionGroundTexture>

<InvasionHorizonTexture>Gfx\Invasion\Invasion_Horizon01.png</InvasionHorizonTexture>

</InvasionTextures>

</ColorDef>

</ColorDef>

</ColorDef>

</ColorDef>

</ColorDef>

</ColorDef>

</ColorDef>

</ColorDef>

</ColorDef>

</ColorDef>

</ColorDef>

<TerrainType>Usable</TerrainType>

<TerrainName>TerrainTypePrairie</TerrainName>

<QueryPicture>Prairie_Query_Earthlike.png</QueryPicture>

</ColorDef>

</ColorDef>

</ColorDef>

</Override>

<TerrainType>PolarUnusable</TerrainType>

<TerrainName>TerrainTypeWasteland</TerrainName>

</ColorDef>

</ColorDef>

</ColorDef>

</ColorDef>

</Override>

<TerrainType>EquatorialUnusable</TerrainType>

<TerrainName>TerrainTypeDesert</TerrainName>

</ColorDef>

</ColorDef>

</ColorDef>

</ColorDef>

</ColorDef>

</Override>

</TerrainColorScheme>

SchemeName: (String) Defines the name of the scheme as it is used in the game. If you change this, you'll also have to make sure you update any other data files that reference it. If you don't, the renamed scheme will probably be ignored by the game. As of 1/5/05, the only file that references this one is PlanetDescriptions.xml.

PolarCapExtent: (Float) Defines how many sector rows are covered by the polar caps. For example, a value of 0.5 indicates that the top half of the top row and the bottom half of the bottom row are within the polar region of the planet. (optional, default is 0)

SurfaceLightColor: (comma-separated rgb triple) Defines the color of the light on the planet's surface (used to tint invasions).

InvasionGroundTexture, InvasionHorizonTexture: Filenames of textures to use for invasions of planets with this scheme.

ColorDef: Each ColorDef describes a color and the elevation at which that color is displayed. Colors are linearly interpolated between defined elevations. ColorDefs can also have optional information.

Thresh: (Float) Defines the altitude at which the associated color will be displayed. You can make sure the colors go where you want by finding the RGB color of a particular location on the RAW map in your graphics program; the three values for Red, Green, and Blue will be the same number. Just take that number and divide by 255 to get the threshold value for that altitude.

RGBColor: (3 comma-delimited decimal integers) Defines the RGB color for this ColorDef.

Shadow: (0 or 1) Indicates whether or not this color should be shadowed by surrounding terrain when that surrounding terrain is at a higher elevation than the point which is colored with this color. Usually you'll set this for water color values to avoid having your oceans look like blue mountains. (optional, default is 1)

You can override the color scheme for most of the terrain types so that sectors of a particular terrain type are colored differently than the scheme. To do this, within the scheme, create an Override tag. Each Override tag must have a TerrainType tag with one of these values:

Usable

PolarImprovable1

EquatorialImprovable1

PolarImprovable2

EquatorialImprovable2

PolarImprovable2

EquatorialImprovable2

LowAltUnusable

HighAltUnusable

PolarUnusable

EquatorialUnusable

Following the terrain type tag, there are some optional tags which can follow:

TerrainName: Specifies the name of the text resource for this terrain type; this name will be used to get a UI text string from the PlanetWnd section of the text resource screens.str.

QueryPicture: Specifies the filename (no path) of the graphic to use for the query in the planet management screen.

BlendFactor: Specifies how much of the override should be blended with the default scheme. If you don't specify this tag, 1.0 is used, indicating that none of the default should be blended into texels with overridden colors.

Finally, follow up with one or more ColorDef elements.

IMPORTANT NOTE: The TerrainType tag must occur before any other override tags or those tags will be ignored.

Planet Descriptions

This folder contains data like in the file PlanetDescriptions.xml, which describe what a planet surface looks like.

<Name>Testing123</Name>

<ColorScheme>Earthlike</ColorScheme>

</PlanetDescription>

Name in this case is just a unique identifier; you will never see this string in game. This information is used solely to generate the planet surface. The string in ColorScheme is the SchemeName of a TerrainColorScheme. UsableElevationRange contains the min and max elevation for the planet surface, separated by a comma but no spaces. The programmer who wrote this code did not document what the valid ranges are, but the default range is from 0.3 to 0.8. In our data files, we go as low as 0.29 and as high as 0.99 so you could probably play around with these values. EnhancementPotential is a percentage that, when multiplied by the base planet class, determines how many tiles can be enhanced to useable. ClassRange gives the minimum and maximum planet class of planets that use this description, separated by a comma.

The example given above, when used with the earth.raw file, gives us a planet surface like this for Earth:

Or, if you use this planet description for RedPlanet:

<Name>RedPlanet</Name>

<ColorScheme>RedPlanet1</ColorScheme>

</PlanetDescription>

It will look something like this:

Custom Planets

The CustomPlanets.xml file allows you to specify what the star system a race starts out with at the beginning of a game looks like. This is another file that has to be replaced. Just put it in the Mods\Data folder, not the CustomPlanets folder. It doesn’t need an ignore field, though, because if a race is not enabled, it will not use the star system definition. This is the custom planet definition for the Sol system, which belongs to the Terran Alliance.

<Texture>gfx/planets/sol.png</Texture>

<DisplayName>Earth</DisplayName>

<Texture>gfx/planets/earth.png</Texture>

<RAWTerrain>earth.raw</RAWTerrain>

<TerrainPalette>Testing123</TerrainPalette>

<Moon>gfx/planets/m00.png</Moon>

</Planet>

<Texture>gfx/planets/mars.png</Texture>

<TerrainPalette>RedPlanet</TerrainPalette>

</Planet>

<DisplayName>Mercury</DisplayName>

<Texture>gfx/planets/M10.png</Texture>

<TerrainPalette>JustRockPlanet</TerrainPalette>

</Planet>

<DisplayName>Jupiter</DisplayName>

<Texture>gfx/planets/jupiter.png</Texture>

<TerrainPalette>DesertPlanets1</TerrainPalette>

</Planet>

<DisplayName>Saturn</DisplayName>

<Texture>gfx/planets/saturn.png</Texture>

<Rings>gfx/planets/r00.png</Rings>

</Planet>

</StarSystem>

I believe that the StarSystem’s Name has to correspond to the home star name in the RaceConfigXML file, but I’m not certain. As I mentioned previously, the Star System table contains tables within it that describe the planets in the system. The max number of planets in a star system is 5. This is not moddable. It causes problems with generating the galaxy and hit detection if you have more than 5 planets in a star system. It also looks bad, so we're not changing it. The star texture name is unused right now, but if we allow custom textures for the star systems of major races, this is where we will get the filename. The display name is what is displayed on the map. If you don't specify display names for the planets, they should use the display name of the star plus a roman numeral.

The Class of the planet specifies the number of useable tiles on the planet surface. Most planets generate their own texture based on their planet surface, but if you specify a texture in the planet definition, it will use that texture instead. The RawTerrain is the Height Map of the planet surface, and its TerrainPalette refers to its Planet Description.

The PercentOfStarSize is a floating point number that indicates what size the planet will be, as a percent of the star size. Planets of quality greater than zero usually range from 50-75% of the star size and class 0 planets may be further modified by 25-125% of the star size. However, big planets can make the map look pretty jumbled, particularly if you’re trying to move ships around them. This is how a planet gets it size when it's in a random star system:

1) Get the size of the star

2) Get a random value between 0.5 and 0.75.

3) If the planet class is equal to 0, get a random value between 0.25 and 1.25 and multiply it by the previous value.

4) Multiply the value by the size of the star.

If a moon texture is specified, a moon will be created for the planet. If a rings texture is specified, it will create rings. For display reasons, you can't have both rings and moons on the same planet. Planets with moons get a production bonus and planets with rings get a research bonus. Orbit, InnerRadius, and OuterRadius all are specific for rings. The orbit is the distance from the planet and the InnerRadius and OuterRadius determine the thickness of the rings. The Orbit value derives from the planet size, ranging from the 5 units larger than the planet to 1.5 * the planet size. The InnerRadius and OuterRadius derive from the Orbit value. The InnerRadius ranges from the value of Orbit to 1.2, and the OuterRadius ranges from Orbit+1 to Orbit+20.

Techs

Techs unlock various items like ship components and starbase modules and can add to your native race abilities. The TechTree.xml file is one of our more complex xml files, so I may miss a few fields, but I'll do the best I can to not miss any. Techs definitions are separated into various branches of the tech tree: Culture, Propulsion, Weapons, Defenses, Logistics, Industry, Biology, and Computing.

A tech definition uses its branch name as the main tag, like this:

<DisplayName>Interstellar Governments</DisplayName>

<Description>Allows us to begin researching advanced types of governments.</Description>

<Details>Each culture has its own government system, and we want to research each government so we can learn and grow in our knowledge and understanding of other races. There can be no understanding between the different galactic species until we understand as much of each other's culture and society as possible. Plus we want to copy the good parts and use them to improve our own government...</Details>

<Requires>UniversalTranslator</Requires>

<Category>Government</Category>

<Model>stardemoc0</Model>

</Culture>

The ID is the internal name of the tech, and is used to identify tech requirements both of other techs and things like planetary improvements. The Display Name is what you actually see in the tech tree viewer, etc. Cost determines how long it will take to research the tech. If you make the cost 0, everyone gets the tech by default. Description is a short description that is supposed to give you a basic idea of what the tech does. Details is a wordy explanation, and can be pretty whimsical. Requires is the ID of the pre-requisite tech. The Category field further divides the tech branches. The values for the Category field in the standard tech tree are:

Armor

Beam

Culture

Diplomacy

Economics

Farming

Government

Hull

Invasion

Logistics

Manufacturing

MD (Mass Drivers)

Medical

Military

Miniaturization

Missile

PD (Point Defense)

Propulsion

Pure Research

Range

Research

Sensor

Shields

Starbase

Terraforming

Trade

AIValue assigns a value to the tech for the AI when deciding if it should trade it or not; the higher the value, the less likely the AI is to trade this tech. Model is the name of a Bink file to represent the tech. Alignment refers to the required alignment for the civilization to be able to use the tech. There are also various ability tags which add to the race's native ability, corresponding to the abilities in the Abilities Table I listed in the Modding GalCiv2’s Data section:

EconomicsAbility

WeaponsAbility

DefenseAbility

SpeedAbility

MoraleAbility

PopulationGrowthAbility

SocialProductionAbility

MilitaryProductionAbility

ResearchAbility

CultureAbility

TradeAbility

DiplomacyAbility

HitpointsAbility

RepairAbility

SensorsAbility

EspionageAbility

SoldieringAbility

InterestRatesAbility

PlanetQualityAbility

TradeRoutesAbility

CrimeAbility

CabinetAbility

RangeAbility

LuckAbility

CourageAbility

CreativityAbility

GovernmentAbility

LoyaltyAbility

LogisticsAbility

MiniaturizationAbility

Modding Ships

If you just want to use the existing graphics that come with GalCiv2, you can build your ships in game and then move the files from your My Documents\My Games\GalCiv2\ship folder to the appropriate mods folders. Or, if you can make or get access to models in the .x file format, you can create your own components, or replace the graphics for the existing components. This section will give you the data you need to mod ships at whatever level you’re comfortable. There are 6 possible ship styles used by the various major races and the Dread Lords. These are the current ship styles:

0	Human
1	Torian
2	Yor
3	Drengin
4	Altarian
5	Dread Lords

I added code so that you can enable the Dread Lords style when customizing your race by un-commenting its entry in the screens.str file, but you will need to create more ship configurations and possibly models, or you’ll get invisible ships and possibly crashing. Only the Dread Lords use style 5, so if you want to make a race use a unique ship style, you can specify style 5 for their ships. Otherwise, you would have to change the style of other races so that your race’s style is unique.

A given ship in the game is actually using data from 3 different files: a file containing component definitions such as GC2Types.xml, a file containing the ship definition such as GC2Ships.xml, and a file containing the ship configuration, stored in a .shpcfg file (really an ini file). There is a subfolder for each of these data files in the Mods folder: ShipComponents, ShipDefs, and ShipCfg.

Ship Components

Ship component entries have to be read in before the ship definitions in order for the ships to load properly, which is why I made a separate folder for them instead of allowing them to be in a separate file. These are the types of ship components: Defense, Weapon, Hull, Drive, Sensor, LifeSupport, Module, and Structure. Each type has some unique fieldnames, so I'll go through each type one at a time and avoid duplicating explanations for fieldnames that the categories have in common. The common fieldnames are: Name, DisplayName, Size, SizeMod, Cost, Model, Thumbnail, Category and Tech_Requirement.

Name is the unique identifier of the component, and DisplayName is the name that is displayed in game text. The size is how much space the component takes up, or in the case of the Hulls, its capacity. The SizeMod is a value that modifies the size of a component, and is unused by hulls; the size mod is a percent of the max capacity of the ship. The cost of each component, including the hull, determines the total cost to build the ship. The Model field is the name of the x file used by the component. The thumbnail field tells the game which thumbnail to use if one is provided. The Category field is used mainly for the filters on the ship design screen. Tech_Requirement is the internal name of the tech that is required before this component can be added to a ship.

Defenses also use these fieldnames: Class, Absorption, and Animation. Class determines what kind of defense the component provides and has these possible values: A, S and PD, for Armor, Shields, and Point Defense, which are the possible values for the Category field. The reason that the data uses the Class field instead of the Category field is that the Category field needs to be something intelligible when it shows up in game, and the Class field needs to not be translated. Absorption determines how much damage is blocked from the ship. Animation is the name of the .x file with the animation to use when a defense is being used. Here is a sample defense:

<Name>ArmorPlating</Name>

<DisplayName>Armor Plating</DisplayName>

<Description>Armor helps deflect damage from mass-driver based weapons.</Description>

<Model>armor0</Model>

<Thumbnail>armor</Thumbnail>

<Category>Armor</Category>

<Tech_Requirement>StarshipDefenses</Tech_Requirement>

<Animation>Defense.x</Animation>

</Defense>

Weapons use these fieldnames: Class, Type, Damage, Animation, LaunchFrame, ImpactFrame, Explosion, AttackSound, ExplosionSound0 - ExplosionSound2, DeflectSound, and ScaleWidthPercent. Class is similar to the Class fieldname used by Defenses in that it determines what kind of damage the component does: G for Gun (Mass Drivers), B for Beam, and M for Missiles. The possible Category values for Weapons are: Mass Driver, Beam, and Missile. Type appears to be unused. Damage is the amount of damage that the weapon does. Animation is the name of the x file used to display its weapon animation. LaunchFrame and ImpactFrame determine which frame of the animation it should be at when the weapon is fired, and which frame it should be at when it hits its target. Explosion is the name of a .png file that is used for the explosion. AttackSound is the sound effect that is played when the weapon is fired, and the ExplosionSound fields are chosen randomly when the weapon hits its target. DeflectSound is the sound played when the weapon is blocked. ScaleWidthPercent is a number from 1 to 100% that scales the width of the animation. Here is a sample weapon:

<Name>SpaceCannon</Name>

<DisplayName>Space Cannon</DisplayName>

<Model>SpaceCannon</Model>

<Description>Small projectile weapon.</Description>

<Category>Mass Driver</Category>

<Tech_Requirement>Mass Driver Theory</Tech_Requirement>

<Animation>WFX_SpaCannon01.X</Animation>

<Explosion>explosion01.png</Explosion>

<AttackSound>battle_mini_attack</AttackSound>

<ExplosionSound0>battle_explosion_small</ExplosionSound0>

<ExplosionSound1>battle_explosion_small_2</ExplosionSound1>

<ExplosionSound2>battle_explosion_small</ExplosionSound2>

<DeflectSound>battle_armor_deflect</DeflectSound>

</Weapon>

Hulls have to have some basic information included in their definition so that people don't accidentally create ships with 0 hitpoints, 0 move points, or be forced to put sensors on every ships to be able to explore the galaxy. These required fields are: SensorRange, HP, Speed, and Logistics. SensorRange gives the ship a default sensor range in tiles aka parsecs, for how much Fog of War (FOW) the ship clears as it moves. The HP determines how many hitpoints the ship using this hull has. Speed is the default number of moves the ship can make in a turn without adding engines or increasing the civilization's native ability. Yes, I know that this is not realistic, but if you had to cram engines and sensors on every ship, you'd be sorry. Trust me. Logistics determine how much space in a fleet the ship takes up. Possible categories for Hulls are Tiny, Small, Medium, Large, Huge and Cargo. Hulls used to use the Category string to determine how to scale them in the combat viewer, but it appears that they now use the Model name, so you should always use the category name in the filename of the .x file.

<Description>Tiny hulls have very little space but are cheap and only use 2 logistic points. This means you can build bigger fleets of them.</Description>

<Tech_Requirement>XenoIndustrialTheory</Tech_Requirement>

</Hull>

Drives are engines. They have a Speed field also, which adds to the default Speed value of the Hull. They all use the Engine category in the file, but you could probably change them if you want to be able to filter your engines further.

<DisplayName>HyperDrive</DisplayName>

<Model>Hyperdrive0</Model>

<Tech_Requirement>HyperDrive</Tech_Requirement>

<Thumbnail>Hyperdrive0</Thumbnail>

<Category>Engine</Category>

</Drive>

Sensors, LifeSupport and Modules all are considered modules and they use the same tab in the ship design screen, so keep that in mind if you decide to monkey with their category values.

Sensors determine how much Fog of War (FOW) is uncovered when the ship moves. It also matters for a few ship functions like Sentry and Guard, which use the Sensor range of a ship to determine if they can come out of their sentry or guard mode. Sensors have a SensorRange field, which adds to the Hull's sensor range, but they can also have an Ability: Survey. Ships with a sensor that has the Survey ability can survey anomalies. Sensors also introduce the fields AltCost and AltCostPrereq. Currently, this is only used by the Survey Module, which you can get for 0 cost if you have built the Galactic Achievement Galactic Guidebook. The AltCostPrereq string consists of a two-letter prefix followed by a colon and then a name. The possible pre-fixes are GA and TG, Galactic Achievement and Trade Good. The name that follows the colon is the name of the improvement you have to have built to use the alternate cost. At the moment, there is a cap on sensor range of 15 parsecs (tiles) because the FOW code really bogs down the framerate once you get past the 15 parsecs limit. I’d like to fix this someday, but it’s one of the more low priority items.

<DisplayName>Sensors</DisplayName>

<Description>Increases the area your ships can see around them.</Description>

<Category>Sensor</Category>

<Thumbnail>Sensor</Thumbnail>

<Model>Sensor0</Model>

</Sensor>

LifeSupport extends the range that a ship can travel from its civilization's planets and starbases. A ship that is stranded out of range is considered as having to put all the crew in cryogenic chambers for the trip back home, and has to be set on autopilot to a destination that is in range of its planets and starbases. Yes, I know that a ship can move outside of its displayed range when it's on autopilot, but you can't stop it to attack another ship or colonize a planet, etc. so just live with the cheesiness, ok? Perfect solutions almost always take up a lot of time or memory, or both. Their special field name is just Range. Their Category field value is Support.

<DisplayName>Basic Support</DisplayName>

<Description>Extends the range of our ships.</Description>

<Category>Support</Category>

<Thumbnail>Support</Thumbnail>

<Model>Support0</Model>

</LifeSupport>

The Modules class is the catch all type for modules that do special stuff. This type includes colony modules, troop modules, constructor modules, and trade modules. These all add special abilities to the ships that they are on, although only the colony and troop modules add additional benefit after the first one is put on the ship. Eventually, I'd like to have multiple constructor modules correspond to multiple starbase modules and additional trade modules add to trade revenue, but we didn't have time for 1.0. These all use the Category string Capacity. Eventually, we will add more special ship modules like the Vampire and Wraith modules from Altarian Prophecy, and Detonation modules to make the GC2 equivalent of Anti-Matter Missiles. The Anti-Matter Missiles were some of my favorite ships in GC1. The module's ability is determined by its Ability field. Currently, the only supported values are Colonize, Troops, ConstructStarbase, and Trade. One last note: you will have noticed that you can't put Colony or Troops modules on Trade ships or Constructors, or vice versa. This is because it makes it harder for the hit detection logic to figure out what the ship is trying to do and because colonizing or invading a planet will destroy the colony or transport ship. So in an effort to avoid crashes or endless loops, you can't build colony freighters.

<DisplayName>Colony Module</DisplayName>

<Description>Each colony module holds 500 legions of colonists. Put these on your ships and then send those ships to uncolonized worlds that are habitable (class 1 or better).</Description>

<Model>Colony0</Model>

<Ability>Colonize</Ability>

<Thumbnail>Colony0</Thumbnail>

<Category>Capacity</Category>

</Module>

Structures don't do anything special. They're just eye candy. They all use the Category Structure, but if you try to change the Category so that there are multiple filters for these, you probably won't get what you expect because structure definitions might use different models for different styles. If you want to make additional ones, look at Structures that use style 99 and higher because those are less funky. They do have a Hidden field, which you can use to hide structures you don't want to see. Here's an example of a hidden structure:

<DisplayName>Attachment Modifier</DisplayName>

<Model>Structure100</Model>

<Thumbnail>Structure100</Thumbnail>

<Category>Structure</Category>

<Description>Rotate Hardpoint +90 Degrees</Description>

</Structure>

When we added the ability to rotate any component on the ship itself, the rotation hardpoints became obsolete, so we hid them. They will still be used for ships that already use them, but they don't appear in the ship design list.

Ship Definitions

Basically, a ship definition is a list of the components, a model name (corresponds to the shipcfg file) and a name. You can also add additional tech requirements, but by default the only tech requirements are from the components on the ship. Miniaturization is not directly a tech requirement, but ships that need miniaturization won't show up until you've researched enough miniaturization to meet its max capacity. You can take the ships right out of your My Documents\GalCiv2\ships folder and put them here, and their shipcfg files in the ShipCfg folder.

Here's a sample ship definition:

<DisplayName>Scout</DisplayName>

<Model>Scout</Model>

<Description>I find stuff, it's what I do.</Description>

<Component>TinyHull1</Component>

<Component>HyperDrive</Component>

<Component>Sensors0</Component>

<Component>BasicSupport</Component>

</Ship>

As you can see, the Tech_Requirement field does not appear. Its tech requirements are completely based on the components, which is really the best way to do it. It's less confusing. The fields in the sample, Name, DisplayName, Model, Description and Components are really the only ones you need. Also, you should probably only ever have 1 starbase definition, because the code will only use the first one it finds, which might lead to unexpected behavior. Model specifically refers to the shipcfg file. It leaves off the prefix, S0_, S1_, etc, because that refers to the ship style.

You can remove the UserDefined field and the UD_ from the model name if you want it to be more like a core ship, and it should still detect that it's a mod from being in the mods folder. You want it to be detected as a mod, because otherwise it won't find the shipcfg file and then it won't show up in the build lists. The UserDefined field is automatically added by the game when it is creating the xml file.

The Component fields are the internal names of the ShipComponents that the ship uses.

Ship Configurations

This folder same as in the Data folder: it holds the files that tell the game how to put together a ship from its parts. All the ShipCfg files use the same file naming convention. For example, the file S0_ColonyShip.shipcfg file means that this shipcfg file is used by the ship definition with the model name ColonyShip, in style 0. There are 6 styles, so possible prefixes range from S0_ to S5. User defined ships and config files used by the AI ships will also have numbers following the model name. In user defined ships, the number refers to the number of times the ship has been re-designed, starting with 0 for the original. The AI just randomly picks one of the shipcfg files with the number. User defined ships also have the string _UD_ in them.

So a core ship that any race could use would have a name like this: S0_ColonyShip.shipcfg.

An AI ship would use a filename like this: S4_Fighter1.shipcfg.

A user defined ship would use a filename like this: S0_UD_AngelOfWar0.shipcfg.

The .shipcfg file is an .ini file. The only section in this file is named [HULL]. It has two set key names. The first is Version, which stores what version of shipcfg file is. This allows us to specify different default values based on the version, or delete incompatible older versions if necessary. The other is BASE_HULL, which stores the filename of the model used by the ship's hull. The rest of the key names are determined by the name of the hardpoint. Hardpoints are visible as red arrows on the Ship Design Screen. Here's an example of the beginning of a shipcfg file:

[HULL]

Version=26

BASE_HULL=S0_Cargo_1.x

Dummy01=S0_Support0.x

Dummy01_Scale=0.250000

Dummy01_Yaw=0.000000

Dummy01_Pitch=0.000000

Dummy01_Roll=0.000000

Dummy01_Component=BasicSupport

The name of the hardpoint in this case is Dummy01. The key name that uses just the hardpoint name is the model of the component: in this case, a life support model. The rest of the key names use the hardpoint name plus an underscore and a suffix. They store the Scale of the component (to make it bigger or smaller than the default size), the Yaw (rotation around the y-axis), the Pitch (rotation around the x-axis), the Roll (rotation around the z-axis) and Component, which stores the name of the component in its definition file.

Sometimes a hardpoint has something attached to it that has another attachment. That's when you will see things like this:

Dummy01|Dummy09=S0_Colony0.x

Dummy01|Dummy09_Scale=1.275000

Dummy01|Dummy09_Component=ColonyModule

Dummy01|Dummy09_Scale_Component=ColonyModule

It's the name of the first hardpoint with the name of the second hardpoint appended to it, separated by the character that is a single vertical line: |

The easiest way to generate one of these files is to just build the ship in the game. I'm planning on adding code that will auto-generate the shipcfg files for all styles someday when you design the ship in one style, so that it saves all of the functional components and then you just have to add the jewelry and move around the functional components. It will save you some time and hassle, anyway.

So to tie all of the ship files together, here’s an example of a user designed ship that I made, saved in AngelOfWar.xml:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Component>MediumHull2</Component>

<Component>Impulsedrive</Component>

<Component>Plasma0</Component>

<Component>Duranthium</Component>

<Description>Made for smiting</Description>

<DisplayName>Angel Of War</DisplayName>

<Model>UD_AngelOfWar0</Model>

</Ship>

</GC2Ships>

Since I was playing as a race that used ship style 0, its Model (shipcfg file) is S0_UD_AngelOfWar0.shipcfg. It’s the first time that I designed a ship with this name. If I upgrade this ship later, it will update the xml file to use the model UD_AngelOfWar1 and create a shipcfg file called S0_UD_AngelOfWar0.shipcfg.

If I want to make this a core ship design, I change the model to AngelOfWar, and rename the shipcfg file to S0_AngelOfWar.shipcfg. If I want other races to be able to use it, I’ll have to either design other ships in different styles with the same components, or make multiple copies of the shipcfg file and change the prefix. I want to make an option to automatically create shipcfg files for the other styles which you can then edit, but I don’t know if I’ll have time for that.

I could also rename the shipcfg file to S0_Fighter1.shipcfg to replace one of the shipcfg files used by the AI ships.

Starbase Modules

Starbase modules make your starbase do something other than extend the area where your ships can travel. There are four types of starbases: Military, Economy, Culture, and Mining, in that order. Mining starbases can only be built on resources. You can only add modules to starbases that correspond to their type, or are allowed for any type of starbase.

Here is an example starbase module:

<Name>Invulnerability Bloom</Name>

<Model>Starbase01</Model>

<Tech_Requirement>Advanced Force Fields</Tech_Requirement>

<Module_Requirement>BattleStations</Module_Requirement>

<Description>Overlord-class Beam attacks don't stand a chance against these shields!</Description>

<StarbaseAbility>StarbaseDefense</StarbaseAbility>

<Type>Defense</Type>

</StarbaseModule>

Its InternalName is the unique identifier. The Name is actually the display name. I think that the model is unused because all of the ones in our files use Starbase01. Tech_Requirement is the internal name of the tech that allows it to be built on a starbase. The Module Requirement is the internal name of the starbase module that must be present on the starbase before this module can be built. The Module Size is unused. StarbaseAbility determines what the module does, more specifically than the Type, which directly corresponds to the numbers I gave earlier. Possible Type strings are:

Military	For military starbases only.
Economy	For economy starbases only.
Culture	For influence starbases only.
Mining	For mining starbases only.
Defense	Modules to aid in the defense of starbases; can be installed on any starbase.
Range	Modules to increase the area of the starbase’s influence.
Sensor	Modules to increase the base sensor range of the starbase.

These are the possible StarbaseAbility strings:

AttackAssist	Increases the attack values of ships with weapons in the area of effect.
Culture	Increases the influence of your civilization in its area of effect.
DefenseAssist	Increases the defense values of ships with defenses in the area of effect.
Mining	Increases the bonuses from mining a resource
ProductionAssist	Increases the production on planets in the area of effect.
RepairAssist	Increases the rate at which ships repair themselves in the area of effect.
ShipDocking	Unused, but was meant to allow ships to dock at the starbase, similar to being in orbit of a planet.
SlowEnemies	Decreases the move/attack points that an enemy ship can use in its area of effect.
SpeedAssist	Increases the move/attack points that one of your ships can use in its area of effect.
StarbaseAttack	Gives the starbase weapons
StarbaseDefense	Gives the starbase defenses
StarbaseRange	Increases the distance that a ship can travel from the starbase
StarbaseSensors	Increases the sensor range of the starbase
TerrorStar	Currently not implemented, but it would be a special kind of military starbase that can destroy star systems.
Trade	Increases the amount of revenue that a freighter on a trade route brings in while it is in the area of effect.

There are a few fields that give the values for the StarbaseAbility. StarbaseAbilityValue is the generic one. These three are the values for adding weapon values to the starbase or ships in the area of effect:

AttBeam, AttMissile, and AttMassDriver. These three are the values for adding defense values to the starbase or ships in the area of effect: DefShields, DefPointDefense, and DefArmor. This was in the code, but it seems that it should just use the StarbaseAbilityValue because it doesn't require it to be stored differently than any of the other values: SensorRange

Planet Improvements

Planet Improvements are structures you can build on your colonies to improve the colony, or occasionally improve your entire civilization. There are a lot of possible fields in these definitions so I'm not going to use a real definition to go through and list what each one does, because not every improvement has to have every field. As a warning, some of the values are hard-coded, which will make the fields not useful for modding. At some point, I might have time to change this, but not now. Generally, fields with the word bonus mean that they multiply current values rather than adding additional value.

The S_ before a field name indicates that it's a string field. The F_ before a field indicates that the value is a floating point number. This is for use by the parser.

S_Name	This is the name displayed in the game
S_InternalName	This is a unique identifier which we use to track the improvement.
S_Description	This is a description of what the improvement does.
S_Type	This sets the type of improvement: Destroy, Normal, SuperProject, GalacticAchievement, or TradeGood. Destroy is only used by the Decommission entry, which is used to destroy improvements that have been built. There should only be one of these as there is no advantage in having multiple destruction improvements. A Normal improvement can be built multiple times on multiple planets and affect only the planet on which they are built. SuperProjects, GalacticAchievements, and TradeGoods have limits about how often they can be built. SuperProjects and TradeGoods can only be built by one civilization, but they can be stolen by invasion. They benefit the entire civilization that controls them, not just the planet on which they are built. TradeGoods can be "traded" to other civilizations. The civilization that controls it is the only civilization that can trade it, but they still retain the benefit from the trade good after trading it, and the other civilization still gets the bonuses. GalacticAchievements can be built once by each civilization, but you still get the benefit of a duplicate galactic achievement if you conquer or culture flip a world with the duplicate achievement.
Cost	This is the cost to build the improvement, which affects how long it takes to build the improvement.
Maintenance	This is the maintenance cost that the improvement takes per turn after it is built.
S_IconName	This is the graphic (a png) that is used in the list entries on the Colony Management Window.
S_QueryGraphicName	This is the graphic shown in the context area that describes the improvement.
PlacementLimit	This field is used to limit the number of this type of improvement that can be built on a planet.
ManufactureBonus	This is the value of the bonus to production.
MoraleBonus	This is the value of the bonus to the morale (approval) of a planet.
EconomicBonus	This is the value of the bonus when calculating income from the planet.
PrestigeBonus	This is the value of the bonus to the influence of the planet.
PlanetaryQualityBonus	This is a bonus to the planet's quality, which affects its class and the number of useable tiles.
StarshipQualityBonus	This is a bonus to the attack and defense values of the ships built on the planet.
ResearchBonus	This is a bonus to the research production of the planet.
S_TechRequirement	This is the ID of the tech that unlocks this improvement to be built on a planet.
Industry	This is the amount of manufacturing points that this improvement produces.
Food	This is the amount of megatons of food that this improvement produces.
Research	This is the amount of research points that this improvement produces.
Indestructable	This means that the player cannot destroy this improvement. The initial colony has this tag.
S_BriefDescription	This is a shorter description of the improvement, should be able to fit on one line.
PlanetaryDefenseBonus	This adds a bonus to defense when defending against invasions.
AI	The AI uses this number when deciding what to build.
Employment	Unused.
S_UpgradeTarget	This is the internal name of the improvement that this improvement upgrades.
EnhanceLevel	This is the amount this improvement enhances a tile, with a value of 1-3. One is a yellow tile, two is a green tile, and three is a red tile. Enhancement projects are removed from the surface as soon as they are built and their affect applied, so you won't want to add this to an improvement that has another affect.
AbilityType	This is the Ability ID for Economics, etc. This is only used by Trade Goods, SuperProject, and GalacticAchievements.
AbilityAmount	This is the amount of ability added by this improvement, as a percent. For example, 10 is a 10% bonus.
S_Omega	Unused.
F_MightMultiplier	This is a spin variable that makes the AI think that you're tougher than you are, so they won't try attacking you because they think that you're an easy target.
F_LogisticLimit	This value increases the number of ships that you can have in an orbital fleet. The code that uses this looks for specific improvements, so adding this to additional improvements would have no affect.
F_AbilityFactor	This value specifies the percentage of the base ability that should be added to the base ability to arrive at the actual ability. For example, a value of 0.25 would increase the base ability by 25%
ShipMoveBonus	This adds additional movement points to ships built on a planet with this improvement. This also uses a hard-coded improvement name.
ResistanceBonus	This is a bonus to your colonists' ability to resist the cultural influence of other races. In other words, it makes the planet less likely to culture flip.
SpecialID	A unique identifier used by trade goods and galactic achievements. This will almost certainly cause problems if there are duplicate SpecialIDs and possibly if there are gaps between the numbers.
S_DataUpdateRequired	This is a delimited list of data that needs to be updated internally when the improvement becomes or ceases to be operational. Possible values are: ShipTypes, MiniMap.
ShipSpeedBonus	Like ShipMoveBonus, this adds additional movement points to ships built on a planet with this improvement, but without hard-coded names, so this can be used by multiple improvements.
F_OwnerBonus	This is only used by the temple improvements (more hard-coded names), which re-direct some of the money from other races' tourism income. It's a percent: so, 0.25 = 25%.
F_NonOwnerPenalty	This is the penalty you get if you don't have one of these temples built and there is another built.
MaxAlignment and MinAlignment	These are also used by the temple improvements, to determine if the civilization is affected by the temple improvements.

Anomalies

These are weird looking objects on the map that usually give you some kind of bonus, but not always. This is what an anomaly definition looks like:

<Description>Deep within the anomaly, your research team has stumbled across an abandoned starship. Using their interstellar know-how, spare rubber-bands, and a screwdriver, they hotwire the bad boy and get it going again. Nothing better than a free ship!</Description>

<Image>Gfx\\TestFreeShip.png</Image>

</Anomaly>

The internal name is the unique identifier for the object. As discussed previously, a mod with the same name as an existing definition will replace the existing data. The title is the name that is displayed in game. Description is pretty obvious; it shows up when you explore the anomaly. The Image field is the png file that is shown in the message dialog when you explore an anomaly, and the model is the .x file that it uses. Anomaly .X files use the naming convention Anomaly00.X. If the number is less than 10, it has a 0 in front of it, even if it's a 0. Otherwise it can just be a normal number. The number (without a leading zero) is what you list in the Model field. Quantity refers to the amount of the value that is being affected. In the above example, you get 1 free ship. In this particular case, that's meaningless because you only ever get one ship. Commonness is unused at this time. Power is a multiplier for the Quantity, but it's not the exact number because we usually divide it by 100 or otherwise mess with the data. Class is a further modification of the Type, which says what the anomaly does.

These are the anomaly types:

0	transfer money to (or take money from) player
1	relationship with other alien race is altered - not implemented
2	population of a planet is increased or decreased a %
3	research of the current technology is changed
4	find an undiscovered colony - not implemented
5	find a free ship - disabled
6	improve the current ship
7	fog of war areas are made visible - not implemented
8	a temporary wormhole takes your ship to random part of the galaxy
9	a planets' quality is improved by 1 – not implemented
10	a temporary wormhole takes your ship to a specific part of the galaxy - not implemented
11	find something to raise or lower one of the players' abilities
12	a space monster is released into the galaxy - disabled
13	an energy flux causes all ships in the sector to take damage - not implemented

These classes correspond to the Improve Current Ship type (6)

0	alter number of moves it gets in a turn
1	change the Max Hit Points of the ship
2	increase the ships experience
3	change strength
4	alter defense

In the type that modifies your civilizations' racial abilities (11), the ability index is stored as the quantity and the power is the change in the ability.

Events

These are the random events that require an ethical choice to be made. These can happen when you colonize a planet or at the end of the turn, but they stop happening once you research XenoEthics and choose an alignment.

<Description>Our scouts report that significant portions of the planet are inhabited by a sentient pod-like creature. These pods bond with other sentient life. Those who are bonded by these pods experience significant physical pain at all times, but have heightened intelligence. What are your orders?</Description>

<Image>Gfx\event_pods.png</Image>

<GoodOption>Keep our people away from those things. No one should have to live in agony.</GoodOption>

<NeutralOption>Encourage our people to make use of the pods, but don't force anyone. (+[NEUTRALVALUE]% Research bonus)</NeutralOption>

<EvilOption>Excellent! Require all colonists to be 'introduced' to these pods! (+[EVILVALUE]% Research bonus)</EvilOption>

</Event>

This is a pretty simple definition. There is a description of the event and 3 choices that you can make in response to this event, each one is considered good, neutral, or evil. EventType refers to if it happens at colonization of a planet (0) or at the end of a turn (1). GoodAttribute, NeutralAttribute and EvilAttribute refer to the planet attribute or racial ability that will be modified. The planet attributes that can be modified are:

0	None
1	Population of the planet
2	Morale/Approval
3	Production
4	Planet Quality (class)
5	Economy
6	Manufacturing
7	Influence
8	Defense
9	Research
10	Starships built on this planet gain attack and defense bonuses

If you want to affect the civilization's ability, use 100 for the attribute. If you want to add or subtract money, use the value 200 for the attribute. GoodPopChange, NeutralPopChange, and EvilPopChange is a value for when you lose population in an end turn event. The values for the GoodValue, NeutralValue, EvilValue, GoodPopChange, NeutralPopChange, and EvilPopChange are the max values for randomly generated values so that the event is different each time it occurs. The morality weight determines how much this event affects your morality.

The text in the square brackets are tags that are replaced dynamically in game by values. These are the possible tags:

[PLANETNAME]	The name of a planet.
[CIVNAME]	The name of your civilization when you get the event.
[PLAYERNAME]	Your player's (emperor's) name.
[GOODVALUE]	The change in the attribute if you choose the good option.
[NEUTRALVALUE]	The change in the attribute if you choose the neutral option.
[EVILVALUE]	The change in the attribute if you choose the evil option.
[GOODPOPCHANGE]	The change in population if you choose the good option.
[NEUTRALPOPCHANGE]	The change in population if you choose the neutral option.
[EVILPOPCHANGE]	The change in the population if you choose the evil option.

United Planets Issues

United Planets Issues change the rules of the game, but if you don't want to play by their rules, you can leave the council.

<Question>Since the beginning of intergalactic trade, we have all respected the private economies of our neighboring races. By allowing only a limited number of trade routes to be established, we've kept unfair trade practices from damaging relations. However, to further prosperity, we are considering expanding the number of immediately available trade routes by 2.</Question>

<SubQuestion>How many additional trade routes do you suggest?</SubQuestion>

<Option04>Three</Option04>

</UPIssue>

As always, InternalName is a unique identifier. The Question field is the main text of the issue that describes what the issue will change. The SubQuestion gets to the point and puts the question to the assembled civilizations. Option01-Option06 list the possible answers, with unused slots having no value. OptionVal01-OptionVal06 is the value associated with the choice. In the example above, it's the number of new trade routes that are available. Attribute is the type of issue being voted on. We currently have defined 31 attributes:

1	Change the number of trade routes: value01 = # of trade routes to alter, value02 = 0 add, 1 subtr
2	Anomalies in an owned sector can only be searched by sector owner
3	Tax on those engaging in warfare
4	Bonus income for civilizations with other races existing in their sector
5	Transports can now be armed
6	Player holds the Galactic Olympics, get increased revenue for x turns
7	Freighters are protected from attacks, at the cost of a certain % of trade revenue
8	Something to increase a racial ability has been found...which race gets it?: value01 = AbilityType, value02 = Ability Amount
9	Two races at war are forced to make temporary peace
10	One of the major races is forced to hand over a star system to the weakest major race
11	A once uninhabitable planet has recently become inhabitable...who gets the planet?
12	All major races at war have to make peace
13	A theme park holding space creatures is constructed on a planet, with a risk of beasts escaping
14	Evil races are forced to suspend trade for x years
15	Minor races are not allowed to be attacked
16	Number of modules allowed on a starbase is restricted
17	Starbases with assist upgrades will help allied ships/planets in the sector
18	All players must conform to a certain government
19	Evil players are taxed for their crimes against humanity
20	A random planet is converted to a prison world...production is doubled, but risk pirate breakout
21	A planet is chosen as the UP headquarters, increasing influence of that planet
22	Each player has to exchange technology secrets...leveling technology playing field
23	Number of ships each player should give the weakest player
24	Fleet found...who gets it
25	Vote on whether or not terror stars are allowed in the galaxy
26	Each race puts money towards event, morale goes up respectively for x years
27	Can't attack starbases
28	Costs money to own a starbase in someone else’s sector
29	Vote on whether or not to allow civilizations to build bombardment units
30	Raise the base speed of constructors so they aren't sitting ducks
31	Whoever is winning has to pay everyone else.

We took out the ones with space monsters and terror stars because they are not currently implemented.

AppliesTo seems to do nothing at the moment. Prereq also seems to be unused; I think that it was meant to be used for series of UP events, or maybe UP events that only happen if something else has happened, like a tech has been researched. That sounds cool, so maybe we'll do something with that in an expansion. Probability is also not implemented; originally, it was going to be used to determine how often an UP issue came up. YearsInEffect determines how long a proposition will remain in effect, if it is limited in time. If the value of YearsInEffect is 0, it's in effect forever. Value01-Value04 are used to apply the affect, which are in the descriptions of the Attributes above. The QuestionStr01-Question04 values are unused. HowAIWouldVote gives a small measure of control on how the AI would vote on the issue. These are the possible values:

0	Randomly vote, no logic involved
1	Vote on the higher number if winning the game
2	Vote on higher number if losing the game
3	Vote higher value if evil
4	Vote higher value if good
5	Vote for your enemy, or random person
6	Vote for you friend or yourself
7	Vote for yourself if losing, otherwise for a friend

Invasions

Invasion tactics give you various bonuses during invasion that may make up for a disadvantage in numbers. Here is a sample:

<DisplayName>Traditional Warfare</DisplayName>

<Description>Using the troops on hand and the best military equipment available, we send our soldiers into battle the classic way. Our men won't receive any bonuses, but this is the safest way to attack without fear of damaging the worlds we are invading.</Description>

<Tech_Requirement></Tech_Requirement>

<Image>Tactics_Flag</Image>

</InvTactic>

The tech requirement is the ID string for a tech, which will make this invasion tactic available when the tech is researched. The Image is a png file that is located in the Gfx\Invasion folder, or the corresponding mods folder. The cost is the price in money that you have to pay to use this tactic. The Luck factor in this file is currently unused, as is the Prerequirement and PreReq Values. The Bonus Type refers to what the invasion tactic affects to give you the bonus. These are the values:

0	no bonus
1	bonus to players attack
2	bonus to player’s defense
3	decrease defending planet's attack
4	decrease defending planet’s defense
5	take a % of the unhappy citizens (use overall morale to determine people to take)

The BonusValueMin and BonusValueMax determine the range that the applied bonus will fall in, determined randomly. The PlanetQualityPenaltyMin and PlanetQualityPenaltyMax fields determine the range of possible damage to the planet quality (and therefore the number of useable tiles). The InfluencePenaltyMin and InfluencePenaltyMax fields determine the range of the penalty applied to the planet's influence. The ImprovementPenaltyMin and ImprovementPenaltyMax determine the percentage of improvements that will be destroyed by using this invasion tactic.

Fleet Formations

The GalCiv2 Combat Viewer organizes ships into formations. Ships will be placed one by one into a formation until it is full. Only ships of the same hull size will be placed in the same formation. Attack ships will be grouped together in formations with other attack ships, while non-attack ships will be grouped together in formations with other non-attack ships.

The first formation a fleet will use is the default vee formation with three ships.

Then, new formations will be created to fit the other ships. Whenever a new formation is created, the formation type is randomly chosen from the following:

+ Default Formation (data/fleetformations/std_vee_3.fleet)

+ Standard 3 Ship Vee Formation (data/fleetformations/std_vee_3.fleet)

+ Standard 3 Ship Echelon Formation (data/fleetformations/std_ech_3.fleet )

+ Standard 3 Ship Pyramid (data/fleetformations/std_pyr_3.fleet)

+ A custom fleet formation file from the mods/fleetformations folder (If Mods are enabled in Options screen)

How to create your own custom fleet formations:

Fleet formation files must have the .fleet extension. They are text files that can be created with a simple text editor like NotePad.

The first line of the file is a header identifying the file as a formation. This must be first in every fleet file.

The header is:

[GALCIV2FLEETFORMATION]

The next line is a number specifying the number of ship positions in the formation.

Each line from this point specifies the position of a ship in the formation.

The fields on these lines are separated by a TAB character.

Each of these lines has the same format:

ShipNo ShipX ShipY ShipZ Unused1 Unused2

ShipNo is the position number. Numbers start at 1 and increase by 1 each line.

ShipX is the X position of the ship (relative to the formation position) ShipY is the Y position of the ship (relative to the formation position) ShipZ is the Z position of the ship (relative to the formation position)

Unused1 and Unused2 are no longer used by the program but must be present for the file to be used.

The position of the first ship should typically be (0.0, 0.0, 0.0). By default, formations face the positive Z direction.

Here is an example of the standard vee formation:

[GALCIV2FLEETFORMATION]

1 0.0 0.0 0.0 2 3

2 -120.0 0.0 -120.0 0 0

3 120.0 0.0 -120.0 0 0

Like all fleet formation files, this file begins with the header.

The first line specifies that there are 3 ship positions in this formation.

The last three lines specify the positions of the 3 ships, relative to the formation position.

This produces a formation that looks like this:

X X

This example uses a value of 120.0 as the space between ships. You can use different amounts for the space between ships, but keep in mind that after placing ships into formations, the program will adjust any ships that may be overlapping or colliding with each other. If the space between ships is too small, your formations may get distorted because they will need to be adjusted to correct any collisions.

Scenarios

Scenarios allow you to actually change the rules of the game, to some extent. These follow pretty much the same format as they did in GC1, although this time they are saved as ASCII text files instead of binary files. They use the ini file format. We would have liked to do a little more with scenarios and events, but we ran out of time. In scenarios, the symbol | is used to represent the end of line character.

Scenarios use these tags for the different races, but they are only tags, so if you mod the race names, they will still appear correctly in the game. These are the tags: Human, Drengin, Altarian, Arcean, Torian, Yor, Korx, Drath, Thalan, Iconian, Custom, and Dread Lords. I'm not sure if it's actually possible to play with a custom race in a scenario at the moment, though.

I am fairly sure that case matters with the section names and key names, and probably for tech names as well, so be careful when creating the file.

Under the [INFO] section name are the following fields: Description, Title, Image, Victory, Defeat, PlayerRace, Conversation, IntroScenePath, and VictoryScenePath. Description, Victory, and Defeat are basic text fields that describe what happens in the scenario. The description shows up when you select the scenario, and Victory or Defeat shows up at the end of the game. The Title of the scenario was added so that the filename doesn't have to be something intelligible. This is currently only used by the campaign scenarios, because I have to modify the code that the GalaxyWnd uses for its combo boxes to load the scenarios and the custom maps. Currently, the combo boxes only use the filename of the scenario with the extension removed. The image is a png file that is associated with the Scenario. This may only work with the campaign scenarios, but it might also show up in the loading dialog if you load a non-campaign game with a scenario that has an image specified. The player race is the Race ID of the race that the player will use when playing the scenario. The default is 0, for Humans. Conversation allows you to set another XML file to use for flavor text while playing the scenario. IntroScenePath and VictoryScenePath allow you to set cutscenes (in .bik format) to play at the beginning and successful conclusion of the game, respectively.

The [TEAM] section name contains the info about the teams in the scenario. 0 is no team. The key names are the race tags, set to an integer representing their team. Since there are only 12 possible races in the scenario, only 12 teams are possible, but if you can't actually play as a custom race, that number is only 11. Realistically, you are probably not going to have 10 or 11 one person teams, because it really wouldn't do anything. The Name1-Name12 fields are for the names of the teams, if you want to name them. This only shows up in campaign scenarios. If you don't specify the team names, they default to Team 1 - Team 12. I think. It might be Team 0 - Team 11 because I've been a C/C++ programmer long enough that it makes sense to me to start counting at 0.

The enabled races are listed under [ACTIVE]. A value of 1 means that the race is enabled and a value of 0 means that it is disabled.

When the race tag is a section name, that's where the starting relations are set. These are the possible values:

0	Unknown
1	At War
2	Hostile
3	Unfriendly
4	Cool
5	Neutral
6	Warm
7	Friendly
8	Close
9	Ally
10	Team
-1	Permanently At War

Values that affect all races are stored under the section [UNIVERSE]. The key names are TechRate, Velocity, PopulationGrowth, Morale, ShipCost, StarbaseLimit, and Influence. The possible values for these tags in the file run from 0 - 100, but then we monkey with them a bit when we load them into the game. Now remember, these affect ALL of the races. So if it helps you, it will help the AI just as much.

TechRate affects how fast you can research techs. This number is divided by 20 to get a 5 point scale.

Velocity affects how fast ships move. 50 points are subtracted from this value in game to give a range of -50% to 50%. Cranking this one up is fun. :)

Population Growth affects how fast populations grow. 50 points are subtracted from this value in game to give a range of -50% to 50%.

Morale affects how happy people naturally are. 50 points are subtracted from this value in game to give a range of -50% to 50%.

ShipCost affects military production. The value read in from the file is subtracted by 100 to get the inverse value and then 50 points are subtracted to give a range of -50% to 50%.

StarbaseLimit actually affects logistics, and now that starbases have nothing to do with logistics, it's a misnomer. 50 points are subtracted from this value in game to give a range of -50% to 50%.

Influence affects how fast cultural influence grows. 50 points are subtracted from this value in game to give a range of -50% to 50%. So if you want to slow down the affects of cultural influences, put a value less than 50 here. To make influence grow faster, give it a value greater than 50.

You can either give techs to all the civilizations, or restrict techs from all civilizations by listing them under the [TECHNOLOGY] section name. First, you have to list the number of starting techs that you are giving to the civilizations by setting a value for the key name Starting. Then the key names range from Starting0 to StartingN where N is the number 1 less than the number of starting techs. So if you start with 42 techs, the key names will range from Starting0 to Starting41. These should be set to the internal tech names as they appear in the tech definition files. The Restricted techs work the same way. First you set the number of restricted techs with the key name Restricted. Then the key names start with Restricted0 and go up just like the Starting techs. A restricted tech cannot be researched by any civilization.

Next are scenario end conditions. First, you set the number of Events under the section name [EVENT] with the key name count. Then each end condition has a section name with the format [EVENT#], starting with [EVENT0] up to the number of end conditions, minus 1. Here's a sample end condition:

[EVENT0]

type=1

race=0

outcome=0

description=Standard winning conditions.

In this event, nothing is actually changed.

The possible values for type are:

0	The game ends when a specific player gets control of a planet.
1	The game ends when a specific player is eliminated.
2	The game ends if relations rise or fall to a specified level.

The possible values for race are the RaceIDs, 0-11, with 11 standing in for the Dread Lords.

The possible values for outcome are: 0 for Defeat, and 1 for Victory.

Description is just a text description of what the end condition is. If no description is given, a pidgin description is generated for you in game.

You used to be able to change the default initial alignment of the races under the [MORALITY] section name, but it looks like that is currently unimplemented. The key names are the race tags, and the possible values range from 0 to 4, which would be modified in game to get a range from 0 - 100.

The [INTELLIGENCE] section name is still used, which will affect your difficulty setting. This section also uses the race tags for the key names and the possible values range from 0-8, which are indices for the actual values.

Custom Maps

We have an editor that we used for custom maps, but it barely functioned to get our custom maps done, and it’s not ready for public use.

Custom maps allow you to specify the placement of stars, planets, resources, and ships. Our map editor has a button for placing anomalies too, but we don’t actually parse that information. If you do not specifically place resources on a custom map, none will be created.

Here is a sample of a very simple map:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<Info>

</Info>

<Race>

</Race>

</Star>

</Planet>

<Moon>

</Moon>

</Planet>

<Ring>

</Ring>

</Planet>

</Resource>

</Anomaly>

<Type>Avatar</Type>

</Ship>

</GC2Map>

The Info section gives general information about the map. It is 3 sectors by 3 sectors (the code only supports square galaxies), and I think that the Size is corresponds to the index in our map editor, but we do not appear to use it in the GalCiv2 code. I don’t know if it’s possible to specify a number of sectors that doesn’t directly correspond to one of the galaxy sizes. You definitely won’t be able to specify more than 18, because that will cause crashes.

0	Tiny	3 sectors
1	Small	4 sectors
2	Medium	5 sectors
3	Large	8 sectors
4	Huge	12 sectors
5	Gigantic	18 sectors

Stars, Planets, Resources, Anomalies, and Ships all just give the number of these objects that are specified in the file. HomelessPlayers is a value that we added for the campaign, which allows players to start without a home planet; this value is 0 for false or 1 for true. If you do not specify a home planet and the HomelessPlayers field is 0, GalCiv2 will try to pick uninhabited planets for the players without planets.

The Race section lists the races with a number that is their ID in the file. It was a quick fix so that we could specify planets owned by Dread Lords. If we release the map editor, I’ll probably change it to just use the race name.

Now we’ll go through the objects, all of which specify their location with the fields X and Y. This refers to their position in the grid, with 0,0 being the upper left hand corner, as our map editor uses a top down view. We’ll start with the stars:

</Star>

The Star Name is the name of the star. If CustomName is set to 1, this is the name that will appear on the map for the star. Otherwise, it picks the name from the list of stars in stars.txt. Its type corresponds to the type field in Star Types. Size is a floating point number between 50 and 100. RotationSpeed determines how fast the star rotates and can range from 0.02 to 0.08. Pattern and Density are values that are passed to the function that creates the Star graphic. I’m not really sure what effect they have on the star, but their possible values are 1-100.

</Planet>

Planets can also have a custom name, like this one does. If a custom name is not specified, it uses the star name with a roman numeral. Owner is an optional field, and specifies the owner of the planet. Homeworld indicates if this is a homeworld for a race. If no owner is specified, but the homeworld flag is 1, this homeworld will be randomly assigned to a race that does not have a homeworld specified. Quality indicates the class of the planet. Size can be between 10 and 35. Rotation speed is the same as for the star. Influence is how much influence the planet has naturally. Star is the name of the planet’s star.

</Resource>

As you can see, the resource is very simple. The only value you don’t know is the Type, which has one of these values:

1	Influence (blue square)
2	Military (red cone)
3	Economy (green polyhedron)
4	Morale (yellow cylinder)
5	Technology (purple pyramid)

0 is an invalid value for resource types.

</Anomaly>

I’m going to skip anomalies because they are the same as resources except their type refers to the anomaly type. I think that if we actually parsed the data and no tag was specified, we would just randomly choose the anomaly type.

<Type>Avatar</Type>

</Ship>

We should probably add a custom name field for ships as well so that it will generate a name for the ship based on the class, but at the moment that’s not implemented. You could probably add the CustomName field to your ship entries so that it will be compatible if we add that in the future. The type refers to the ship name in the ship definition, what we usually refer to as the ship’s class name.

Owner works the same way as it does for planets.