Mod API Reference

This explains how to use Warzone's mod API and links to the documentation for each object type.

Types

When writing a mod, you'll encounter variables/objects of three basic types:

• Primitives: strings, numbers, booleans, etc.
• Tables: collections of key/value pairs. A table is a lot like a hashmap or dictionary in other languages. Note that in Warzone, the key of a table will always be either a string or an integer. Some places in this reference will refer to Arrays which are just tables with numeric keys starting at 1.
• Proxy objects: Discussed in the next section.

Proxy Objects

A proxy object proxies information back and forth between your mod and Warzone. You can tell if an object is a proxy object by looking for a proxyType field. All proxy objects always have the following fields:

• proxyType: A string identifying the type of proxy object.
• readOnly: False if you're allowed to make changes to this proxy object, or true if it's read-only.
• readableKeys: An array containing all fields you're allowed to read from this object.
• writableKeys: An array containing all fields you're allowed to change on this object if readOnly is False.

To read a field, simply read it like a property: obj.field. Similarly, to write to a proxy object, just assign to that field: obj.field = newVal.

Here's a handy function you can include in your mod to print out everything on a proxy object:

function PrintProxyInfo(obj)
    print('type=' .. obj.proxyType .. ' readOnly=' .. tostring(obj.readonly) .. ' readableKeys=' .. table.concat(obj.readableKeys, ',') .. ' writableKeys=' .. table.concat(obj.writableKeys, ','));
end

Writing Tables

If a writable Warzone proxy object exposes a table, and you wish to make changes to that table, you must assign the table back to the proxy object. For example, assume you have a GameStanding object named standing which exposes the Cards table, and you want to add something at index 9:

 standing.Cards[9] = something  --WRONG!

This code won't work since the proxy object isn't having anything assigned to it. Proxy objects are only aware of changes when something is directly assigned into them. To make this work, you must assign the table into the proxy object's field:

 local cards = standing.Cards
 cards[9] = something
 standing.Cards = cards; --Right

Note: If you use lua's type function, proxy objects will identify themselves as tables. However, that should be considered an implementation detail. For the purposes of this wiki, proxy objects aren't considered tables.

API Reference

• ActiveCard
• ActiveCardWoreOff
• Armies
• BonusDetails
• Boss1
• Boss2
• Boss3
• Boss4
• CardGame
• CardGameAbandon
• CardGameAirlift
• CardGameBlockade
• CardGameBomb
• CardGameCustom
• CardGameDiplomacy
• CardGameGift
• CardGameOrderDelay
• CardGameOrderPriority
• CardGameReconnaissance
• CardGameReinforcement
• CardGameSanctions
• CardGameSpy
• CardGameSurveillance
• CardInstance
• ClanPlayerInfo
• ClientGame
• Commander
• CustomScenario
• CustomScenarioTerritory
• DistributionMode
• Game
• GameColor
• GameOpenSeat
• GameOrder
• GameOrderAttackTransfer
• GameOrderAttackTransferResult
• GameOrderBossEvent
• GameOrderCustom
• GameOrderDeploy
• GameOrderDiscard
• GameOrderEvent
• GameOrderPlayCard
• GameOrderPlayCardAbandon
• GameOrderPlayCardAirlift
• GameOrderPlayCardAirliftResult
• GameOrderPlayCardBlockade
• GameOrderPlayCardBomb
• GameOrderPlayCardCustom
• GameOrderPlayCardDiplomacy
• GameOrderPlayCardFogged
• GameOrderPlayCardGift
• GameOrderPlayCardOrderDelay
• GameOrderPlayCardOrderPriority
• GameOrderPlayCardReconnaissance
• GameOrderPlayCardReinforcement
• GameOrderPlayCardSanctions
• GameOrderPlayCardSpy
• GameOrderPlayCardSurveillance
• GameOrderReceiveCard
• GameOrderStateTransition
• GamePlayer
• GameSettings
• GameStanding
• GameWL
• IncomeMod
• IsVersionOrHigher
• MapDetails
• MapFamily
• NoParameterCardInstance
• PendingStateTransition
• PlayerCards
• PlayerInfo2
• ReinforcementCardInstance
• ServerGame
• SpecialUnit
• TerritoryConnection
• TerritoryDetails
• TerritoryModification
• TerritoryStanding
• TickCount
• UI
• WL

Newer API features

Some features were introduced after the first version of the Mod API framework and should be checked for using IsVersionOrHigher:

