Gods and Kings API Documentation Changes

[DonQuiche]

Everyone is free to contribute, I will update this post. May become something important or just be my public scratch pad, we will see.
Remember, methods can be enumerated with getmetatable(someobject.__index). Don't know how to get their prototypes.

Based on the diff with the wiki. Some changes may actually be older then G&K.
No parentheses means the signature is unknown.

Others
Civ5 now bundles the Lua debug library.

Network (incomplete)
New methods
SendFoundReligion
SendEnhanceReligion (rename also)
SendMoveSpy
SendStageCoup

Events (incomplete)
New methods
SerialEventEspionageScreenDirty

Game Events (incomplete)
New methods
GetFounderBenefitsReligion(ePlayer)
CityBuildingsIsBuildingSellable(iPlayer ID, iBuildingID)
CityConvertsReligion(iOwner, eReligion, iX, iY)
GameCoreUpdateBegin()
GetScenarioDiploModifier1(ePlayer1, ePlayer2) --change diplo relations???!!!!
GetScenarioDiploModifier2(ePlayer1, ePlayer2)
GetReligionToSpread(ePlayer)
PlayerCityFounded(iPlayer, iCityX, iCityY)
SetAlly(iMinor, iOldAlly, iNewAlly)

Game (complete)
New methods
CanDoControl
ChangeNumVotesForTeam
DoMinorBullyGold
DoMinorBullyUnit
DoMinorBuyout
DoMinorGiftGold (besides of DoMinorGoldGift?!)
DoMinorGiftTileImprovement
DoMinorPledgeProtection
EnhanceReligion(iPlayer, eReligion, eBelief4, eBelief5)
FoundPantheon
FoundReligion(iPlayer, eReligion, nil, eBelief1, eBelief2, eBelief3, -1, pCity)
GetAvailableBonusBeliefs
GetAvailableEnhancerBeliefs
GetAvailableFollowerBeliefs
GetAvailableFounderBeliefs
GetAvailablePantheonBeliefs
GetBeliefsInReligion(eReligion) --an iterator: e.g., for i,v in ipairs(Game.GetBeliefsInReligion(eReligion)) do
GetBuildingYieldChange
GetBuildingYieldModifier
GetCombatPrediction
GetDealDuration
GetFaithCost
GetFounder(eReligion, -1)
GetFounderBenefitsReligion
GetHolyCityForReligion(eReligion, -1)
GetMinimumFaithNextPantheon
GetNumCitiesFollowing
GetNumCitiesPolicyCostMod
GetNumFollowers
GetNumReligionsFounded()
GetNumReligionsStillToFound
GetPreviousVoteCast
GetReligionName
GetReplayMessage
GetReplayMessages
GetResearchAgreementCost
GetTimeString
GetTurnsBetweenMinorCivElections
GetTurnsUntilMinorCivElection
GetUnitUpgradesTo
GetVariableCitySizeFromPopulation
GetWorldNumCitiesUnhappinessPercent
HasAdvisorMessageBeenSeen
IsProcessingMessages
SetAdvisorBadAttackInterrupt
SetAdvisorCityAttackInterrupt
SetAdvisorMessageHasBeenSeen
SetFounder(eReligion, iPlayer)
SetGameState
SetHolyCity(eReligion, pCity)
SetMinimumFaithNextPantheon
SetNumVotesForTeam
SetUnitedNationsCountdown
SetVictoryValid

Removed methods
RegisterMethod (did it even exist?)
GetAdvisorCheckFlags
GetReplayMessageColor (use GetReplayMessage and GetReplayMessages)
GetReplayMessagePlayer
GetReplayMessagePlotX
GetReplayMessagePlotY
GetReplayMessageText
GetReplayMessageTurn
GetReplayMessageType
GetScriptData
SetAdvisorCheckFlags
SetScriptData


