Age of Wonders 3 Scripting Guide

Triumph Studios B.V.
Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Level Editor Script Guide

Scripting Examples:...................................................................................................................................5
Scripting Story Message Example.........................................................................................................5
Spawning Units Example.....................................................................................................................11
1. Scripting Overview..........................................................................................................................15
1.1
Scripts in LevelEd.........................................................................................................................15
1.1.1
Create script.......................................................................................................................15
1.1.2
Attach script to hex entity..................................................................................................15
1.1.3
Responding to events.........................................................................................................16
1.1.4
Embedded Scripts..............................................................................................................16
1.2
Diplomatic States..........................................................................................................................16
1.3
Structure States.............................................................................................................................17
1.4
Alias..............................................................................................................................................18
1.4.1
Alias Tags...........................................................................................................................18
1.4.2
Supported types..................................................................................................................18
2. Script Reference: Common..............................................................................................................18
2.1
GetAlias........................................................................................................................................18
2.2
SetAlias.........................................................................................................................................19
2.3
GetPosition....................................................................................................................................19
3. Script Reference: Classes.................................................................................................................20
3.1
City................................................................................................................................................20
3.1.1
CityGetRace..............................................................................................................................20
3.1.2
DestroyCityGuards....................................................................................................................21
3.1.3
CitySetDiplomaticState.............................................................................................................21
3.1.4
AICityBuilding..........................................................................................................................21
3.1.5
CityGetDiplomaticState............................................................................................................22
3.2
Item...............................................................................................................................................22
3.2.1
ItemHasTag...............................................................................................................................22
3.3
Marker...........................................................................................................................................23
3.3.1
MarkerEnable............................................................................................................................23
3.3.2
MarkerDisable...........................................................................................................................23
3.4
Player............................................................................................................................................24
3.4.1
PlayerGetAlias..........................................................................................................................24
3.4.2
PlayerGetLeaderAlias...............................................................................................................24
Script Guide - Triumph Studios B.V.

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
3.4.3
PlayerIsLeaderInVoid................................................................................................................25
3.4.4
PlayerEnableResearch...............................................................................................................25
3.4.5
PlayerGetNumSustainedSpells..................................................................................................25
3.4.6
PlayerGetSustainedSpell...........................................................................................................26
3.4.7
PlayerHasMetPlayer..................................................................................................................26
3.4.8
PlayerMeetsPlayer.....................................................................................................................27
3.4.9
PlayerGetDiplomaticState.........................................................................................................27
3.4.10 PlayerSetDiplomaticState..........................................................................................................27
3.4.11 PlayerOpenCloseBorders..........................................................................................................29
3.4.12 PlayerSendMessage...................................................................................................................29
3.4.13 PlayerSendMessageWithSender................................................................................................29
3.4.14 PlayerKillLeader.......................................................................................................................30
3.4.15 PlayerSetVictorious...................................................................................................................30
3.4.16 PlayerSetDefeated.....................................................................................................................31
3.4.17 PlayerAddItem..........................................................................................................................31
3.4.18 PlayerCastSpell.........................................................................................................................32
3.4.19 PlayerIsTrespassingInDomain...................................................................................................32
3.4.20 PlayerGetNumCities..................................................................................................................33
3.4.21 PlayerGetCity............................................................................................................................33
3.4.22 PlayerGetThroneCity................................................................................................................34
3.5
Race...............................................................................................................................................34
3.5.1
RaceIsEliminated......................................................................................................................34
3.6
Unit Groups...................................................................................................................................35
3.6.1
SetGroupHome..........................................................................................................................35
3.6.2
SetGroupBehavior.....................................................................................................................35
3.6.3
GetGroupBehavior....................................................................................................................35
3.6.4
DestroyGroup............................................................................................................................35
3.7
Quest.............................................................................................................................................36
3.7.1
PlayerOfferQuest.......................................................................................................................36
3.7.2
PlayerOfferCityQuest................................................................................................................36
3.7.3
PlayerForceQuest......................................................................................................................37
3.7.4
PlayerOfferSubQuest.................................................................................................................37
3.7.5
PlayerForceSubQuest................................................................................................................38
3.7.6
PlayerCompleteQuest................................................................................................................38
3.7.7
PlayerFailQuest.........................................................................................................................39
3.7.8
PlayerIncreaseQuestCompletionCount.....................................................................................39
3.7.9
PlayerDecreaseQuestCompletionCount....................................................................................39
3.8
AI..................................................................................................................................................40
3.8.1
ToggleAI....................................................................................................................................40
3.8.2
DiplomacyAISetPassive............................................................................................................40
3.8.3
DiplomacyAIEnabled................................................................................................................41
3.8.4
DiplomacyAIDisabled...............................................................................................................41
3.8.5
AISpellcastingLimit..................................................................................................................41

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
3.8.6
AISetTargetBounty....................................................................................................................42
3.8.7
AISetPlayerTargetBounty.........................................................................................................42
3.8.8
ToggleResources.......................................................................................................................42
3.8.9
SetOffensiveAIEnabled.............................................................................................................43
3.8.10 AISetRazeEnabled....................................................................................................................43
3.9
Camera..........................................................................................................................................44
3.9.1
CenterCameraOnEntity.............................................................................................................44
3.10 Spawn Group................................................................................................................................44
3.10.1 SpawnGroupSpawnAtPosition..................................................................................................45
3.11 Stack..............................................................................................................................................45
3.11.1 StackGetPosition.......................................................................................................................45
3.11.2 StackGetNumUnits....................................................................................................................46
3.11.3 StackGetUnit.............................................................................................................................46
3.11.4 StackJoinPlayer.........................................................................................................................47
3.11.5 StackGetPlayer..........................................................................................................................47
3.11.6 StackSetDirection......................................................................................................................47
3.12 StrategicWorld..............................................................................................................................48
3.12.1 StrategicWorldChangeOverlay..................................................................................................48
3.12.2 StrategicWorldChangeTheme...................................................................................................49
3.12.3 StrategicWorldGetNumPlayers.................................................................................................49
3.12.4 StrategicWorldGetPlayerAlias..................................................................................................50
3.13 Structure........................................................................................................................................50
3.13.1 StructureGetState......................................................................................................................50
3.13.2 StructureSetState.......................................................................................................................51
3.13.3 StructureGetOwner....................................................................................................................51
3.13.4 StructureSetOwner....................................................................................................................52
3.14 Timer.............................................................................................................................................52
3.14.1 TimerStart..................................................................................................................................52
3.14.2 TimerStop..................................................................................................................................53
3.14.3 TimerReset................................................................................................................................53
3.15 Unit...............................................................................................................................................53
3.15.1 UnitHasRequisite......................................................................................................................53
3.15.2 UnitKill......................................................................................................................................54
3.15.3 UnitGetInventoryItem...............................................................................................................54
3.15.4 UnitGetStackAlias.....................................................................................................................55
3.15.5 UnitSetGroup............................................................................................................................55
3.15.6 UnitDropItem............................................................................................................................56
3.15.7 UnitCannotDieInTC..................................................................................................................56
4. Script Reference: Campaign & Data Access...................................................................................57
4.1
Campaign......................................................................................................................................57
4.1.1
CampaignUnlockScenario.........................................................................................................57
4.1.2
CampaignSaveUnit....................................................................................................................57
4.1.3
CampaignSpawnSavedUnit.......................................................................................................57

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
4.1.4
CampaignSpawnAsLeader........................................................................................................58
4.2
Data Access...................................................................................................................................58
4.2.1
GetMapBool..............................................................................................................................59
4.2.2
SetMapBool...............................................................................................................................60
4.2.3
GetMapNumber.........................................................................................................................60
4.2.4
SetMapNumber.........................................................................................................................60
4.2.5
GetMapString............................................................................................................................60
4.2.6
SetMapString.............................................................................................................................61
4.2.7
GetCampaignBool.....................................................................................................................61
4.2.8
SetCampaignBool......................................................................................................................61
4.2.9
GetCampaignNumber................................................................................................................61
4.2.10 SetCampaignNumber................................................................................................................62
4.2.11 GetCampaignString...................................................................................................................62
4.2.12 SetCampaignString....................................................................................................................62

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Scripting Examples:
Here follow a few examples to get you started:
Scripting Story Message Example

