Skip to content

XML Reference

Jump to bottom
ghost-ng edited this page Jan 28, 2026 · 3 revisions

XML Reference

This page documents all XML elements, attributes, and tags used in Civilization VII modding. Information sourced from official Firaxis documentation and verified against game source files.

XML File Types

Civ VII uses several XML file types with different root elements:

Root Element Purpose File Extension
<Database> Standard database modifications .xml
<GameEffects> Simplified modifier definitions .xml
<Mod> Mod configuration .modinfo

ModInfo XML Schema

The .modinfo file is the entry point for all mods.

Root Element: <Mod> 

<?xml version="1.0" encoding="utf-8"?>
<Mod id="my-mod-id" version="1" xmlns="ModInfo">
Attribute Required Description
id Yes Unique identifier. Use lowercase, dashes, ASCII only. Max 64 chars. Prefix with developer tag (e.g., fxs-, suk-)
version Yes Version number
xmlns Yes Must be ModInfo

<Properties>

<Properties>
    <Name>My Mod Name</Name>
    <Description>What the mod does</Description>
    <Authors>Your Name</Authors>
    <AffectsSavedGames>1</AffectsSavedGames>
    <Package>optional-package-name</Package>
    <PackageSortIndex>0</PackageSortIndex>
    <ShowInBrowser>1</ShowInBrowser>
    <EnabledByDefault>1</EnabledByDefault>
</Properties>
Element Required Description Default
Name Yes Display name in Add-Ons screen -
Description Yes Description text -
Authors Yes Author name(s) -
AffectsSavedGames No 1 = can't add/remove mid-game, 0 = UI/text only 1
Package No Groups mods together (not currently used) -
PackageSortIndex No Sort order within package -
ShowInBrowser No Show in Add-Ons screen 1
EnabledByDefault No Auto-enable on first install 1

<Dependencies>

<Dependencies>
    <Mod id="other-mod-id" title="Other Mod Name"/>
</Dependencies>

Dependencies must be active for this mod to activate. They load before this mod.

Attribute Description
id Mod ID of dependency
title Display name of dependency

Default dependencies (always loaded): core, base-standard, age-antiquity, age-exploration, age-modern

<References>

<References>
    <Mod id="other-mod-id" title="Other Mod Name"/>
</References>

References load before this mod but don't require activation.

<ActionCriteria>

Defines conditions for when ActionGroups execute.

<ActionCriteria>
    <Criteria id="my-criteria">
        <AgeInUse>AGE_ANTIQUITY</AgeInUse>
    </Criteria>
</ActionCriteria>
Attribute Description
id Unique identifier (per mod)
any If true, ANY condition matches. If absent/false, ALL must match

Criterion Types

Element Description Example
<AlwaysMet> Always true <AlwaysMet></AlwaysMet>
<NeverMet> Always false <NeverMet></NeverMet>
<AgeInUse> Current age matches <AgeInUse>AGE_ANTIQUITY</AgeInUse>
<AgeWasUsed> Previous age matches (not current) <AgeWasUsed>AGE_ANTIQUITY</AgeWasUsed>
<AgeEverInUse> Current or previous age matches <AgeEverInUse>AGE_ANTIQUITY</AgeEverInUse>
<ModInUse> Mod is active <ModInUse>other-mod-id</ModInUse>
<MapInUse> Map type matches <MapInUse>{base-standard}maps/continents.js</MapInUse>
<RuleSetInUse> Ruleset matches <RuleSetInUse>RULESET_STANDARD</RuleSetInUse>
<GameModeInUse> Game mode matches <GameModeInUse>SinglePlayer</GameModeInUse>
<LeaderPlayable> Leader is selectable <LeaderPlayable>LEADER_HATSHEPSUT</LeaderPlayable>
<CivilizationPlayable> Civ is selectable (age-aware) <CivilizationPlayable>CIVILIZATION_ROME</CivilizationPlayable>
<ConfigurationValueMatches> Game config matches See below
<ConfigurationValueContains> Config in list See below

Inverse modifier: Add inverse="1" to negate any criterion.

