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

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

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

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

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 it’s time to add story scripting.

Let’s 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.

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 doesn’t exist anymore to reply, etc).

· With the Stack Area Trigger selected I click the Script button to open the Script Pool.

· I click the New EventScript button and name my script TreasureCommentScript. It’s 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:

· 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 stack’s 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;

Then a part that’s 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 there’s text in them, so if you forget this you cannot get rid of your story message!).

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

It works, but it would be kind of boring if that was the end of it!

Let’s say the treasure has been placed there for a powerful band of thieves by a nearby city, as a bribe so they won’t 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.

· 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 group’s 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 I’ll be using it for that I give it the alias ASSASSINSPAWNLOC.

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 who’s alias I filled in.

Since LUA doesn’t mind, I can actually substitute the hexPosition parameter by the script that finds it for me, so I don’t 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")

Now it’s 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!

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 doesn’t warn you about all the ways scripting may go wrong. It doesn’t always define when or how it’s safe to use the scripts. We also don’t guarantee it’s 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.

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 doesn’t contain text it’s 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.

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 The visit structure is charged. When a stack moves onto it it will receive the benefit.