Mod Structure

Mod Basics

A Mod consists of a directory on disk that includes an XML file that provides information about the mod, a preview image that is used in-game when browsing mods, and a subdirectory containing one or more replacement or additional data files to be loaded by the game that apply the effects of the mod.

The root of the mod directory should contain at least the following:

• TheGreatWar_Mod.xml
• TheGreatWar_Mod.jpg
• DATA\

Mod Configuration

TheGreatWar_Mod.xml contains basic information about the mod that is presented to the user when they are browsing mods in-game. The ModInfo structure has the following fields:

• <Name> - The non-localized name of the mod. This name is combined the mod version numbers to create a unique identifier for the mod. If multiple mods have the exact same name and version number fields, only the first mod found will be considered.
• <LocalizedNames> - A place to put UTF-8 localized versions of your mod's name that will be shown to the user based on their locale.
• <Description> - Default description of the mod to display to the user.
• <LocalizedDescriptions> - UTF-8 Localized descriptions of the mod that will be shown to the user based on their locale. If this isn't present, the default will be used
• <Author> - The name of the mod's author
• <VersionLow> and <VersionHigh> - Used in combination with the field to uniquely identify a mod.
• <ModTypeText> - A field suggesting the mod type. There are no hard and fast rules about which to use since mods can change/add multiple things. Builtin localized options are one of
  • TEXT_MOD_MANAGER_MOD_TYPE_CAMPAIGN
  • TEXT_MOD_MANAGER_MOD_TYPE_GENERAL
  • TEXT_MOD_MANAGER_MOD_TYPE_SKIRMISH,
  • TEXT_MOD_MANAGER_MOD_TYPE_HISTORIC.
  • Or you can supply your own non-localized text in this field.

Example

<?xml version="1.0" encoding="utf-8"?>
<GreatWarMods>
  <!--
  This file contains info about the mod used by the game when loading/displaying the mod
  -->
  <ModInfo>
    <!--
    Mod name displayed in-game. The mod name and version must be unique across all installed mods
    -->
    <Name>Petroglyph: Siege of Paris</Name>
      <!--
      Mod name displayed in-game (localized)
      -->
      <LocalizedNames>
        <Entry>
          <Locale>en-us</Locale>
          <Name>Petroglyph: Siege of Paris</Name>
        </Entry>
      </LocalizedNames>

    <!--
    Description displayed in-game
    -->
    <Description>A sample mod that adds an alternate history campaign: Siege of Paris. Accessible via
    "Campaign" from the main menu. </Description>

    <!--
    Author displated in-game
    -->
    <Author>Petroglyph</Author>

    <!--
    Version of mod
    -->
    <VersionLow>0</VersionLow>
    <VersionHigh>1</VersionHigh>

    <!--
    Can be one of TEXT_MOD_MANAGER_MOD_TYPE_CAMPAIGN, TEXT_MOD_MANAGER_MOD_TYPE_GENERAL,
    TEXT_MOD_MANAGER_MOD_TYPE_SKIRMISH, TEXT_MOD_MANAGER_MOD_TYPE_HISTORIC, or use non-localized text
    -->
    <ModTypeText>TEXT_MOD_MANAGER_MOD_TYPE_CAMPAIGN</ModTypeText>
  </ModInfo>
</GreatWarMods>

Mod File Types & Locations

In mods, data files that have the same name as a data file in the base game will be loaded in preference to the base game's file. This is true of all data file types. Active Mods will be searched in the order that they are listed in the mod selection dialog in-game. Files in mods at the top of the list will be found before those later in the list. Once a file with the same name is found in an active mod, the search completes and that first found file is loaded in preference to the file in the base game. Similarly named files in lower priority mods will then be ignored.

In general, to replace an original file with a modded version, the modded file should be placed in the same relative path under the mod's data directory as the original file. The exceptions to this are new XML files referenced in ModConfig.xml, and Lua and shader (.pgso, .pgso12) files that didn't exist in the original base game.

Replacement File Types & Locations

Mod Specific Log Output

Mod activity is output to mod-specific log files located in the Log directory. Mod_Log_0.txt contains mod log entries output by the game client Mod_Log_Client0.txt contains mod log entries output by the game server.

Special Rules for XML Files in Mods

In order to maximize compatibility between mods, additional XML files not present in the base game can also be loaded. Such additional XML files are specified in the ModConfig.xml that should be included with each mod.

These additional XML files specified in ModConfig.xml must be named differently to any of the XML files present in the base game. For example, you can't specify an additional Game Constants XML file called GameConstants.xml because that's the name of the base game's Game Constants file. Any other name is allowed, so for example you could call it MyGameConstants.xml or SuperCampaignModConstants.xml.

