Difference between revisions of "Level specification"

From Open Surge Engine Wiki
Jump to: navigation, search
m (object)
(43 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
== Introduction ==
 
== Introduction ==
  
This document contains the specification of the levels. You will not learn how to make a level here. Instead, this will present you all the documentation in order to teach you how levels work and how can you use them to make your own MODs.
+
This document presents the specification of level files (.lev). You will not learn how to make a level here. This will present you documentation that teaches you how Open Surge levels work and how can you use them to make your own games.
  
'''ATTENTION!''' If you want to learn how to make a level for Open Surge, follow this link: http://opensnc.sourceforge.net/forum/viewtopic.php?id=8
+
'''ATTENTION!''' If you just want to learn how to make a level, follow this link: [[How to make a level]]. Also read [[Level Design Document]] for tips on how to make great levels.
  
 
== Definition ==
 
== Definition ==
  
In Open Surge, a level is a scene. Usually, levels are playable; that is, they have a scenario and the player controls the heroes to clear it. This, however, is not a strict requirement: one may create a level that is actually a cutscene. Or perhaps a special menu. You decide.
+
In Open Surge, a level is a scene. Usually, levels are playable: they have scenery and the player controls the heroes. This, however, is not a strict requirement: one may create a level that is actually a cutscene. Or perhaps a special menu. Or a bonus level. You decide.
  
Levels are represented by .lev files that are stored in the '''levels/''' subdirectory, which stays inside the game folder. .lev files are human-readable, that is, you can open them with a simple text editor like Notepad, gedit, vim, etc. and you'll be able to figure out what information it holds.
+
Levels are represented by .lev files stored in the '''levels/''' subdirectory, which is located inside the game folder. Level files are human-readable. You may open them with a simple text editor such as: Notepad, gedit, vim, etc.
  
 
If you want to play in a specific level of your choice, open the game, go to the options screen and enter in the '''STAGE SELECT''' area. Alternatively, you can save some time by using the command line:
 
If you want to play in a specific level of your choice, open the game, go to the options screen and enter in the '''STAGE SELECT''' area. Alternatively, you can save some time by using the command line:
  
Under Linux,
+
Under Linux / OSX,
  
''alex@euler:~/opensurge$ ./opensurge --level levels/template.lev''
+
''./opensurge --level levels/template.lev''
  
 
Under Windows,
 
Under Windows,
Line 21: Line 21:
 
''opensurge.exe --level levels/template.lev''
 
''opensurge.exe --level levels/template.lev''
  
== Available entities ==
+
And here's a secret for the initiates: as soon as you run the engine, you'll see the Open Surge Engine splash screen. Press RIGHT 3 times to enter the ''developer mode''. From there, you'll be able to enter on any .lev file.
  
In order to simplify matters, we'll say that all levels are composed by three things (which we'll denominate '''entities'''):
+
== Level elements ==
* bricks
+
* built-in items
+
* custom objects
+
  
=== Bricks ===
+
=== Level objects ===
  
Bricks are entities that behave as static objects: they can be platforms, walls, decorative objects (like trees or plants), moveable platforms, breakable obstacles, etc. The amount of interaction bricks offer are limited compared to the other entity types, but they are essential to any playable level.
+
Levels objects are basically of two types:
 +
* bricks
 +
* entities
  
A detailed documentation about bricks can be found at: [[Bricksets]]
+
==== Bricks ====
  
=== Built-in items ===
+
Bricks are level objects that are static: they can be platforms, walls, decorative objects (like trees or plants), breakable walls, and so on.
  
Built-in items are "hard-coded" objects. These items are native to the engine. Examples of built-in items include: a life box, a checkpoint, a spring, spikes, etc. These objects allow no customization. The best you can do is to modify their sprites, but you should really use them the way they are.
+
A detailed documentation about bricks can be found at: [[Bricksets]].
  
=== Custom objects ===
+
==== Entities ====
  
This is by far the most interesting type of entity. Custom objects allow you to create pretty much anything your imagination tells you to - within the boundaries of the engine, of course. No, you can't create a last-generation MMORPG, but you can make pretty much anything "reasonable": different kinds of items, new enemies, bosses, cutscenes, special effects, simple intelligent CPU-controlled agents, non-playable-characters, menus, etc.
+
Entities are level objects created via scripting. You can create pretty much anything your imagination tells you to: new items, new enemies, bosses, CPU-controlled agents, non-playable-characters, etc.
  
