Appendix - The Encyclopedia Component in Detail

The encyclopedia component is a data block that controls all text, icon and image data for the object it is attached to. In most cases, this will be found within a unit’s company data, though this component can be attached to almost any object type in the game. This document will break down the contents of the component when used in companies; other objects may not use every aspect described here.

<EncyclopediaComponent>
  <ObjectNameTextID> TEXT_UNIT_NAME_UNIT_BRITISH_INFANTRY_00 </ObjectNameTextID>
  <ObjectDescriptionTextID> TEXT_UNIT_TOOLTIP_UNIT_BRITISH_INFANTRY_00 </ObjectDescriptionTextID>
  <EncyclopediaDescriptionTextID> TEXT_UNIT_TOOLTIP_UNIT_BRITISH_INFANTRY_00 </EncyclopediaDescriptionTextID>
  <DefaultIcons>
      <SmallIconName> UI_TacticalInfopanel_CompanyType_INF.tga </SmallIconName>
      <LargeIconName> UI_TacticalInfopanel_Nationality_ENG.tga </LargeIconName>
      <AltLargeIconName> UI_Tactical_BuildItem_Inf_UK_00.tga </AltLargeIconName>
      <PurchaseMenuFactionIconName> UI_StrategicPurchaseItem_Flag_ENG.tga </PurchaseMenuFactionIconName>
      <PurchaseMenuLogoIconName> UI_StrategicPurchaseItem_Type_Inf.tga </PurchaseMenuLogoIconName>
      <BackgroundImageIconName> ui_skirmish_lobby_unitnationality_ENG.tga </BackgroundImageIconName
      <GenericItemIconName> ui_genericitemicon_inf.tga </GenericItemIconName>
    </DefaultIcons>
    <CompanyInfo>
      <TypeIconTextureName> UI_TacticalInfopanel_CompanyType_INF.tga </TypeIconTextureName>
      <SideBarButtonTypeTextureName> UI_BuildBarItem_Inf_Basic.tga </SideBarButtonTypeTextureName>
      <SideBarButtonPortraitTextureName> UnitTray_Portrait_Inf_UK_00.tga </SideBarButtonPortraitTextureName>
      <TypeTextID> TEXT_COMPANY_TYPE_INFANTRY </TypeTextID>
      <CorpsTextID> TEXT_COMPANY_CORPS_BRITISH_I </CorpsTextID>
      <NationalityBonusTextID>TEXT_PERK_CORPS_INFANTRY_BRITISH_00</NationalityBonusTextID>
      <NationalityFlagTextureName> UI_Skirmish_Lobby_UnitNationality_ENG.tga </NationalityFlagTextureName>
      <NationalityInfoFlagTextureName> UI_Skirmish_Lobby_UnitNationality_ENG.tga </NationalityInfoFlagTextureName>
      <BannerFlagMaxZoomTopTextureName> Empty.tga </BannerFlagMaxZoomTopTextureName>
      <BannerFlagMaxZoomMiddleTextureName>UI_TacticalInfopanel_Nationality_ENG.tga</BannerFlagMaxZoomMiddleTextureName>
      <BannerFlagMaxZoomBottomTextureName> Empty.tga </BannerFlagMaxZoomBottomTextureName>
      <BannerFlagMidZoomTopTextureName> Empty.tga </BannerFlagMidZoomTopTextureName>
      <BannerFlagMidZoomMiddleTextureName>  UI_TacticalInfopanel_Nationality_ENG.tga </BannerFlagMidZoomMiddleTextureName>
      <BannerFlagMidZoomBottomTextureName> Empty.tga </BannerFlagMidZoomBottomTextureName>
      <BannerFlagMinZoomTopTextureName> Empty.tga </BannerFlagMinZoomTopTextureName>
      <BannerFlagMinZoomMiddleTextureName>  UI_TacticalInfopanel_Nationality_ENG.tga </BannerFlagMinZoomMiddleTextureName>
      <BannerFlagMinZoomBottomTextureName> Empty.tga    </BannerFlagMinZoomBottomTextureName>
      <GUIVirtualMaxUnitCount> 225 </GUIVirtualMaxUnitCount>
      <LobbySelectedInfoImageName> UI_Skirmish_Lobby_UnitImage_Infantry_00.tga </LobbySelectedInfoImageName>
    </CompanyInfo>
