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:
-- Getting the alias of the stack that entered the area trigger:
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).
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.
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!