Additional XML files specified this way in ModConfig.xml do not have to have unique names across all mods, only collisions with the base game need to be avoided. For example, 'JoesSuperMod' and 'WorstModEver' could both specify additional XML files called 'NewConstants.xml' and both files would be loaded and applied according to their relative position in the mod selection list in-game.

The following additional XML file types are supported:

<!--
Add additional Game Object XML files here. These are files that would normally be listed in
GameObjectFiles.xml in the base game. Adding new files
here instead of completely replacing GameObjectFiles.xml will improve compatibility with other
mods.
-->
<AdditionalGameObjectXMLFiles>
</AdditionalGameObjectXMLFiles>

<!--
Add additional Game Constants XML files here. Values in files listed here will overwrite values
in the base GameConstants.xml file. Changing only the
values needed for the mod will improve compatibility with other mods vs. replacing the entire
base GameConstants.xml file. There's no need to use
the 'modify=""' attribute on tag names in additional game constants files as modification is
assumed here.
-->
<AdditionalGameConstantsXMLFiles>
</AdditionalGameConstantsXMLFiles>

<!--
Add additional Instances XML files here. Adding new instances in their own files here instead
of replacing the entire Instances.xml file will improve
compatibility with other mods.
-->
<AdditionalInstancesXMLFiles>
</AdditionalInstancesXMLFiles>

<!--
Add additional SFX Events XML files here. These are files that would normally be listed in
SFXEventFiles.xml in the base game. Adding new files
here instead of completely replacing SFXEventFiles.xml will improve compatibility with other
mods.
-->
<AdditionalSFXEventXMLFiles>
</AdditionalSFXEventXMLFiles>

<!--
Add additional Anim Template XML files here. These are files that would normally be listed in
AnimTemplateFiles.xml in the base game. Adding new files
here instead of completely replacing AnimTemplateFiles.xml will improve compatibility with
other mods.
-->
<AdditionalAnimTemplateXMLFiles>
</AdditionalAnimTemplateXMLFiles>

<!--
Add additional Enum XML files here. These are files that would normally be listed in EnumFiles.
xml in the base game. Adding new files
here instead of completely replacing EnumFiles.xml will improve compatibility with other mods.
-->
<AdditionalEnumXMLFiles>
</AdditionalEnumXMLFiles>

<!--
Add additional Attribute System XML files here. These are files that would normally be listed
in Attribute_System_Files.xml in the base game. Adding new files
here instead of completely replacing Attribute_System_Files.xml or Attributes.xml will improve
compatibility with other mods.
-->
<AdditionalAttributeXMLFiles>
</AdditionalAttributeXMLFiles>

<!--
Add additional Damage To Attribute XML files here. Adding new files here instead of completely
replacing DamageToAttribute.xml will improve compatibility with other mods.
-->
<AdditionalDamageToAttributeXMLFiles>
</AdditionalDamageToAttributeXMLFiles>

<!--
Add additional Effect Class XML files here. Adding new files here instead of completely
Copyright 2023 Petroglyph Games, Inc. 8
replacing EffectClasses.xml will improve compatibility with other mods.
-->
<AdditionalEffectClassesXMLFiles>
</AdditionalEffectClassesXMLFiles>

<!--
Add additional Object Classification XML files here. Adding new files here instead of
completely replacing ObjectClassifications.xml will improve compatibility with other mods.
-->
<AdditionalObjectClassificationsXMLFiles>
</AdditionalObjectClassificationsXMLFiles>

<!--
Add additional Object Classification Template XML files here. Adding new files here instead of
completely replacing ObjectClassificationTemplates.xml will improve compatibility with other mods.
-->
<AdditionalObjectClassificationTemplateXMLFiles>
</AdditionalObjectClassificationTemplateXMLFiles>

<!--
Add additional Object State XML files here. Adding new files here instead of completely
replacing ObjectStates.xml will improve compatibility with other mods.
-->
<AdditionalObjectStateXMLFiles>
</AdditionalObjectStateXMLFiles>

<!--
Add additional Graphics Details XML files here. Adding new files here instead of completely
replacing GraphicsDetails.xml will improve compatibility with other mods.
-->
<AdditionalGraphicDetailXMLFiles>
</AdditionalGraphicDetailXMLFiles>

<!--
Add additional Input Translator XML files here. Adding new files here instead of completely
replacing InputTranslatorConfigurations.xml will improve compatibility with other mods.
-->
<AdditionalInputTranslatorXMLFiles>
</AdditionalInputTranslatorXMLFiles>

<!--
Add additional Logical Event Map XML files here. Adding new files here instead of completely
replacing LogicalEventMaps.xml will improve compatibility with other mods.
-->
<AdditionalLogicalEventMapXMLFiles>
</AdditionalLogicalEventMapXMLFiles>