<AgeInUse inverse="1">AGE_ANTIQUITY</AgeInUse>  <!-- NOT Antiquity -->

ModInUse with version:

<ModInUse>
    <Version>2.0</Version>
    <Value>other-mod-id</Value>
</ModInUse>

ConfigurationValueMatches:

<ConfigurationValueMatches>
    <Group>Game</Group>
    <ConfigurationId>SpeedType</ConfigurationId>
    <Value>GAMESPEED_STANDARD</Value>
</ConfigurationValueMatches>

ConfigurationValueContains:

<ConfigurationValueContains>
    <Group>Game</Group>
    <ConfigurationId>Handicap</ConfigurationId>
    <Value>DIFFICULTY_PRINCE,DIFFICULTY_KING</Value>
</ConfigurationValueContains>

GameModeInUse values: WorldBuilder, SinglePlayer, HotSeat, MultiPlayer

<ActionGroups>

<ActionGroups>
    <ActionGroup id="my-actions" scope="game" criteria="my-criteria">
        <Properties>
            <LoadOrder>10</LoadOrder>
        </Properties>
        <Actions>
            <!-- Action elements here -->
        </Actions>
    </ActionGroup>
</ActionGroups>
Attribute Description
id Unique identifier (per mod)
scope game (gameplay) or shell (frontend/menus)
criteria References a Criteria id

Action Types

Action Description Scope
<UpdateDatabase> Load .xml/.sql into game/shell database Both
<UpdateText> Load localization data Both
<UpdateIcons> Load icon definitions Both
<UpdateColors> Load color definitions Both
<UpdateArt> Load art assets Both
<ImportFiles> Import files (images, scripts) Both
<UIScripts> Load UI JavaScript files Both
<UIShortcuts> Load debug panel HTML Both
<UpdateVisualRemaps> Remap visual assets Both
<MapGenScripts> Load map generation scripts Game
<ScenarioScripts> Load gameplay scripts Game

Each action contains <Item> elements with file paths:

<Actions>
    <UpdateDatabase>
        <Item>data/my-data.xml</Item>
        <Item>data/more-data.sql</Item>
    </UpdateDatabase>
    <UpdateText>
        <Item>text/my-text.xml</Item>
    </UpdateText>
    <ImportFiles>
        <Item>icons/my-icon.png</Item>
    </ImportFiles>
</Actions>

Database XML Schema

Root Element: <Database>

Standard database modifications use <Database> as root:

<?xml version="1.0" encoding="utf-8"?>
<Database>
    <!-- Table elements here -->
</Database>

Table Elements

Each table is an element containing <Row> children:

<TableName>
    <Row Column1="value1" Column2="value2"/>
    <Row Column1="value3" Column2="value4"/>
</TableName>

Core Tables

Types

Every game entity must be registered:

<Types>
    <Row Type="UNIT_MY_UNIT" Kind="KIND_UNIT"/>
    <Row Type="BUILDING_MY_BUILDING" Kind="KIND_BUILDING"/>
    <Row Type="CIVILIZATION_MY_CIV" Kind="KIND_CIVILIZATION"/>
</Types>
Column Type Description
Type TEXT Unique identifier (e.g., UNIT_WARRIOR)
Kind TEXT Entity kind (e.g., KIND_UNIT)

Common Kinds: KIND_UNIT, KIND_BUILDING, KIND_CIVILIZATION, KIND_LEADER, KIND_TRAIT, KIND_TRADITION, KIND_MODIFIER, KIND_ABILITY, KIND_RESOURCE, KIND_NARRATIVE_STORY

Units

<Units>
    <Row
        UnitType="UNIT_WARRIOR"
        Name="LOC_UNIT_WARRIOR_NAME"
        Description="LOC_UNIT_WARRIOR_DESCRIPTION"
        BaseSightRange="2"
        BaseMoves="2"
        UnitMovementClass="UNIT_MOVEMENT_CLASS_FOOT"
        Domain="DOMAIN_LAND"
        CoreClass="CORE_CLASS_MILITARY"
        FormationClass="FORMATION_CLASS_LAND_COMBAT"
        ZoneOfControl="true"
        CanTrain="true"
    />
