74
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 Script Guide - © Triumph Studios B.V. 1

Age of Wonders 3 Scripting Guide

Embed Size (px)

DESCRIPTION

Age of Wonders 3 Scripting Guide to help create scenarios!

Citation preview

Level Editor Script Guide5Scripting Examples:

5Scripting Story Message Example

11Spawning Units Example

151.Scripting Overview

151.1Scripts in LevelEd

151.1.1Create script

151.1.2Attach script to hex entity

161.1.3Responding to events

161.1.4Embedded Scripts

161.2Diplomatic States

171.3Structure States

181.4Alias

181.4.1Alias Tags

181.4.2Supported types

182.Script Reference: Common

182.1GetAlias

192.2SetAlias

192.3GetPosition

203.Script Reference: Classes

203.1City

203.1.1CityGetRace

213.1.2DestroyCityGuards

213.1.3CitySetDiplomaticState

213.1.4AICityBuilding

223.1.5CityGetDiplomaticState

223.2Item

223.2.1ItemHasTag

233.3Marker

233.3.1MarkerEnable

233.3.2MarkerDisable

243.4Player

243.4.1PlayerGetAlias

243.4.2PlayerGetLeaderAlias

253.4.3PlayerIsLeaderInVoid

253.4.4PlayerEnableResearch

253.4.5PlayerGetNumSustainedSpells

263.4.6PlayerGetSustainedSpell

263.4.7PlayerHasMetPlayer

273.4.8PlayerMeetsPlayer

273.4.9PlayerGetDiplomaticState

273.4.10PlayerSetDiplomaticState

293.4.11PlayerOpenCloseBorders

293.4.12PlayerSendMessage

293.4.13PlayerSendMessageWithSender

303.4.14PlayerKillLeader

303.4.15PlayerSetVictorious

313.4.16PlayerSetDefeated

313.4.17PlayerAddItem

323.4.18PlayerCastSpell

323.4.19PlayerIsTrespassingInDomain

333.4.20PlayerGetNumCities

333.4.21PlayerGetCity

343.4.22PlayerGetThroneCity

343.5Race

343.5.1RaceIsEliminated

353.6Unit Groups

353.6.1SetGroupHome

353.6.2SetGroupBehavior

353.6.3GetGroupBehavior

353.6.4DestroyGroup

363.7Quest

363.7.1PlayerOfferQuest

363.7.2PlayerOfferCityQuest

373.7.3PlayerForceQuest

373.7.4PlayerOfferSubQuest

383.7.5PlayerForceSubQuest

383.7.6PlayerCompleteQuest

393.7.7PlayerFailQuest

393.7.8PlayerIncreaseQuestCompletionCount

393.7.9PlayerDecreaseQuestCompletionCount

403.8AI

403.8.1ToggleAI

403.8.2DiplomacyAISetPassive

413.8.3DiplomacyAIEnabled

413.8.4DiplomacyAIDisabled

413.8.5AISpellcastingLimit

423.8.6AISetTargetBounty

423.8.7AISetPlayerTargetBounty

423.8.8ToggleResources

433.8.9SetOffensiveAIEnabled

433.8.10AISetRazeEnabled

443.9Camera

443.9.1CenterCameraOnEntity

443.10Spawn Group

453.10.1SpawnGroupSpawnAtPosition

453.11Stack

453.11.1StackGetPosition

463.11.2StackGetNumUnits

463.11.3StackGetUnit

473.11.4StackJoinPlayer

473.11.5StackGetPlayer

473.11.6StackSetDirection

483.12StrategicWorld

483.12.1StrategicWorldChangeOverlay

493.12.2StrategicWorldChangeTheme

493.12.3StrategicWorldGetNumPlayers

503.12.4StrategicWorldGetPlayerAlias

503.13Structure

503.13.1StructureGetState

513.13.2StructureSetState

513.13.3StructureGetOwner

523.13.4StructureSetOwner

523.14Timer

523.14.1TimerStart

