Level header

From SRB2 Wiki
(Redirected from Level Header)
Jump to: navigation, search

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. MAP01D for MAP01 and MAPA1D for MAPA1.



This level header gives Greenflower Zone Act 1 its characteristics:

Level 1
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 LevelName, Act, MusicSlot, TypeOfLevel, NextLevel and 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, LevelName and 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 LEVEL 101.

Example: LEVEL 1


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.

Example: 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 Normal.

Example: 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.

Example: Countdown = 600


Specifies the number of a cutscene to display after the level. Set to 0 to disable.

Example: 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.

Example: 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.

Example: 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.

Example: Hidden = true


If set to true, the level will not appear in the Statistics screen. The default value is false.

Example: 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.

Example: InterScreen = INTERSCRW


An alternative way of setting the parameters ScriptIsFile, SpeedMusic, NoSSMusic, NoReload and NoZone. The value is calculated as follows:

Value Parameters
1 ScriptIsFile
2 SpeedMusic
4 NoSSMusic
8 NoReload
16 NoZone

For each parameters that should be set to true, add its value to the LevelFlags value.

Example: LevelFlags = 22 (NoZone, NoSSMusic and SpeedMusic)


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.

Example: LevelName = Green Hill


If set to 1, the level is shown on the unlockable level select. Values 2 and above are used for custom level selects that can be defined in custom unlockables.

Example: LevelSelect = 1


An alternative way of setting the parameters Hidden, HideInStats, RecordAttack, NightsAttack and NoVisitNeeded. The value is calculated as follows:

Value Parameters
1 Hidden
2 HideInStats
4 RecordAttack
8 NightsAttack
16 NoVisitNeeded

For each parameters that should be set to true, add its value to the MenuFlags value.

Example: MenuFlags = 13 (Hidden, RecordAttack and NightsAttack)


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.

Example: 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.
Example: NextLevel = 2


If set to true, the level is accessible in NiGHTS Mode. The default value is false.

Example: 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 false.

Example: 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 false.

Example: 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 false.

Example: NoVisitNeeded = true


If set to true, "Zone" is not added to the level's name. The default value is false.

Example: NoZone = true


Sets the number of laps for Circuit maps.

Example: 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 PLAYPAL, and CLM0000 instead of COLORMAP. If set to 10000, the map uses PAL9999 for PLAYPAL, and CLM9999 for COLORMAP. 0 is undefined, and 10001 and above sets the map to use the default PLAYPAL and COLORMAP palettes.

Example: Palette = 2, which would load the lumps PAL0001 and CLM0001.


Specifies the number of a cutscene to display before the level. Set to 0 to disable.

Example: PreCutsceneNum = 1


If set to true, the level is accessible in Record Attack. Use this in mods to create a Record Attack unlockable. This parameter can also be written as TimeAttack, which will have the same effect.

Example: RecordAttack = true


Specifies the lump name of a SOC to run on level load. The SOC must be a lump inside the WAD file.

Example: RunSOC = EGGEXTRA


Use with 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 (false).

Example: ScriptIsFile = true


Specifies the name of a console script to load and run on level load. ScriptIsFile specifies whether the script is an external file or a lump in the WAD file.

Example: 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.

Example: 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.

Example: 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.

Example: 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.

Example: 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.

Example: SkyNum = 7


If set to true, the music will be sped up when the player busts open a Super Sneakers Monitor, rather than playing the mus_shoes music (MusicSlot number 1040). The default value is false.

Example: 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.

Example: 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.

Mode Identifiers
Single Player Solo, SP, Singleplayer, Single
Cooperative Coop, Co-op
Competition Competition
Race Race
Match Match
Tag Tag
Capture the Flag CTF
Custom (Lua-scripted etc.) Custom
2D mode 2D
Mario mode Mario
ERZ3 mode Oldbrak
Christmas NiGHTS Xmas, Christmas, Winter
Example: 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:

Number Unlockable Requirement
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.

Example: Unlockable = 17


This sets the weather used in your map:

Value Effect
0 None
1 Storm (thunder and rain)
2 Snow
3 Rain
4 Preloaded precipitation
5 Thunder (no rain)
6 Storm (no lightning)
Example: Weather = 2

Making level headers

Test.png 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
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.

Personal tools