Custom objects are created via [[Introduction to objects|scripting]].
+
To create new entities, [http://docs.opensurge2d.org learn SurgeScript].
  
=== Extended entities ===
+
=== Other elements ===
 
+
These are not really entities, but they are as essential as them to level / MOD making.
+
  
 
==== Backgrounds ====
 
==== Backgrounds ====
  
Be it playable or not, a level will always have a background. A background is some image that is displayed behind everything else. It could be some nice mountains in a far distance, a city with falling snow, or some nice moving texture for a menu screen.
+
A background is some image or animation that is displayed behind everything else. It could be some nice mountains in a far distance, a city with falling snow, or some nice moving texture for a menu screen.
  
Backgrounds have their own [[Backgrounds|specification]]
+
Backgrounds have their own [[Backgrounds|specification]].
  
 
==== Groups of objects ====
 
==== Groups of objects ====
  
In order to make level design simpler, we have invented the concept of groups of objects. You can pack up many entities together (bricks, built-in items and custom objects) and work with them in the level editor as if they were one.
+
In order to make level design simpler, we have invented the concept of groups of objects. You can pack up many level objects together and work with them in the level editor as if they were one.
  
Read more about groups of objects at http://opensnc.sourceforge.net/forum/viewtopic.php?id=241
+
Read more about groups of objects at [[Groups]].
 +
 
 +
=== Legacy elements ===
 +
 
 +
The elements below were used in legacy versions of the engine, such as 0.2.0. They are no longer used.
 +
 
 +
==== Built-in items ====
 +
 
 +
Built-in items are "hard-coded" objects. These items are native to the engine. Examples of built-in items include: a life box, a checkpoint, a spring, spikes, etc. These objects allow no customization. The best you can do is to modify their sprites, but you should really use them the way they are.
 +
 
 +
==== Custom objects ====
 +
 
 +
Custom objects allow you to create pretty much anything your imagination tells you to - within the boundaries of the engine, of course. No, you can't create a last-generation MMORPG, but you can make pretty much anything "reasonable": different kinds of items, new enemies, bosses, cutscenes, special effects, simple intelligent CPU-controlled agents, non-playable-characters, menus, etc.
 +
 
 +
Custom objects are created via [[Introduction to objects|scripting]].
  
 
== The built-in level editor ==
 
== The built-in level editor ==
Line 66: Line 77:
 
Nowadays the Open Surge Engine is much more customizable, and the built-in level editor has gained much power. However, it has retained its principles: it is still very simple to learn and to use.
 
Nowadays the Open Surge Engine is much more customizable, and the built-in level editor has gained much power. However, it has retained its principles: it is still very simple to learn and to use.
  
Whenever you're playing on any level, press F12 to activate/deactivate the editor. The Level Editor has its own series of tutorials, which you can find in the [http://opensnc.sourceforge.net/forum/viewforum.php?id=6 Tutorials] area of the community forums. You may start by [http://opensnc.sourceforge.net/forum/viewtopic.php?id=8 Lesson one].
+
Whenever you're playing on any level, press F12 to activate/deactivate the editor. See also: [[How to make a level]].
  
 
== Commands ==
 
== Commands ==
Line 84: Line 95:
 
  name "Sunshine Paradise"
 
  name "Sunshine Paradise"
  
==== act ====
+
==== author ====
  
'''Syntax:''' ''act number''
+
'''Syntax:''' ''author level_author''
  
 
'''Available since:''' 0.1.0
 
'''Available since:''' 0.1.0
  
Specifies the act number (usually 1, 2 or 3). This property only makes sense for playable levels. This only makes sense on playable levels. Example:
+
Name of the person/people who made the level.
  
  name "Sunshine Paradise Boss"
+
  author "Your name"
act 3
+
  
==== spawn_point ====
+
==== license ====
  
'''Syntax:''' ''spawn_point xpos ypos''
+
'''Syntax:''' ''license license_name''
  
'''Available since:''' 0.1.0
+
'''Available since:''' 0.5.0
  
(''xpos'', ''ypos'') denotes the initial position of the player. Both ''xpos'' and ''ypos'' must be non-negative integers. (0,0) is the top-left corner of the level. This only makes sense on playable levels. Example:
+
The license of the level file (.lev). You may pick any license you'd like. Examples: CC-BY-SA 3.0, CC-BY 3.0, CC-0 (public domain).
  
  spawn_point 40 5700
+
  license "CC-BY 3.0"
  
==== author ====
+
==== requires ====
  
'''Syntax:''' ''author level_author''
+
'''Syntax:''' ''requires engine_version''
  
 
'''Available since:''' 0.1.0
 
'''Available since:''' 0.1.0
  
Name of the person/people who made the level. This has no impact on gameplay.
+
Specifies the minimum engine version your user has to have in order to play the level. You should not specify this property yourself: once you save the level using the built-in editor, the engine will assume that ''engine_version'' is the engine version you use. This guarantees that any engine features you use will also be available to your target player. Example:
  
  author "Open Surge Team"
+
  requires "0.5.0"
  
==== version ====
+
==== act ====
  
'''Syntax:''' ''version level_version''
+
'''Syntax:''' ''act number''
  
 
'''Available since:''' 0.1.0
 
'''Available since:''' 0.1.0
  
Version of your level. Although this has no impact on gameplay, it may be relevant to the level designer.
+
Specifies the act number (usually 1, 2 or 3). This property, an optional one, only makes sense for playable levels. Example:
  
  version 1.0
+
  name "Sunshine Paradise Boss"
 +
act 3
  
==== requires ====
+
==== spawn_point ====
  
'''Syntax:''' ''requires engine_version''
+
'''Syntax:''' ''spawn_point xpos ypos''
  
 
'''Available since:''' 0.1.0
 
'''Available since:''' 0.1.0
  
Specifies the minimum engine version your user has to have in order to play the level. You should not specify this property yourself: once you save the level using the built-in editor, the engine will assume that ''engine_version'' is the engine version you use. This guarantees that any engine features you use will also be available to your target player. Example:
+
(''xpos'', ''ypos'') denotes the initial position of the player. Both ''xpos'' and ''ypos'' must be non-negative integers. (0,0) is the top-left corner of the level. This only makes sense on playable levels. Example:
  
  requires 0.2.0
+
  spawn_point 40 5700
  
 
==== readonly ====
 
==== readonly ====
Line 141: Line 152:
 
'''Available since:''' 0.1.0
 
'''Available since:''' 0.1.0
  
One should not specify this property. If the level is ''readonly'', then the user will not be able to access the level editor.
+
If the level is set to ''readonly'', the user will not be able to access the level editor.
 +
 
 +
readonly
  
 
=== Look and feel ===
 
=== Look and feel ===
Line 165: Line 178:
 
  bgtheme "themes/template.bg"
 
  bgtheme "themes/template.bg"
  
==== group ====
+
==== grouptheme ====
  
'''Syntax:''' ''group path_to_grp_file''
+
'''Syntax:''' ''grouptheme path_to_grp_file''
  
 
'''Available since:''' 0.1.3
 
'''Available since:''' 0.1.3
Line 173: Line 186:
 
Tells the engine which [[Groups|group collection]] to use in this level. Example:
 
Tells the engine which [[Groups|group collection]] to use in this level. Example:
  
  group "themes/template.grp"
+
  grouptheme "themes/template.grp"
  
 
==== music ====
 
==== music ====
Line 185: Line 198:
 
  music "musics/title.ogg"
 
  music "musics/title.ogg"
  
=== Entities ===
+
=== Setup & players ===
  
You should not worry about specifying the entities manually. Let the Level Editor take care of them for you.
+
==== setup ====
 +
 
 +
'''Syntax:''' ''setup object1 [object2 [object3 ... [objectN] ... ]]''
 +
 
 +
'''Available since:''' 0.5.0
 +
 
 +
The ''setup'' command takes one or more object names as parameters. It simply creates the objects specified in the list when the level loads. If no ''setup'' command is specified, then an object named '''Default Setup''' will be created by default.
 +
 
 +
The '''Default Setup''' object takes care of basic game elements such as: pause, quit, default camera and displaying the HUD (Heads-Up Display). Therefore, it should be specified in the setup list in most cases (unless you want to change these basic elements).
 +
 
 +
Examples:
 +
 
 +
1) create only the '''Default Setup''' object (the default)
 +
 
 +