<!--
Add additional Mouse Pointer XML files here. The X2 version of the XML file contains the
pointers used when the larger mouse pointer option is enabled.
Adding new files here instead of completely replacing MousePointers.xml or MousePointersX2.xml
will improve compatibility with other mods.
-->
<AdditionalMousePointerXMLFiles>
</AdditionalMousePointerXMLFiles>
<AdditionalMousePointerX2XMLFiles>
</AdditionalMousePointerX2XMLFiles>

<!--
Add additional UI Hint Map XML files here. Adding new files here instead of completely
replacing UIHints.xml will improve compatibility with other mods.
-->
<AdditionalUIHintXMLFiles>
</AdditionalUIHintXMLFiles>

<!--
Add additional UI Cinematic XML files here. Adding new files here instead of completely
replacing UICinematics.xml will improve compatibility with other mods.
-->
<AdditionalUICinematicsXMLFiles>
</AdditionalUICinematicsXMLFiles>

<!--
Add additional Surface FX XML files here. Adding new files here instead of completely replacing
SurfaceFX.xml will improve compatibility with other mods.
-->
<AdditionalSurfaceFXXMLFiles>
</AdditionalSurfaceFXXMLFiles>

<!--
Add additional Shadow Blob Materials XML files here. Adding new files here instead of
completely replacing ShadowBlobMaterials.xml will improve compatibility with other mods.
-->
<AdditionalShadowBlobMaterialsXMLFiles>
</AdditionalShadowBlobMaterialsXMLFiles>

<!--
Add additional Camera XML files here. Adding new files here instead of completely replacing
Cameras.xml will improve compatibility with other mods.
-->
<AdditionalCameraXMLFiles>
</AdditionalCameraXMLFiles>

<!--
Add additional Voter XML files here to extend StructureVoters.xml. Adding new files here
instead of completely replacing StructureVoters.xml will improve compatibility with other mods.
-->
<AdditionalVoterXMLFiles>
</AdditionalVoterXMLFiles>

<!--
These entries are for extending animation index, hard point, and model bounds files. These will
be needed if new models are added to the game
Adding new files here instead of completely replacing the original XML/DAT files will improve
compatibility with other mods.
-->
<AdditionalAnimationIndexXMLFiles>

<!--
The AnimationIndex.dat file that is included in the base game is a binary
representation of the data. To extend it, we need to use an XML
version. A simple example looks like this:
<?xml version="1.0" encoding="utf-8"?>
<AnimationIndex>
  <AnimationIndexLoader>
    <AnimationSets>
      <Entry>
        <AnimationRootName>P_WINDMILL_03<
        /AnimationRootName>
        <Animations>
          <Entry>P_WINDMILL_03+DEATH_00.ala<
          /Entry>
          <Entry>P_WINDMILL_03+IDLE_00.ala</Entry>
        </Animations>
      </Entry>
    </AnimationSets>
  </AnimationIndexLoader>
</AnimationIndex>
-->
</AdditionalAnimationIndexXMLFiles>
<AdditionalHardPointsXMLFiles>
</AdditionalHardPointsXMLFiles>
<AdditionalModelBoundsXMLFiles>
</AdditionalModelBoundsXMLFiles>

<!--
Copyright 2023 Petroglyph Games, Inc. 10
Add additional SFX/Music XML files here. Adding new files here instead of completely replacing
the original XML files will improve compatibility with other mods.
-->
<AdditionalAmbientSFXXMLFiles>
</AdditionalAmbientSFXXMLFiles>
<AdditionalMusicEventXMLFiles>
</AdditionalMusicEventXMLFiles>
<AdditionalAudioSystemXMLFiles>
</AdditionalAudioSystemXMLFiles>

<!--
Add additional Movie Audio Events (subtitles) files here using the appropriate entry for the
language being modified.
Adding new files here instead of completely replacing the original XML files will improve
compatibility with other mods.
-->
<AdditionalMovieAudioEventsEnglishXMLFiles>
</AdditionalMovieAudioEventsEnglishXMLFiles>

<AdditionalMovieAudioEventsFrenchXMLFiles>
</AdditionalMovieAudioEventsFrenchXMLFiles>

<AdditionalMovieAudioEventsGermanXMLFiles>
</AdditionalMovieAudioEventsGermanXMLFiles>

<AdditionalMovieAudioEventsSpanishXMLFiles>
</AdditionalMovieAudioEventsSpanishXMLFiles>

<AdditionalMovieAudioEventsRussianXMLFiles>
</AdditionalMovieAudioEventsRussianXMLFiles>