No campaign scenario is complete without story messages!
Once you have roughed out a map and set up the leaders its time to add story scripting.
Lets say I am making a single player map and I want my units to say something in a story message
when they grab a treasure chest from a specific location.
I place the treasure chest pickup on the ground and edit the surroundings to
signify the importance of the chest.
Under Objects I select the Marker tab and place a Stack Area Trigger.

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
I leave it to its default settings (Active True, Trigger Type Trigger Once, Marker Cancel Movement
True).
When sending story messages Cancel Movement should always be true, otherwise a unit may trigger
other events that can break the scripting (maybe it dies from a Hook Briar hazard so it doesnt exist
anymore to reply, etc).
With the Stack Area Trigger selected I click the Script button to open the
Script Pool.

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
I click the New EventScript button and name my script

TreasureCommentScript. Its added to the Declared Scripts folder.
I click on the little arrow and see my script listed.
Now on the right side I see a number of events:


Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
I drag the gear icon next to OnStackEnters on the script and release it: the
Script Editor will open with a function in it. Everything I write in that function
block will fire as soon as a stack enters the hex I placed the stack area
trigger on.
So now I need a script to send a message.

I can get the stacks alias from the argTarget variable which has stored the stack entity that triggered the
trigger. Then I need to get the alias of the first unit in the stack (the army leader), as messages can only
be sent by units and not by stacks.
Then I give that unit a specific alias that I will use as sender of the message.
The script I write is the following:
function Class:Event_OnStackEnters(argTarget)
-- Getting the alias of the stack that entered the area trigger:
stackalias = HexWorld:GetScriptingS():GetAlias(argTarget)
-- Getting the first unit from the stack who triggered the area trigger:
speakerunit = HexWorld:GetScriptingS():StackGetUnit(stackalias, 0)
-- Getting the alias of that unit:
speakerunitalias = HexWorld:GetScriptingS():GetAlias(speakerunit)
-- Setting the alias of that unit:
HexWorld:GetScriptingS():SetAlias(speakerunitalias, "SPEAKER")
-- Sending a stroy message (sender alias in message needs to be SPEAKER):
HexWorld:GetScriptingS():PlayerSendMessage("TREASURECOMMENT", "PLAYER1")
end;

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Then a part thats easy to forget!

I drag the TreasureCommentScript to the Attached Scripts folder and
release: only then will the script actually be attached to the area trigger and
function at all!
Then I place an AIBlocker (another type of Marker) nearby and with the Edit
trigger locations button I paint an area on and around the chest to be off
limits to the AI.
Now I need to make that story message:
I select the Story tab on the right top of the editor and click Add.
As alias of the message I fill in TREASURECOMMENT (this must be exactly
the same as in the PlayerSendMessage script).
As alias of the sender I type in SPEAKER, the alias I gave to the unit who
needs to do the talking.
I type some words in the title and body and Button 1 custom string fields
(buttons are only displayed if theres text in them, so if you forget this you
cannot get rid of your story message!).

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Now I am going to test my script to see if it all works according to plan!

10

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
It works, but it would be kind of boring if that was the end of it!
Lets say the treasure has been placed there for a powerful band of thieves by a nearby city, as a bribe
so they wont disturb them for another month. A few assassins, coming to collect the treasure are
spawned nearby and attack.
Spawning Units Example
To spawn units I need to make a Spawn Group.
11

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
I select the tab on the right that says Spawner, and from the empty-looking
drop-down list I select the unit spawn group (the only possible selection).
Then I click the New Group button.
A new group will be made. I change its alias to ASSASSINSPAWN and the
Owning player to Independent(Hate All). At the bottom I set the groups
alias to ASSASSINS and the behavior to Raid (that will make sure they attack
everyone they meet).
Then, with the group selected, I click Edit and under Rogue units I add 3 Orc
Assassins.
Now I need to spawn the units when the treasure is taken.
I put down another stack area trigger, but this time I set Marker Is Active to
false, as I only need it as a location for the assassins to spawn at. Since Ill
be using it for that I give it the alias ASSASSINSPAWNLOC.
12

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Now for the script, I am going to use the button of the story message I created earlier.
I can just click the On Button 1 Script field and then click the
button and a
script editor will open. This script will be executed as soon as the user clicks
the button on the story message.
The SpawnGroupSpawnAtPosition script needs a location in hexPosition format, but I have no idea
what that could be, so I need to get the position of the stack area trigger in hexPosition format using the
GetPosition script which returns the position of the entity whos alias I filled in.
Since LUA doesnt mind, I can actually substitute the hexPosition parameter by the script that finds it
for me, so I dont need a separate variable to store it in first.
The script I come up with is this:
-- Spawning group ASSASSINSPAWN at the location of the marker with alias
ASSASSINSPAWNLOC, facing southwest.
HexWorld:GetScriptingS():SpawnGroupSpawnAtPosition("ASSASSINSPAWN",
HexWorld:GetScriptingS():GetPosition("ASSASSINSPAWNLOC"), "SW")
13

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Now its time to test again!
It works, the Assassins spawn and next turn they will attack me.
Later I can add the city that paid the gold, and when I meet them and tell them about the gold and the
assassins they can give me a quest to kill the leader of the thieves, with the city as reward.
Last tip: save often! As soon as you get a popup with an assertion or any error/access violation however
do not save! You might corrupt the entire map file and lose all your work!
14

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
1. Scripting Overview
This is a short overview of how scripting works in AoW3.
Please note that scripting may very well break the game! The documentation provided is
incomplete, in the sense that it doesnt warn you about all the ways scripting may go wrong. It
doesnt always define when or how its safe to use the scripts. We also dont guarantee its up to
date and 100% correct.
Scripting in AoW3 consists of LUA scripts that can be attached to all hex entities on the strategic map.
This can be done in the AoW3 LevelEd. Scripting can respond to events or call methods on those hex
entities. This wiki lists these events and methods, and provides descriptions and examples on how to
use them.
The object to call the methods on is always:
HexWorld:GetScriptingS()
For example:
HexWorld:GetScriptingS():StackGetNumUnits("STACKALIAS")
1.1 Scripts in LevelEd

Scriptable hex entities have a 'Scripting' button. This opens the 'Scripting Pool Editor' for that hex
entity. Here you can create, modify and delete scripts.
1.1.1 Create script
Click the 'New Script' button icon in the top left corner
Name your script
The script appears under the 'Declared Scripts' folder in the left treeview
1.1.2 Attach script to hex entity

When a script is created it is not yet attached to the entity. To do this:
Drag a script from the 'Declared Scripts' folder in the left treeview to the 'Attached Scripts'
folder in the right treeview.
15

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
1.1.3 Responding to events

Events that are generated for a hex entity are listed in the right treeview and can be identified by the
icon. In order to have scripts execute when an event is fired you will need to link the event to a script.
Drag an event to a script you have created
Notice how the script is opened for editing and a new function has been created. This is the function
that gets executed when the event is fired.
1.1.4 Embedded Scripts

Sometimes you can embed scripts directly into a structure: they get fired on the condition mentioned in
the event and open a script editor window right away.
These scripts do not need to be named.
For example, Quests can have scripts embedded On Quest Accepted, On Quest Completed, etc.
Messages can have scripts embedded On Button 1, On Button 2 etc. (if a button doesnt contain text its
not displayed).
Players too can have embedded scripts: Open the Script Manager by clicking on the plus and you can
embed scripts On City Founded, On Defeat, etc.
There are more places where embedded scripts are possible. You can open the script editor of an
embedded script by clicking the button.
1.2
Diplomatic States
A diplomatic state describes relation standing between two players. The diplomatic states are:
Unknown = 0
The state between two players that have not yet meet each other.
Neutral = 1
The initial state when two players meet for the first time.
War = 2
Peace = 3
Alliance = 4
In scripts the diplomatic state is indicated by an integer as shown in the list.

Since indie cities count as players too in code, they have a diplomatic state too (you can toggle this
with CitySetDiplomaticState). The states are the same, except:
Alliance = 4
The city is absorbed by the player.
You should never script the diplomatic state to become unknown.