City (complete)
New methods
AdoptReligionFully(eReligion)
CanPlaceUnitHere
ChangeBaseYieldRateFromReligion
ConvertPercentFollowers(eReligion1, eReligion2, int)
CreateGreatAdmiral
GetBaseYieldRateFromReligion
GetBuildingEspionageModifier
GetBuildingFaithPurchaseCost
GetBuildingGlobalEspionageModifier
GetBuyablePlotList
GetFaithPerTurn
GetFaithPerTurnFromBuildings
GetFaithPerTurnFromPolicies
GetFaithPerTurnFromReligion
GetFaithPerTurnFromTraits
GetFaithPurchaseBuildingTooltip
GetFaithPurchaseUnitTooltip
GetFavoredReligion
GetHappiness
GetHappinessFromBuildings
GetJONSCulturePerTurnFromReligion
GetLocalHappiness
GetMaxHitPoints
GetNumFollowers
GetPressurePerTurn
GetRawProductionDifference
GetRawProductionDifferenceTimes100
GetReligionBuildingClassHappiness
GetReligionBuildingClassYieldChange
GetReligionCityRangeStrikeModifier
GetReligiousMajority()
GetUnitFaithPurchaseCost
IsHolyCityAnyReligion
IsHolyCityForReligion
IsOriginalCapital
IsReligionInCity
RangeCombatDamage
RangeCombatUnitDefense

Removed methods
ChangeJONSCulturePerTurnFromTerrain
GetJONSCulturePerTurnFromTerrain
SetScriptData