533.14.2TimerStop

533.14.3TimerReset

533.15Unit

533.15.1UnitHasRequisite

543.15.2UnitKill

543.15.3UnitGetInventoryItem

553.15.4UnitGetStackAlias

553.15.5UnitSetGroup

563.15.6UnitDropItem

563.15.7UnitCannotDieInTC

574.Script Reference: Campaign & Data Access

574.1Campaign

574.1.1CampaignUnlockScenario

574.1.2CampaignSaveUnit

574.1.3CampaignSpawnSavedUnit

584.1.4CampaignSpawnAsLeader

584.2Data Access

594.2.1GetMapBool

604.2.2SetMapBool

604.2.3GetMapNumber

604.2.4SetMapNumber

604.2.5GetMapString

614.2.6SetMapString

614.2.7GetCampaignBool

614.2.8SetCampaignBool

614.2.9GetCampaignNumber

624.2.10SetCampaignNumber

624.2.11GetCampaignString

624.2.12SetCampaignString

Scripting Examples:Here follow a few examples to get you started:Scripting Story Message ExampleNo 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.

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.

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:

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;

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!).

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!

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.

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.

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")

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!

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 treeview1.1.2 Attach script to hex entityWhen 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 eventsEvents 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 createdNotice 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 = 4In 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. 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.

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 TagsIf 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:

The alias of the hex entity. Returns "INVALID" on failure:

The hex entity to get the alias forExample: Print the alias ofall 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.:

The alias of the entity to set the alias for.:

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.:

The position of the hex entity. Returns NULL on failure.:

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.

:

The race name of the city. Returns NULL on failure.:

The alias of the city to get the race name for.

3.1.2 DestroyCityGuards

void DestroyCityGuards(cityAlias : string)

Destroys all city guards that are defending a city.Note: Only works for independents.:

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)

:

The alias of the city who's state will be set.:

The alias of the player for who the relation with the city will be set.:

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:

The alias of the city to affect

false to prevent the AI queing production orders in the city3.1.5 CityGetDiplomaticState

int CityGetDiplomaticState(playerAlias : string, cityAlias : string)

Get the diplomatic state between a player and a city:

The diplomatic state between the player and the city. Returns -1 on failure. See diplomatic states how they are mapped to ints.:

The alias of the player in the relation.:

The alias of the city in the relation.Example:

local diplomaticState = HexWorld:GetScriptingS():CityGetDiplomaticState("PLAYER1", "CITY1")

3.2 Item

ItemClassAn class that represents a item that can be equiped by hero unitsEvents______________________________________________________OnPickUp Triggers when item is pickup by a unit.OnDrop Triggers when item is moved from the unit's inventory to an item sack3.2.1 ItemHasTag

bool ItemHasTag(item : Item, tags : string)

Returns whether the items has the tags that are specified.:

Returns true if the item has the tags.

:

The item to check for tags.:

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 TriggerOnStackEnters(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 cellOnStackLeaves(Stack) Called when a stack leaves the cell

Item Area TriggerOnItemEnters Called when an item enters the cellOnItemLeaves Called when an item leaves the cell3.3.1 MarkerEnable

int MarkerEnable(markerAlias : string)

Enable the marker.

:

The alias of the marker to enable3.3.2 MarkerDisable

int MarkerDisable(markerAlias : string)

Disable the marker.

:

The alias of the marker to disable.3.4 Player

A class that represents one of the playersEvents______________________________________________________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:

The alias of the 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).:

The alias of the leader unit.:

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:

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.:

The alias of the player whose skill will be enabled/disabled for research.:

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. :

Whether the specified skill should be enabled or disabled for research.

3.4.5 PlayerGetNumSustainedSpells

int PlayerGetNumSustainedSpells(playerAlias : string)

Get the number of spells the player is sustaining.:

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.

:

The sustained spell at the specified index. Returns NULL on failure.:

The alias of the player to get the sustained spells from.:

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).

Whether the two players have met.