setup "Default Setup"
 +
 
 +
2) create two setup objects
 +
 
 +
setup "Default Setup" "Example Setup"
 +
 
 +
'''Note:''' in version 0.2.0 of the engine, this command was available under the name ''startup''. Setup objects created with the legacy scripting system must specify the [[API Reference#always_active|always_active]] flag.
 +
 
 +
==== players ====
 +
 
 +
'''Syntax:''' ''players player1 [player2 [player3 ... [playerN] ... ]]''
 +
 
 +
'''Available since:''' 0.2.0
 +
 
 +
The ''players'' command takes one or more parameters. It will create the list of [[Characters|characters]] specified on the list. If no ''players'' command is specified, then Surge, Neon and Charge will be spawned by default.
 +
 
 +
Examples:
 +
 
 +
1) regular team-play with Surge, Neon and Charge
 +
 
 +
players "Surge" "Neon" "Charge"
 +
 
 +
2) a Surge-only level
 +
 
 +
players "Surge"
 +
 
 +
3) [http://en.wikipedia.org/wiki/Tux Tux the Penguin]
 +
 
 +
players "Tux"
 +
 
 +
4) no players
 +
 
 +
// None is a special character that does not move and does not appear in the screen
 +
players "None"
 +
 
 +
=== Level objects ===
 +
 
 +