Player (complete)
New methods
AddMinorCivQuestIfAble
AddTemporaryDominanceZone
CanCreatePantheon
CanMajorBullyGold
CanMajorBullyUnit
CanMajorBuyout
CanMajorGiftTileImprovement
CanMajorGiftTileImprovementAtPlot
CanMajorProtect
CanMajorStartProtection
CanMajorWithdrawProtection
CanResearchForFree
CanSpyStageCoup
ChangeFaith
ChangeFreePromotionCount
ChangeGarrisonedCityRangeStrikeModifier
ChangeNavalCombatExperience
ChangeNewCityExtraPopulation
ChangeNumFaithGreatPeople
ChangeNumFreeGreatPeople
ChangeNumMayaBoosts
ChangeNumWorldWonders
ChangeScoreFromFutureTech
ChangeScoreFromTechs
GetAvailableSpyRelocationCities
GetBeliefInPantheon
GetBuildingProductionModifier
GetBuyoutCost
GetCapitalSettlerProductionModifier
GetCombatBonusVsHigherTech
GetCombatBonusVsLargerCiv
GetCommonFoeValue
GetCoupChanceOfSuccess
GetCulturePerTurnFromMinor
GetCulturePerTurnFromMinorCivs
GetCulturePerTurnFromReligion
GetDealMyValue
GetDealTheyreValue
GetDealValue
GetEmbarkedGraphicOverride
GetEspionageCityStatus
GetEspionageSpies
GetExtraBuildingHappinessFromPolicies
GetFaith
GetFaithPerTurnFromCities
GetFaithPerTurnFromMinorCivs
GetFaithPerTurnFromReligion
GetFaithPurchaseIndex
GetFaithPurchaseType
GetFoundedReligionEnemyCityCombatMod
GetFoundedReligionFriendlyCityCombatMod
GetFreePromotionCount
GetGarrisonedCityRangeStrikeModifier
GetGiftTileImprovementCost
GetGoldPerTurnFromReligion
GetGreatAdmiralsThresholdModifier
GetHappinessFromCities
GetHappinessFromLuxury
GetHappinessFromMinorCivs
GetIntrigueMessages
GetJONSCultureEverGenerated
GetLateGamePolicyTree
GetLifetimeCombatExperience
GetLifetimeGrossGold
GetMajorCivApproach
GetMayaCalendarLongString
GetMayaCalendarString
GetMinimumFaithNextGreatProphet
GetMinorCivBullyGoldAmount
GetMinorCivContestValueForLeader
GetMinorCivContestValueForPlayer
GetMinorCivCurrentCultureBonus
GetMinorCivCurrentCultureFlatBonus
GetMinorCivCurrentCulturePerBuildingBonus
GetMinorCivCurrentFaithBonus
GetMinorCivCurrentHappinessBonus
GetMinorCivCurrentHappinessFlatBonus
GetMinorCivCurrentHappinessPerLuxuryBonus
GetMinorCivFriendshipAnchorWithMajor
GetMinorCivNumActiveQuestsForPlayer
GetMinorCivUniqueUnit
GetNaturalWonderYieldModifier
GetNavalCombatExperience
GetNegativeReligiousConversionPoints
GetNewCityExtraPopulation
GetNumCiviliansReturnedToMe
GetNumFaithGreatPeople
GetNumFreeGreatPeople
GetNumFriendsDenouncedBy
GetNumMayaBoosts
GetNumSpies
GetNumTechsToSteal
GetNumTimesIntrigueSharedBy
GetNumTimesRobbedBy
GetNumUnassignedSpies
GetNumWarsFought
GetNumWondersBeatenTo
GetOpinionTable
GetOtherPlayerNumProtectedMinorsAttacked
GetPlayerBuildingClassHappiness
GetPlayerBuildingClassYieldChange
GetPolicyBuildingClassYieldChange
GetPolicyBuildingClassYieldModifier
GetPolicyCatchSpiesModifier
GetPolicyEspionageCatchSpiesModifier
GetPolicyEspionageModifier
GetProjectProductionModifier
GetQuestTurnsRemaining
GetRecentAssistValue
GetRecentIntrigueInfo
GetRecentTradeValue
GetReligionCreatedByPlayer
GetReplayData
GetResearchCost
GetResearchProgress
GetSpecialistProductionModifier
GetTotalFaithPerTurn
GetTradeRouteGoldModifier
GetTurnLastPledgeBrokenByMajor
GetTurnLastPledgedProtectionByMajor
GetTurnsSincePlayerBulliedProtectedMinor
GetTurnsSinceThreatenedAnnouncement
GetUnhappinessFromCitySpecialists
GetUnhappinessFromPuppetCityPopulation
GetUnitBaktun
GetUnitProductionModifier
GetWeDeclaredWarOnFriendCount
GetWeDenouncedFriendCount
GreatAdmiralThreshold
HasCreatedPantheon
HasCreatedReligion
HasOthersReligionInMostCities
HasRecentIntrigueAbout
HasReligionInMostCities
HasSpyEstablishedSurveillance
IsAbleToAnnexCityStates
IsAngryAboutProtectedMinorAttacked
IsAngryAboutProtectedMinorBullied
IsAngryAboutProtectedMinorKilled
IsAngryAboutSidedWithTheirProtectedMinor
IsCanPurchaseAnyCity
IsCapitalCapturedBy
IsDenouncingPlayer
IsDoF
IsDoFMessageTooSoon
IsEmpireSuperUnhappy
IsFreeMayaGreatPersonChoice
IsFreePromotion
IsFriendDeclaredWarOnUs
IsFriendDenouncedUs
IsGaveAssistanceTo
IsHasPaidTributeTo
IsHasPlayerBulliedProtectedMinor
IsLiberatedCapital
IsLiberatedCity
IsMinorCivActiveQuestForPlayer
IsMinorCivContestLeader
IsMinorCivHasUniqueUnit
IsNukedBy
IsPlayerBrokenAttackCityStatePromise
IsPlayerBrokenNoConvertPromise
IsPlayerBrokenSpyPromise
IsPlayerDenouncedEnemy
IsPlayerDenouncedFriend
IsPlayerDoFwithAnyEnemy
IsPlayerDoFwithAnyFriend
IsPlayerForgivenForSpying
IsPlayerIgnoredAttackCityStatePromise
IsPlayerIgnoredBullyCityStatePromise
IsPlayerIgnoredNoConvertPromise
IsPlayerIgnoredSpyPromise
IsPlayerStopSpyingRequestEverAsked
IsProtectedByMajor
IsStopSpyingMessageTooSoon
IsThreateningBarbariansEventActiveForPlayer
IsTraitBonusReligiousBelief
IsUntrustworthyFriend
IsUsingMayaCalendar
SetEmbarkedGraphicOverride
SetFaith
SetFaithPurchaseIndex
SetFaithPurchaseType
SetNavalCombatExperience
SetNumFaithGreatPeople
SetNumFreeGreatPeople
SetNumMayaBoosts
SetNumWondersBeatenTo
SetReplayDataValue
WasResurrectedBy
WasResurrectedThisTurnBy


