official Map Editor Tutorial - Scripting Basic Events Part 2

[R4bitF00t]

Welcome back!
I hope you are properly refreshed and ready to get back into action.

We will look into further actions and conditions we will need to complete our scenario.

 

If you encounter any issues, don't hesitate to ask in Skylords Reborn Map Making Discord.

 

• Content

• Setting up the Scenario Pt.3
• Scripting Pt.3 - Ambush
• Setting up the Scenario Pt.4
• Scripting Pt.4 - Respawning
• Scripting Pt.5 - Victory and Loss
• Next Chapter

 

• Setting up the Scenario Pt.3

In the previous chapter, I mentioned a surprise to the south.
Since the southern path only has one Firesworn, I want to add a little ambush when the player approaches that location.

Put another marker near the southern cave and name it ambush_cave.

We will also want to set up the next waypoint for our Goldwagon, further to the east.
Tag it target_east.

 

 

• Scripting Pt.3 - Ambush

Let's return to the _main script once again.

Now, we need to script our cave ambush.
For that we need another OnOneTimeEvent. (See how much you can get done with the simplest things.)
And add PlayerSquadSpawn action to it.

Quote

Note: There is a difference between spawning and playing a card.
Spawning units pops them into existence without any delay or fanfare.
Playing the units as cards makes them spawn as if they were played out by a player - animation, effects and all.

There are several PlayerCard actions such as:

• PlayerCardBuildingFakePlay
• PlayerCardSquadFakePlay
• PlayerCardSpellFakePlay

These actions need a Card ID, not squad/building or spell ID!
Unfortunately, card IDs are not all publicly available, and you have to ask for them in the discord.

I want to spawn a Magma Spore - for that, I will need to know its ID.
Squad ID can be found in the editor, in entity properties as Database ID.
The actual ID starts with the first number after the initial number.

I filled in the TargetTag, Player, SquadId and amount into the PlayerSquadSpawn action, and I am ready for testing.

Quote

Note: The Amount is 1 by default, if I have left it there, the script would also work.

And our Magma Spore spawns as expected. (I have moved the cave location, so that the Spore aggroes to the approaching player units.)

Finishing the Goldwagon movement is simple, we just need a OnOneTimeEvent, with a very similar condition as the first two, that sends the Goldwagon to the target_east position.

 

• Setting up the Scenario Pt.4

In the east, I want to have an enemy base with respawning defenders. So we need to set it up.

Let's add a fire spawner building, and tag it fire_spawn.
You can use any building for this, including towers, but keep in mind that players are used to which buildings are the spawners.

I've placed a defensive tower and a squad of Sunstriders and a Wrecker to act as defenders of this fire outpost.

 

Now we need to tag our squads so we can respawn them.
You can either tag the units one by one manually, or you can select all the squads (Sunstriders and the Wrecker) and with both of them selected, tag them spawn_defender1 and hit enter.
The units will automatically be tagged as spawn_defender1 and spawn_defender2.
This is very useful, particularly with larger groups.

 

Last thing I want to do is create our final waypoint in the east and tag it target_finish.
Then, I added a Thunder Wagon to act as a final obstacle before the players can win the map.
I tagged him final_challenge.

Now we will look at how we can respawn the outpost defenders, and script the win and lose conditions for the map.

 

• Scripting Pt.4 - Respawning

Respawning units can be done in several ways.
The easiest and most correct way is through the OnRespawnEvent.

You might remember that I noted that the OnRespawnEvent is a special event. That is because it needs to be inside a script, that shares the name with a tagged entity or a script group on the map (I will explain script groups later).

So let's look into that.
On our map, we have two squads in the fire outpost - spawn_defender1 and spawn_defender2.

We need to create a script for each of them. Create a new text file in the script1 folder, and name the new file spawn_defender1.lua.

BattleForge automatically detects scripts that have the same name as a tagged entity on the map -> we have an entity tagged spawn_defender1 on the map, so we can create spawn_defender1.lua script and the game will automatically load it.
The game only loads some predetermined scripts that start with "_" - such as _main, _scriptgroups, _scriptlist and _spawngroups.
You can have a script that isn't named after a tagged entity, in that case, you need to declare it in _scriptlist.lua, which we will look at in future chapters.

Now, open the spawn_defender1.lua script, create a state in the script (name it whatever you want) and insert an OnRespawnEvent into that state via the snippets.

Now we need to adjust some parameters and declare a condition for the respawn.