</EncyclopediaComponent>

The above example is from Company_Objects.XML and is the EncyclopediaComponent entry for the default British Infantry company if you want to see it in its normal location.

Section 1: Naming

The first section contains the three text tags required to see the name and tooltip descriptions for the company. The first line is the name by itself (for example, British Infantry Company) While the second and third lines contains the tooltip information. Note that the XML tag EncyclopediaDescriptionTextID is not currently used, so we just copy the previous line data into that one.

Section 2: Icons and Portraits

Section two is located in a sub-set of data called DefaultIcons. This set is used to display any icons, portraits and flags for the unit for tooltips, production menus and in skirmish mode.

Small Icon Name – This is the company type general icon (infantry, tank, artillery, etc.) You shouldn’t need to change this unless you are making something that does not currently exist in the game. The format is a 160x80 RGBA TGA texture.

Large Icon Name – This is the nationality flag icon that is shown above units on the battlefield. The format is a 160x80 RGB TGA texture.

Alt Large Icon Name – This is the image used for the purchase menu button. The format is a 140x208 RGBA TGA texture.

Purchase Menu Faction Icon Name and Purchase Menu Logo Icon Name – These tags are only needed on a corps objects, and only when it is purchased from the world map purchase menu.

Background Image Icon Name – This is used in multiple locations and represents the nationality flag of the company. The format is a 106x54 RGB TGA texture.

Generic Item Icon Name – This is the unit type icon shown in the unit’s banner on the battlefield. The format is a 160x80 RGBA TGA texture.

Section 3: Company-Specific Information

All XML tags in this portion of the component are in the CompanyInfo sub-section. Most of the data here is to display banners, unit tray and skirmish loadout information.

Audio - documented elsewhere at https://modding.playthegreatwar.com/xml/adding-custom-audio

Type Icon Texture Name – uses the same texture as SmallIconName to display the company type icon.

Side Bar Button Type Texture Name – displays the general unit type icon on the unit tray. The format is a 480x80 RGBA TGA texture.

Side Bar Button Portrait Type Texture Name – Displays the portrait image for the company on the unit tray. The format is a 120x224 RGB TGA texture.

Text Type ID – This is a text tag with a general descriptive name (Infantry Company) that displays in the infopanel in the lower right corner.

Corps Text ID – This text tag is not currently used, but could display unique company names if desired.

Nationality Bonus Text ID – This text tag is a tooltip description for the nationality bonus of the unit (currently limited to infantry companies). This is displayed in the info pane tooltip.

NationalityFlagTextureName - This the nationality flag displayed in the skirmish menu. Can use the same texture and format as BackgroundImageIconName.

Nationality Info Flag Texture Name – This the nationality flag displayed in the skirmish loadout menu. Can use the same texture and format as BackgroundImageIconName.

Banner Flag Max Zoom Middle Texture Name – This (and the set of icons around this entry) are used for the different zoom levels of the camera when displaying the flag texture on unit banners. In general, these are unused; if they are shown as “Empty.TGA” you don’t need to worry about them. Can use the same texture format as LargeIconName. If you want the image to stay the same at all zoom levels, simply use the same texture for Max, Middle and Min zoom.

GUI Virtual Max Unit Count – This number is used to simulate a larger population than is actually present for a company. In this example, a company of British soldiers contains only 75 actual soldier models, but we inflate this in the GUI to 225 in the display so that each soldier represents three. You can put any number here, but it is a good idea to keep the display number as a multiple of the actual company model count.