16

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
1.3
Structure States
Some structures have different functionality depending on the state they are in. This page lists all
structure state. Note that not all structures have a state, and that some states are for a specific type of
structure.
None = 0
State when the structure doesn't have a (current) state.
Player Structures Only*
Structure_Owned = 1
State when the structure is razed.
City Only
City_Owned = 2
The city is under control of a player
City_Occupied = 3
The city is occupied. Not producing anything.
Rebellion State has been Removed, count skips state 4 to prevent previously existing scripts
from not working anymore.
Treasure Site Only
Treasure_Unexplored = 5 The treasure site is not yet explored by a player.
Treasure_Explored = 6
The treasure site is explored. A player has claimed its rewards.
Visit Structure Only
Visit_Charged = 7
receive the benefit.
The visit structure is charged. When a stack moves onto it it will
Visit_Depleted = 8
The visit structure is charging. Benefit not available yet.
Teleporter Only:
Teleporter_Active = 9
The teleporter is active and can be used to teleport from.
Teleporter_Inactive = 10 The teleporter is inactive. It cannot be used to teleport from. It can

be used to teleport to from another teleporter.
In scripts the structure state is indicated by an integer as shown in the list.

Player Structures Only*:
Cities, Watch Towers, Forts and Spelljamers are Player Structures.
17

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
1.4
Alias
An alias is a name given to an entity. You can set your own aliases in levelED. This makes it possible to
refer to an entity in scripting without having to obtain the alias first. For example if you want a specific
unit to speak at some point, you can name that unit ELFGUARDSPEAKER, and use that alias as the
message sender in the story message.
An alias must be unique.
Stacks also have aliases, but beware: stack aliases can change dynamically because stacks can merge,
split, lose a unit etc. So usually you wont use a stack alias unless you have just found out the stack
alias in the same script, or are very sure the stack cannot have changed in the time between.
1.4.1 Alias Tags