You should not worry about specifying the level objects manually. Let the Level Editor take care of them for you.
  
 
==== brick ====
 
==== brick ====
  
'''Syntax:''' ''brick brick_id xpos ypos''
+
'''Syntax:''' ''brick brick_id xpos ypos [layer] [flip]''
  
 
'''Available since:''' 0.1.0
 
'''Available since:''' 0.1.0
  
Creates ''brick_id'' at the specified position. Example:
+
Creates brick ''brick_id'' at the specified position. Example:
  
 
  brick 101 6917 1316
 
  brick 101 6917 1316
  
==== item ====
+
If a [[layer]] is specified, the brick will appear in that layer (green or yellow):
  
'''Syntax:''' ''item builtin_item_id xpos ypos''
+
brick 101 6917 1316 green
 +
brick 221 7212 3281 yellow
  
'''Available since:''' 0.1.0
+
If flip is specified, the brick will be flipped. The possible values for flip are: noflip, hflip, vflip, vhflip.
  
Creates ''builtin_item_id'' at the specified position. Example:
+
brick 101 6917 1316 hflip
 +
brick 101 6917 1316 green hflip
  
item 0 3322 774
+
'''Note:''' the optional layer parameter is available since 0.2.0. The optional flip parameter, since 0.5.0.
  
==== object ====
+
==== entity ====
  
'''Syntax:''' ''object object_name xpos ypos''
+
'''Syntax:''' ''entity entity_name xpos ypos [entity_id]''
  
'''Available since:''' 0.1.4
+
'''Available since:''' 0.5.0
  
Creates ''object_name'' at the specified position. Note that this refers to custom objects (made via scripting), not to built-in items! Example:
+
Spawns the specified entity at world position (''xpos'', ''ypos''). Parameter ''entity_id'' is an optional hexadecimal code that is used to uniquely identify the entity in the level. Example:
  
  object "Basic Pipe System: Pipe Master" 831 2046
+
  entity "Collectible" 240 9936 "be647e181fcd7513"
  
Objects whose name start with a "." (examples: ''.hidden'', ''.secret'', ''.internal'') will not be available for selection in the built-in level editor. This is useful to make objects that are only supposed to be spawned by other objects.
+
=== Water ===
  
=== Misc ===
+
==== waterlevel ====
  
==== startup ====
+
'''Syntax:''' ''waterlevel ycoord''
  
'''Syntax:''' ''startup object1 [object2 [object3 ... [objectN] ... ]]''
+
'''Available since:''' 0.2.0
 +
 
 +
Specifies that there should be water at every point with y-coordinate greater or equal than ycoord. Example:
 +
 
 +
// at y-position 6410 and below, there is water
 +
waterlevel 6410
 +
 
 +
==== watercolor ====
 +
 
 +
'''Syntax:''' ''watercolor red green blue''
  
 
'''Available since:''' 0.2.0
 
'''Available since:''' 0.2.0
  
The ''startup'' command takes one or more object names as parameters. It simply creates right away the custom objects specified in its list of parameters at position (0,0), the top-left corner of the scene. If no ''startup'' command is specified, then an object named '''.default_startup''' will be spawned by default.
+
Specifies the color of the water, where 0 <= red, green, blue <= 255. Please see the [[Colors]] page for more information.
  
