official Map Editor Tutorial - Script Introduction

[R4bitF00t]

Welcome to the scripting introduction.

Here, I will explain the basic principles of writing BattleForge scripts.

This part focuses a lot on explanation of script structure and rules, if you are not interested in this, and you prefer to learn by doing - skip to the next part of the tutorial HERE.

 

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

 

• Content

• Script Structure
  • States
  • Events
    • Conditions
    • Actions
  • Commas
• Next Chapter

 

• Script Structure

BattleForge uses LUA scripts to influence the map when playing.
These scripts are not pure Lua, they use a customized version of Lua called BattleForge Script (BF Script for short).

The name of the script can be whatever you choose, just follow these pointers.

• Use lower case letters
• Don't include spaces in the name
• Don't put any dots or special characters in the name
• File extension needs to be .lua

All the scripts for a map need to be located within the script1 folder.

Quote

Note: You can have up to 3 folders for scripts. These folders need to be named script1, script2 and script3.

You can use these for organizational purposes - separate different kinds of scripts into different folders.

BUT, the actual function of these folders is performance. BattleForge evaluates scripts at the speed of 10 ticks per second. But instead of checking all the conditions in every script each tick, it separates checking of the scripts per folder.
So scripts in:
script1 are evaluated every 1, 4, 7, etc. tick
script2 are evaluated every 2, 5, 8, etc. tick
script3 are evaluated every 3, 6, 9, etc. tick

For the most part, you can get away with putting all your scripts into one folder, I've never run into issues.
Unless you intend on having thousands of events active at any time - in that case, it would be prudent to split the scripts into different script folders.

To start off, I will provide you with an example script, so you can see what I am talking about.

example_script.lua

 

BattleForge scripts are state machines.
The machine (or script) contains one or more states, and can switch between the states, but only one state can be active at any time.
Think of it like a machine that can make either lollipops or baskets. The machine cannot make lollipops and baskets at the same time - you need to switch it from lollipop making state into basket making state, and vice versa.

Within these states, we have events.
Events are functions, that will execute actions once the conditions are met.

Take a while to look at the example script and try to identify the states, events, and where they begin and end.

 

• States

The states are the basic building blocks of scripts.

States don't do anything by themselves, but they are containers for events.

The state starts with { and ends with };
Everything between these brackets are the contents of the state.
An example:

State
{
            StateName = "Example State",

};

Every state needs a name - you should not include any dots or special characters, and the name should be unique to that script.
(You can have multiple scripts that contain a state of the same name, but you cannot have one script with multiple states with the same name.)
You declare the name between the state brackets with "StateName = "State name here",".

You need at least one state in each script, but you can have as many states as you want. Just be aware that, the more complex you make the script, the harder it will be to fix if something goes wrong.

The script will start in the first declared state in the script (the one at the top).
Functionally, the script can only be in one state at a time, so you will need to switch between states via events.

Remember:
Every state needs to have a unique name.
Only one state can be active at any time - meaning the script will evaluate events only from the active state.

Now this might have sounded a bit robotic, but the gist of it is, within your script, you need at least one state with a unique name, and you can put events that influence the map into that state.

State is the only part of the script, where you need to have a semicolon ( ; ) after the closing bracket.

 

• Events

The events are the workhorses of scripts. They control the behaviour of maps, for example: casting spells on Nightmare Shard, sending attack waves, respawning enemies, timers etc.

Similar to states, the events can be named.
Contrary to states, the name of the event doesn't matter - it is there so you can label the event, quickly explaining what it does.
You can have multiple events with the same name.

Same as states, the event's contents are declared inside the { and }; brackets.
Like this:

OnOneTimeEvent
{
           EventName = "Name here",

           Conditions =
           {
           }, 

           Actions =
           {
           }, 

           GotoState = "self", 
};

There are a number of different events you can use in your scripts, we will go into detail about them in the next part of the tutorial.
At the moment, the important thing is this.

All events have conditions and actions.
If the conditions are met, the actions will execute.

You might have already deduced what the GotoState parameter is for.
Once the conditions are met, the event will execute the actions and switch into the state declared in the GotoState. You need to write the name of the state exactly as you have declared it.

Note that not all events have the GotoState parameter.

The GotoState parameter is optional, you can delete it if you don't intend to switch states in that event.

Quote

Note: The GotoState = "self", means the event will switch to the state the script is currently in, meaning no state switching will occur, and the script will continue as if this line wasn't even there.

The events contain actions and conditions, let's look at them now.

 

Conditions

Condition is a line of code that returns either true, or false.

There are too many possible conditions to list here. The best way to find out what the conditions do, is simply by looking at their names and experimenting.

Condition can have one, or multiple parameters. Some are optional, some are not.

You can consult the scripting reference wiki for condition parameters and descriptions.

Conditions are written into condition blocks of events.
You can have multiple conditions inside a condition block - meaning that ALL the conditions written need to be true, for the event to execute its actions.
You can also have no conditions in a condition block - meaning the event's actions will be executed instantly, because no condition is preventing the execution.

 

Actions

Action is a line of code that determines what the event will do - spawn a squad, destroy a building, send out an attack wave etc.

There are too many possible actions to list here. The best way to find out what the actions do, is simply by looking at their names and experimenting.

Actions are written into action blocks of events.
Same as conditions, an action can have one, or multiple parameters.
Some of these can get pretty long.

You can consult the scripting reference wiki for action parameters and descriptions.

All the defined actions will get executed simultaneously when the conditions are met.

 

• Commas

Notice the commas ( , ) at the ends of most lines. These commas are not optional, they separate the different blocks of code from each other. You need to put a comma ( , ) or semicolon ( ; ) after every

• Closing bracket } of an event, action block, and condition block
• Parameter inside a condition or action
• Extra parameter - such as StateName, EventName, GotoState and others

You need to put a semicolon ( ; ) after the closing bracket } of every state.

Personally, I use commas inside an event, and semicolon after the closing bracket of an event.
Look at the example below (or any other examples), and notice where the commas and semicolons are written.

To reiterate, States are the only parts of the script, where you need to have a semicolon ( ; ) after the closing bracket.

Quote

Note: You can also make comments inside scripts by writing "--" at the start of a line. Comments will not be seen by the game, so they have only informative value for you, or any other person reading your scripts. You can also use comments to disable actions or conditions instead of deleting them. This way, you won't have to write the action or condition again, if you ever find you needed it.

 

 

• Next Chapter

This concludes the scripting theory. It was a bit boring, I know.

But in the next chapter, we will go over how we can create a fully functional script, and influence enemy squads placed on the map.

 

• Scripting Basic Events Part 1 •
 

Edited Wednesday at 10:31 AM by R4bitF00t