</Units>
Column Type Description
UnitType TEXT Primary key, matches Type
Name TEXT Localization key
Description TEXT Localization key
BaseSightRange INTEGER Vision range
BaseMoves INTEGER Movement points
UnitMovementClass TEXT Movement type
Domain TEXT DOMAIN_LAND, DOMAIN_SEA, DOMAIN_AIR
CoreClass TEXT CORE_CLASS_MILITARY, CORE_CLASS_CIVILIAN, etc.
FormationClass TEXT Formation type
ZoneOfControl BOOLEAN Exerts ZOC
CanTrain BOOLEAN Can be trained
CanPurchase BOOLEAN Can be purchased
CanEarnExperience BOOLEAN Gains XP

Unit_Stats

<Unit_Stats>
    <Row UnitType="UNIT_WARRIOR" Combat="25"/>
    <Row UnitType="UNIT_ARCHER" Combat="15" RangedCombat="25" Range="2"/>
</Unit_Stats>

TypeTags

<TypeTags>
    <Row Type="UNIT_WARRIOR" Tag="UNIT_CLASS_COMBAT"/>
    <Row Type="UNIT_WARRIOR" Tag="UNIT_CLASS_MELEE"/>
    <Row Type="UNIT_WARRIOR" Tag="UNIT_CLASS_INFANTRY"/>
</TypeTags>

Civilizations

<Civilizations>
    <Row
        CivilizationType="CIVILIZATION_ROME"
        Name="LOC_CIVILIZATION_ROME_NAME"
        FullName="LOC_CIVILIZATION_ROME_FULLNAME"
        Description="LOC_CIVILIZATION_ROME_DESCRIPTION"
        Adjective="LOC_CIVILIZATION_ROME_ADJECTIVE"
        StartingCivilizationLevelType="CIVILIZATION_LEVEL_FULL_CIV"
        CapitalName="LOC_CITY_NAME_ROME_CAPITAL"
        RandomCityNameDepth="15"
    />
</Civilizations>

Traits

<Traits>
    <Row
        TraitType="TRAIT_CIV_ABILITY"
        Name="LOC_TRAIT_NAME"
        Description="LOC_TRAIT_DESCRIPTION"
        InternalOnly="false"
    />
</Traits>

CivilizationTraits

<CivilizationTraits>
    <Row CivilizationType="CIVILIZATION_ROME" TraitType="TRAIT_ANTIQUITY_CIV"/>
    <Row CivilizationType="CIVILIZATION_ROME" TraitType="TRAIT_ROME_ABILITY"/>
</CivilizationTraits>

Leaders

<Leaders>
    <Row
        LeaderType="LEADER_CAESAR"
        Name="LOC_LEADER_CAESAR_NAME"
        InheritFrom="LEADER_DEFAULT"
    />
</Leaders>

Traditions (Policies)

<Traditions>
    <Row
        TraditionType="TRADITION_MY_POLICY"
        Name="LOC_TRADITION_NAME"
        Description="LOC_TRADITION_DESCRIPTION"
    />
</Traditions>

ProgressionTreeNodeUnlocks

<ProgressionTreeNodeUnlocks>
    <Row
        ProgressionTreeNodeType="NODE_TECH_AQ_BRONZE_WORKING"
        TargetKind="KIND_UNIT"
        TargetType="UNIT_WARRIOR"
        UnlockDepth="1"
    />
</ProgressionTreeNodeUnlocks>

Modifier Tables (Database Method)

When not using GameEffects XML:

DynamicModifiers

<DynamicModifiers>
    <Row
        ModifierType="MY_MODIFIER_TYPE"
        CollectionType="COLLECTION_PLAYER_CITIES"
        EffectType="EFFECT_CITY_ADJUST_YIELD"
    />
</DynamicModifiers>

Modifiers

<Modifiers>
    <Row
        ModifierId="MY_MODIFIER"
        ModifierType="MY_MODIFIER_TYPE"
        OwnerRequirementSetID="REQSET_OWNER"
        SubjectRequirementSetID="REQSET_SUBJECT"
    />