The '''.default_startup''' object takes care of commonly used game routines like: character switching, pause, quit game and HUD (Heads-Up Display), so it should be specified in your startup list, unless you have a very good reason not to do so.
+
Example:
  
The ''startup'' command is immensely useful to create custom user experiences. Examples:
+
// the water should start at y-coord 6410 and it must be green
 +
waterlevel 6410
 +
watercolor 0 128 0
  
1) just the default startup object
+
=== Legacy ===
  
startup ".default_startup"
+
The commands below were used in previous versions of the engine. '''You must no longer use them.''' They have been kept in this page for historical purposes.
  
2) we'll create two objects on startup: .default_startup and .follow_the_leader
+
==== item ====
  
  startup ".default_startup" ".follow_the_leader"
+
'''Syntax:''' ''item builtin_item_id xpos ypos''
 +
 
 +
'''Available since:''' 0.1.0
 +
 
 +
'''Deprecated since:''' 0.5.0
 +
 
 +
Creates ''builtin_item_id'' at the specified position. Example:
 +
 
 +
  item 0 3322 774
 +
 
 +
==== object ====
 +
 
 +
'''Syntax:''' ''object object_name xpos ypos''
 +
 
 +
'''Available since:''' 0.1.0 | 0.1.4
 +
 
 +
'''Deprecated since:''' 0.5.0
 +
 
 +
Creates ''object_name'' at the specified position. Note that this refers to custom objects (created with scripting), not to built-in items! Example:
 +
 
 +
object "Basic Pipe System: Pipe Master" 831 2046
 +
 
 +
Objects created with legacy scripting whose name start with a "." (examples: ''.hidden'', ''.secret'', ''.internal'') will not be available for selection in the built-in level editor. This is useful to make objects that are only supposed to be spawned by other objects.
 +
 
 +
'''Note:''' in versions prior to 0.1.4, this command was called ''enemy''.
  
 
==== dialogbox ====
 
==== dialogbox ====
Line 249: Line 350:
 
'''Available since:''' 0.1.0
 
'''Available since:''' 0.1.0
  
Whenever the player enters in the rectangle described by ''xpos'', ''ypos'', ''width'' and ''height'', the engine will show a dialog box with the given parameters: ''title'' and ''message''.
+
'''Deprecated since:''' 0.5.0
  
This command was widely used in the past when the engine was not very customizable, but now ''dialogbox'' has become obsolete. Nowadays, instead of using ''dialogbox'', you should make a custom object to display a message box.
+
Whenever the player enters in the rectangle described by ''xpos'', ''ypos'', ''width'' and ''height'', the engine will show a message box with the given parameters: ''title'' and ''message''. Example:
  
Example:
+
dialogbox 190 2400 200 200 "WELCOME" "Welcome to the Dark Forest, a place where everybody enters but nobody leaves."
  
dialogbox 190 2400 200 200 "WELCOME" "Welcome to the Black Forest, a place where everybody enters but nobody leaves."
+
'''Note:''' use an Event Trigger to display a message instead. Native message boxes are not as flexible as what you can do with scripting nowadays. With the dialogbox command, you can only create dialog boxes, but with Event Triggers you can do much more, due to the fact that they are more flexible.
  
 
[[Category:MODs]]
 
[[Category:MODs]]
 
[[Category:Level specification]]
 
[[Category:Level specification]]

Revision as of 01:32, 5 June 2021

Introduction

This document presents the specification of level files (.lev). You will not learn how to make a level here. This will present you documentation that teaches you how Open Surge levels work and how can you use them to make your own games.

ATTENTION! If you just want to learn how to make a level, follow this link: How to make a level. Also read Level Design Document for tips on how to make great levels.

Definition

In Open Surge, a level is a scene. Usually, levels are playable: they have scenery and the player controls the heroes. This, however, is not a strict requirement: one may create a level that is actually a cutscene. Or perhaps a special menu. Or a bonus level. You decide.

Levels are represented by .lev files stored in the levels/ subdirectory, which is located inside the game folder. Level files are human-readable. You may open them with a simple text editor such as: Notepad, gedit, vim, etc.

If you want to play in a specific level of your choice, open the game, go to the options screen and enter in the STAGE SELECT area. Alternatively, you can save some time by using the command line:

Under Linux / OSX,

./opensurge --level levels/template.lev

Under Windows,

opensurge.exe --level levels/template.lev

And here's a secret for the initiates: as soon as you run the engine, you'll see the Open Surge Engine splash screen. Press RIGHT 3 times to enter the developer mode. From there, you'll be able to enter on any .lev file.

