official Map Editor Tutorial - Scripting Basic Events Part 1

[R4bitF00t]

The time has finally come!

Now, we are ready to get to the meat and bones of map making - scripting.
Here, we will learn by example and create a very tiny scenario to ease you into creating your own scripts.

To create LUA scripts, we will need the ability to edit file extensions, if you don't know how to do that - see File Extensions chapter in the Script Editors tutorial.

From this topic on, I will presume that you have read, or are familiar with the previously covered topics in this tutorial.

 

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

 

• Content

• Creating the Map
• Setting up the Scenario Pt.1
• Creating _main Script
• Scripting Pt.1 - Intro Outcry
• Setting up the Scenario Pt.2
• Scripting Pt.2 - Moving the Goldwagon
• Next Chapter

 

• Creating the Map

To start off, we will need to create a map.
I will be creating a PVE 1P map, but feel free to deviate.

• Decide on map size
• Set up the teams and player kits
• Place and assign starting position and monument to each player
• Don't forget about power wells

Then save the map, and update the map description.
I've named my map "Map Editor Tutorial".

Now we have a playable PVE map.

 

 

• Setting up the Scenario Pt.1

I've decided I want to make an escort mission (yay!).

There will be a Goldwagon near the player's starting monument. The goldwagon must reach safety in the east.
Depending on which way the player will choose, the goldwagon will follow his decision.

This is what my layout looks like.

For this scenario, I will not be designing the map past T2.

Since the Goldwagon needs to be friendly towards the player, hostile towards the enemy, but not under player's direct control, I've added a new player to tm_Team1 and created and assigned a new player kit to him.