If you want to add the name of the structure dynamically to a localized string you can use an alias tag
like this:
Suppose a structure with the alias 'MY_CITY'.
Localized string: "In this localized string the name of the city {MY_CITY} will be dynamically
added"
1.4.2 Supported types
Structures
Cities
Units
Quests (Make sure they don't share the same alias as hex entities)
2. Script Reference: Common

2.1
GetAlias
string GetAlias(hexEntity : object)

Get the alias for the specified hex entity
<return value>:
18

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
The alias of the hex entity. Returns "INVALID" on failure

<param hexEntity>:
The hex entity to get the alias for
Example:
Print the alias of all the units in a stack
for i = 0, HexWorld:GetScriptingS():StackGetNumUnits("stackAlias") - 1, 1 do
local unit = HexWorld:GetScriptingS():StackGetUnit("stackAlias", i)
Print(HexWorld:GetScriptingS():GetAlias(unit))
end
2.2
SetAlias
void SetAlias(alias : string, aliasToSet : string)

Set the alias for a hex entity.
<param alias>:
The alias of the entity to set the alias for.
<param alias>:
The alias to set for the entity.
Example: To set the Alias of a Campaign Hero you can do the following:
local AliasGroshak = HexWorld:GetScriptingS():CampaignSpawnSavedUnit("GROSHAK", position :
HexPosition)
HexWorld:GetScriptingS():SetAlias(AliasGroshak, "GROSHAK")
2.3
GetPosition
HexPosition GetPosition(hexEntityAlias : string)

Get the position for the hex entity with the specified alias.
<return value>:
The position of the hex entity. Returns NULL on failure.
19

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
<param hexEntityAlias>:
The alias of the hex entity to get the position for.
Example:
Change the terrain around a marker to artic. (#0000000105800063 is the resourceID of artic in
this case)
local markerPostion = HexWorld:GetScriptingS():GetPosition("MARKERALIAS")
HexWorld:GetScriptingS():StrategicWorldChangeTheme(markerPostion, 1, "#0000000105800063")
3. Script Reference: Classes

3.1
City
A city is a special type of structure. In addition to the methods and functions listed here it also has
access to all the methods and events of the structure class.
Events______________________________________________________
OnRaceChanged
Called when the race of the city has changed.
OnStartRebellion
Called when the city begins rebelling.
OnStopRebellion
Called when the city stops rebelling.
OnCityOperationCompleted
Called when a city operation has been completed.
Please note that OnEnable, OnDisable, OnActivate, OnPostActivate and OnDeactivate are handles that
get fired by code at unpredictable times or only during map creation/destruction. Do not attach
scripting to these.
3.1.1 CityGetRace
string CityGetRace(cityAlias : string)
Get the race name of the city.
<return value>:
The race name of the city. Returns NULL on failure.
<param cityAlias>:
The alias of the city to get the race name for.
20

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
3.1.2 DestroyCityGuards
void DestroyCityGuards(cityAlias : string)
Destroys all city guards that are defending a city.
Note: Only works for independents.
<param cityAlias>:
The alias of the city.
3.1.3 CitySetDiplomaticState
void CitySetDiplomaticState(cityAlias : string, playerToChangeBordersFor : string, diplomaticState :
int)
Sets the diplomatic state of the independent city.
Player will meet the city if they have not met it yet.
For any state except state 4, there should be an if statement checking that the city isnt already in the
state that it is set to, otherwise the system may assert and throw a warning (example:
if HexWorld:GetScriptingS():CityGetDiplomaticState("SUNDREN", "ELDASTE") ~= 3 then
HexWorld:GetScriptingS():CitySetDiplomaticState("ELDASTE", "SUNDREN", 3)
End)
<param1 - cityAlias >:
The alias of the city who's state will be set.
<param2 - playerToOpenCloseBordersFor>:
The alias of the player for who the relation with the city will be set.
<param3 - diplomaticState>:
The diplomatic state the relation will be set to. See diplomatic states how they are mapped to ints.
Peace will also open borders.
War will also close borders.
Alliance will absorb the city.
3.1.4 AICityBuilding
string AICityBuilding(cityAlias : string, canBuild : boolean)
Sets if the AI may build upgrades and units in the target city
<param cityAlias>:
21

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
The alias of the city to affect

<param canBuild>
false to prevent the AI queing production orders in the city
3.1.5 CityGetDiplomaticState
int CityGetDiplomaticState(playerAlias : string, cityAlias : string)
Get the diplomatic state between a player and a city
<return value>:
The diplomatic state between the player and the city. Returns -1 on failure. See diplomatic states
how they are mapped to ints.
<param playerAlias >:
The alias of the player in the relation.
<param cityAlias >:
The alias of the city in the relation.
Example:
local diplomaticState = HexWorld:GetScriptingS():CityGetDiplomaticState("PLAYER1", "CITY1")
3.2
Item
Item
Class
An class that represents a item that can be equiped by hero units
Events______________________________________________________
OnPickUp
Triggers when item is pickup by a unit.
OnDrop
Triggers when item is moved from the unit's inventory to
an item sack
3.2.1 ItemHasTag
bool ItemHasTag(item : Item, tags : string)
22

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Returns whether the items has the tags that are specified.
<return value>:
Returns true if the item has the tags.
<param item>:
The item to check for tags.
<param pTags>:
A comma separated list of tags.
3.3
Marker
An object that can be placed in LevelEd to respond to specific events.

Events______________________________________________________
Stack Area Trigger
OnStackEnters(Stack)
Called when a stack enters the cell (moving through AND
stopping)
OnStackArrives(Stack)
Called when a stack stops its movement on a cell (ONLY
stopping)
OnStackChangesSides(Stack)
Called when a stack changes sides on the cell
OnStackLeaves(Stack)
Called when a stack leaves the cell
Item Area Trigger
OnItemEnters
OnItemLeaves
Called when an item enters the cell

Called when an item leaves the cell
3.3.1 MarkerEnable
int MarkerEnable(markerAlias : string)
Enable the marker.
<param markerAlias>:
The alias of the marker to enable
3.3.2 MarkerDisable
int MarkerDisable(markerAlias : string)
23

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Disable the marker.

<param markerAlias>:
The alias of the marker to disable.
3.4
Player
A class that represents one of the players

Events______________________________________________________
OnCastSpell
Called when the player casts a spell on the strategic map.
OnRelationChanged
Called when one of the player's relations have changed.
OnAlignmentChanged
Called when the player's alignment has changed.
OnNumCitiesChanged
Called when the number of cities the player owns has changed.
OnDefeat
Called when the player has lost.
OnVictory
Called when the player has won.
OnPlayersMeet
Called when two players meet each other.
3.4.1 PlayerGetAlias
string PlayerGetAlias(player : Player)
Get the alias of the specified player
<return value>:
The alias of the player.
<param player>:
The player to get the alias for.
3.4.2 PlayerGetLeaderAlias
string PlayerGetLeaderAlias(playerAlias : Player)
Get the alias of the leader unit from the specified player.
Note that by exception the alias of a Leaderunit is the same as the alias of the Lord player entity, to
make things more intuitive (for example if the Alias of Player 1s Lord is PLAYER1, then the Alias of
the unit ingame representing Player 1s leader also has the alias PLAYER1, even though they are
separate entities in reality).
24

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
<return playerAlias>:
The alias of the leader unit.
<param player>:
The alias of the player to get the leader for.
3.4.3 PlayerIsLeaderInVoid
bool PlayerIsLeaderInVoid(playerAlias : string)
Returns whether the leader of the specified player is in the void
<return value>:
True if the player is in the void, false otherwise
The alias of the player for whom we want to know if the leader is in the void
3.4.4 PlayerEnableResearch
void PlayerEnableResearch(playerAlias : string, skillResourceID : string, enable : bool)
Enables or disables a spell from being available for research.
<param playerAlias>:
The alias of the player whose skill will be enabled/disabled for research.
<param skillResourceID>:
The resource id of the skill that will be enabled/disabled. Changes in resources can alter this id, so it
should be considered unsafe to use. For now the only way to obtain a resource id is to ask for it on the
games forums. The devs are the only ones who can look them up.
<param enable>:
Whether the specified skill should be enabled or disabled for research.
3.4.5 PlayerGetNumSustainedSpells
int PlayerGetNumSustainedSpells(playerAlias : string)
25

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Get the number of spells the player is sustaining.

<return value>:
The number of sustained spells. Returns -1 on failure.
The alias of the player to get the number of sustaining spells from.
3.4.6 PlayerGetSustainedSpell
SustainedSpell PlayerGetSustainedSpell(playerAlias : string, index : int)
Get the sustained spell for the player at the specified index.
<return value>:
The sustained spell at the specified index. Returns NULL on failure.
The alias of the player to get the sustained spells from.
<param index>:
The index of the spell.
3.4.7 PlayerHasMetPlayer
bool PlayerHasMetPlayer(player1Alias : string, player2Alias : string)
Returns whether the two players have met. Useful to detect if its the first time the players meet
(OnMeet is triggered every time a player meets a player/indie city, so if it triggers and
PlayerHasMetPlayer returns true it was the first time they met).
<returns value>
Whether the two players have met.
<param player1Alias>:
The alias of a player.
26

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
3.4.8 PlayerMeetsPlayer
void PlayerMeetsPlayer(player1Alias : string, player2Alias : string)
Let the two players meet each other. This will allow trading, setting of diplomatic states, applying
modifiers etc.
3.4.9 PlayerGetDiplomaticState
int PlayerGetDiplomaticState(player1Alias : string, player2Alias : string)
Get the diplomatic state between two players.
<return value>:
The diplomatic state between the two players as an int. Returns -1 on failure. See diplomatic states
The alias of one of the players in the relation.
Example:
local diplomaticState = HexWorld:GetScriptingS():PlayerGetDiplomaticState("PLAYER1",
"PLAYER2")
3.4.10
PlayerSetDiplomaticState
int PlayerSetDiplomaticState(player1Alias : string, player2Alias : string, diplomaticState : string,

immediate : bool)
27

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Set the diplomatic state between two players. There should be an if-statement checking that the players
arent already in the state that they are set to, otherwise the system may assert and throw a warning.
Also note that players, even in a script, should pass through the peace state before they are set to war
from alliance. So first set two allied players to peace, immediate bool true, and then to war, if you want
to script the breaking of an alliance into war.
<return value>:
The diplomatic state between the two players as an int. Returns -1 on failure. See diplomatic states
<param1 - player1Alias>:
<param2 - player2Alias>:
<param3 - diplomaticState>:
The diplomatic state the relation will be set to. See diplomatic states how they are mapped to ints.
<param4 - immediate>:
Whether the new diplomatic state is applied immediately to the relation. If this is set to false the
normal rules for changing diplomatic states of a relation apply (Changes from Alliance to Peace and
Peace to War take a turn before they are applied). True means the changes in diplomatic state are
applied without the 'wait' turn.
Example:
Change the diplomatic state from the relation between "PLAYER1" and "PLAYER2" to alliance.
if HexWorld:GetScriptingS():PlayerGetDiplomaticState("PLAYER1",
"PLAYER2") == 2 then
-- Player1 and Player2 are at war with each other, set the
-- diplomatic state to peace before we can set it to alliance
HexWorld:GetScriptingS():PlayerSetDiplomaticState("PLAYER1",
"PLAYER2", 3, true)
end
-- Set the diplomatic state to alliance
HexWorld:GetScriptingS():PlayerSetDiplomaticState("PLAYER1",
"PLAYER2", 4, true)
28

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
3.4.11
PlayerOpenCloseBorders
void PlayerOpenCloseBorders(domainOwner : string, playerToOpenCloseBordersFor : string, open :

bool)
Open or close borders of the domain owner for the other player.
<param1 - domainOwner>:
The alias of the player who will open or close his borders.
<param2 - playerToOpenCloseBordersFor>:
The alias of the player for who the borders will be closed or opened.
<param3 - open>:
If true the borders will be opened, otherwise they will be closed.
3.4.12
PlayerSendMessage
void PlayerSendMessage(messageAlias : string, playerAlias : string)

Send a message to a player.
Note: When sending a message from an area trigger make sure the area trigger is set to 'Cancel
Movement, otherwise the game may crash/hang!
<param messageAlias>:
The alias of the message that will be sent.
The alias of the player the message will be send to.
3.4.13
PlayerSendMessageWithSender
void PlayerSendMessageWithSender(messageAlias : string, playerAlias : string, senderAlias : string)

Send a message to a player with a custom sender alias.
29

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Note: When sending a message from an area trigger make sure the area trigger is set to 'Cancel
Movement'
<param messageAlias>:
The alias of the message that will be sent.
The alias of the player the message will be send to.
<param senderAlias>:
The alias of the unit which will be displayed as the sender of the message.
3.4.14
PlayerKillLeader
void PlayerKillLeader(playerAlias : string, resurrectable : bool, AnnihilateInventory : bool,

SuppressDeathAnimation : bool)
Kill the leader unit of the specified player.
The alias of the player whose leader will be killed.
<param resurrectable>:
Whether this leader should be resurrectable.
<param AnnihilateInventory>:
If true than the items in the inventory are destroyed. If false the items are dropped.
<param SuppressDeathAnimation>:
If true then the unit will not play a death animation when it's removed from the world.
3.4.15
PlayerSetVictorious
void PlayerSetVictorious(playerAlias : string, victoryText : string)

Tell the system that the given player has won the map. Other players will be automatically set to
defeated, if you want to display text for them use PlayerSetDefeated.
30

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Note! Support to be able to set a string of text to display on win will (probably) come in patch 03!
Note: If you want to enforce that no victory can be gained through any other means than scripting set
victory condition to "Scripted".
The alias of the player that has won.
<param victoryText>:
The text that will be shown on the victory screen as the reason for victory. (Wait till patch 03 to use
this, check patchnotes to see if it made it in the patch.)
3.4.16
PlayerSetDefeated
void PlayerSetDefeated(playerAlias : string, defeatText : string)

Tell the system that the given player has lost the map.
Note! Support to be able to set a string of text to display on defeat will (probably) come in patch 03!
Note: Instantly sets player state to defeated no matter if its leader is still alive or if it has a throne city.
The alias of the player that has been defeated
<param defeatText>:
The text that will be shown on the defeat screen as the reason for defeat. (Wait till patch 03 to use
this, check patchnotes to see if it made it in the patch.)
3.4.17
PlayerAddItem
void PlayerAddItem(playerAlias : string, itemResourceId : string)

Add item to the leader unit of the player.
Note: If the player does not have a leader unit / hero, no item will be given. If the existing hero's
inventory is full, the item will be dropped on the ground.
31

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
The alias of the player of whom the leader unit will receive the item
<param itemResourceId>:
The resourceID of the item which will be given to the unit. Changes in resources can alter this id, so
it should be considered unsafe to use. For now the only way to obtain a resource id is to ask for it on
the games forums. The devs are the only ones who can look them up.
3.4.18
PlayerCastSpell
void PlayerCastSpell(playerAlias : string, position : LUAHMPos, spellResourceId : string)

Cast Spell on Strategic Map
Note: To cast a spell the player must exist. Player INDEPENDENTS can be used if you do not want a
lord player to cast the spell.
The alias of the player who casts the spell
<param position>:
The position at which the spell will be cast
<param spellResourceId>:
The resourceID of the spell which will be cast. Changes in resources can alter this id, so it should be
considered unsafe to use. For now the only way to obtain a resource id is to ask for it on the games
forums. The devs are the only ones who can look them up.
Example:
Cast spell lightning storm on the position of a stack. (#0000011A00000B56 is the resourceID of
lightning storm here)
local stackPosition = HexWorld:GetScriptingS():StackGetPosition("stackAlias")
HexWorld:GetScriptingS():PlayerCastSpell("INDEPENDENTS", stackPosition,
"#0000011A00000B56")
3.4.19
PlayerIsTrespassingInDomain
bool PlayerIsTrespassingInDomain(trepassingPlayerAlias : string, domainOwningPlayerAlias : string)

32

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Checks if any units of the player (trespassingPlayerAlias) are trespassing are trespassing in the domain
of the other player (domainOwningPlayerAlias)
<param trepassingPlayerAlias>:
The alias of the player who is trespassing
<param domainOwningPlayerAlias>:
The alias of the player of which its domain is being trespassed
Example:
local isTrespassing =
HexWorld:GetScriptingS():PlayerIsTrespassingInDomain("PLAYER_1","PLAYER_2")
3.4.20
PlayerGetNumCities
int PlayerGetNumCities(playerAlias : string)

returns the number of cities the specified player has
The alias of the player of whom you want the number of cities
Example:
local numCities = HexWorld:GetScriptingS():PlayerGetNumCities("PLAYER1")
3.4.21
PlayerGetCity
string PlayerGetCity(playerAlias : string, cityIndex : int)

Gets the city with the specified cityIndex from the specified player
The alias of the player of whom you want the city
<param cityIndex >:
The index of the city you want from this player
33

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Example:
local cityIndex = 1
local cityAlias = HexWorld:GetScriptingS():PlayerGetCity("PLAYER1",cityIndex)
3.4.22
PlayerGetThroneCity
bool PlayerGetThroneCity(playerAlias : string)

Returns the throne city of the specified player
<return value>:
The alias of the throne city. Returns NULL on failure
The alias of the player of whom you want the throne city
3.5
Race
3.5.1RaceIsEliminated
bool RaceIsEliminated(raceName : string)
Check if a race is present on the map
If there are no Cities or Settlers of a specific race, then this function returns true
Note: There is no difference between a race which never existed on the map and a race which was
eliminated.
<param raceName>:
The RaceName of the Race, ex. "DRACONIAN".
Available Races:
HIGHELF
HUMAN
ORC
GOBLIN
DWARF
DRACONIAN
34

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Example:
Check if all Draconians have been eliminated from the map
local raceHasBeenEliminated = HexWorld:GetScriptingS():RaceIsEliminated("DRACONIAN")
3.6
Unit Groups
Unit groups are used by the strategic AI to enable control behaviors.
3.6.1 SetGroupHome
void SetGroupHome(GroupAlias : string, HomeAlias: string)
Sets the home location of a group using the alias of a map entity. Some group behaviors have a home
location they will move to.
3.6.2 SetGroupBehavior
void SetGroupBehavior(GroupAlias : string, BehaviorName: string)
Sets the behavior of a group.
<param BehaviorName>:
"GUARD" : guard behavior - guards a single location or a specified area.
"PATROL": patrol behavior - patrols around the home location with a specified range. Attacks all
enemy units it encounters.
"RAID": raid behavior - attacks everything it can find...
3.6.3 GetGroupBehavior
object GetGroupBehavior(GroupAlias : string)
Returns the behavior that is active on a group. Use this function to modifiy behavior parameters..
3.6.4 DestroyGroup
void DestroyGroup(GroupAlias : string)
Destroys a player group, all units will be controlled by the central player AI. (not supported for
independents)
35

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
3.7
Quest
A Quest is a task you can give to the player, completing a quest gives the player a reward.
3.7.1 PlayerOfferQuest
void PlayerOfferQuest(playerAlias : string, questAlias : string, popupQuest: bool)
Offers a quest to the player which he can accept or decline.
The alias of the player to offer the quest.
<param questAlias>:
The alias of the quest to offer.
<param popupQuest>:
Determines if it is a popup quest (= true) or a to-do quest (=false).
Example:
HexWorld:GetScriptingS():PlayerOfferQuest("PLAYER1", "QUEST1", false)
3.7.2 PlayerOfferCityQuest
void PlayerOfferCityQuest(playerAlias : string, cityAlias : string, questAlias : string)
Offers a quest from a city to the player which he can accept or decline. Completing this quest will
absorb the city into the player's domain.
The alias of the player to offer the quest to.
<param cityAlias>:
The alias of the city offering the city quest.
<param questAlias>:
Example:
36

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
HexWorld:GetScriptingS():PlayerOfferCityQuest("PLAYER1", "CITY1", "QUEST1")
3.7.3 PlayerForceQuest
void PlayerForceQuest(playerAlias : string, questAlias : string)
Force a quest to the player which is automatically accepted (cannot be declined).
The alias of the player to force the quest.
<param questAlias>:
The alias of the quest to force.
Example:
HexWorld:GetScriptingS():PlayerForceQuest("PLAYER1", "QUEST1")
3.7.4 PlayerOfferSubQuest
void PlayerOfferSubQuest(playerAlias : string, questHeaderAlias : string, questAlias : string,
popupQuest: bool)
Offers a subquest to the player which he can accept or decline, this quest will get added to the
specified quest header.
The alias of the player to offer the quest.
<param questHeaderAlias >:
The alias of the questheader to which the subquest will be attached (required to add subquest)
<param questAlias>:
<param popupQuest>:
Determines if it is a popup quest (= true) or a to-do quest (=false).
Example:
37

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
HexWorld:GetScriptingS():PlayerOfferSubQuest("PLAYER1", "QUEST_HEADER_1", "QUEST1",

false)
3.7.5 PlayerForceSubQuest
void PlayerForceSubQuest(playerAlias : string, questHeaderAlias : string, questAlias : string)
Force a subquest to the player which is automatically accepted (cannot be declined), this quest will be
added to the specified quest header.
The alias of the player to force the quest.
<param questHeaderAlias>:
The alias of the questheader the subquest will be attached to.
<param questAlias>:
The alias of the quest to force.
Example:
HexWorld:GetScriptingS():PlayerForceSubQuest("PLAYER1", "QUEST_HEADER1", "QUEST1")
3.7.6 PlayerCompleteQuest
void PlayerCompleteQuest(playerAlias : string, questAlias : string)
Completes a quest of the player.
The alias of the player to complete the quest.
<param questAlias>:
The alias of the quest to complete.
Example:
HexWorld:GetScriptingS():PlayerCompleteQuest("PLAYER1", "QUEST1")
38

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
3.7.7 PlayerFailQuest
void PlayerFailQuest(playerAlias : string, questAlias : string)
Fails a quest of the player.
The alias of the player to fail the quest.
<param questAlias>:
The alias of the quest to fail.
Example:
HexWorld:GetScriptingS():PlayerFailQuest("PLAYER1", "QUEST1")
3.7.8 PlayerIncreaseQuestCompletionCount
void PlayerIncreaseQuestCompletionCount(playerAlias : string, questAlias : string)
Increases the completion count of a player's quest by 1.
The alias of the player to increase the quest completion type of.
<param questAlias>:
The alias of the quest to increase the quest completion type of.
Example:
HexWorld:GetScriptingS():PlayerIncreaseQuestCompletionCount("PLAYER1", "QUEST1")
3.7.9 PlayerDecreaseQuestCompletionCount
void PlayerDecreaseQuestCompletionCount(playerAlias : string, questAlias : string)
Decreases the completion count of a player's quest by 1.
The alias of the player to decrease the quest completion type of.
39

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
<param questAlias>:
The alias of the quest to decrease the quest completion type of.
Example:
HexWorld:GetScriptingS():PlayerDecreaseQuestCompletionCount("PLAYER1", "QUEST1")
3.8
AI
AI (Artificial Intelligence) controls the actions of a computer controlled player.
3.8.1 ToggleAI
void ToggleAI(playerAlias : string, enableAI: bool)
Toggles the AI on or off for a specific player.
The alias of the player to toggle the AI for (the AI player)
<param enableAI>:
Determines if the AI needs to be enabled (=true) or disabled (=false) for a player
Example:
HexWorld:GetScriptingS():ToggleAI("PLAYER1", true)
HexWorld:GetScriptingS():ToggleAI("PLAYER1", false)
3.8.2 DiplomacyAISetPassive
void DiplomacyAISetPassive(playerAlias : string, passive : bool)
Set the diplomacy AI to passive. When passive the AI will not initiated trades but only respond to trades
offered to it
The alias of the player whose diplomacy AI will be changed
<param passive>:
40

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Whether the AI will be set to passive (true=passive)
3.8.3 DiplomacyAIEnabled
void DiplomacyAIEnabled( playerAlias : string )
enables the diplomatic AI for an AI player. this way the AI will react on offers and send them to other
players.
NOTE: AIpassive can still be disables and cause the AI to only react on offers
<return value>:
none
<param1 : string>:
The alias of the player to enable the AI of
3.8.4 DiplomacyAIDisabled
void DiplomacyAIDisabled( playerAlias : string )
Disables the diplomatic AI for an AI player. this way the AI will NOT react on offers and NOt send
them to other players.
<return value>:
none
<param1 : string>:
The alias of the player to disable the AI of
3.8.5 AISpellcastingLimit
void AISpellcastingLimit(playerAlias : string, limit : int)
Sets a limit to amount of mana the AI can spend per turn sustaining sustained spells like summons.
The alias of the player whos AI will be changed
<param limit>:
41

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Amount of mana that can be spent per turn, or -1 for no limit
3.8.6 AISetTargetBounty
void AISetTargetBounty(pEntityAlias : string, pBounty : int)
Sets a bounty (in gold) on a target - this influences the target priority of all AI players.
<param pEntityAlias>:
The entity alias of a structure / unit / pickup.
<param pBounty>:
Value in gold (0=none=default)
Note: AI only sees targets in a radius of ~5 turns from all its sources (units / structures)
3.8.7 AISetPlayerTargetBounty
void AISetPlayerTargetBounty(pPlayerAlias: string, pEntityAlias : string, pBounty : int)
Sets a bounty (in gold) on a target player - this influences the target priority of the AI Player with
pPlayerAlias.
<param pPlayerAlias>:
The entity alias of a player.
<param pEntityAlias>:
The entity alias of a structure / unit / pickup.
<param pBounty>:
Value in gold (0=none=default)
3.8.8 ToggleResources
void ToggleResources(playerAlias : string, enableGoldIncome: bool, enableManaIncome: bool,
enableResearch: bool, enableGrowth: bool)
42

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Toggles income enabled states on or off for a specific player

Note: enableResearch toggle is not implemented yet.
The alias of the player to toggle the AI for (the AI player)
<param enableGoldIncome>:
Determines if gold income needs to be enabled (=true) or disabled (=false) for a player
<param enableManaIncome>:
Determines if gold income needs to be enabled (=true) or disabled (=false) for a player
<param enableResearch>:
Determines if researching needs to be enabled (=true) or disabled (=false) for a player
<param enableGrowth>:
Determines if city growth needs to be enabled (=true) or disabled (=false) for a player
Example:
HexWorld:GetScriptingS():ToggleResources("PLAYER1", true, false, true, false )
HexWorld:GetScriptingS():ToggleResources("PLAYER1", true, false, false, false )
3.8.9 SetOffensiveAIEnabled
SetOffensiveAIEnabled("PlayerAlias", bool)
False will disable the offensive AI: AI troops will only defend and return to their cities.
True will enable the offensive AI (basically return it to normal after it has been toggled off).
3.8.10
AISetRazeEnabled
AISetRazeEnabled(playeralias, bool)
Toggles whether the AI is allowed to raze/plunder its own cities.
true means razing/plundering is allowed per normal AI routine
false means razing/plundering is not allowed
43

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
3.9
Camera
Camera controls what the player sees.
3.9.1 CenterCameraOnEntity
void CenterCameraOnEntity(playerAlias : string, entityAlias : string, exploreArea: bool, radius: int,
timeout: int)
Centers the Camera of the specified Player on the specified Entity
Important note: Only use this function based on user input in order for it to work correctly in
hotseat mode (for example in the OnButton embedded script of a story message).
The alias of the player to center the camera for.
<param entityAlias >:
The alias of the entity to center the camera on
<param exploreArea>:
If true the surrounding area of the entity will be revealed.
<param radius>:
The amount of hexes surrounding the entity to be revealed.
<param timeout>:
The time in ms the camera remains centered on the center entity before it goes back to its old
camera position
Example:
HexWorld:GetScriptingS():CenterCameraOnEntity("PLAYER1", "DRAGON", true, 2, 2000)
3.10
Spawn Group
Class used to spawn objects on the strategic world
44

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
3.10.1
SpawnGroupSpawnAtPosition
string SpawnGroupSpawnAtPosition(spawnGroupAlias : string, spawnPosition : HexPosition,

pDirection : string)
Spawns the spawn group with the specified alias facing a given direction.
<return value>:
The alias of the spawned stack.
<param spawnGroupAlias>:
The alias of the spawn group to spawn.
<param spawnPosition>:
The position to spawn the group at.
<param pDirection>:
The Direction of the group to face towards
NE, E, SE, SW, W, NW
3.11
Stack
A stack entity represents a collection of units on one hex on the strategic map.
3.11.1
StackGetPosition
HexPosition StackGetPosition(stackAlias : string)

Get the position of the stack.
<return value>:
The position of the stack. Returns NULL if it fails.
<param stackAlias>:
The alias of the stack to get the position from.
Example:
45

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
3.11.2
StackGetNumUnits
int StackGetNumUnits(stackAlias : string)

Get the number of units in a stack
<return value>:
The number of units in the stack. Returns -1 if the stack is invalid
<param stackAlias>:
The alias of the stack to get the number of units for
Example:
end
3.11.3
StackGetUnit
Unit StackGetUnit(stackAlias : string, unitIndex : int)

Get the unit in the stack with the specified index
<return value>:
The unit at the index. Returns NULL on failure
<param stackAlias>:
The alias of the stack to get the unit from
<param unitIndex>:
The index of the unit in the stack
Example:
46

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
end
3.11.4
StackJoinPlayer
int StackJoinPlayer(stackAlias : string, playerAlias : string)

Make the stack join the player.
<param stackAlias>:
The alias of the stack that will join the player.
The alias of the player that the stack will join.
Example:
HexWorld:GetScriptingS():StackJoinPlayer("STACKALIAS", "PLAYERALIAS")
3.11.5
StackGetPlayer
string StackGetPlayer(stackAlias : string)

Get the player that owns the stack
<return value>:
The alias of the player that owns the stack
<param stackAlias>:
The alias of the stack we want the know the player of
3.11.6
StackSetDirection
string StackSetDirection(pStackAlias : string, pDirection : string)

Set the facing direction of a stack
<param pStackAlias >:
The alias of the stack to change the direction of.
47

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
<param pDirection>:
The Direction of the group to face towards
NE, E, SE, SW, W, NW
3.12
StrategicWorld
A class that represents the strategic hex world.
3.12.1
StrategicWorldChangeOverlay
bool StrategicWorldChangeOverlay(position : LUAHMPos, radius : int, resourceID : string)

Change the overlay of the terrain.
<return value>:
True on success, false on failure.
<param position>:
The hex position which will be changed to the new overlay.
<param radius>:
The radius around the position that will be changed to the new overlay.
<param resourceID>:
The resourceID of the overlay that will be painted. Changes in resources can alter this id, so it
should be considered unsafe to use. For now the only way to obtain a resource id is to ask for it on the
games forums. The devs are the only ones who can look them up.
Example:
Change the terrain around the stack to wetlands. (#0000000105800063 is the resourceID of
wetlands here)
HexWorld:GetScriptingS():StrategicWorldChangeOverlay(stackPosition, 1, "#0000000105800063")
48

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
3.12.2
StrategicWorldChangeTheme
bool StrategicWorldChangeTheme(position : HexPosition, radius : int, resourceID : string)

Change the theme of the terrain.
<return value>:
True on succes, false on failure.
<param position>:
The hex position which will be changed to the new theme.
<param radius>:
The radius around the position that will be changed to the new theme. Radius of 0 changes only the
specified hex position.
<param resourceID>:
The resourceID of the theme that will be painted. Changes in resources can alter this id, so it should
be considered unsafe to use. For now the only way to obtain a resource id is to ask for it on the games
forums. The devs are the only ones who can look them up.
Example:
Change the terrain around the stack to artic. (#0000000105800063 is the resourceID of artic in
this case)
HexWorld:GetScriptingS():StrategicWorldChangeTheme(stackPosition, 1, "#0000000105800063")
3.12.3
StrategicWorldGetNumPlayers
int StrategicWorldGetNumPlayers()
Get the number of players in the world.
<return value>:
The number of players in the world.
49

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
3.12.4
StrategicWorldGetPlayerAlias
string StrategicWorldGetPlayerAlias(index : int)

Get the alias of a player by the player's index.
<return value>:
The alias of the player.
<param index>:
The index of the player.
3.13
Structure
A structure on the strategic map.

Events______________________________________________________
OnRazed
Called when the structure is razed.
OnRebuild
Called when the structure is rebuild. I.e. unrazed
OnChangeOwner(newPlayer : Player)
Called when the owning player of the structure changes.
3.13.1
StructureGetState
int StructureGetState(structureAlias : string)

Get the state of the structure.
<return value>:
The state of the structure as an int. See Structure States how structure states are mapped to ints.
<param structureAlias>:
The alias of the structure to set the state for.
Example:
Set the teleporter to active if its inactive
50

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
if HexWorld:GetScriptingS():StructureGetState("STRUCTUREALIAS") == 10 then
HexWorld:GetScriptingS():StructureSetState("STRUCTUREALIAS", 9)
end
3.13.2
StructureSetState
void StructureSetState(structureAlias : string, state : int)

Set the state of the structure.
The alias of the structure to set the state for.
<param state>:
The state to set for the structure. See Structure States how structure states are mapped to ints.
Example:
Set the teleporter to active if its inactive
if HexWorld:GetScriptingS():StructureGetState("STRUCTUREALIAS") == 10 then
HexWorld:GetScriptingS():StructureSetState("STRUCTUREALIAS", 9)
end
3.13.3
StructureGetOwner
string StructureGetOwner(structureAlias : string)

Get the owner of the structure.
<return value>:
The alias of the player owns the structure. Returns NULL on failure.
The alias of the structure to get the owner for.
51

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
3.13.4
StructureSetOwner
void StructureSetOwner(structureAlias : string, playerAlias : string)

Set the owner of the structure. Note this doesnt work if units are present on the structure. They will
need to be removed or change owner first.
The alias of the structure to set the owner for.
The alias of the player that will be the new owner.
Example:
HexWorld:GetScriptingS():StructureSetOwner("CITYALIAS", "PLAYER1")
3.14
Timer
A timer class which can be used to delay the execution of a script for a specified amount of rounds.
These timers can be created in LevelEd. On the right side on the 'Scripts' tab -> 'Timers' tab. The
number of rounds correspond to the rounds in game (i.e. round = 1 fires at the start of the game)
Events______________________________________________________
OnElapsed
Called when the timer has reached its specified number of rounds.
3.14.1
TimerStart
void TimerStart(timerAlias : string)

Start the timer.
<param timerAlias>:
The alias of the timer to start.
52

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
3.14.2
TimerStop
void TimerStop(timerAlias : string)

Stop the timer.
<param timerAlias>:
The alias of the timer to stop.
3.14.3
TimerReset
void TimerReset(timerAlias : string)

Reset the timer. Setting the number of rounds that have elapsed to zero.
<param timerAlias>:
The alias of the timer to reset.
3.15
Unit
A class that represents a unit which is contained in a stack

Events______________________________________________________
OnDeath
Triggers when the unit dies.
OnChangeOwner
Triggers when the owning player of the unit changes.
3.15.1
UnitHasRequisite
int UnitHasRequisite(unitAlias : string, requisite : UnitRequisite)

Check if the unit has the specified requisite.
<return value>:
True if the unit has the requisite, false otherwise.
<param unitAlias>:
The alias of the unit to check for the requisite.
<param requisite>:
53

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
The requisite to check for.
3.15.2
UnitKill
int UnitKill(unitAlias : string, resurrectable : bool, AnnihilateInventory : bool,

SuppressDeathAnimation : bool)
Kill the unit immediately.
<param unitAlias>:
The alias of the unit to kill.
<param resurrectable>:
Whether this unit should be ressurrectable (only valid for heroes)
<param AnnihilateInventory>:
If true than the items in the inventory are destroyed. if false the items are dropped
<param SuppressDeathAnimation>
If true then the unit will not play a death animation when it's removed from the world.
Example:
HexWorld:GetScriptingS():UnitKill("UNITALIAS", true, false, true)
3.15.3
UnitGetInventoryItem
Item UnitGetInventoryItem(unitAlias : string, inventorySlot : int)

Get an item from the units inventory.
<return value>:
The item in the inventory slot. Returns NULL if there is no item.
<param unitAlias>:
The alias of the unit whose inventory to get the item from.
<param inventorySlot>:
54

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
The index of the inventory slot to get the item from.

Index reference:
Example:
Print the the id of the item in the unit's head slot
local item = HexWorld:GetScriptingS():UnitGetInventoryItem("UNITALIAS", 3)
HexWorld:GetScriptingS():ItemHasTag(item, "OVERPOWERED"))
3.15.4
UnitGetStackAlias
string UnitGetStackAlias(pUnitAlias : string)