Level elements

Level objects

Levels objects are basically of two types:

  • bricks
  • entities

Bricks

Bricks are level objects that are static: they can be platforms, walls, decorative objects (like trees or plants), breakable walls, and so on.

A detailed documentation about bricks can be found at: Bricksets.

Entities

Entities are level objects created via scripting. You can create pretty much anything your imagination tells you to: new items, new enemies, bosses, CPU-controlled agents, non-playable-characters, etc.

To create new entities, learn SurgeScript.

Other elements

Backgrounds

A background is some image or animation that is displayed behind everything else. It could be some nice mountains in a far distance, a city with falling snow, or some nice moving texture for a menu screen.

Backgrounds have their own specification.

Groups of objects

In order to make level design simpler, we have invented the concept of groups of objects. You can pack up many level objects together and work with them in the level editor as if they were one.

Read more about groups of objects at Groups.

Legacy elements

The elements below were used in legacy versions of the engine, such as 0.2.0. They are no longer used.

Built-in items

Built-in items are "hard-coded" objects. These items are native to the engine. Examples of built-in items include: a life box, a checkpoint, a spring, spikes, etc. These objects allow no customization. The best you can do is to modify their sprites, but you should really use them the way they are.

Custom objects

Custom objects allow you to create pretty much anything your imagination tells you to - within the boundaries of the engine, of course. No, you can't create a last-generation MMORPG, but you can make pretty much anything "reasonable": different kinds of items, new enemies, bosses, cutscenes, special effects, simple intelligent CPU-controlled agents, non-playable-characters, menus, etc.

Custom objects are created via scripting.

The built-in level editor

Level Editor: click to resize

The Open Surge Engine was not always very modifiable. In the beginning, the most you could do was to create simple levels using built-in features of the engine. The built-in level editor was used to make levels.

Nowadays the Open Surge Engine is much more customizable, and the built-in level editor has gained much power. However, it has retained its principles: it is still very simple to learn and to use.

Whenever you're playing on any level, press F12 to activate/deactivate the editor. See also: How to make a level.

Commands

As we have already said, levels are represented by .lev files stored in the levels/ folder. .lev files are human-readable, that is, you can open them with a simple text editor like Notepad and understand what is written.

General properties

name

Syntax: name name_of_the_level

Available since: 0.1.0

Specifies the name of your level. Example:

name "Sunshine Paradise"

author

Syntax: author level_author

Available since: 0.1.0

Name of the person/people who made the level.

author "Your name"

license

Syntax: license license_name

Available since: 0.5.0

The license of the level file (.lev). You may pick any license you'd like. Examples: CC-BY-SA 3.0, CC-BY 3.0, CC-0 (public domain).

license "CC-BY 3.0"

requires

Syntax: requires engine_version

Available since: 0.1.0

Specifies the minimum engine version your user has to have in order to play the level. You should not specify this property yourself: once you save the level using the built-in editor, the engine will assume that engine_version is the engine version you use. This guarantees that any engine features you use will also be available to your target player. Example:

requires "0.5.0"

act

Syntax: act number

Available since: 0.1.0

Specifies the act number (usually 1, 2 or 3). This property, an optional one, only makes sense for playable levels. Example:

name "Sunshine Paradise Boss"
act 3

spawn_point

Syntax: spawn_point xpos ypos

Available since: 0.1.0

(xpos, ypos) denotes the initial position of the player. Both xpos and ypos must be non-negative integers. (0,0) is the top-left corner of the level. This only makes sense on playable levels. Example:

spawn_point 40 5700

readonly

Syntax: readonly

Available since: 0.1.0

If the level is set to readonly, the user will not be able to access the level editor.

readonly

Look and feel

theme

Syntax: theme path_to_brk_file

Available since: 0.1.0

Tells the engine which brickset to use in this level. Example:

theme "themes/template.brk"

bgtheme

Syntax: bgtheme path_to_bg_file

Available since: 0.1.0

Tells the engine which background theme to use in this level. Example:

bgtheme "themes/template.bg"

grouptheme

Syntax: grouptheme path_to_grp_file

Available since: 0.1.3

Tells the engine which group collection to use in this level. Example:

grouptheme "themes/template.grp"

music

Syntax: music path_to_ogg_song

Available since: 0.1.2

