official Map Editor Tutorial - Script Groups, Script Areas and Script Paths

[R4bitF00t]

Hello there!

Scripting groups, paths and areas are extremely useful when creating maps, I would even go as far as to say that they are necessary in most cases.

Now, it is time to see what these groups, areas and paths are all about.

 

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

 

• Content

• Script Groups
  • Creation in the Editor
  • Creation in the _scriptgroups.lua
• Script Areas
• Script Paths
• Next Chapter

 

• Script Groups

Let's start with the most important topic first.

Script groups do what their name implies.
They group individual tags under one, master tag.

If you learn one thing from this chapter, let it be how to create script groups. 

You can use script groups in scripts the same way as you would normal tags.
You can easily discern if a tag references a script group, because a script group's name starts with the prefix sg_.

Naming conventions for script groups follow the same rules as tagging entities, with the addition that the name of the script group must start with the sg_ prefix.
E.g. sg_fire_outpost_defenders.

 

There are two ways of creating script groups.

Through the editor, or through a script called _scriptgroups.lua.

I would suggest you pick one of these and stick with it, combining them is not ideal for clarity.

Let's look at both of them now.

 

• Creation in the Editor

Creating script groups in the editor is very simple and super quick.
In the beginning, this should be all you need.
But as time goes on, and you get more experience, you will find that doing the groups in the editor is very rigid and prevents you from using some advanced coding practices.

To create a script group in the editor, we need to open the Script Group Editor in Windows -> Script Group Editor.
We will also need the Entity Properties window.

 

We can create new script group by pressing the New button in the Script Group Editor. The group's properties will be shown in the Entity Properties window.
That is where you can rename the script group.

Let's name it sg_fire_spawn_defenders, this group will include our spawn_defenders from the previous chapter of the tutorial.
(Remember, we need to put sg_ prefix at the start of the group name!)

Now, we need to insert our spawn_defender1 and spawn_defender2 squads into the script group.

At the bottom of the Script Group Editor, there is a search bar, you can start typing the tags there and the editor will automatically offer you autocompletions.

Quote

Note: Typing into the Script Group Editor searchbar is very finicky. The editor will stop you after typing every letter, and you need to click into the searchbar again to type another letter.
It is best to just use the offered autocompletions.

When you get more used to this, and need to insert a lot of entities, just pick the first entity and then delete the last number with backspace, press arrow down to select the next entity and press enter to insert the next entity.
With a bit of practice, you will be able to insert a lot of entities into the script group quickly.

Select the spawn_defender1 in the offered list and press enter to insert it into the group.
Do the same for spawn_defender2.

There is also a very helpful feature, that will highlight tags that are not on the map in red.
This is very useful if you have decided to change the tags of entities, or delete them.

 

 

• Creation in the _scriptgroups.lua

Creating script groups in the _scriptgroups.lua is a bit trickier, it actually requires you to follow some strict formatting.
But in return, it gives you more flexibility when you need to adjust your script groups at runtime.

The good thing is, once you've set up one _scriptgroups.lua, you can just copy it into other maps.

 

To start defining our script groups, we first need to create _scriptgroups.lua, same as we would create any other script.
Create the script in the script1 folder.

Because of its complexity, I will give you an example _scriptgroups.lua, so you can fall back on it if anything goes wrong.

_scriptgroups.lua

The _scriptgroups file will return an array (think of an array as a list) of script groups to the game. Since the script groups themselves are arrays of tags, the _scriptgroups thus returns an array of arrays.

This is just to confuse you, now to the example.

We first need to declare a local empty array, we do that with

local array_name = { }

When we want to create a script group, we need to assign it to our local array. We do that by first typing the name of the local array, followed by a dot, then we name the script group and declare its contents (tags) between the curly brackets.

array_name.sg_example = {example_tag1, example_tag2, example_tag3}

At the bottom of the script, we just need to return our local array to the game with

return array_name

You can probably see that writing dozens of script groups, each of them containing up to dozens of tags, is not exactly fast.
Luckily, there is a function in Notepad++ that can make inserting tags easier, and that is Column Editor.

I will just direct you to official Notepad++ tutorial on how to use that functionality.

https://npp-user-manual.org/docs/editing/

I will cover creating difficulties in more detail in another tutorial.
For the moment, you have the example script that includes adding entities into a script group on expert difficulty.

 

• Script Areas

Script areas are mostly used to check if an entity is inside it, or not.

You can access script areas via Windows -> Scripting Tool.

   

You might need to check the View Scripting Areas checkbox to be able to see what you are doing.

To place a script area, click the Place Point button.
Then, click and drag to extend the area from point to point.

After the first two points are placed, you can extend the area by clicking and dragging a new point from anywhere along the line between two points. You can add as many points as you want to an area.

   

If you need to move the points, you can do that by clicking the Select button.

To remove the points, click Remove Point button and click on the points you want to delete.

To use the area in scripts, we need to tag it. We do that by using the Select mode, and double-clicking any of the points of an area. That will select the whole area, and give us the ability to tag the area through the Entity Properties window.

If we go back to our _main.lua script from previous chapter, we could change the TargetTag of the PlayerSquadIsInRange check.

With the area clearly defined, we don't need to measure or gauge the distance ourselves.

I have also changed the range to default, which seems to work best with script areas.
Like this.

 

 

• Script Paths

The Scripting Tool also houses our next guest - scripting paths.

You can place a script path the same way you do a script area, only with script paths, you extend the path by click-dragging a new point from the last point of the path.

Select a script path by using the Select mode and double-clicking any of the points of the path.

Scripting paths have some extra options in Entity Properties.

Here, we have:

• Continuous - makes the path continuous, meaning if you send units along that path, they will patrol it indefinitely.
• Travel in Reverse - reverses the direction in which you placed the points, making units start from the last point placed.

When you send units along the path, they will follow it as closely as possible.
The units will first start walking towards the first point of the path, and from that, they will continue to the next point and etc.
emember that units will walk to the first point placed, first.
If the path is continous, the units will patrol the path indefinitely.

Sending units on a script path uses a different action than SquadGoto.

To send a single squad along a path, use SquadCheckpointGoto action.
To send a group of units along a path, use SquadGroupCheckpointGoto action.

As stated, units sent on a script path will follow the path as closely as possible.

When sending a script group along a path with SquadGroupCheckpointGoto, the units will wait at each point of the path, until all the units from the group are present before continuing. This is extremely useful when sending attack waves.

 

• Next Chapter

This is the end of three, very imporant topics.
It wasn't as much fun as making units move around, but these three things are practically necessary for map creation.

Now, goals in BattleForge are a bit unwieldy to work with, I will tell you all about it in the next chapter.

 

• Creating Goals •

 

Edited Wednesday at 10:32 AM by R4bitF00t