returns the alias of the stack which contains the unit
<return value>:
The alias of the stack as string.
If the unit or the stack does not exist the return value is NULL
<param pUnitAlias>:
The alias of the unit we want the stack alias from
3.15.5
UnitSetGroup
void UnitSetGroup(stackAlias : string, unitAlias : string)

55

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Adds the unit to an existing group. Note that groups should at most be 3 stacks and they should be
close together. Group behavior will break if members of 1 group are many and/or far apart.
<param stackAlias>:
The alias of the stack to get the strategic group from
<param unitAlias>:
The alias of the unit to add to the group
Example:
HexWorld:GetScriptingS():UnitSetGroup("STACKALIAS", "UNITALIAS")
3.15.6
UnitDropItem
void UnitDropItem(unitAlias : string, itemData : Item)

Drops the specified item from the specified Unit
<param unitAlias>:
The alias of the unit whose inventory to drop the item from.
<param itemData >:
The item that needs to be dropped
Example:
HexWorld:GetScriptingS():UnitDropItem("UNITALIAS", item)
3.15.7
UnitCannotDieInTC
int UnitCannotDieInTC(unitAlias : string)

Marks the named unit. If the unit dies in tactical combat, then the army of the controlling player will be
instantly killed. Should be used for heroes that have been marked with "XXX Must Survive!" quests
<param unitAlias>:
The alias of the unit to affect.
Example:
56

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
HexWorld:GetScriptingS():UnitCannotDieInTC("UNITALIAS")
4. Script Reference: Campaign & Data Access