:

The alias of a player.:

The alias of a player.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.:

The alias of a player.:

The alias of a player.

3.4.9 PlayerGetDiplomaticState

int PlayerGetDiplomaticState(player1Alias : string, player2Alias : string)

Get the diplomatic state between two players.:

The diplomatic state between the two players as an int. Returns -1 on failure. See diplomatic states how they are mapped to ints.:

The alias of one of the players in the relation.:

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)

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.:

The diplomatic state between the two players as an int. Returns -1 on failure. See diplomatic states how they are mapped to ints.

:

The alias of one of the players in the relation.:

The alias of one of the players in the relation.:

The diplomatic state the relation will be set to. See diplomatic states how they are mapped to ints.:

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)3.4.11 PlayerOpenCloseBorders

void PlayerOpenCloseBorders(domainOwner : string, playerToOpenCloseBordersFor : string, open : bool)

Open or close borders of the domain owner for the other player.:

The alias of the player who will open or close his borders.:

The alias of the player for who the borders will be closed or opened.:

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!:

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.Note: When sending a message from an area trigger make sure the area trigger is set to 'Cancel Movement'

:

The alias of the message that will be sent.:

The alias of the player the message will be send to.:

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.:

Whether this leader should be resurrectable.:

If true than the items in the inventory are destroyed. If false the items are dropped.:

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.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.:

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

:

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.

:

The alias of the player of whom the leader unit will receive the item

:

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 MapNote: 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:

The position at which the spell will be cast:

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)

Checks if any units of the player (trespassingPlayerAlias) are trespassing are trespassing in the domain of the other player (domainOwningPlayerAlias):

The alias of the player who is trespassing:

The alias of the player of which its domain is being trespassedExample:

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 citiesExample:

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:

The index of the city you want from this playerExample:

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:

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.1 RaceIsEliminated

bool RaceIsEliminated(raceName : string)

Check if a race is present on the mapIf there are no Cities or Settlers of a specific race, then this function returns trueNote: There is no difference between a race which never existed on the map and a race which was eliminated.

:

The RaceName of the Race, ex. "DRACONIAN".

Available Races: HIGHELF HUMAN ORC GOBLIN DWARF DRACONIANExample: 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.:

"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)

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.:

The alias of the quest to offer.:

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.:

The alias of the city offering the city quest.:

The alias of the quest to offer.Example:

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.:

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.:

The alias of the questheader to which the subquest will be attached (required to add subquest):

The alias of the quest to offer.:

Determines if it is a popup quest (= true) or a to-do quest (=false).Example:

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.:

The alias of the questheader the subquest will be attached to.:

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.:

The alias of the quest to complete.Example:

HexWorld:GetScriptingS():PlayerCompleteQuest("PLAYER1", "QUEST1")

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.:

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.:

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.:

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):

Determines if the AI needs to be enabled (=true) or disabled (=false) for a playerExample:

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:

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

:

none:

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.

:

none:

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:

Amount of mana that can be spent per turn, or -1 for no limit3.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.:

The entity alias of a structure / unit / pickup.:

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.:

The entity alias of a player.:

The entity alias of a structure / unit / pickup.:

Value in gold (0=none=default)

3.8.8 ToggleResources

void ToggleResources(playerAlias : string, enableGoldIncome: bool, enableManaIncome: bool, enableResearch: bool, enableGrowth: bool)

Toggles income enabled states on or off for a specific playerNote: enableResearch toggle is not implemented yet.:

The alias of the player to toggle the AI for (the AI player):

Determines if gold income needs to be enabled (=true) or disabled (=false) for a player:

Determines if gold income needs to be enabled (=true) or disabled (=false) for a player:

Determines if researching needs to be enabled (=true) or disabled (=false) for a player:

Determines if city growth needs to be enabled (=true) or disabled (=false) for a playerExample:

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 routinefalse means razing/plundering is not allowed

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 EntityImportant 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.:

The alias of the entity to center the camera on:

If true the surrounding area of the entity will be revealed.:

The amount of hexes surrounding the entity to be revealed.:

The time in ms the camera remains centered on the center entity before it goes back to its old camera positionExample:

HexWorld:GetScriptingS():CenterCameraOnEntity("PLAYER1", "DRAGON", true, 2, 2000)3.10 Spawn Group

Class used to spawn objects on the strategic world3.10.1 SpawnGroupSpawnAtPosition

string SpawnGroupSpawnAtPosition(spawnGroupAlias : string, spawnPosition : HexPosition, pDirection : string)

Spawns the spawn group with the specified alias facing a given direction.:

The alias of the spawned stack.:

The alias of the spawn group to spawn.:

The position to spawn the group at.:

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.:

The position of the stack. Returns NULL if it fails.:

The alias of the stack to get the position from.Example:

local stackPosition = HexWorld:GetScriptingS():StackGetPosition("stackAlias")3.11.2 StackGetNumUnits

int StackGetNumUnits(stackAlias : string)

Get the number of units in a stack:

The number of units in the stack. Returns -1 if the stack is invalid:

The alias of the stack to get the number of units forExample: 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

3.11.3 StackGetUnit

Unit StackGetUnit(stackAlias : string, unitIndex : int)

Get the unit in the stack with the specified index:

The unit at the index. Returns NULL on failure:

The alias of the stack to get the unit from:

The index of the unit in the stackExample: Print the alias ofall 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

3.11.4 StackJoinPlayer

int StackJoinPlayer(stackAlias : string, playerAlias : string)

Make the stack join the player.:

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:

The alias of the player that owns the stack:

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:

The alias of the stack to change the direction of.:

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.:

True on success, false on failure.:

The hex position which will be changed to the new overlay.:

The radius around the position that will be changed to the new overlay.:

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) local stackPosition = HexWorld:GetScriptingS():StackGetPosition("stackAlias") HexWorld:GetScriptingS():StrategicWorldChangeOverlay(stackPosition, 1, "#0000000105800063")

3.12.2 StrategicWorldChangeTheme

bool StrategicWorldChangeTheme(position : HexPosition, radius : int, resourceID : string)

Change the theme of the terrain.:

True on succes, false on failure.:

The hex position which will be changed to the new theme.:

The radius around the position that will be changed to the new theme. Radius of 0 changes only the specified hex position. :

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) local stackPosition = HexWorld:GetScriptingS():StackGetPosition("stackAlias") HexWorld:GetScriptingS():StrategicWorldChangeTheme(stackPosition, 1, "#0000000105800063")

3.12.3 StrategicWorldGetNumPlayers

int StrategicWorldGetNumPlayers()

Get the number of players in the world.:

The number of players in the world.

3.12.4 StrategicWorldGetPlayerAlias

string StrategicWorldGetPlayerAlias(index : int)

Get the alias of a player by the player's index.:

The alias of the player.:

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. unrazedOnChangeOwner(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.:

The state of the structure as an int. See Structure States how structure states are mapped to ints.:

The alias of the structure to set the state for. Example: Set the teleporter to active if its inactive 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.:

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.:

The alias of the player owns the structure. Returns NULL on failure.:

The alias of the structure to get the owner for.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.:

The alias of the timer to start.

3.14.2 TimerStop

void TimerStop(timerAlias : string)

Stop the timer.:

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.:

The alias of the timer to reset.3.15 Unit

A class that represents a unit which is contained in a stackEvents______________________________________________________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.

:

True if the unit has the requisite, false otherwise.

:

The alias of the unit to check for the requisite.:

The requisite to check for.3.15.2 UnitKill

int UnitKill(unitAlias : string, resurrectable : bool, AnnihilateInventory : bool, SuppressDeathAnimation : bool)

Kill the unit immediately.:

The alias of the unit to kill.:

Whether this unit should be ressurrectable (only valid for heroes):

If true than the items in the inventory are destroyed. if false the items are dropped

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.:

The item in the inventory slot. Returns NULL if there is no item.:

The alias of the unit whose inventory to get the item from.:

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:

The alias of the stack as string. If the unit or the stack does not exist the return value is NULL:

The alias of the unit we want the stack alias from

3.15.5 UnitSetGroup

void UnitSetGroup(stackAlias : string, unitAlias : string)

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.:

The alias of the stack to get the strategic group from:

The alias of the unit to add to the groupExample:

HexWorld:GetScriptingS():UnitSetGroup("STACKALIAS", "UNITALIAS")

3.15.6 UnitDropItem

void UnitDropItem(unitAlias : string, itemData : Item)

Drops the specified item from the specified Unit:

The alias of the unit whose inventory to drop the item from.:

The item that needs to be droppedExample:

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:

The alias of the unit to affect.Example:

HexWorld:GetScriptingS():UnitCannotDieInTC("UNITALIAS")

4. Script Reference: Campaign & Data Access4.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 unitCampaignSpawnSavedUnit

Spawn a saved unit by its save alias.CampaignSpawnSavedUnitAsLeaderSpawn a saved hero unit as leader unit.4.1.1 CampaignUnlockScenario

CampaignUnlockScenario(scenarioName : string)

Unlock the named scenario is the current campaign.:

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.:

The alias of the unit to save.:

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)

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:

The alias of the unit that is spawned. Returns NULL on failure.:

The alias with which the unit was saved.:

The alias of the player which will own the unit.:

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 functionNote 2: Unit will be spawned at the position of the current leader unit.

:

The alias of the unit that is spawned. Returns NULL on failure.:

The alias with which the unit was saved.:

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. Map DataThis 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 dataSetMapBool

Set a boolean value in the map data GetMapNumber

Retrieve a numeric value from the map dataSetMapNumber

Set a numeric value in the map dataGetMapStringRetrieve a numeric value from the map dataSetMapString

Set a numeric value in the map data

Campaign DataThis 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 dataSetCampaignBool

Set a boolean value in the campaign dataGetCampaignNumber

Retrieve a numeric value from the campaign data SetCampaignNumber

Set a numeric value in the campaign data GetCampaignStringRetrieve a string value from the campaign dataSetCampaignString 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.: The name of the value to retrieve, must have been previously created in the map's data store.4.2.2 SetMapBool

SetMapBool(valueName : string, newValue : bool)

Set the named boolean value in the map data store.: The name of the value to set, must have been previously created in the map's data store.

: The bool to place into the data store value4.2.3 GetMapNumber

float GetMapNumber(valueName : string)

Retrieve the named numeric value from the map data store.: The name of the value to retrieve, must have been previously created in the map's data store.4.2.4 SetMapNumber

SetMapNumber(valueName : string, newValue : float)

Set the named numeric value in the map data store.: The name of the value to set, must have been previously created in the map's data store.

: The number to place into the data store value4.2.5 GetMapString

string GetMapString(valueName : string)

Retrieve the named string value from the map data store.: The name of the value to retrieve, must have been previously created in the map's data store.

4.2.6 SetMapString

SetMapString(valueName : string, newValue : string)

Set the named string value in the map data store.: The name of the value to set, must have been previously created in the map's data store.

: 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.: 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.: The name of the value to set, must have been previously created in the campaign's data store.

: 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.: The name of the value to retrieve, must have been previously created in the campaign's data

4.2.10 SetCampaignNumber

SetCampaignNumber(valueName : string, newValue : float)

Set the named numeric value in the campaign data store.: The name of the value to set, must have been previously created in the campaign's data store.

: 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.: The name of the value to retrieve, must have been previously created in the campaign's data

4.2.12 SetCampaignString

SetCampaignString(valueName : string, newValue : string)

Set the named string value in the campaign data store.: The name of the value to set, must have been previously created in the campaign's data store.

: The string to place into the data store valuePAGE 22Script Guide - Triumph Studios B.V.