This mod allows players to hire and fire mercenaries as auxillaries to their regular military forces.
Mercenaries Mod v0.6
Patch Compatibility: v1.61
MP Compatible: ?
This mod allows players to hire and fire mercenaries as auxillaries to their
regular military forces.
Please note that I have tried to maintain the flow of the regular game
interface as best as I could. Please read the known issues section for the
current release of this mod before contacting me about some type of issue or
inconsistency that you may be seeing. Most of these are lack of hooks into the
game relating to the display of some of the in-game graphics.
1) Unzip this into the "civ4_install_folder\Mods\" folder.
2) Open the CivilizationIV.ini configuration file
3) Change the Mod line to read: Mod = Mods\Mercenaries Mod
4) Load the game.
5) Then play as normal.
- Mod configuration through the "Mercenaries Mod Config.ini" file, no more
going through python files to tweak the mod.
- 25 non-dynamic mod configurable options, fully documented in the
"Mercenaries Mod Config.ini" file. Some of these are:
- When mercenaries should be available in the game
- When mercenaries should be added: beginning of each game turn or beginning
or beginning of each player's turn
- Minimum and maximum number of mercenaries game should create
- Maximum number of mercenaries that should be available in the game
- Where mercenaries should be placed when hired
- If certain buildings should be required to hire and place mercenaries
- Tweaking the mercenaries hiring and maintenance costs
- Dynamic unit exclusion through INI file, don't want to allow civilization
unique units as mercenaries? Well you can update the INI to exclude them
as game generated mercenaries.
- UI (user interface) updates created to flow with the existing game interfaces
- Randomly generated mercenaries (types dependent on mod configuration) with
random experience and promotions.
- All mercenaries or units contracted out as mercenaries get unique name. Over
16,000,000 names possible through random name generator.
- Hire and fire mercenaries at will
- Contract out units as mercenaries
- Mercenary per turn maintenance costs and income accurately represented in
- AI players can hire, fire and use mercenaries, you have been warned.
- Keyboard shortcut 'ALT-M' brings up the "Mercenary Manager" screen
- Messages announce the arrival of hired mercenaries to a players civilization,
return of contracted out units to a players civilization, hiring and firing
of units contracted out as mercenaries and deaths of units contracted out as
mercenaries when hired by other players.
- Financial advisor reports all mercenary costs and income
- 2 new action buttons allow quick contracting out of units and firing of
- Self Preservation I:
- +25% Withdrawal chance
- +10% Strength
- Requires Mercenary promotion
- Only available for mercenaries
- Self Preservation II:
- +20% Withdrawal chance
- +10% Strength
- Requires Self Preservation I
- Immune to first strikes
- Only available for mercenaries
- Self Preservation III:
- +15% Withdrawal chance
- +15% Strength
- Requires Self Preservation II
- Can use enemy roads
- Only available for mercenaries
- Used to identify mercenaries from regular units
-----Notes to Modmakers-----
I have used Dr. Elmer Jiggles event manager code to make integrating this
code as easy as possible with other mods that use his event manager code.
If your mod does not use his event manager code I highly recommend it,
especially if you are planning to use multiple mods that need to act on
the various events in the game.
I have tried to make this mod component as configurable as possible to
achieve this I have used Dr. Elmer Jiggles INI parsing code. In order for
this functionality to work correctly you need to change the name of the
mod in the CvModName.py file to your own mods name, otherwise the INI
file will not be read in and the default values will be used.
If you want to use the Mercenaries Mod in your mod I have tried to make
things as easy as possible for you. In the XML files modified sections are
In the Python files I have added # < Mercenaries Start > and
# < Mercenaries End > in all of the places that I have made changes to
the original files.
All I ask is that you give me credit
- Updated all python code and XML to be compatible with the v1.61 patch.
- Files updated: CvMainInterface.py, CvMercenaryModGameUtils.py and
- Fixed the issue reported by DanoDavid, this issue is the same issue addressed
by talchas in his action buttons mod comp where sometimes an exception is
thrown when a action button ID number is used.
- Fixed the issue reported by DanoDavid, the placement code is broken when the
barbarian hires a mercenary. To fix this barbarians can no longer hire
- Added fix to the INI parser code provided by Dr. Elmer Jiggle
- Changed the code to bind the 'M' key as a shortcut to the 'Mercenary Manager'
screen to 'Alt-M'
- Fixed the issue reported by DanoDavid. Mercenaries were not being correctly
removed when they were lost or killed.
- Fixed the bug reported by Darkhour. Units contracted out with extra
experience would loose that experience when hired and placed in the game.
- Added mercenary placement information in the "Mercenary Information" panel
so it matches the information displayed in the "Unit Information" panel,
requested by Darkhour.
- Updated getHireCost code so there are no more 0 hire cost mercenaries.
Reported by Darkhour.
- Commented out mercenary groups lines in CvMercenaryManager.py file since
the mercenary groups feature will not be implemented as part of the first
release of the Mercenaries Mod.
- Finished fully documenting and commenting the MercenaryUtils.py and
- Added action button in CvMainInterface.py allowing players to indicate that
they want to contract out the selected mercenary as a mercenary.
- Added action button in CvMainInterface.py allowing players to fire
- Updated the plot to plot distance code using 12monkeys algorithm instead
of using the sqrt((X2-X1)^2 + (Y2-Y1)^2)
- Added a find button to the "Mercenary Manager: Mercenaries" screen when
pressed it will close the "Mercenary Manager" screen and zoom to the unit.
This should be helpful when trying to find hired mercenaries.
- Added a find button to the "Mercenary Manager: Mercenary Contracts" screen
when pressed it will close the "Mercenary Manager" screen and zoom to the
unit. This should be helpful when deciding which unit should be contracted
out as a mercenary.
- Changed the "Mercenary Promotion Chance" default value from 25% to 10%.
- Changed the "Hire Cost Modifier" default value from 1.0 to 0.8
- Fixed the disappearing mercenary/contracted out unit issue when they are
upgraded. As it turns out when a unit is upgraded (i.e. archer to
longbowman) they do not retain their original ID number as one would
- Added option allowing players to require units be in friendly cities
to be contracted out. Default value set to true. Requested by Belizan.
- Added location information to the available units in the "Mercenary
Manager: Mercenary Contracts" screen when the units are in a friendly
city and the "Require City Unit Contract Creation" is set to true.
- Added check for multiplayer game, if it is then the unitSelect method will
not be called
- Updated "Mercenary Manager" screen:
- Using the hire or fire functionality now clears out the "Mercenary
Information" panel, reported by Shqype.
- Removed the duplicate XP information in the "Mercenary Information" panel,
reported by Shqype.
- Added strength and movement information to the "Mercenary Information"
panel, requested by Shqype and Belizan
- Removed the "Use Enemy Routes" bonus for the "Self Preservation"
promotion, reported by Shqype.
- Fixed python issue in computerPlayerThink method, reported by Shqype and
- Added option allowed players the ability to configure if mercenaries should
start with or without their full movement points. If the option is set to
false then the last hired mercenary will be selected when the "Mercenary
Manager" screen is hidden.
- Fixed game crash error, reported by Belizan
- Finished fully re-documenting and commenting the MercenaryUtils.py file.
- Finished documenting the MercenaryNameUtils.py file.
- Added changes made to the Financial Advisor screen in the mod. These changes
display the mercenary maintenance costs and income. Also removed the tool tip
information displayed when hovering over the strings since they displayed the
- Updated "Mercenary Manager" screen with a new screeing allowing players to
designate units as mercenaries for hire and the ability to cancel their
unit's mercenary contracts. The code will not allow players to subcontract
out mercenaries they have hired.
- Hooked up code to add the hire and maintenance income to players gold when
their contracted out units are hired.
- Split up the self preservation promotion into three promotions that can only
be used by game generated mercenaries.
- Added the mercenary trait/promotion. It is given to any mercenary unit, game
generated or player contracted out unit. This new trait is useful for
identifying mercenary units in play and through the military advisor.
- Updated the random name generator, it will now generate over 16,000,000
unique unit names.
- Added option allowing players to delay mercenary placement by a configurable
amount. When mercenaries are placed in the game they are announced using
an announcement message. When the delay mercenary placement option is used
mercenaries will still appear in the hired mercenary list in the "Mercenary
Manager" screen but players will be unable to fire them until they arrive to
the player's civilization. Also, when units contracted out are hired they
will continue to show up in the "Units Contracted Out" list but players will
be unable to cancel their contracts until they are placed. Requested by
- Add option allowing players to supress mercenary appearence messages.
- Added option allowing players to indicate that the mercenary starting
location must be set to a list of buildings and that for players to hire
mercenaries at least one of their cities must contain at least one of the
buildings in the list. Requested by Belizan.
- Added code to have messages sent to players when one of their contracted
out units gets hired or killed.
- Added option allowing players to delay unit return by a configurable
amount. When units are returned to the game they are announced using an
announcement message. When the delay unit return option is used units will
still appear in the "Units Contracted Out" list but players will be unable
to re-contract them out until they arrive back to the player's civilization.
- Added options allowing players to link the number of available mercenaries
to the number of military units in the game. Allow players to specify the
ratio between the number of available mercenaries to the total number of
units in the game. Requested by Belizan
- Setup and tested the new event handling code that uses Dr. Elmer
Jiggle's custom event handler class. This should make it easier for mod
makers wanting to integrate this mod with their mod or other mods.
- Added code to bind the 'M' key as a shortcut to the 'Mercenary Manager'
- Updated "Mercenary Manager" screen.
- Added mercenary cost string
- Added placeholders for the planned future features.
- Added code to handle the conditions where mercenaries are removed from the
game either by being killed or being removed by a player
- Fix the mercenary promotion code to make sure that promotions are only added
if their prereq promotions have been previously added. Another option is if
a promotion has prereqs but they haven't been added then they should be
added as well.
- Updated main interface to display correct gold information. Gold per turn
is now reflected correctly when a player hires a mercenary. To-do for future
version will be to update the method to take into account the money made
by the player for hiring out their units as mercenaries.
- Updated Financial Advisor to include mercenary maintenance costs and
mercenary contract income.
- Updated MercenaryUtils.py:
- Added placeholder method "getPlayerMercenaryContractIncome" that returns
0. It will be updated when the feature allowing players to contract out
their units as mercenaries.
- Added method "removePlayerMercenary" to gracefully handle removing
mercenaries that have been killed off.
- Added optimization fix suggested by The Great Apple for loading the
"Mercenary Manager" screen faster. Also updated the code for the "Mercenary
Manager" screen so it doesn't reload the entire contents of the screen when
players view the details of a mercenary.
- Added code to allow players to specify where mercenaries should be placed.
There are three main options: "Capital City", "Civilization Edge" and
"Random". The fourth option allows players to specify that the hired
mercenaries are to be placed in cities that contain one or more buildings
specified in the comma separated list.
- "Hooked-up" all variables to their INI file counterparts. All of them seem
to be working
- Added option allowing players to specify the minimum number of promotions
mercenaries will have when added to the global mercenary pool by the game.
- Added option allowing players to limit the number of mercenaries that can
be in the global mercenary pool.
- Added options allowing players to indicate that some mercenaries should
wander away from the global mercenary pool.
- Added support allowing players to specify units that the game should not
consider when generating mercenaries for the global mercenary pool.
- Fixed the hire and fire code in the "Mercenary Manager" screen so it doesn't
reload the screen each time they are used.
- Developed code to allow AI to take advantage of the mercenaries mod features
by letting them hire and fire mercenaries. The code is simple but it works.
- Finished fully documenting and commenting the MercenaryUtils.py file.
- Added code to randomize mercenary experience level
- Updated code to base mercenary maintenance cost more on mercenary level
rather than their hiring cost.
- Added code to generate random names for each mercenary. In this code I
have also added checks to make sure there will never be two mercenaries
within the same game. There are over 2,000,000 possible mercenary names
that a given mercenary could have.
- Updated "Mercenary Manager" screen.
- It shows the mercenary details on the right side of the screen when the
mercenary image is pressed.
- It displays the players current amount of gold in the upper left hand
corner of the screen
- Hooked up the hire and fire buttons in the "Mercenary Manager" screen,
hired mercenaries will be put in the civ's capital city, but that will
be configurable option through the INI file. Hired mercenaries are moved
from the "Availabe Mercenaries" list to the "Hired Mercenaries" list and
their hire cost is deducted from the players gold. Fired mercenaries are
moved from the "Hired Mercenaries" list to the "Available Mercenaries"
list. Players will only be displayed the option to hire a mercenary if
they have enough gold.
- Added check in CvMainInterface.py to only show the "Mercenary Manager"
button if the player has at least one city built.
- Added code to deduct the mercenary maintenance cost at the beginning of
of the game turn.
- Added code to create mercenaries at the beginning of either the game turn
or player turn.
- Setup Great Mercenaries Mod infrastructure
- Developed code to randomly generate era appropriate mercenaries, this
code is flexible to take in just the EraType. This will allow mod makers
to either send in a players era, the highest era among all players, a
random era, etc.
- Added button next to the "Event Log" button on the main screen to
access the "Mercenary Manager" screen
- Created the "Mercenary Manager" screen and layout. Tied it to the
"Mercenary Manager" button on the main screen. The screen displays the
available and player hired mercenaries.
- "Mercenary Manager" button next to the "Event Log" button does not
"light-up". Basically I cannot create a new style that will highlight the
"Mercenary Manager" button. Unfortunately the graphics are hardcoded into
the styles instead of being like an overlay style that changes the gamma of
- Rolling over the "Mercenary Manager" does not show the same type of
information as rolling over the "Event Log" button. The game does not read-in
any new ControlInfo data I have left the CONTROL_MERCENARIES_MANAGER XML data
in case this changes in a future release.
- "Mercenary Manager" takes longer than the other screens to load when there
too many mercenaries in the global mercenary pool. To counter-act this several
configurable options have been added to the mod: "Wanderlust Mercenaries
Maximum", "Wanderlust Mercenaries" and "Max Global Mercenary Pool".
- "Hire" and "Fire" buttons do not have a tool tip displayed when the mouse
is hovered above them due to core game engine limitations.
- Hovering the mouse cursor over the "Mercenary Maintenance Costs" and "Mercenary
Income" strings in the "Financial Advisor" screen do not display any information
since the widget information is hardcoded into the game and currently new
widgets cannot be added into the game.
- FIX: Combat string use mercenary instead of the mercenary name.
"Your mercenary has destroyed a ..." instead of
"Your Maliryn Keda has destroyed a ..."
- Allow players to configure what location mercenaries should start at if buildings
have been set in the "Mercenaries Starting Location" INI configurable value. There
should only be three valid values:
- Civilization Edge (default value)
- Capital City
- When mercenaries are placed remove all but one sub-entity to represent the
mercenary as a single unit.
- Add mercenary group support
- Develop code to randomly generate era appropriate mercenary groups
- Allow players to hire and fire mercenary groups
- Make sure player has enough gold to hire mercenary groups. Only show join buttons
for mercenary groups the player can hire.
- Add option to have mercenary group leaders, if they get killed mercenary group
leaves the player
- Allow players to designate groups units as a mercenary group for hire. Allow
players to cancel mercenary groups contracts.
- Allow players to specify max number of mercenary groups created either at
beginning of game turn or player turn.
- Allow players to specify min number of mercenary groups created either at
beginning of game turn or player turn.
- Allow players to specify when new mercenary groups are added to the mercenary
group pool: beginning of game turn or player turn.
- Allow players to specify the minimum number of mercenaries mercenary groups should
- Automatically group mercenary groups together when hired and put in the game. Also
prevent players from ungrouping the mercenary group and adding more units to the
mercenary group stack.
- Add mercenary group only traits/promotions, only given when one or more mercenaries
from the same group are stacked together. Also, an extra trait when mercenaries are
stacked with their leader.
- Store mercenary experience history - how many kills, what type of kills, etc.
- Announce the availability of mercenaries, should be configurable through INI file.
- Add code to allow players to hire already hired mercenaries. They should only
be allowed to do this if the mercenary is viewable by the player.
- Develop more savey AI code.
- Allow other types of terrain domain units as mercenaries such as water based units.
When implementing, checks will be required to make sure that players have cities
where water based units can be placed. Requested by Belizan
- Allow players to specify that there be a lag time between techs being discovered and
the units being added to the global mercenary pool. This should be a new configurable
option in the INI file. Requested by Belizan
- Allow certain buildings to give discounts when hiring mercenaries. Requested by Belizan
- Mercenaries that are the player civ's UU should be discounted. Requested by Belizan
- Allow modders to change the delay placement time of mercenaries through buildings,
wonders, etc. Requested by Belizan
- It might also be nice to have a confirmation on the cancel mercenary contract and on the
hire out as mercenary button. Requested by Belizan
- Allow for delaying placement of mercenaries/return of units to be realistic. Requested
- Contracting and Cancelling also gives you a free full heal. Reported by Belizan.
- It might be nice if you had a reputation or standing with "mercenaries" in general that
impacted your mercenary costs. So, for instance, if you tended to lose a lot of
mercenaries, or have them abandon your cause because you didn't pay them, you might find
mercenaries more expensive in the future. Requested by Belizan
- Add some supply and demand economics to the pricing of mercenaries.
- Also, it'd be nice if mercenaries put up by a player were identified that way (Swiss
Mercenaries) etc. In the mercenary listing, and possibly in the unit display pane area
on the main interface screen as well... Requested by Belizan
- Add option to allow players to specify that players contracting out units get a % of
the hire cost back if their unit dies while being contracted out.
-----===Credits & Thanks===-----
Composite Mod - readme.txt format
- The Great Apple
Going through the code, suggesting ideas for optimizing the code to make
it run faster and for the code to bring the AI IQ from 42 to 84 :).
For testing the mod throughout its evolution and sending me easily over
50 PMs with bug reports, feedback and enhancement ideas.
- Dr. Elmer Jiggles
INI and event manager code.
Provided a very good starting point from his Enhanced military advisor
Provided feedback on the initial screens
- Shqype, Aussie_Lurker, and seZereth
Testing and providing great feedback, bug reports and enhancement ideas.
Proving the correct method of getting the distance between two plots.
Testing and providing several critical bug reports!
- Last, my wife
Provided her tech. writer services during the development of the new
screens and helped out with their layout... even though shes pregnant and
can't stop eating