Difference between revisions of "Map editor guide"

Globulation 2 includes a map editor which allows you to create custom maps and games for everyone to enjoy. The map editor is quite straightforward. There is, however, some obscure behaviours. They include:

• When clicking with the middle button on a team (the color square corresponding to the team), the team is toggled between an AI and a human. By default teams are AI. It doesn't change anything for multiplayer and custom games, but for campaigns, one team has to be set to humans.
• When deleting a team, all related buildings and units are destroyed.
• If terrain is set to water under a unit who can't swim, the unit is deleted.

Scripting Syntax

Globulation 2 includes a powerful scripting language called "SGSL" that lets map creators add features to their maps, to improve the gaming experience. SGSL is simple and has a very easy syntax. An SGSL script is nothing else than a list of lines which are executed sequentially. The power of SGSL is it's ability to execute several scripts at the same time. So there can be, for instance, two different ways to win the game, and both will be valid. This is known as multi-threaded-scripting (MTS).

SGSL is functional, that is, every keyword is a function. In order for the script to continue, each of the functions has to evaluate to true. The syntax is simple, math-like with "functionName(list arguments)" possible arguments can also be functions.

SGSL can be edited from the map editor. You can get to it by clicking on the script editing button in the right sidebar (directly below the "Quit" button). In the SGSL editor, the script can be saved to or loaded from external text files, allowing you to edit it in any word application such as WordPad.

Keywords

The possible keywords (functions) are:

show("text", lang)

Shows "text" until hide is reached. If lang is given, "text" is only displayed if lang is equal to the current language.

hide 

Hides the text displayed by show.

wait(condition)

Waits until condition is true. As a special case, specifying an integer waits that number of seconds (e.g. wait (300) makes the script execution wait for 300 seconds at this line), and specifying a numerical comparison waits until that comparison is true (e.g. wait(Inn(0,0) = 1) makes the script wait until there is exactly one level 1 inn being built.

space

Waits until the spacebar is pressed before executing any other part in the script.

not(function)

Negates the result of the function given as parameter.

isdead(player)

Returns true if the player "player" (designed by an integer) is dead (this is mostly useful in wait())

area("areaName", who)

Returns true if globules or structures of the players designed by the function who are in the area "areaName" (mostly useful with wait()). Valid values of who include:

1. enemy(player) enemies of player
2. ally(player) allies of player
3. an integer p player p

timer(time)

Starts a global timer. When it reaches 0, the game is won. The remaining time is shown on the screen.

alliance(player1, player2, level)

Changes alliance level between players player1 and player2 to level.

label("labelName")

Puts the marker "labelName" in the code to go back with jump.

Jump("labelName")

Jumps to the code labelled "labelName" by label.

setArea("name", x, y, r)

Defines an area with the name "name" at x, y and radius r on the map.

summonUnits("areaName", amount, type, level, player)

Creates an amount of globules of type type, controlled by the player at the position set by the area "areaName". The radius of the area is not important, but if there is no place to summon the globules, less or no globules will be summoned.

summonFlag("flagName", x, y, r, unitcount, team)

Creates a `WarFlag for the team with the given position x, y and radius r. The `WarFlag is set to require unitcount units.

destroyFlag("flagName")

Destroys a flag created by summonFlag

win(player)

loose(player)

Makes player win/lose the game (note the misspelling of the word lose).

story

Indicates the beginning of a new script to execute in parallel.

guiEnable(guiElement)

guiDisable(guiElement)

Enables/disables a GUI element. Be aware that only the GUI elements are disabled - AIs are still able to use the related functions. In campaigns with several missions, GUI elements are not re-enabled between missions, so you will should explicitly enable and disable GUI elements at the start of your scripts. Valid GUI elements are:

• AllianceScreen
• BuildingTab
• FlagTab
• TextStatTab
• GfxStatTab
• ExporationFlag
• WarFlag
• ClearingFlag
• ForbiddenFlag
• CancelFlag
• any variable (see below)

Conditions

The possible parameters for the function wait are:

any integer

The amount of seconds to wait (example: wait (300), makes the script execution wait for 300 seconds at this line).

The other conditions are functions returning true or false (true meaning that waiting is over / false meaning it will continue to wait):

not(function)

Negates the result of the function given as parameter.

isdead(player)

eturns true if the player "player" (designed by an integer) is dead.

area("areaName", who)

Returns true if globules or structures of the players designed by the function who are in the area "areaName". Who may be:

• enemy(player) enemies of player
• ally(player) allies of player
• an integer p player p

variable(...) comparison value

True when the comparison comparison is true between value and the result of the function variable. comparison can be: greater-than, less-than and equal to

Variables

variable(player, level); 

Returns the number of buildings (or globules, depending of the chosen "variable" function) belonging to the player player and which are of level level (levels are disregarded for globules). The "variable" functions are the following:

• Worker: Number of working globules.
• Explorer: Number of exploring globules.
• Warrior: Number of warrior globules.
• Swarm: Number of swarms.
• Inn: Number of inns.
• Hospital: Number of hospitals.
• Racetrack: Number of race tracks.
• Pool: Number of swimming pools.
• Camp: Number of training camps.
• School: Number of schools.
• Tower: Number of towers.
• Market: Number of markets.
• Wall: Number of walls.

Building levels are treated like this:

Example

Here is the script used in the map The Sand Square:

setArea("dest1",60,0,1)
setArea("dest0",31,0,1)

show("Get to the sand square in your apponents base.")
wait(10)
hide
story

wait(area("dest0",1))
loose(0)
story
wait(area("dest1",0))
loose(1)

Future changes

Scripting support in Globulation 2 is often discussed on the mailing list. Because we are currently focussing on stabilising the main tree for a 1.0 release, SGSL will remain in Globulation 2 for now, but in the long-term, it is very likely that we will replace it with a ready-made scripting language that could be hooked more deeply into the system. The exact choice of language is hotly debated, but the final decision won't be made until someone actually sits down to do the work - and will no doubt be decided on whatever their personal interest is.