</Modifiers>

ModifierArguments

<ModifierArguments>
    <Row ModifierId="MY_MODIFIER" Name="YieldType" Value="YIELD_FOOD"/>
    <Row ModifierId="MY_MODIFIER" Name="Amount" Value="2"/>
</ModifierArguments>

RequirementSets

<RequirementSets>
    <Row
        RequirementSetId="REQSET_MY_REQUIREMENTS"
        RequirementSetType="REQUIREMENTSET_TEST_ALL"
    />
</RequirementSets>
RequirementSetType Description
REQUIREMENTSET_TEST_ALL ALL requirements must be met
REQUIREMENTSET_TEST_ANY ANY requirement must be met

Requirements

<Requirements>
    <Row
        RequirementId="REQ_HAS_GRANARY"
        RequirementType="REQUIREMENT_CITY_HAS_BUILDING"
    />
</Requirements>

RequirementSetRequirements

<RequirementSetRequirements>
    <Row RequirementSetId="REQSET_MY_REQUIREMENTS" RequirementId="REQ_HAS_GRANARY"/>
</RequirementSetRequirements>

RequirementArguments

<RequirementArguments>
    <Row RequirementId="REQ_HAS_GRANARY" Name="BuildingType" Value="BUILDING_GRANARY"/>
</RequirementArguments>

EntityModifier Tables

Link modifiers to game entities:

Table Links To
TraitModifiers Civilization/Leader traits
TraditionModifiers Traditions and policies
UnitAbilityModifiers Unit abilities
ConstructibleModifiers Buildings and wonders
GameModifiers Global game modifiers 
<TraitModifiers>
    <Row TraitType="TRAIT_CIV_ABILITY" ModifierId="MY_MODIFIER"/>
</TraitModifiers>

<TraditionModifiers>
    <Row TraditionType="TRADITION_MY_POLICY" ModifierId="MY_MODIFIER"/>
</TraditionModifiers>

GameEffects XML Schema

Simplified modifier creation. Cannot mix with standard Database operations in same file.

Root Element: <GameEffects> 

<?xml version="1.0" encoding="utf-8"?>
<GameEffects xmlns="GameEffects">
    <!-- Modifier elements here -->
</GameEffects>

<Modifier> Element

<Modifier id="MY_MODIFIER" collection="COLLECTION_PLAYER_CITIES" effect="EFFECT_CITY_ADJUST_YIELD" permanent="true">
    <Argument name="YieldType">YIELD_FOOD</Argument>
    <Argument name="Amount">2</Argument>
    <String context="Description">LOC_MY_MODIFIER_DESCRIPTION</String>
</Modifier>
Attribute Required Description
id Yes Unique modifier ID
collection Yes Collection type (subjects)
effect Yes Effect type (what it does)
permanent No true for persistent effects (narrative events)

<Argument> Element

<Argument name="ArgumentName">ArgumentValue</Argument>

Arguments vary by effect type. Common examples:

Argument Used With Description
YieldType Yield effects YIELD_FOOD, YIELD_PRODUCTION, etc.
Amount Most effects Numeric value
BuildingType Building effects Building type
ConstructibleType Constructible effects Building/wonder type
UnitTag Unit effects Unit class tag

<String> Element

<String context="Description">LOC_MY_TEXT</String>
<String context="Preview">LOC_COMBAT_PREVIEW</String>

Requirements in GameEffects

<Modifier id="MY_MODIFIER" collection="COLLECTION_PLAYER_CITIES" effect="EFFECT_CITY_ADJUST_YIELD">
    <OwnerRequirements type="REQUIREMENTSET_TEST_ALL">
        <Requirement type="REQUIREMENT_PLAYER_HAS_TECHNOLOGY">
            <Argument name="TechnologyType">TECH_WRITING</Argument>
        </Requirement>
    </OwnerRequirements>
    <SubjectRequirements type="REQUIREMENTSET_TEST_ANY">
        <Requirement type="REQUIREMENT_CITY_HAS_BUILDING">
            <Argument name="BuildingType">BUILDING_GRANARY</Argument>
        </Requirement>
        <Requirement type="REQUIREMENT_CITY_HAS_BUILDING">
            <Argument name="BuildingType">BUILDING_WAREHOUSE</Argument>
        </Requirement>
    </SubjectRequirements>
    <Argument name="YieldType">YIELD_FOOD</Argument>
    <Argument name="Amount">2</Argument>