Lobby Selected Info Image Name – This is a generic unit type icon used in skirmish (infantry, tank, aircraft, and artillery. It is in the format 722x406 RBGA TGA.

Icon Specifications

The following is a list of special XML files that are powerful tools when modding, along with a description of their purpose. Note that changes to these files can break the game, so use caution when editing data in them.

ArtilleryCastAbilityGenerators.XML

This file contains all of the abilities and effect generators for all of the artillery abilities. WARNING: This is one of the most complex files in the game and not for beginners. It is suggested that only modders familiar with previous Petroglyph game modding try to make changes to this file.

Attributes.XML

This is a list of numeric modifiers that are used throughout the game. These can be used in formulas, counts or anywhere you need a numeric variable. It is suggested that only advanced modders edit this file.

CompanyEffectGenerators.XML

This file contains effect generators used on companies. This generally handles such things as trench bonuses, morale penalty or bonus effects, weather effects, etc.

CompanyObjects.XML

This file contains every company in the game for both factions, including the base templates for the multiple company types. Companies also contain the portrait, banner and flag information for each company.

CorpsObjects.XML

This file contains every corps object in the game for both factions. This includes the marker object that is moved on the world map.

DamageToAttribute.xml

This file contains a matrix of modifiers for all damage types versus all armor types. Every object in the game has an armor type (listed in the DamageableComponent as DamageGroup), and every weapon has a damage type (this will be listed either in the DamageableComponent as PrimaryDamageType or in the individual weapon ability). The matrix here modifies the incoming damage before applying it to the recipient. For example, if a Tank armor has 0.5 vs. Machine Gun damage and the base MG damage is 4, the tank will only take 2 points per shot from that machine gun. This file is for those who wish to perform a full combat rebalance for the game.

Events_SAMPLE_TEST.XML

This file contains a list of sample events of all types and includes extensive comment sections to show format and setup. Highly useful if you want to create your own events and need a detailed guide on how things need to be formatted.

Faction Files (FactionX.XML, FactionX_Strategic.XML)

The X in the file names above will be 1 for Allies and 2 for Germany. The faction files contain all of the default values for a specific faction. This includes a list of which units and structures they can build, team/GUI colors and layout, etc. The Faction file contains tactical map data, while the Faction strategic file handles world map data. If you add a new object to the game and want the faction to build it, it must be listed here.

FactionX_Structure_Voters.XML and FactionX_Unit_Voters.XML

The X in the file names above will be 1 for Allies and 2 for Germany. Voters are blocks of rules that dictate when an object can be built or placed in the game. In most cases this will include a rule for “must have enough resources” but will also contain rules for pre-requisite tech, other structures, etc.

GameConstants.XML

This file contains all static data that is universal to the game, generally applying to all game modes. Examples include the encyclopedia setup, auto-resolve data, and multiple default values for game modifiers. If there is a value that is used everywhere in the game,chances are it is in this file.

GameObjectFiles.XML

This file is a list of all files that the game uses for its data. If you want to add a new file to the game, it must be listed here. If you reference a new object from a file that is not listed here, the game will crash.

Instances.XML

This file contains the full list of every map, campaign and historic battle available in the game. If you are going to be creating your own campaigns or historic missions, you will need to add it to this file.

MovieAudioEvents_XXX.XML (Where XXX is a language)

This file contains the subtitles for the cinematics in the game. Each data block is the name of the movie, with text tags for subtitle lines and timing in seconds. If you want to add a new movie and offer subtitles, you do that here.

MusicEvents.XML

This file contains a list of the primary places in the game where music is used, and the track list for which music tracks can be played in those locations. If you want to adjust or replace music tracks, you will need this file.

ObjectStates.XML

This is a list of flags that can be used in a variety of ways including labels for unit types, checks for targeting, flags for events or scripting, etc. It is suggested that only advanced modders edit this file.

Regions_XXX.XML (Where XXX is a year or description)

These files contain the unique region data for a specific campaign. These files are references in Instances.XML to be tied to a specific world map campaign. The file contains starting units, region structures, star levels, etc. If you want to make a new campaign, copy one of these, give it a new name and then edit it as desired.