Triumph Studios B.V.
2611 AM Delft
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.2 Diplomatic States 16
1.3 Structure States 17
1.4 Alias 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
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:
-- 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:
-- Sending a stroy message (sender alias in message needs to be SPEAKER):
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!