Then, add a Goldwagon near the starting monument and add some fire enemies to every path.
I've added two Rageclaws and two Gladiatrix to the north, and one Firesworn to the south. (I will explain why later.)
Assign all the fire enemies to the pk_enemy1 and tm_Enemy1 so we see them as enemies in the game. (Don't forget to assign the correct team and player kit to the Goldwagon.)
I also want to have a little surprise in the south, so I've added a cave.

(Image rotated for better clarity)

Now that we have the starting challenges in place, we can create the first script.

 

• Creating _main Script

Every map needs to have a _main.lua script.
We will need to create it ourselves.

If you navigate to your map folder, you will notice we have no script folder, so we will need to create that, too.

Create a folder and name it "script1".

Then open that folder and create a new text file.

Rename the file to _main.lua and confirm.

Quote

Note: BattleForge automatically loads only certain kinds of scripts.
These scripts are:

• _main.lua
• _scriptgroups.lua
• _spawngroups.lua
• _globalvars.lua
• _scriptlist.lua
• scripts named after a tagged entity or a script group

You can also create scripts that don't adhere to this list - such as a script named main_boss_behaviour.lua.
These scripts need to be manually defined in the _scriptlist.lua file, which we will talk about in a later chapter.

Here is a list of scripts we will create by the end of next chapter.

spawn_defender2.luaspawn_defender1.lua_main.lua

 

Now we are ready to start scripting.

 

• Scripting Pt.1 - Intro Outcry

Let's open our _main.lua script.
It is harrowingly empty at the moment.

But we can quickly fix that with snippets!

Under BF-Events+State+Outcries, you will find the State snippet.

When you double-click it in the list, it will create a State for us, like this.

Since the StateName cannot be empty, let's name the state INIT, for example.

Let's save the script, PAK the map and try playing it - remember, we will find the map in the Community Maps node of the world map.

If everything is set up correctly, and you didn't make any typos in the script, you will be able to start the map.

Great!
Now that we've checked that everything is working, we can get around to the _main script actually doing something.

In the same snippet library that we have the State, we have all the types of events available to us.
Let's add an OnOneTimeEvent.

OnOneTimeEvent is the most basic event available.
This event will only trigger once, as soon as its conditions are met.

Quote

Note: I strongly encourage you to read through all the snippets, or through the Script Information Wiki HERE. You will get a better idea what is possible, and some of the possibilities might inspire you to create unique map mechanics.
There are also too many Actions and Conditions to go over them in detail in this tutorial.

Now, I want to have an outcry at the start of the map, telling us what we need to do.
For that, we will need to search for MissionOutcry in BF-Actions library and insert it into the action block of our event.

Set the text to something like "Get the Goldwagon to safety in the east!" and set the DurationSeconds to about 5 seconds.
(Notice I've deleted the GotoState as I don't need it for this event.)

Be sure to follow the correct formatting or the script will not work, or the game will crash.

Quote

Note: The snippet libraries are split into logical chunks. Actions go into action blocks of events, conditions and conditions-negated go into conditions blocks of events.

Be sure never to put conditions into action blocks, or actions into conditions blocks - this leads to a game crash without returning an error.

With our introductory OnOneTimeEvent set up, we can save the script, save and PAK the map, and return to the game to test out our outcry.
For the future, I will assume you have saved the script, map and PAKed it after every change we do.

This is the general workflow of scripting.

• Make changes to scripts
• Save the scripts
• Save the map
• PAK the map
• Test the changes in-game
• Close the game and repeat
   

Quote

Note: You cannot PAK a map while the game is running, close the game before PAKing.

And everything is working, great!

Before we continue, I will give you a list of most commonly used events.

• OnOneTimeEvent - triggers only one time, once the conditions are met.
   
• OnIntervalEvent - evaluates the conditions every X seconds, and if the conditions are met, triggers the actions every time.
   
• OnEvent - evaluates the conditions every tick, and if the conditions are met, triggers the actions every time
  use carefully as it will spam the actions several times per second
   
• OnOneTimeTimerEvent - once the conditions are met, triggers the TimerStartActions and starts a timer, upon expiration of said timer, it will evaluate the conditions in TimerElapsedConditions, if the conditions are met, triggers the TimerElapsedActions - works only one time
   
• OnTimerEvent - very similar to OnOneTimeTimerEvent, with the exception that once the event's timer expires, the actions will be spammed as long as the TimerElapsedConditions are true
  The event's timer cannot be reset
   
• OnToggleEvent - this event activates when the OnConditions are met, in that case it will trigger the OnActions
  Once the event is turned on, it will wait for the OffConditions to be met  to trigger the OffActions
  The event will switch between on and off state and trigger the on and off actions every time the conditions are met
   
• OnRespawnEvent - this is a special event, used to respawn killed entities. It can only be used in scripts named after tagged entities or script groups - we will look at this in detail a bit later

 

• Setting up the Scenario Pt.2

Now, let's set everything up so we can make our Goldwagon move.

Almost every action and condition in BattleForge needs a target - be it a location on the map, or an entity.
We label these important targets with tags.

I want the Goldwagon to move south if my units move south, and for it to move north if my units move north.
Once I've picked a direction, I don't want the Goldwagon to turn back and go the other way.

Since we will need to somehow check where our units are, and where to send the Goldwagon to, we will need an object with a tag.
We could place a small stone at the target area, tag it and use that as our target, but for these purposes, the game has special objects called Scriptmarkers - these are visible in the editor, but invisible in the game.
You will find them in the Objects category in Entity Placement.

Let's place one Scriptmarker Target near the fire units to the north, and one near the Firesworn in the south.
Which Scriptmarker you use, or if you decide to use any other object instead, doesn't matter. Using the correct Scriptmarkers only makes the map more organized.

Now, we will need to tag the Scriptmarkers - tag the one in the north target_north and the one in the south target_south.

   

Remember the tag naming convention!

• Use only lower-case letters
• No spaces or special characters
• Don't use the tag "default"
• Tag things in english - you might not be the only one working on the map

Next, we will tag our Goldwagon - goldwagon, we need to tag it, otherwise we are unable to give it commands or reference it in scripts.

Now, save the map and let's do something with these markers.

 

• Scripting Pt.2 - Moving the Goldwagon

Return to our _main script.

We need to create some single fire events, that will send our Goldwagon one way, or the other, based on some conditions.
OnOneTimeEvents will be best fitted for this situation.

First, I don't want the Goldwagon to go the other direction, once it has chosen its path. We can do that with a simple MapFlag.
Map flags are one of the most useful conditions, and are the simplest to understand.

Map flags can either be true, or false. Every map flag you declare automatically starts as false and we will use that to our advantage.

Now, we have declared one condition for our events. Right now, both of these events would trigger at the start of the game (Because the map flag starts out as false), and nothing would happen, because our Action blocks are empty.

So let's add an action to both events, that will set the map flag to true.
With this, once we have triggered one of these events, the other event will not trigger because of our MapFlagIsFalse condition.

Quote

Note: Values, Flags and Timers come in several different types - Map, Entity, Player and Network.

Map variables are accessible from any script in your map, any script can check them in its conditions.
(MapFlag,MapTimer,MapValue)

Entity variables are accessible only from the script in which they are declared. If you set an EntityFlag in _main script, you will not be able to check it in the conditions of other scripts.
(EntityFlag,EntityTimer,EntityValue)

Network and Player flags, values, and timers are not generally used.

We will need further conditions and actions to complete our events.

First, I will add a SquadGoto action to both events, the Tag parameter references a squad you want to move, TargetTag parameter references the target location.

Then, we will need a condition to check if the player's units are near one of the targets.
I have used TeamSquadIsInRange to check for squads of a given team. I have chosen the check range so that the Goldwagon (which is also set to tm_Team1, remember) doesn't trigger the events.

Since we have only one human player on the map, more appropriate condition would be PlayerSquadIsInRange - this checks for squads of a given player, regardless of their team. With this, we don't need to take the Goldwagon into consideration when going to the checkpoint.

Quote

IMPORTANT NOTE: When having only one player on the map, using PlayerSquadIsInRange works as intended.
HOWEVER, with multiple players, you also need to combine it with the condition PlayerIsHuman - this condition checks if a player is playing the map.
You need to add this condition because, when a player is not playing (such as he disconnected, or you started the map with an empty player slot), the game evaluates him as being everywhere on the map - hence he would trigger all PlayerSquadIsInRange checks.

I am only presenting you the different options you can choose, but the final choice is yours. Depending on how you set up the teams, distances between the targets and starting location, TeamSquadIsInRange might be more suitable for you, especially if you have multiple human players in the same team.

Let's save and PAK everything, and try our script in-game.
And indeed, the Goldwagon will go the way we choose first, and if we move our units to the other side, it will not turn back, excellent!

 

• Next Chapter

This is the end of the first part of basic events. Go grab a snack, something to drink and have a little break. When you're ready, continue to the second part of the tutorial.

 

 

• Scripting Basic Events Part 2 •
 

Edited Wednesday at 10:31 AM by R4bitF00t