4.1
Campaign
The following commands only function within campaign maps.

Methods____________________________________________________
CampaignUnlockScenario
Allows the player to play a new scenario in the campaign.
CampaignSaveUnit
Save a unit
CampaignSpawnSavedUnit
Spawn a saved unit by its save alias.
CampaignSpawnSavedUnitAsLeader
Spawn a saved hero unit as leader unit.
4.1.1 CampaignUnlockScenario
CampaignUnlockScenario(scenarioName : string)
Unlock the named scenario is the current campaign.
<param scenarioName>:
The name of the scenario to unlock. This is the name listed in the campaign editor, typically the
filename of the map without a file extension.
4.1.2 CampaignSaveUnit
void CampaignSaveUnit(unitAlias : string, saveAlias : string)
Save the specified unit in the campaign data so it can be used in other campaign scenarios.
<param unitAlias>:
The alias of the unit to save.
<param saveAlias>:
The name with which the unit will be save, this can be used to spawn the saved unit.
4.1.3 CampaignSpawnSavedUnit
string CampaignSpawnSavedUnit(saveAlias : string, playerAlias : string, position : HexPosition)
57

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Save the specified unit in the campaign data so it can be used in other campaign scenarios.
Note 1: Spawned units will NOT have the same alias as when they were saved. If you want to change
the alias of the spawned unit use SetAlias on the spawned unit that is returned by this function
<return value>:
The alias of the unit that is spawned. Returns NULL on failure.
<param saveAlias>:
The alias with which the unit was saved.
The alias of the player which will own the unit.
<param position>:
The position to spawn the unit.
4.1.4 CampaignSpawnAsLeader
string CampaignSpawnSavedUnitAsLeader(saveAlias : string, playerAlias : string)
Spawn a saved hero unit as a leader unit.
Do this ONLY on map startup (use a timer that triggers at the beginning of turn 1).
Note 1: Spawned units will NOT have the same alias as when they were saved. If you want to change
the alias of the spawned unit use SetAlias on the spawned unit that is returned by the function
Note 2: Unit will be spawned at the position of the current leader unit.
<return value>:
The alias of the unit that is spawned. Returns NULL on failure.
<param saveAlias>:
The alias with which the unit was saved.
<param pPlayerAlias>:
The player whose leader we are spawning.
4.2
Data Access
The following commands are used to read and write data which is saved when the game is saved.
58

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
Map Data
This data is stored in the current map, and should be used to store data relating to a players progress
through that map.
First data values must be created in the Data Store for the map, found under Map Settings in Level Ed.
Only previously created values can be used by these functions.
Methods____________________________________________________
GetMapBool
Retrieve a boolean value from the map data
SetMapBool
Set a boolean value in the map data
GetMapNumber
Retrieve a numeric value from the map data
SetMapNumber
Set a numeric value in the map data
GetMapString
Retrieve a numeric value from the map data
SetMapString
Set a numeric value in the map data
Campaign Data
This data is stored in the current campaign, and should be used to transmit information between
scenarios within a campaign.
First data values must be created in the Data Store for the campaign, found in the campaign settings in
the campaign editor in Level Ed. Only previously created values can be used by these functions.
Methods____________________________________________________
GetCampaignBool
Retrieve a boolean value from the campaign data
SetCampaignBool
Set a boolean value in the campaign data
GetCampaignNumber
Retrieve a numeric value from the campaign data
SetCampaignNumber
Set a numeric value in the campaign data
GetCampaignString
Retrieve a string value from the campaign data
SetCampaignString
Set a string value in the campaign data
4.2.1 GetMapBool
bool GetMapBool(valueName : string)
Retrieve the named boolean value from the map data store.
<param valueName>:
The name of the value to retrieve, must have been previously created in the map's data store.
59

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
4.2.2 SetMapBool
SetMapBool(valueName : string, newValue : bool)
Set the named boolean value in the map data store.
<param valueName>:
The name of the value to set, must have been previously created in the map's data store.
<param newValue>:
The bool to place into the data store value
4.2.3 GetMapNumber
float GetMapNumber(valueName : string)
Retrieve the named numeric value from the map data store.
<param valueName>:
4.2.4 SetMapNumber
SetMapNumber(valueName : string, newValue : float)
Set the named numeric value in the map data store.
<param valueName>:
<param newValue>:
The number to place into the data store value
4.2.5 GetMapString
string GetMapString(valueName : string)
Retrieve the named string value from the map data store.
<param valueName>:
60

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
4.2.6 SetMapString
SetMapString(valueName : string, newValue : string)
Set the named string value in the map data store.
<param valueName>:
<param newValue>:
The string to place into the data store value
4.2.7 GetCampaignBool
bool GetCampaignBool(valueName : string)
Retrieve the named boolean value from the campaign data store.
<param valueName>:
The name of the value to retrieve, must have been previously created in the campaign's data
4.2.8 SetCampaignBool
SetCampaignBool(valueName : string, newValue : bool)
Set the named boolean value in the campaign data store.
<param valueName>:
The name of the value to set, must have been previously created in the campaign's data store.
<param newValue>: true, false
The bool to place into the data store value
4.2.9 GetCampaignNumber
float GetCampaignNumber(valueName : string)
Retrieve the named numeric value from the campaign data store.
61