This property is optional. If you specify it, the engine will play the specified song, looping it when it's over. Musics must be in the .ogg format. Example:

music "musics/title.ogg"

Setup & players

setup

Syntax: setup object1 [object2 [object3 ... [objectN] ... ]]

Available since: 0.5.0

The setup command takes one or more object names as parameters. It simply creates the objects specified in the list when the level loads. If no setup command is specified, then an object named Default Setup will be created by default.

The Default Setup object takes care of basic game elements such as: pause, quit, default camera and displaying the HUD (Heads-Up Display). Therefore, it should be specified in the setup list in most cases (unless you want to change these basic elements).

Examples:

1) create only the Default Setup object (the default)

setup "Default Setup"

2) create two setup objects

setup "Default Setup" "Example Setup"

Note: in version 0.2.0 of the engine, this command was available under the name startup. Setup objects created with the legacy scripting system must specify the always_active flag.

players

Syntax: players player1 [player2 [player3 ... [playerN] ... ]]

Available since: 0.2.0

The players command takes one or more parameters. It will create the list of characters specified on the list. If no players command is specified, then Surge, Neon and Charge will be spawned by default.

Examples:

1) regular team-play with Surge, Neon and Charge

players "Surge" "Neon" "Charge"

2) a Surge-only level

players "Surge"

3) Tux the Penguin

players "Tux"

4) no players

// None is a special character that does not move and does not appear in the screen
players "None"

Level objects

You should not worry about specifying the level objects manually. Let the Level Editor take care of them for you.

brick

Syntax: brick brick_id xpos ypos [layer] [flip]

Available since: 0.1.0

Creates brick brick_id at the specified position. Example:

brick 101 6917 1316

If a layer is specified, the brick will appear in that layer (green or yellow):

brick 101 6917 1316 green
brick 221 7212 3281 yellow

If flip is specified, the brick will be flipped. The possible values for flip are: noflip, hflip, vflip, vhflip.

brick 101 6917 1316 hflip
brick 101 6917 1316 green hflip

Note: the optional layer parameter is available since 0.2.0. The optional flip parameter, since 0.5.0.

entity

Syntax: entity entity_name xpos ypos [entity_id]

Available since: 0.5.0

Spawns the specified entity at world position (xpos, ypos). Parameter entity_id is an optional hexadecimal code that is used to uniquely identify the entity in the level. Example:

entity "Collectible" 240 9936 "be647e181fcd7513"

Water

waterlevel

Syntax: waterlevel ycoord

Available since: 0.2.0

Specifies that there should be water at every point with y-coordinate greater or equal than ycoord. Example:

// at y-position 6410 and below, there is water
waterlevel 6410

watercolor

Syntax: watercolor red green blue

Available since: 0.2.0

Specifies the color of the water, where 0 <= red, green, blue <= 255. Please see the Colors page for more information.

Example:

// the water should start at y-coord 6410 and it must be green
waterlevel 6410
watercolor 0 128 0

Legacy

The commands below were used in previous versions of the engine. You must no longer use them. They have been kept in this page for historical purposes.

item

Syntax: item builtin_item_id xpos ypos

Available since: 0.1.0

Deprecated since: 0.5.0

Creates builtin_item_id at the specified position. Example:

item 0 3322 774

object

Syntax: object object_name xpos ypos

Available since: 0.1.0 | 0.1.4

Deprecated since: 0.5.0

Creates object_name at the specified position. Note that this refers to custom objects (created with scripting), not to built-in items! Example:

object "Basic Pipe System: Pipe Master" 831 2046

Objects created with legacy scripting whose name start with a "." (examples: .hidden, .secret, .internal) will not be available for selection in the built-in level editor. This is useful to make objects that are only supposed to be spawned by other objects.

Note: in versions prior to 0.1.4, this command was called enemy.

dialogbox

Syntax: dialogbox xpos ypos width height title message

Available since: 0.1.0

Deprecated since: 0.5.0

Whenever the player enters in the rectangle described by xpos, ypos, width and height, the engine will show a message box with the given parameters: title and message. Example:

dialogbox 190 2400 200 200 "WELCOME" "Welcome to the Dark Forest, a place where everybody enters but nobody leaves."

Note: use an Event Trigger to display a message instead. Native message boxes are not as flexible as what you can do with scripting nowadays. With the dialogbox command, you can only create dialog boxes, but with Event Triggers you can do much more, due to the fact that they are more flexible.