Additive Data Mods

*こはね发表于 2022-5-1 10:05:46* · こはね发表于 2022-5-1 10:05:46

The Mods system now supports the concept of additive data mods.

In the old system of modding the game data the mod would take a copy of a game data file and make changes to it. This mod file would then override the base version of the file. When a new patch is released this would invalidate the mod which would have to be updated to incorporate the new changes to the data file. Also, if two different mods changed the same data file they would not be compatible so they couldn't both be enabled at the same time.

With additive mods, rather than overriding a base data file, the mod file is merged with the base data so that when the base data changes with a new patch the mod file is merged with the new data, so it should still be valid without needing to update it.

How to use it?
Place the additive mod file in the Data directory in your mod. The names of the mod files are shown in the table linked below:

Give the root xml node the name shown in the table.

Fill out the file with the changes that are to be made for the mod.

There is a new mergeMode attribute that is supported for each xml node (except for string mods) that determines how it is merged with the base data.

The valid values of mergeMode are: modify, add, remove and replace. If the mergeMode attribute is not present then it will default to modify if a matching node can be found in the base data, otherwise add.

Examples
protomods.xml
<protomods>
    <!-- remove a proto unit -->
    <Unit mergeMode='remove' name='PropsPottedPlants'/>
    <!-- modify a proto unit (add a new flag) -->
    <Unit name='PropsPoles'>
	<Flag>NotPlayerPlaceable</Flag>
    </Unit>
    <!-- modify a proto unit (add a Train and remove an existing Train) -->
    <Unit name='Manor'>
	<Train row='0' page='1' column='2'>Longbowman</Train>
	<Train mergeMode='remove'>xpColonialMilitia</Train>
    </Unit>
    <!-- replace a proto unit -->
    <Unit mergeMode='replace' id="1797" name='deIconUSCowboy'>
	<DBID>2372</DBID>
	<Icon>resources\art\units\spc\outlaws\cowboy_icon2.png</Icon>
	<PortraitIcon>resources\art\units\spc\outlaws\cowboy_portrait2.png</PortraitIcon>
    </Unit>
    <!-- add a proto unit -->
    <Unit name='MyNewProtoUnit'>
	<DBID>2400</DBID>
	<!-- ... proto unit data ... -->
    </Unit>
</protomods>


techtreemods.xml
<techtreemods>
     <!-- modify a tech (add effect - enable Pikeman for the Russians) -->
     <Tech name ='Age0Russian'>
	<Effects>
	    <Effect mergeMode='add' type ='Data' amount ='1.00' subtype ='Enable' relativity ='Absolute'>
		<Target type ='ProtoUnit'>Pikeman</Target>
	    </Effect>
	</Effects>
    </Tech>
    <!-- modify a tech (modify an effect by adding and removing - Sacred Cows now cost 10 food instead of 125 
food) -->
    <Tech name ='ypAge0IndiansSpecialTechs'>
	<Effects>
	    <Effect mergeMode='remove' type ='Data' amount ='45.00' subtype ='Cost' resource ='Food' relativity 
='Absolute'>
		<Target type ='ProtoUnit'>ypSacredCow</Target>
	    </Effect>
	    <Effect mergeMode='add' type ='Data' amount ='-70.00' subtype ='Cost' resource ='Food' relativity 
='Absolute'>
		<Target type ='ProtoUnit'>ypSacredCow</Target>
	    </Effect>
	</Effects>
    </Tech>
</techtreemods>


stringmods.xml
<stringmods>
   <StringTable>
      <Language name='English'>
	 <!-- change the text of the Continue button on the Main Menu -->
	 <String _locID='20038'>ModContinue</String>
      </Language>
   </StringTable>
</stringmods>

Hints and tips
There is a config variable called DebugOutputGameData. When this is defined the game will write out each data file after any additive mod files have been merged with the base data file every time the game data is loaded.

This can be used to check that the additive mods are having the expected effect on the data. Write out the data files with no mods enabled and then with mods enabled and compare the files to see the differences.

The files are written out to %TEMP%\Age of Empires 3 DE\Data (where %TEMP% is the location of your temp folder, eg. C:\Users\<user>\AppData\Local\Temp).

To set the config variable add DebugOutputGameData to the user.cfg file in the C:\Users\<user>\Games\Age of Empires 3 DE\<id>\Startup folder (create the file if it doesn't exist).

Additive Data Mods Reference
These are the data files that currently support additive modding:

Base file Mod file Root node name
protoy.xml protomods.xml <protomods>
techtreey.xml techtreemods.xml <techtreemods>
civs.xml civmods.xml <civmods>
politiciandata.xml politicianmods.xml <politicianmods>
nuggets.xml nuggetmods.xml <nuggetmods>
protounitcommands.xml protounitcommandmods.xml <protounitcommandmods>
cultures.xml culturemods.xml <culturemods>
maptypes.xml maptypemods.xml <maptypemods>
mapspecifictechs.xml mapspecifictechmods.xml <mapspecifictechmods>
attacktime.xml attacktimemods.xml <attacktimemods>
abilities\abilities.xml abilities\abilitymods.xml <abilitymods>
abilities\powers.xml abilities\powermods.xml <powermods>
randomnames.xml randomnamemods.xml <randomnamemods>
strings\<language>\*.xml strings\<language>\stringmods.xml <stringmods>
economymode.xml economymodemods.xml <economymodemods>
personalities.xml personalitiesmods.xml <personalitiesmods>
homecity<civ>.xml homecity<civ>.mods.xml <homecitymods>
tactics\<type>.tactics tactics\<type>.mods.tactics <tacticsmods>
uitechtree\techtreedata_<civ>.xml uitechtree\techtreedata_<civ>.mods.xml <uitechtreemods>