Version	Features
5.34	Create radio buttons Lua errors in the browser now give stack traces with line numbers in the mod-crashed dialog Client_PresentPlayCardUI now gives mods the ability to close the cards dialog - closeCardsDialog Fixed Client_GameOrderCreated not being able to read territory picks in manual distribution games Fixed WL.enumtype.ToString() functions Fixed Client_PresentPlayCardUI not registering Mod and UI hooks if it was called before other client hooks Fixed an error if you set number of card pieces to 0 or negative Fixed GameOrderAirliftResult.Results throwing an error instead of returning nil when there are no results yet Fixed allowing GameOrderAttackTransferResult.ActualArmies to be set to a negative number Fixed "can't transfer to a neutral" error that occurred when a mod resurrected a failed transfer
5.33	WL.FogMod GameOrderEvent.FogModsOpt GameOrderEvent.RemoveFogModsOpt GameStanding.IncomeMods Fixed the AI trying to move its commander even if it doesn't control the territory the commander is on (which can happen with mods) Fixed a bug that could make a generic Warzone error instead of a mod failed error if you tried to set a property on a destroyed object (for example, Button's SetInteractable)
5.32.0.1	"addCard" callback function now returns the card ID of the newly added card Fixed a bug with custom cards that made old clients produce an error
5.32	Client_GameOrderCreated Client_GameCommit Custom Cards
5.31	Proper support for Neutral Special Units Fixed GameOrderCustom.TurnPhase not correctly persisting in multi-player Fixed Lua global state not persisting in some cases on the website Note: this update may have prevented the use of custom turn phases
5.26	Use ServerGame.SetPlayerResource in Server_StartGame Fixed a bug with airlifting special units that are set to always visible
5.24.2	CustomSpecialUnit.Health
5.24.1	CustomSpecialUnit.CombatOrder WL.TickCount
5.22.2	Boss1.CombatOrder Boss2.CombatOrder Boss3.CombatOrder Boss4.CombatOrder Commander.CombatOrder CustomSpecialUnitBuilder.Health
5.22	GameOrderCustom.OccursInPhaseOpt TerritoryModification.RemoveSpecialUnitsOpt
5.21	Client_PresentCommercePurchaseUI ClientGame.CreateLocatorCircle ClientGame.HighlightTerritories CustomSpecialUnit GameOrderEvent.JumpToActionSpotOpt GameOrderEventResult.CardInstancesCreated UI.IsDestroyed WL.CancelClickIntercept
5.20	Setting TerritoryStanding.OwnerPlayerID to WL.PlayerID.AvailableForDistribution GameOrderEvent.AddCardPiecesOpt GameOrderEvent.AddResourceOpt GameOrderEvent.RemoveWholeCardsOpt TerritoryModification.AddArmies TerritoryModification.AddStructuresOpt
5.17	Using argument two of addNewOrder in Server_AdvanceTurn_Order GameOrderEvent.IncomeMods IncomeMod UI.InterceptNextBonusLinkClick UI.InterceptNextTerritoryClick WL.IsVersionOrHigher WL.StructureType.Arena WL.StructureType.ArmyCache WL.StructureType.ArmyCamp WL.StructureType.Attack WL.StructureType.Crafter WL.StructureType.DigSite WL.StructureType.Draft WL.StructureType.Hospital WL.StructureType.Market WL.StructureType.MercenaryCamp WL.StructureType.Mine WL.StructureType.MoneyCache WL.StructureType.Mortar WL.StructureType.Power WL.StructureType.Recipe WL.StructureType.ResourceCache WL.StructureType.Smelter

There is a chance that a player has a version of the app that pre-dates the introduction of the IsVersionOrHigher function. Many features were added after the first version of the Mod API Framework, but before the introduction of the function:

Version	Features
Up to 4.14.2	Various bug fixes / performance enhancements relating to mods. No other changes made to mod API framework until version 5.17.
3.20.2	Mod support for Commerce games (Commerce added in 3.20.0)
3.19.3	Bug fixes for GameOrderPlayCard, Armies.Add, Armies.Subtract Client_GameRefresh Client_PresentMenuUI Data storage Game.CreateDialog Game.SendGameCustomMessage GamePlayer.Income Server_GameCustomMessage
3.19.2	GameOrderCustom UI.Alert UI.Destroy UI.PromptFromList
3.18.2	Moved all WarLight mod classes into the global "WL" namespace. For example, to create an Armies object instead of just saying "Armies()", you now say WL.Armies.Create()
3.18.0	Mod API Framework added