Level specification
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.
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
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.
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.
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,
alex@euler:~/opensurge$ ./opensurge --level levels/template.lev
Under Windows,
opensurge.exe --level levels/template.lev
Available entities
In order to simplify matters, we'll say that all levels are composed by three things (which we'll denominate entities):
- bricks
- built-in items
- custom objects
Bricks
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.
A detailed documentation about bricks can be found at: Bricksets
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
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.
Custom objects are created via scripting.
Extended entities
These are not really entities, but they are as essential as them to level / MOD making.
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.
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 entities together (bricks, built-in items and custom objects) 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
The built-in level editor
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. The Level Editor has its own series of tutorials, which you can find in the Tutorials area of the community forums. You may start by Lesson one.
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"
act
Syntax: act number
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 "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
author
Syntax: author level_author
Available since: 0.1.0
Name of the person/people who made the level. This has no impact on gameplay.
author "Open Surge Team"
version
Syntax: version level_version
Available since: 0.1.0
Version of your level. Although this has no impact on gameplay, it may be relevant to the level designer.
version 1.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.2.0
readonly
Syntax: readonly
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.
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"
group
Syntax: group path_to_grp_file
Available since: 0.1.3
Tells the engine which group collection to use in this level. Example:
group "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"
Entities
You should not worry about specifying the entities manually. Let the Level Editor take care of them for you.
brick
Syntax: brick brick_id xpos ypos
Available since: 0.1.0
Creates brick_id at the specified position. Example:
brick 101 6917 1316
item
Syntax: item builtin_item_id xpos ypos
Available since: 0.1.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.4
Creates object_name at the specified position. Note that this refers to custom objects (made via scripting), not to built-in items! Example:
object "Basic Pipe System: Pipe Master" 831 2046
Objects whose name start with a "." (example: .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.
Misc
startup
Syntax: startup object1 [object2 [object3 ... [objectN] ... ]]
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.
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.
The startup command is immensely useful to create custom user experiences. Examples:
1) just the default startup object
startup ".default_startup"
2) we'll create two objects on startup: .default_startup and .follow_the_leader
startup ".default_startup" ".follow_the_leader"
dialogbox
Syntax: dialogbox xpos ypos width height title message
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.
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.
Example:
dialogbox 190 2400 200 200 "WELCOME" "Welcome to the Black Forest, a place where everybody enters but nobody leaves."