A level header, also called a map header, is a type of SOC block that defines a map's metadata, such as its name, act number, background music, background sky, and various other settings. Level headers can be stored either as a separate lump in the same WAD file as the map, or as an entry in the WAD file's
MAINCFG lump. When storing a level header as a separate lump, the lump name must be
MAPxxD, where xx is the double-digit map number, e.g.
This level header gives Greenflower Zone Act 1 its characteristics:
Level 1 Levelname = GREENFLOWER Act = 1 MusicSlot = 1 TypeOfLevel = Singleplayer,Co-op,Competition,Race NextLevel = 2 SkyNum = 1 RecordAttack = true LevelSelect = 1
The following is a list of all parameters that can be set in a level header. Not all of these have to be specified; if a parameter is left out, it will revert to its default value. However, at least the parameters
SkyNum should always be set, to ensure that the level works correctly. Note that overriding a level header that already exists in SRB2 will cause the entire header to be reset, so if you want to change only one parameter, you will have to repeat the rest of the original header as well.
As with all SOC entries, the capitalization of text does not matter and is purely a convention. For example,
Levelname will all have the same effect. The parameters can be listed in any order.
This statement begins the block. n is the map number. Leading zeros are not required. So, if you want to set the properties of
MAP09, you would write
LEVEL 09 or just
LEVEL 9. You may use either the two-digit extended map numbers or convert them to integer numbers. For example,
MAPA1 can be represented with either
LEVEL A1 or
This sets the act number, which is displayed along with the level name. The available numbers range from 1 to 19, all other numbers will report an error on the console and place no act number in the title card. If you do not want an act number to be displayed, set this parameter to 0.
Act = 0
Specifies which bonuses are added to the player's score at the end of the level.
Normal is used for regular levels, and awards a bonus for time and rings, as well as an additional perfect bonus if the player collected all rings.
Boss is used for boss levels, and will award a ring bonus, as well as a guard bonus for avoiding hits.
ERZ3 is used by Egg Rock Zone Act 3, and awards a ring bonus, a guard bonus and a perfect bonus.
None awards no bonuses at all. The default value is
BonusType = Boss
Specifies the time, in seconds, that the player has to complete the level. If this time expires, the player will receive a Time Over and lose a life, much like in the classic Sonic games. The default value is 0, which disables the time limit.
Countdown = 600
Specifies the number of a cutscene to display after the level. Set to 0 to disable.
CutsceneNum = 1
Specifies the name of a character that players are forced to use in the level. This is only enforced at the beginning of the level, and players can change the skin at any time afterwards. In netgames, the server or an admin can still change the character everyone is forced to use. Note that skin numbers (including 255/-1) do not work in place of skin names here, unlike in previous versions of SRB2.
ForceCharacter = Sonic
Sets the scores that need to be reached for each rank in NiGHTS levels. Six values should be entered, separated by commas. These stand for, in order: E rank, D rank, C rank, B rank, A rank, rainbow A rank.
Grades = 45000,70000,90000,100000,125000,200000
If set to
true, the level will not appear in the list of maps presented when creating a server. The default value is
false. Useful for secret maps.
Hidden = true
If set to
true, the level will not appear in the Statistics screen. The default value is
HideInStats = true
Specifies the lump name of the image to draw as the background in the intermission screen (that is, the 'level complete' screen in Single Player and Coop, and the score screen in Match, Tag, and CTF.) This allows custom images to be used as the background.
InterScreen = INTERSCRW
For each parameters that should be set to
true, add its value to the
LevelFlags = 22(
The name of the level that appears in the title card, level select, and other places. SRB2 will automatically add "Zone" to the end of the name, unless the
NoZone parameter is set to
true. The name is limited to 21 characters, everything after that is cut off.
LevelName = Green Hill
LevelSelect = 1
For each parameters that should be set to
true, add its value to the
MenuFlags = 13(
- See also: MusicSlot
This sets the music that is used in the level. You can either use the music supplied in SRB2 itself or supply your own custom music by storing it in a lump
O_MAPxxM, with xx being the MusicSlot number. After that, set the
MusicSlot for the level to the same number. Note that MusicSlots use the same abridging system for slots above 100.
MusicSlot = A9
Subsong to play. Only really relevant for music modules and specific formats supported by GME. 0 to ignore.
This sets the level that follows after this one ends. Both extended map numbers and integers are accepted. Keep in mind that no leading zeros are necessary. For example, if you want the next level to be
MAP02, specify 2.
The following values have special meanings:
- 1100 takes you to the title screen.
- 1101 takes you to the evaluation screen (the one which shows you which secrets have you unlocked, how many emeralds you have collected, etc.). Single Player/Coop only.
- 1102 ends the game, taking you to the credits.
NextLevel = 2
If set to
true, the level is accessible in NiGHTS Mode. The default value is
NightsAttack = true
When set to
true, the level will not reset when a player dies. So, for example, collectible items will not reappear and linedef executors will not be reset. This is useful for switches, for instance. Mystic Realm, in particular, uses this parameter. The default value is
NoReload = true
If set to
true, this will prevent the Super Sonic music from playing when it would otherwise. Super Sneakers music is also suppressed. The default value is
NoSSMusic = true
If set to
true, the level will accessible in Record Attack/NiGHTS Mode without having visited the level before. The default value is
NoVisitNeeded = true
If set to
true, "Zone" is not added to the level's name. The default value is
NoZone = true
Sets the number of laps for Circuit maps.
NumLaps = 4
This changes the palettes used for the map, affecting all flats, textures and sprites. The available numbers range from 0 to 10000. If set to 1, the map loads a lump called
PAL0000 instead of
CLM0000 instead of
COLORMAP. If set to 10000, the map uses
COLORMAP. 0 is undefined, and 10001 and above sets the map to use the default
Palette = 2, which would load the lumps
Specifies the number of a cutscene to display before the level. Set to 0 to disable.
PreCutsceneNum = 1
RecordAttack = true
Specifies the lump name of a SOC to run on level load. The SOC must be a lump inside the WAD file.
RunSOC = EGGEXTRA
ScriptName. Specifies whether the script name is the name of an external file to load (
true) or the name of a lump in the WAD file (
ScriptIsFile = true
ScriptName = SCRIPT01
Specifies the scale at which the skybox (if one exists in the map) moves with the player. 0 stands for no movement, X stands for X:1 fast movement (the skybox moves faster than the player), -X stands for 1:X slow movement (the skybox moves slower than the player), where X is an integer number. 1 and -1 both stand for equal movement.
SkyboxScale = -4, which makes the skybox move at 1/4th of the player's movement
Specifies the scale at which the skybox's X axis moves with the player, independent of the movement of the other axes. The values have the same meaning as for SkyboxScale.
SkyboxScaleX = 0, which makes the skybox's X axis stand still
Specifies the scale at which the skybox's Y axis moves with the player, independent of the movement of the other axes. The values have the same meaning as for SkyboxScale.
SkyboxScaleY = 2, which makes the skybox's Y axis move twice as fast as the player
Specifies the scale at which the skybox's Z axis moves with the player, independent of the movement of the other axes. The values have the same meaning as for SkyboxScale.
SkyboxScaleZ = 1, which makes the skybox's Z axis move as fast as the player
- See also: Flats and textures/Skies
Specifies the number of the sky that is used in the level. The game searches for a texture with the name
SKYx, where x is the integer number specified. If no such texture is found,
REDWALL will be displayed as the sky picture instead. If
SkyNum is not set, the sky with the corresponding integer number to the level number will be used, if it exists.
SkyNum = 7
SpeedMusic = true
Adds a second, smaller title to the title card that is displayed at the start of the level. The subtitle is limited to 32 characters, everything after that is cut off. Unlike most other fields, this field is capitalization-sensitive.
SubTitle = Super Level 1
This sets the gametype(s) that the level can be played under. For each supported gametype, add one of the corresponding identifiers to the
TypeOfLevel value. Separate different gametypes by comma. 2D mode, Mario mode, NiGHTS, ERZ3 mode and Christmas NiGHTS do not work on their own and must be combined with other gametypes.
|Single Player||Solo, SP, Singleplayer, Single|
|Capture the Flag||CTF|
|Custom (Lua-scripted etc.)||Custom|
|Christmas NiGHTS||Xmas, Christmas, Winter|
TypeOfLevel = Singleplayer,Co-op,Competition,Race
Specifies the number of an unlockable that has to be unlocked to play this level. Set to 0 to disable. The numbers of SRB2's unlockables are as follows:
|1||Record Attack||Complete Greenflower Zone Act 1|
|2||NiGHTS Mode||Complete Floral Field|
|3||Play Credits||Complete 1P Mode|
|4||Sound Test||Complete 1P Mode|
|5||Header (not an actual unlockable)||N/A|
|6||Aerial Garden Zone||Complete 1P Mode with all emeralds|
|7||Azure Temple Zone||Complete Aerial Garden Zone|
|8||Header (not an actual unlockable)||N/A|
|9||SRB1 Remake||Collect 20 Emblems|
|10||Mario Koopa Blast||Collect 60 Emblems|
|11||SRB1 Level Select||Complete SRB1 Remake|
|12||Spring Hill Zone||Collect 100 Emblems|
|13||Black Hole||A Rank in all Special Stages|
|14||Emblem Hints||Collect 40 Emblems|
|15||Emblem Radar||Collect 80 Emblems|
|16||Pandora's Box||Collect All Emblems|
|17||Level Select||Collect All Emblems|
Numbers above that may be used by custom unlockables.
Unlockable = 17
This sets the weather used in your map:
|1||Storm (thunder and rain)|
|5||Thunder (no rain)|
|6||Storm (no lightning)|
Weather = 2
Making level headers
|This article or section is outdated and has not been updated to reflect the release of 2.1.
Please help the Wiki by correcting or removing any misinformation, as well as adding any new information to the page.
There are two ways of making level headers: by using SRB2 Doom Builder or by using a lump editor.
Using SRB2 Doom Builder
Open up a WAD file that contains one or more maps in SRB2 Doom Builder and choose any map. Once you have opened a map, go to Scripts menu, click on Edit MAINCFG lump; then, a new window will open, click on Make Script button. Now write a level header of your map. After you have finished the level header, click on Close button and save your map normally, and it is done. Also, you can edit a level header of an existing map by same feature.
Using a lump editor
Open up a text editor such as Notepad. Write the attributes in a format like this:
Level 1 levelname = YOUR MAPNAME HERE act = 0 musicslot = 1 skynum = 1 weather = 0 typeoflevel = Singleplayer nextlevel = 2
At a minimum, you should at least include those attributes, though all values which are left out have reasonable default values. Also, an extra line is needed at the end; otherwise, it won't work. To insert level headers, one can use a lump editor. Save the file as mapxxd.txt (xx is the level number) and use any lump editor, such as SLADE or XWE to insert the header into the wad.