Warlords Python API docs & script

I've updated my Python API documentation to match the changes made in Warlords. No spectacular new things, mostly just the stuff that changed in Warlords's gameplay is also reflected in the Python (and XML) side of things. About a 100 new functions were added, a dozen changed and one was removed (see list below). One important caveat is that the auto-doc feature of stuff that's not in the SDK no longer works in Warlords, so if any changes were made outside the SDK (can't be many but there might be one or two) this isn't reflected in the docs. I will try to confirm with Firaxis if any changes were made outside the SDK and update the site later if needed.

You can find the latest API docs here: http://civilization4.net/files/modding/PythonAPI/

Since I apparently never properly uploaded the v1.61 API for the vanilla game, I did so now (for those people who haven't upgraded to Warlords): http://civilization4.net/files/modding/PythonAPI_original/

For those who were using the beta version of the API docs (for v1.60), I will leave it online for a little while longer but eventually remove it, so update your bookmarks...


Note that there's also a link on both sites where you can download the site to your own computer. Unless you're on a hyper-fast connection this will likely be a bit faster than accessing it through Apolyton, and it's also helpful for accessing the API when you're not online (or when Apolyton is down -- though I think it's been a few years since that last happened *knock on wood*). Of course, the downloaded version doesn't include any updates I might make, so keep an eye on the online version (or this forum) as well. Just unzip wherever you want and it'll put the files in a folder called PythonAPI. Open the index.html in that folder in a browser to use.

I also uploaded the script that I use to create these API documents, so people can use them on custom mods or SDKs (or for whatever else you want to use it). This is mostly useful if you're working on a mod and want the XML type info or newly added C++ code to be reflected in these docs. From the script 'readme':

HTML library reference of CvPythonExtensions v2.00 (and lower)
by Wouter "Locutus" Snijders (locutus@apolyton.net) - 2005-08

Generates HTML documentation for the contents of CyPythonExtensions Classes and methods with their return type and (if available) docstrings are obtained from the Python definitions, their required arguments obtained directly from the C++ source code.

The file started out as a very small, simple script developed in a day or two. But as time progressed more and more additions were necessary, which were made without much planning. Now, 8 months later, the code is very messy but it's functional -- I'm not proud but have neither the time nor the willingness to clean it up. If you want to use this on a mod or modified SDK, you should be able to do so without modificiations. If you want to modify this script for your own purposes, feel free to do so, but I can only say two things: good luck, and my sincere apologies!

Usage:
To start the script, type 'python genHTML.py' in the shell, or double-click it in Windows Explorer (if .py files are associated with Python and not an editor). Python 2.4 or higher must be installed and this file must (by default) be in the root Civ4 folder. It will create a PythonAPI folder in which it will put the HTML files. No updates.html is created, do this manually if you need one and place it in the main PythonAPI folder.

There are a few settings that affect how the script functions just below.

Click to expand...

On to the most important part: here's a list of changes to the Warlords API compared to v1.61:

In CombatDetails:
- added int iHillsAttackModifier
- added int iKamikazeModifier

In CvBonusInfo:
- added int getAIObjective()

In CvBuildingClassInfo:
- added bool isMonument()

In CvBuildingInfo:
- added int getBombardDefenseModifier()
- added int getDomesticGreatGeneralRateModifier()
- removed int getFreeBuilding()
- added int getFreeBuildingClass()
- added int getGreatGeneralRateModifier()
- added int getHappinessTraits(int)
- added int getHurryAngerModifier()
- added bool isAreaBorderObstacle()

In CvCivicInfo:
- added int getDomesticGreatGeneralRateModifier()
- added int getExpInBorderModifier()
- added int getGreatGeneralRateModifier()

In CvEraInfo:
- added int isFirstSoundtrackFirst()

In CvImprovementInfo:
- added int isActsAsCity()

In CvLeaderHeadInfo:
- added int getVassalRefuseAttitudeThreshold()

In CvPromotionInfo:
- added int getCollateralDamageProtection()
- added int getExperiencePercent()
- added int getHillsAttackPercent()
- added int getKamikazePercent()
- added int getPillageChange()
- added int getPrereqPromotion()
- added int getRevoltProtection()
- added int getUnitCombatModifierPercent(int)
- added int getUpgradeDiscount()
- added bool isLeader()

In CvSpecialistInfo:
- added int getExperience()

In CvTechInfo:
- added int isVassalStateTrading()

In CvTraitInfo:
- added int getDomesticGreatGeneralRateModifier()
- added int getGreatGeneralRateModifier()
- added int getHappiness()
- added int getLevelExperienceModifier()

In CvUnitInfo:
- modified CvArtInfoUnit getArtInfo(int, EraType): changed bool argument to EraType
- added bool getDefenderUnitClass(int)
- added bool getDefenderUnitCombat(int)
- added int getHillsAttackModifier()
- added int getLeaderExperience()
- added int getLeaderPromotion()
- added string getMiddleArtDefineTag(int)
- added bool getTargetUnitClass(int)
- added bool getTargetUnitCombat(int)
- added void setCombat(int)
- added void setInvisible(bool)

In CyArea:
- added bool isBorderObstacle(TeamType)

In CyCity:
- added int calculateDistanceMaintenanceTimes100()
- added int calculateNumCitiesMaintenanceTimes100()
- added void changeCultureTimes100(PlayerType, int, bool)
- removed int countTotalCulture()
- added int countTotalCultureTimes100()
- modified void createGreatPeople(UnitType, bool, bool): added bool argument (bIncrementExperience)
- added int getBaseCommerceRateTimes100(CommerceType)
- added int getBuildingBombardDefense()
- added int getCommerceRateTimes100(CommerceType)
- added int getCultureTimes100(PlayerType)
- added int getFeatureProduction()
- added int getHurryAngerModifier()
- added int getMaintenanceTimes100()
- added int getSpecialistFreeExperience()
- modified bool isCoastal(int): - added int argument (iMinWaterSize)
- added void setCultureTimes100(PlayerType, int, bool)
- added void setFeatureProduction(int)

In CyGame:
- added int getAIAutoPlay()
- added void setAIAutoPlay(int)
- added void setOption(GameOptionType, bool)
- added void updateScore(bool)

In CyGameTextMgr:
- added string setVassalRevoltHelp(int, int)

In CyPlayer:
- added int calculateBaseNetResearch()
- added void changeCombatExperience(int)
- added void createGreatPeople(int, bool, bool, int, int)
- added int getCombatExperience()
- added int getDomesticGreatGeneralRateModifier()
- added bool getExpInBorderModifier()
- added int getGreatGeneralRateModifier()
- added int getGreatGeneralsCreated()
- added int getGreatGeneralsThresholdModifier()
- added int getLevelExperienceModifier()
- modified int greatPeopleThreshold(bool): added bool argument (bMilitary)
- removed bool isLateEra()
- added void setCombatExperience(int)

In CyPlot:
- modified int defenseModifier(TeamType, bool, bool): added TeamType argument (iDefendTeam)

In CySelectionGroup:
- added bool canEnterArea(TeamType, CyArea, bool)
- added int getMissionData2(int)

In CyTeam:
- added void assignVassal(TeamType, bool)
- added void changeVassalTradingCount(int)
- added void freeVassal(TeamType)
- added int getMasterPower()
- modified int getPower(bool): added bool argument (bIncludeVassals)
- added int getVassalPower()
- added int getVassalTradingCount()
- added bool isAVassal()
- added bool isVassal(TeamType)
- added bool isVassalStateTrading()
- added void setMasterPower(int)
- added void setVassal(TeamType, bool, bool)
- added void setVassalPower(int)

In CyUnit:
- added bool canEnterArea(TeamType, CyArea, bool)
- added int canGiveExperience(CyPlot)
- added int canLead(CyPlot, int)
- modified bool canPromote(PromotionType, int): added int argument (iLeaderUnitId)
- modified void changeExperience(int, int, bool, bool): added two bool arguments (bFromCombat, bInBorders)
- added int getCollateralDamageProtection()
- added int getExperiencePercent()
- added int getExtraHillsAttackPercent()
- added int getKamikazePercent()
- added UnitType getLeaderUnitType()
- added int getPillageChange()
- added int getRevoltProtection()
- added int getUpgradeDiscount()
- added bool giveExperience()
- added int hillsAttackModifier()
- added bool isPromotionValid(PromotionType)
- added bool lead(int)
- modified void promote(PromotionType, int): added int argument (iLeaderUnitId)
- added void setLeaderUnitType(UnitType)

Awsome. Thanks!

EDIT: The link to the types list from the updates section is mistyped (on both APIs) - should be http://civilization4.net/files/modding/PythonAPI/Types/TypeList.html

Yep, very useful. A big for that!

Your API is hands down the single-most useful Civ4 modding document. Thanks!

The Great Apple said:

EDIT: The link to the types list from the updates section is mistyped (on both APIs) - should be http://civilization4.net/files/modding/PythonAPI/Types/TypeList.html

Click to expand...

Aaargh. That's what you get for testing code on a Windows system that will run on a Linux sever Should be fixed now...

Thanks for the great work Locutus, its been a great help to many people.

Many thanks! This is and has been a tremendous help.

Gerikes said:

Your API is hands down the single-most useful Civ4 modding document. Thanks!

Click to expand...

I agree. I probably would have given up before completing my first mod without your document.

Roger Bacon

Thanks for the compliments guys, glad I can be of help

Someone (don't remember who) asked me a few months ago if I could add an index to the site, but at the time that seemed like a lot of work and I was busy with Warlords then (plus I never found indices terribly useful for APIs myself, as most methods have a prefix like get/set/is/can/etc). I'm still busy now but was kinda getting bored with the type of work I've been doing and haven't done any proper coding in a while, so I put together that index now and updated the site with it. It was easier than I thought and if even one person gets some use out of it it will have been worth it...

So if anyone has any other request, lemme know. It might be 8 months before I get around to it but around to it I'll get

Love your work just a quick question though. while you was looking through the warlords file did you see anything that points to " *name* has won a **** victory" (the bit thats displayed on screen when you win a game) I edited it in the vanilla civ4 so it doesn't show when i continue the game after winning but i can't find it in warlords any ideas? thanks

All the text in the game is in the Assets/XML/Text folders, wether in the Warlords, Civ4, Custom or mod assets. On a clean Warlords install the text should be in Assets/XML/Text/CIV4GameText_Misc1.xml of the regular Civ4 asset tree (so not in Warlords/Assets/XML/Text). If it's not there do a search in all your Civ4 folder structures, both the install folder (in C:\Program Files or wherever you usually install your games) and the ones under My Documents -- it can't be displayed in-game if it isn't in Assets/XML/Text somewhere. The key is TXT_KEY_GAME_WON, that might help your search.

One important thing to note is that Warlords doesn't read the original Civ4 CustomAssets. I suspect you may have stored your changes there, in which case you don't get the message in Civ4 but you do in Warlords. If so, just copy the file from your Civ4 CustomAssets to your Warlords CustomAssets and the problem should be solved.

Locutus said:

One important caveat is that the auto-doc feature of stuff that's not in the SDK no longer works in Warlords, so if any changes were made outside the SDK (can't be many but there might be one or two) this isn't reflected in the docs. I will try to confirm with Firaxis if any changes were made outside the SDK and update the site later if needed.

Click to expand...

Okay, I got the info and once again updated the site. 7 new functions were added to Warlords outside the SDK:

In CyDiplomacy:
- added bool theirVassalTribute()

In CyGInterfaceScreen:
- added void markRenderTexturesDirty()
- added void setHelpLabel(string, string, string, int, float, float, float, FontType, string)

In CyInterface:
- added int getPlotListOffset()
- added bool isOneCitySelected()
- added void setSoundSelectionReady(bool)

In CyInterfaceScreen:
- added ??? markRenderTexturesDirty(???)

I think that's the last update you can expect anytime soon, at least until the next patch...

Thank you Its been doing my head in for a while now It was in my custom assets civ4 so i moved it

Let me add many of my own thanx to the pile. Without this I would have no idea what was new and how to use it, you rock.