Phoenixstraat 66
2611 AM Delft
The Netherlands
Phone: + 31 15 2159902
Fax: + 31 15 2159952
<param valueName>:
4.2.10
SetCampaignNumber
SetCampaignNumber(valueName : string, newValue : float)

Set the named numeric value in the campaign data store.
<param valueName>:
<param newValue>:
The number to place into the data store value
4.2.11
GetCampaignString
string GetCampaignString(valueName : string)

Retrieve the named string value from the campaign data store.
<param valueName>:
4.2.12
SetCampaignString
SetCampaignString(valueName : string, newValue : string)

Set the named string value in the campaign data store.
<param valueName>:
<param newValue>:
The string to place into the data store value
62

Age of Wonders 3 Scripting Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Age of Wonders 3 Scripting Guide

Uploaded by

Copyright:

Available Formats

Triumph Studios B.V.

Level Editor Script Guide

Triumph Studios B.V.

Triumph Studios B.V.

Triumph Studios B.V.

Script Guide - Triumph Studios B.V.

Triumph Studios B.V.

Scripting Story Message Example

Script Guide - Triumph Studios B.V.

Triumph Studios B.V.

Script Guide - Triumph Studios B.V.

Triumph Studios B.V.

I click the New EventScript button and name my script

Now on the right side I see a number of events:

Triumph Studios B.V.

So now I need a script to send a message.

Script Guide - Triumph Studios B.V.

Triumph Studios B.V.

Then a part thats easy to forget!

Script Guide - Triumph Studios B.V.

Triumph Studios B.V.

Now I am going to test my script to see if it all works according to plan!

Triumph Studios B.V.

Spawning Units Example

To spawn units I need to make a Spawn Group.

Script Guide - Triumph Studios B.V.

Triumph Studios B.V.

Now I need to spawn the units when the treasure is taken.

Script Guide - Triumph Studios B.V.

Triumph Studios B.V.

Script Guide - Triumph Studios B.V.

Triumph Studios B.V.

Now its time to test again!

Script Guide - Triumph Studios B.V.

Triumph Studios B.V.

1.1 Scripts in LevelEd

1.1.1 Create script

Name your script

1.1.2 Attach script to hex entity

Script Guide - Triumph Studios B.V.

Triumph Studios B.V.

1.1.3 Responding to events

Drag an event to a script you have created

1.1.4 Embedded Scripts

In scripts the diplomatic state is indicated by an integer as shown in the list.

The city is absorbed by the player.

You should never script the diplomatic state to become unknown.

Triumph Studios B.V.

State when the structure doesn't have a (current) state.

Player Structures Only*

State when the structure is razed.

The city is under control of a player

The city is occupied. Not producing anything.

Treasure_Unexplored = 5 The treasure site is not yet explored by a player.

The treasure site is explored. A player has claimed its rewards.

Visit Structure Only

The visit structure is charged. When a stack moves onto it it will

The visit structure is charging. Benefit not available yet.

The teleporter is active and can be used to teleport from.

Teleporter_Inactive = 10 The teleporter is inactive. It cannot be used to teleport from. It can

In scripts the structure state is indicated by an integer as shown in the list.

Triumph Studios B.V.

1.4.1 Alias Tags

Suppose a structure with the alias 'MY_CITY'.