• StartDespawned - determines if the units vanish at the start of the map, so they can be respawned at a later time
• TargetTag - position where the unit will respawn, "StartPos" means the unit will respawn at the position it was placed in the editor
• RespawnDelayMinutes - delay in minutes before the unit respawns after death
• RespawnDelaySeconds - delay in second before the unit respawns after death
• HealthPercent - with how much health the unit should respawn

We want our units to be at their positions at the start of the map, so we will set StartDespawned to false.

The units should respawn at the location of the fire spawner, so set the TargetTag to fire_spawn.

The respawn should take only a couple of seconds, so leave the RespawnDelayMinutes 0 and set RespawnDelaySeconds to 20.

We want the units to be respawned at full health, so leave HealthPercent as it is.

I will do some further cleanup to make the script more readable.
I have deleted the OnDeathActions block, as I don't need anything to happen when the unit dies.
I have also deleted the GotoState as it is not necessary.

Now, the unit will respawn every 20 seconds after it died.
We need to insert a condition, that only if the fire_spawn is still alive, the units should respawn, otherwise the units will respawn out of thin air. We declare such condition with BuildingIsAlive.

Now, we have explicitly written that the squad will respawn only if the fire_spawn building has not been destroyed.

Quote

Note: the For parameter in BuildingIsAlive is used in a lot of conditions.
It can be either ALL or ANY.

Let's say you have multiple buildings in a script group, and the spawning should stop only once ALL the buildings are destroyed.
We can reference the script group in the Tag, use For = "ALL" and the respawning will stop once ALL the buildings in the script group are destroyed.

Alternatively, using ANY says that from multiple tags, only ONE of them needs to fullfill the condition.
If we had For = "ANY" and we referenced multiple buildings, if only ONE of the buildings were destroyed, the squad would stop spawning.

Instead of creating a new script and writing all of this again, we can simply copy-paste the spawn_defender1.lua script, and rename it spawn_defender2.lua.
This way, we have easily set up the other squad to respawn as well.

 

• Scripting Pt.5 - Victory and Loss

There is only one last thing we need to script, and those are win and lose conditions.

First, we need to create a simple event, that will send the Goldwagon to the final target. We have done this a couple of times now.

Now let's do the lose condition.
Obviously, since we have an escort mission, we want the player to lose if enemies destroy the Goldwagon.
The players lose automatically if they lose all of their monuments, you don't need to script that.

For the Goldwagon, we use a simple condition EntityIsDead. This condition is found in the Conditions-Negated snippet library, as it is the negative of condition EntityIsAlive.
And game over is an action PlayerGameOver. You can ignore the TargetTag parameter.

Quote

Note: There are conditions for SquadIsAlive/Dead and BuildingIsAlive/Destroyed.
Since SquadIsAlive/Dead works only on squads, and BuildingIsAlive/Destroyed works only on buildings, it is usually best to use EntityIsAlive/Dead as that should work with any entity.

For the win condition, I want the players to win if the Goldwagon approaches the final marker AND the Thunder Wagon final_challenge has been killed.

When we want to check if a tagged entity is in range of other tagged entity, we use EntityIsInRange.
You can probably guess what is the condition for when the Thunder Wagon is dead.

To win the game, we need to declare an action PlayerGameWon.

Let's do something a little bit different.
Since winning the game instantly upon the completion of our objectives is a bit anticlimactic, we will set the victory on a delay.

We can do that with the OnOneTimeTimerEvent.
Set the delay to 5 seconds, and try to estimate where you need to put the conditions and the victory action.

Your event should look like this.

Spoiler

If you got it right, great!
If not, don't worry, I will explain.

When the TimerStartConditions are met, the event will start its timer and TimerStartActions will trigger. Since we want to win AFTER the timer is elapsed, we need to write our victory action into TimerElapsedActions, which get triggered when the timer elapses and if the TimerElapsedConditions are met.

 

Now, we just need to test everything in game and...

The fire outpost defenders respawn as expected.

And I was unable to best the Thunder Wagon guardian and lost my Goldwagon...
Only on my second try did I get a win.

The bright side is that, everything works!

 

• Next Chapter

This concludes scripting basic events!
With this knowledge, you should be able to create mechanically interesting, yet simple maps. Search through the available Actions and Conditions in the snippets or on the wiki. Try things out, experiment and soon you will be able to do amazing things in the editor.

In the next chapter, I will go over some very, very useful information on how to create and work with script groups, script areas and script paths.

 

• Script Groups, Script Areas and Script Paths •

 

Edited Wednesday at 10:31 AM by R4bitF00t