level specification
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.
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:
| Platform | Command |
|---|---|
| Linux / macOS | ./opensurge --level levels/template.lev |
| 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.
Levels objects are basically of two types:
- bricks
- entities
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 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.
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.
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.
The elements below were used in legacy versions of the engine, such as 0.2.0. They are no longer used.
Built-in items were "hard-coded" objects. They were native to the engine. Examples of built-in items include: a life box, a checkpoint, a spring, spikes, etc. These objects allowed no customization. The best you could do was to modify their sprites.
Legacy objects allowed you to create pretty much anything your imagination told you to - within the boundaries of the engine, of course. No, you couldn't create a last-generation MMORPG, but you could make different kinds of items, new enemies, bosses, cutscenes, special effects, simple intelligent CPU-controlled agents, non-playable-characters, menus, and so on.
Custom objects were created via legacy scripting. This modality of scripting is no longer used.
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.
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.
Syntax: name name_of_the_level
Since: 0.1.0
Specifies the name of your level. Example:
name "Sunshine Paradise"
Syntax: author level_author
Since: 0.1.0
Name of the person/people who made the level.
author "Your name"
Syntax: license license_name
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"
Syntax: requires engine_version
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"
Syntax: act number
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
Syntax: spawn_point xpos ypos
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
Syntax: readonly
Since: 0.1.0
If the level is set to readonly, the user will not be able to access the level editor.
readonly
Syntax: theme path_to_brk_file
Since: 0.1.0
Tells the engine which brickset to use in this level. Example:
theme "themes/template.brk"
Syntax: bgtheme path_to_bg_file
Since: 0.1.0
Tells the engine which background theme to use in this level. Example:
bgtheme "themes/template.bg"
Syntax: music path_to_ogg_song
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"
Syntax: setup object1 [object2 [object3 ... [objectN] ... ]]
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:
- create only the Default Setup object (the default)
setup "Default Setup"
- 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 legacy always_active flag.
Syntax: players player1 [player2 [player3 ... [playerN] ... ]]
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:
- regular team-play with Surge, Neon and Charge
players "Surge" "Neon" "Charge"
- a Surge-only level
players "Surge"
- Tux the Penguin
players "Tux"
- no players
// None is a special character that does not move and does not appear in the screen
players "None"
You should not worry about specifying the level objects manually. Let the Level Editor take care of them for you.
Syntax: brick brick_id xpos ypos [layer] [flip]
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.
Syntax: entity entity_name xpos ypos [entity_id]
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"
Syntax: waterlevel ycoord
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
Syntax: watercolor red green blue [alpha]
Since: 0.2.0
Specifies the color of the water, where 0 <= red, green, blue, alpha <= 255.
Note
Property alpha is available since Open Surge 0.6.0. It's used to control the opacity of the water: 255 means fully opaque and 0 means fully transparent. It's an optional property. If left unspecified, value 128 is used by default.
Example:
// the water should start at y-coord 6410 and it must be green
waterlevel 6410
watercolor 0 192 0
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.
Syntax: item builtin_item_id xpos ypos
Since: 0.1.0
Deprecated since: 0.5.0
Creates the built-in item whose ID is builtin_item_id at the specified position. Example:
item 0 3322 774
Syntax: object object_name xpos ypos
Since: 0.1.0 | 0.1.4
Deprecated since: 0.5.0
Creates the object whose name is 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.
Syntax: grouptheme path_to_grp_file
Since: 0.1.3
Deprecated since: 0.5.0
Tells the engine which group collection to use in this level. Example:
grouptheme "themes/template.grp"
Syntax: dialogbox xpos ypos width height title message
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."
Tip
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.