Removed methods
ChangeHappinessFromBuildings
ChangeHappinessFromGarrisonedUnits
DoGreatPersonChoice
GetHappinessFromGarrisonedUnits
GetNumCiviliansReturnedToMe (use GetNumCiviliansReturnedToMe)
IsPlayerIgnoredCityStatePromise
IsWorkingAgainstPlayerAccepted
IsWorkingWithPlayer
IsWorkingWithPlayerMessageTooSoon



Unit (complete)
New methods
CanRepairFleet
CapitalDefenseFalloff
CapitalDefenseModifier
ExecuteSpecialExploreMove
FlankAttackModifier
GetActivityType
GetConversionStrength
GetEmbarkedUnitDefense
GetGreatGeneralCombatModifier
GetMajorityReligionAfterSpread
GetNameNoDesc
GetNearbyImprovementModifier
GetNumFollowersAfterSpread
GetOriginalOwner
GetRangedAttackModifier
GetReligion
GetReverseGreatGeneralModifier
GetScenarioData
GetSpreadsLeft
HasName
IsBusy
IsCityAttackOnly
IsDelayedDeath
IsGreatPerson
IsHigherTechThan
IsLargerCivThan
IsReadyToMove
IsStackedGreatGeneral
SetDeployFromOperationTurn
SetOriginalOwner
SetScenarioData

Plot (complete)
Removed methods
ChangeCulture (use CalculateYield)
GetCulture (use CalculateYield)

 

[Pazyryk]

Excellent! The Medieval scenario shows the use of many of these. Here are a few I found in there (some you missed above) with args:

Game.EnhanceReligion(iPlayer, eReligion, eBelief4, eBelief5)
Game.FoundReligion(iPlayer, eReligion, nil, eBelief1, eBelief2, eBelief3, -1, pCity)
Game.GetBeliefsInReligion(eReligion) --an iterator: e.g., for i,v in ipairs(Game.GetBeliefsInReligion(eReligion)) do
Game.GetFounder(eReligion, -1)
Game.GetHolyCityForReligion(eReligion, -1)
Game.GetNumReligionsFounded()
Game.SetFounder(eReligion, iPlayer)
Game.SetHolyCity(eReligion, pCity)

city:GetReligiousMajority()
city:AdoptReligionFully(eReligion)
city:ConvertPercentFollowers(eReligion1, eReligion2, int)

Also some GameEvents:

GameEvents.GetFounderBenefitsReligion(ePlayer)
GameEvents.CityConvertsReligion(iOwner, eReligion, iX, iY)
GameEvents.GetReligionToSpread(ePlayer)

--not religion but I think these are new:
GameEvents.CityBuildingsIsBuildingSellable(iPlayerID, iBuildingID)
GameEvents.GameCoreUpdateBegin()
GameEvents.SetAlly(iMinor, iOldAlly, iNewAlly)
GameEvents.PlayerCityFounded(iPlayer, iCityX, iCityY)
GameEvents.GetScenarioDiploModifier1(ePlayer1, ePlayer2) --change diplo relations???!!!!
GameEvents.GetScenarioDiploModifier2(ePlayer1, ePlayer2)

 

[SamBC]

I don't think Lua has full formal prototypes, so they won't be part of any runtime metadata, IIRC. So not able to be found using Nexus or anything.

 

[DonQuiche]

I don't think Lua has full formal prototypes, so they won't be part of any runtime metadata, IIRC. So not able to be found using Nexus or anything.

I always heard that but I guess that LUA still has to store the arguments names since they are used by the body and since LUA is interpreted.

 

[Pazyryk]

I always heard that but I guess that LUA still has to store the arguments names since they are used by the body and since LUA is interpreted.

I don't think so. After reading this, my understanding is that Lua just piles whatever arguments it has onto a function stack, then gets the return values from the same stack (expecting the last value to be the number of items). A C library for Lua just tells Lua where to find the C functions. I think the Lua side is totally ignorant about arguments to C functions.

 

[DonQuiche]

I don't think so. After reading this, my understanding is that Lua just piles whatever arguments it has onto a function stack, then gets the return values from the same stack (expecting the last value to be the number of items). A C library for Lua just tells Lua where to find the C functions. I think the Lua side is totally ignorant about arguments to C functions.