</Modifier>

<RequirementSet> (Standalone)

For Narrative Events and reusable requirement sets:

<RequirementSet id="REQSET_MY_REQUIREMENTS" type="REQUIREMENTSET_TEST_ALL">
    <Requirement type="REQUIREMENT_PLAYER_CIVILIZATION_TYPE_MATCHES">
        <Argument name="CivilizationType">CIVILIZATION_ROME</Argument>
    </Requirement>
</RequirementSet>

Localization XML

LocalizedText Table

<?xml version="1.0" encoding="utf-8"?>
<Database>
    <LocalizedText>
        <Row Tag="LOC_MY_TEXT" Language="en_US">
            <Text>My localized text here</Text>
        </Row>
    </LocalizedText>
</Database>
Column Description
Tag Unique localization key
Language Language code (e.g., en_US, es_ES, zh_Hans_CN)
Text The actual text

EnglishText Shorthand

<EnglishText>
    <Row Tag="LOC_MY_TEXT">
        <Text>English text here</Text>
    </Row>
</EnglishText>

Equivalent to LocalizedText with Language="en_US".

Inline Icons

Use in localized text:

Icon Code Displays
[icon:YIELD_FOOD] Food icon
[icon:YIELD_PRODUCTION] Production icon
[icon:YIELD_GOLD] Gold icon
[icon:YIELD_SCIENCE] Science icon
[icon:YIELD_CULTURE] Culture icon
[icon:YIELD_HAPPINESS] Happiness icon
[icon:YIELD_INFLUENCE] Influence icon
[icon:STAT_COMBAT] Combat Strength icon
[icon:STAT_MOVEMENT] Movement icon

Icon XML

IconDefinitions

<Database>
    <IconDefinitions>
        <Row>
            <ID>BUILDING_MY_BUILDING</ID>
            <Path>fs://game/my-mod-id/icons/my_icon.png</Path>
        </Row>
    </IconDefinitions>
</Database>

Icon path format: fs://game/{mod-id}/{path-in-mod}

IconTextureAtlases

<IconTextureAtlases>
    <Row Name="ICON_ATLAS_MY_ICONS" IconSize="50" Filename="icons/my_icons_50.dds"/>
    <Row Name="ICON_ATLAS_MY_ICONS" IconSize="38" Filename="icons/my_icons_38.dds"/>
</IconTextureAtlases>

Color XML

Colors

<Database>
    <Colors>
        <Row>
            <Type>COLOR_MY_COLOR</Type>
            <Color>229,117,116,255</Color>
            <Color3D>229,117,116,255</Color3D>
        </Row>
    </Colors>
</Database>
  • Color: RGBA for UI
  • Color3D: RGBA for 3D models

PlayerColors

<PlayerColors>
    <Row>
        <Type>LEADER_MY_LEADER</Type>
        <Usage>Unique</Usage>
        <PrimaryColor>COLOR_MY_PRIMARY</PrimaryColor>
        <SecondaryColor>COLOR_MY_SECONDARY</SecondaryColor>
        <Alt1PrimaryColor>COLOR_ALT1_PRIMARY</Alt1PrimaryColor>
        <Alt1SecondaryColor>COLOR_ALT1_SECONDARY</Alt1SecondaryColor>
    </Row>
</PlayerColors>

Narrative Events XML

NarrativeStories

