How to make a level

From Open Surge Engine Wiki
Revision as of 13:38, 24 December 2021 by Alexandre (Talk | contribs) (Basic usage)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Getting started


This tutorial explains how to make a basic level using the built-in Level Editor. At the time of this writing, the latest version of the game is 0.5.1, but the topics covered here can be applied on newer versions as well.

This is a quick practical introduction to the built-in Level Editor. You'll be able to make your own level in just a few minutes, but only with basic features like simple platforms and items. Advanced topics like custom scenery, new characters, scripting and bosses will be covered later.

NOTE: when making a game with Open Surge, you should use its latest stable release, which can be found at Do not use the development builds, unless you're an advanced user and have a specific reason to do so.

Welcome to the Level Editor!

Level Files

Levels are plain text files with a few instructions written on it. They are .lev files stored in the levels/ folder¹.

To begin our tutorial, open file levels/empty.lev using a simple text editor like Notepad. You'll see something like this:

// ...

// header
name "Empty Level"
license "CC-BY 3.0"
version "1.0"
requires "0.5.0"
act 1
theme "themes/waterworks.brk"
bgtheme "themes/"
spawn_point 128 9920
music "musics/template.ogg"
setup "Default Setup"
players "Surge" "Neon"

// ...

Save a copy of the file to levels/hello.lev.

Additionally, change the name field from "Empty Level" to "Hello".

Windows users: if you're using Notepad, you must double quote the filename, so the program won't save your file as hello.lev.txt. You must type "hello.lev" instead of hello.lev. Make sure to save it to the levels/ folder!

An example: .lev files in the levels/ folder. Your actual setup may vary.

¹ Where is the levels/ folder? On Microsoft Windows, levels/ is stored in the game directory:

  • it's the same place where Open Surge (the executable) is located
  • open the game directory and find the levels/ folder there

On Linux, it may be (you can use any of these places):

  • in the game directory (if you installed opensurge somewhere inside your home)
  • in the installation directory (if you made a system-wide installation)
    • usually, this is /usr/share/games/opensurge/
    • this is a read-only directory! To save a new file, see below
  • in $XDG_DATA_HOME/opensurge2d/opensurge/ (this is read-write)
    • usually, this is ~/.local/share/opensurge2d/opensurge/
    • using Flatpak? find levels/ at ~/.var/app/org.opensurge2d.OpenSurge/data/opensurge2d/opensurge
    • using Snap? find levels/ at ~/snap/opensurge/current/.local/share/opensurge2d
      • note: other user-space files (e.g., settings & screenshots) are found at ~/snap/opensurge/current/.config/opensurge2d and ~/snap/opensurge/common/.cache/opensurge2d

On MacOSX, the folder can be found:

  • in the game bundle (inside Contents/Resources/)
  • in ~/Library/opensurge2d/opensurge/
  • you might also use the Unix installation folder (e.g., /usr/share/games/opensurge)

The Editor

Opening the Editor

Go to the Stage Selection screen (at the options menu) and choose the "Hello" level. After the level loads, press the F12 key to enter the level editor (remember to disable fullscreen, so you can easily follow this tutorial). If "Hello" doesn't show up in the list, check your .lev file. Please go back to the previous section and try again.

Tip: you can edit almost every level by pressing F12 during the game. If you're editing an official level (the levels that come with the game), please do *not* save your changes, as this operation is irreversible!

Main menu: selecting Options
Options screen: entering the Stage select
Stage select: choosing the Hello level

Basic usage

The editor basically works with two types of elements: bricks and entities. Basically a brick is a reusable scenario piece. An entity is something that you can put in your level, such as: a spring, a collectible or a baddie. Entities are created with SurgeScript (scripting for games; this is covered later).

To play with the Level Editor, use the mouse to place objects on the screen and the directional arrow keys to move the camera. Now, press 1 to open the brick palette or 2 to open the entity palette. Choose the item you want to place on the level and have fun!

Tip: press F1 to see a table containing all commands you need to make a level.

Tip: press Ctrl+S to save your level.

Note: when placing a brick on the level, you'll see many properties on the top bar of the editor (such as: type, behavior, size, etc.). These are covered in Bricksets.

Brick palette
Entity palette

Creating your level

Enjoy creating!

This is where creativity comes in. Now you should make your level by placing bricks and entities on the screen. When you're done, press Ctrl+S to save your level.

For tips on how to create amazing levels, read our Level Design Document.


You have created your first level! Level editing, however, is just the tip of the iceberg.

Open Surge is a full game engine that allows you to create many types of 2D games, including: platformers, shooting & racing games, arcades, and so on. You can really go wild with your creativity and build up anything. In order to continue your studies, go to Introduction to Modding.

If you have any questions, feel free to ask on the community forums.

A challenge

Open themes/ folder and look for files with the .bg extension. These are level Backgrounds that are ready to be used in Open Surge. Pick one of them and replace the bgtheme field of the levels/hello.lev file. See what happens!

Create amazing things!