No, it's not possible, it would cause stack corruption if you were going to push more than what will be poped. Besides the LUA interpreter needs to do conversions between LUA args to C args (number to int16, to float32, etc). As a result the LUA interpreter needs to be exactly aware of the C signature, there is no alternative.

Also, don't forget that many (most?) methods are actually not built-in wrappers but regular LUA functions that then call the C function, after they checked and converted some of the arguments for example.

 

[Pazyryk]

Hmm... I have only limited programming experience, so I could be wrong. But I don't see why Lua has to worry about any of this. The C functions are written explicitly for Lua (follow link in my post) and in our case for Civ5: they know what they are getting from the Lua call (both number of args and type) and if you violate this on the Lua side you do crash the game (I've done it). It seems like the philosophy of Lua is speed and small footprint rather than compatibility. (I'm only continuing the argument in the hope that you will prove me wrong: if there is something on the Lua side, perhaps you can find it.)

 

[DonQuiche]

Hmm... I have only limited programming experience, so I could be wrong.

I have a far better proramming experience but very small knowledge of Lua/C interoperability so I took some time to research things up before this new answer.

According to Lua: an overview of the C api, it appears there are two ways to achieve interoperability. On the first one, the burden lies on the LUA side and it calls regular C functions whose signatures have to be known at runtime. It was my assumption. On the second one, the burden lies on the C shoulders and the C code registers its own functions on the LUA side, all being specifically designed for LUA (int func(LUAState*)) and the methods signatures are therefore unknown by LUA. It was your assumption.

There is a priori no way to distinguish the both ways from the LUA pov. However, now that I think about it, Civ5 probably uses the second way because, if I remember correctly, the civ5 game dll exports only two functions. So I guess you are actually right regarding civ5, there would be no way to get the methods signatures. By the way, that would explain why it seems like it's not generally possible to get arguments names in LUA since it would be meaningless for those specific cases.

It seems like the philosophy of Lua is speed and small footprint rather than compatibility.

Well, I would rather say that its focuses are embeddability, interoperability and a sweeter learning curve for non-programmers. "Speed" as a design goal is always off when talking about a (f***ing) weakly-typed language anyway, and the small footprint is only for the interpreter, not the code itself.

 

[Gedemon]

there is this example from civ5 wiki :

// First, obtain the Lua script system.
CvDLLScriptSystemIFaceBase* pkScriptSystem = gDLL->GetScriptSystem();
if(pkScriptSystem)
{
    // Construct and push in some event arguments.
    CvLuaArgsHandle args;   //This is a scoped smart pointer that wraps ICvDLLScriptSystemArgs* 
    args->Push(GetID());
    args->Push(eTeam);

    // Attempt to execute the game events.
    bool bResult = false;  //This is the result of the TestAll calls.  Will be true if all Lua listeners return true.

    // CallTestAll returns true if there were registered Lua Listeners.  It would return false if nothing in Lua is using this event.
    if(pkScriptSystem->CallTestAll("CanDeclareWar", args.get(), bResult))
    {

      // There were Lua listeners! Now check the result.
      if(bResult == false)
      {
        //Guess we're not declaring war :(
        return false;
      }
    }
}

 

[Pazyryk]

Well, Thalassicus is saying that we can get function args through Getlocal. Love to see someone try this.

 

[Spatzimaus]

So they deleted GetScriptData and SetScriptData from the Game block? Sigh, will they ever learn?

Also, I'm disappointed. I was really, really hoping we'd get more useful Set and Change functions, so that we could do things like alter civ-civ relationships or stuff like that. But nearly all of the ones you listed are either religion-based, or are just silly. Seriously, why does the Player structure need a function like ChangeNumWorldWonders? And while more GameEvents are always nice, why did we need one for city founding, since that's the ONE Serial Event that actually works just fine already?

Oh well. I'm still trying to switch the Culture stuff in my mods over to the new system, but I was really hoping for more Lua to work with.

 

[Pazyryk]

, so that we could do things like alter civ-civ relationships or stuff like that.

I'm not sure but perhaps the two new GameEvents do this (GetScenarioDiploModifier1 and GetScenarioDiploModifier2) or perhaps they do something entirely different. They are in the scenarios so one could probably figure this out.

So they deleted GetScriptData and SetScriptData from the Game block? Sigh, will they ever learn?

Did this one even work? The unit one didn't work before (I wonder if it does now?) and city had a Set but not a Get (which was useless). I'm not sure which of these is used by SaveUtils (player?).

 

[Gedemon]

I'm not sure but perhaps the two new GameEvents do this (GetScenarioDiploModifier1 and GetScenarioDiploModifier2) or perhaps they do something entirely different. They are in the scenarios so one could probably figure this out.

They look like modifier, see medieval scenario :

GameEvents.GetScenarioDiploModifier1.Add(function(ePlayer1, ePlayer2)

	local eReligion1;
	local eReligion2;
	
	eReligion1 = MyCurrentReligion(ePlayer1);
	eReligion2 = MyCurrentReligion(ePlayer2);
	
	if (eReligion1 ~= eReligion2) then
		return 60;
	else
		return 0;
	end
end)

Question is how do we get the current value ?

hmmm...

player:GetMajorCivApproach() is new, no ?

 

[Gedemon]

quick test :

> function change() return 50 end
> function raise() return -50 end
> GameEvents.GetScenarioDiploModifier2.Add(raise)
> GameEvents.GetScenarioDiploModifier3.Add(change)
> GameEvents.GetScenarioDiploModifier1.Add(change)

 

[DonQuiche]

So they deleted GetScriptData and SetScriptData from the Game block? Sigh, will they ever learn?

Yeah, that was a great shock to me. That and the many breaking changes, some of them were not necessary (cosmetic renames, the former culture API removed since no longer needed rather than maintained as wrapper functions, etc).

Also, I'm disappointed. I was really, really hoping we'd get more useful Set and Change functions, so that we could do things like alter civ-civ relationships or stuff like that.

Same here, I don't really understand the point of all those functions that look like they were made for being used by a diplo AI while we can't write a diplo AI.

But nearly all of the ones you listed are either religion-based

Well, and even on that... You cannot create a missionary, inquisitor or Great Prophet with InitUnit for example because the ones you create like that have no religion and are useless (no possible orders). There is no way to set their religion (no SetReligion and I also tried possible new args on InitUnit).

 

[daviiadams]

There's a change to the ToolTip in respect of specialist slots - it now looks for "_SLOTS" to be added to the specialist description. Changed mine in Government Buildings and worked.

Could be simular issues for other items relating to tooltips(?)

 

[Ahhuatl]

I for the life of me cannot find a means of finding a particular belief with any of these methods. Browsing through the lua ReligionOverview, the closest one I could find was GetBeliefType(belief) but I couldn't get it to work. If anyone can find a method that will return the name of a belief a player has and post an example of it, I'd be most appreciative.

 

[whoward69]

From ChooseReligionPopup.lua (the one that's used when you enhance your religion, so it must somehow work out what you already have)

if (pPlayer:HasCreatedReligion()) then
  local eReligion = pPlayer:GetReligionCreatedByPlayer();
  for i,v in ipairs(Game.GetBeliefsInReligion(eReligion)) do
    local belief = GameInfo.Beliefs[v];
    -- belief.ShortDescription and belief.Description are the TXT_KEY_s you want
  end
end

 

[Androrc the Orc]

So they deleted GetScriptData and SetScriptData from the Game block?

While it's unfortunate that this breaks backwards compatibility with older mods, Firaxis has added a new (and in my opinion, better) way to perform those functions.

I described briefly how to use the new method in this post.

 

[Spatzimaus]

While it's unfortunate that this breaks backwards compatibility with older mods, Firaxis has added a new (and in my opinion, better) way to perform those functions.

I don't doubt that. This isn't the first time this has happened even in Civ5, where Firaxis deleted an old-and-inferior methodology when they switched to a newer system. The point is, there was no reason to delete the old system at all; even if you want to encourage people to transition to the new system, you gain nothing from invalidating the old methods, and it just causes more pain for us.

I mean, the reason my own mods are dead (and at this point, likely to remain that way) is that they decided to alter how RunCombatSim works, to the point where most of the things I'd used it for in the past will no longer function. If they'd wanted an event with the functionality of the new-and-improved RunCombatSim, they should have just created another event with different characteristics, and used that instead. But instead, they broke any mod relying on the old system. It's just bad programming.