<NarrativeStories>
    <Row
        NarrativeStoryType="EVENT_MY_EVENT"
        Name="LOC_EVENT_NAME"
        Description="LOC_EVENT_DESCRIPTION"
        Completion="LOC_EVENT_COMPLETION"
        StoryTitle="LOC_EVENT_TITLE"
        Age="AGE_ANTIQUITY"
        Activation="REQUISITE"
        ActivationRequirementSetId="REQSET_ACTIVATION"
        RequirementSetId="REQSET_COMPLETION"
        UIActivation="STANDARD"
        IsQuest="FALSE"
        Hidden="FALSE"
    />
</NarrativeStories>
Column Description
NarrativeStoryType Primary key
Name Button text (required even if unused)
Description Tooltip text (required even if unused)
Completion Popup body text
StoryTitle Popup title
Age Which age(s)
Activation REQUISITE, LINKED, LINKED_REQUISITE, AUTO
ActivationRequirementSetId One-time check on init
RequirementSetId Completion check (or Met)
UIActivation STANDARD, DISCOVERY
IsQuest TRUE/FALSE
Hidden Skip popup if TRUE

NarrativeStory_Links

<NarrativeStory_Links>
    <Row
        FromNarrativeStoryType="EVENT_PARENT"
        ToNarrativeStoryType="EVENT_CHILD"
        Name="LOC_BUTTON_NAME"
        Description="LOC_BUTTON_DESC"
    />
</NarrativeStory_Links>

NarrativeRewards

<NarrativeRewards>
    <Row NarrativeRewardType="REWARD_MY_REWARD" ModifierID="MY_MODIFIER"/>
</NarrativeRewards>

<NarrativeStory_Rewards>
    <Row
        NarrativeStoryType="EVENT_MY_EVENT"
        NarrativeRewardType="REWARD_MY_REWARD"
        Activation="COMPLETE"
    />
</NarrativeStory_Rewards>

NarrativeRewardIcons

<NarrativeRewardIcons>
    <Row NarrativeStoryType="EVENT_MY_EVENT" RewardIconType="YIELD_FOOD"/>
    <Row NarrativeStoryType="EVENT_MY_EVENT" RewardIconType="QUEST"/>
</NarrativeRewardIcons>

Common Collection Types

Collection Targets
COLLECTION_OWNER The owner entity
COLLECTION_PLAYER_CITIES All player's cities
COLLECTION_PLAYER_UNITS All player's units
COLLECTION_PLAYER_TRADE_ROUTES Player's trade routes
COLLECTION_CITY_PLOTS Plots in a city
COLLECTION_UNIT_COMBAT During combat

Common Effect Types

Effect Description
EFFECT_CITY_ADJUST_YIELD Modify city yields
EFFECT_PLOT_ADJUST_YIELD Modify plot yields
EFFECT_ADJUST_UNIT_COMBAT_STRENGTH Modify combat strength
EFFECT_PLAYER_ADJUST_CONSTRUCTIBLE_YIELD Modify building yields
EFFECT_TRADE_ROUTE_ADJUST_YIELD Modify trade route yields
EFFECT_CITY_ADJUST_UNIT_TAG_ERA_PRODUCTION Production bonus for unit types

Common Requirement Types

Requirement Description
REQUIREMENT_CITY_HAS_BUILDING City has specific building
REQUIREMENT_PLOT_TERRAIN_TYPE_MATCHES Plot terrain matches
REQUIREMENT_PLOT_FEATURE_TYPE_MATCHES Plot feature matches
REQUIREMENT_PLAYER_HAS_TECHNOLOGY Player has tech
REQUIREMENT_UNIT_TAG_MATCHES Unit has tag
REQUIREMENT_OPPONENT_UNIT_TAG_MATCHES Enemy unit has tag
REQUIREMENT_PLAYER_CIVILIZATION_TYPE_MATCHES Player civ matches
REQUIREMENT_PLAYER_HAS_AT_LEAST_NUM_GOSSIPS Gossip-based (flexible)

See Also

Navigation

Home Cross-Reference Index

Getting Started

Civilization Creation

Database Reference

Units & Combat

Religion

Independents

Diplomacy

Technology & Civics

Victory Conditions

Legacy Paths

Modifier System

JavaScript API

Narrative Events

Technical Reference

Tutorials

Examples

Progress Tracker

Clone this wiki locally