A level header, also called a map header, is a type of SOC that defines the properties of a particular map through a set of parameters. Level headers are what give the official levels, like Greenflower Zone Act 1, as well as almost every custom level their specific characteristics. Level headers control elements such as level name, sky picture, and music.
Level headers are stored in single level header lumps within the same WAD file as the map, or they can be stored in the WAD file's
MAINCFG. When they're stored in their own lump, the lump is named
MAPxxD, where xx is the double-digit map number. There's a difference between choosing either method: storing the level header in the
MAINCFG will overwrite only the values explicitly written to overwrite, while
MAPxxD will reset everything to blank and then apply the values written. For example, if one doesn't set the music for
MAP01 in a
MAP01 will have GFZ1's music because it just used the old value that was already there. Storing the level header in
MAPxxD will give it no music at all because the music wasn't explicitly specified and it's using the blank value it wrote down first.
This level header gives Greenflower Zone Act 1 its characteristics:
LEVEL 1 LevelName = GREENFLOWER Act = 1 MusicSlot = 1 NextLevel = 2 TypeOfLevel = 4099 SkyNum = 1
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 goes along with the level name. The available numbers range from 1 to 19, and numbers 20 and above will report an error on the console, and place no act in the title card. For no act number, set it to 0.
Act = 0
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. Setting this variable to 0 will disable the time-limit. This works much like the 10-minute time limit in classic Sonic games.
Countdown = 600
Specifies which Cutscene to display after the level. Set to 0 to disable.
CutsceneNum = 1
This forces the player to a certain character 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.
|-1 or 255||Disabled|
3 and up will force the characters in the order they were added to the game. -1/255 is useful if your level is replacing a level that already has this in its level header, like the SRB1 Remake levels.
ForceCharacter = 1
If set to 1, the level will not appear in the list of maps presented when creating a server. Useful for secret maps. For secret maps, it's usually necessary to set both this and LevelSelect.
Hidden = 1
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 Co-Op, and the score screen in Match, Tag, and CTF.) This allows custom images to be used as the background.
InterScreen = INTERSCRW
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 1. You cannot make the name too long or the letters will fold over some of the others when the game tries to load it.
LevelName = Green Hill
If set to 1, the level is shown on the unlockable level select. This only works in WADs that would show the level select in the first place.
LevelSelect = 1
- See also: MusicSlot
This sets the music that's 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 = 109
This sets the level that follows after this one ends. You can either specify an integer or an alphanumeric value here. The game verifies if the string contains letters, and if so, it'll assume it's the alphanumeric value. However, if it has more than 3 characters and none are alphanumeric, then it is an integer. 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/Co-Op only.
- 1102 ends the game, taking you to the credits.
NextLevel = 2
If you collect all rings in a level, you get the perfect bonus when you complete it. If NoPerfectBonus is set to 1, this map will not grant players the perfect bonus, even if they got all rings. This is useful for boss maps, amongst others.
NoPerfectBonus = 1
When set to 1, 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.
NoReload = 1
If set to 1 rather than 0, this will prevent the Super Sonic music from playing when it would otherwise. Super Sneakers music is also suppressed.
NoSSMusic = 1
If set to 1, "Zone" is not added to the level's name.
NoZone = 1
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 which Cutscene to display before the level. Set to 0 to disable.
PreCutsceneNum = 1
Runs a SOC on level load. The SOC must be a lump inside the WAD file.
RunSOC = EGGEXTRA
ScriptName. If it is set to 0, the script name is the name of an external file to load the script from. If it is 1, the script name is a lump name in the WAD file.
ScriptIsLump = 1
Loads and runs a script on level load. If
ScriptIsLump is set to 0, this is assumed to be the name of an external file. If
ScriptIsLump is 1, it's a lump name in the WAD file itself.
ScriptName = SCRIPT01
- See also: Flats and textures/Skies
This sets the sky that is used in the level. What
SkyNum does is search for a texture
SKYx, x being the integer number specified. If it's found, it displays that texture as the sky picture. If not,
REDWALL will be displayed as the sky picture instead.
SkyNum is not set, the sky with the corresponding integer number to the level number will be used, if it exists.
SkyNum = 7
If set to 1, the music will be sped up when the player busts open a Super Sneakers Monitor, rather than playing the
D_SHOES music (MusicSlot number 1040). Note however that due to a bug, the music's speed does not go back to normal once the Super Sneakers wear off. This will be fixed in future versions.
SpeedMusic = 1
Use this to add a second smaller title to your map. This appears at the start of the level.
SubTitle = Super Level 1
TimeAttack = 1
This sets the gametype(s) that the level can be played under. More than one gametype can be specified by adding their values together. For instance, if your level supports Match and Tag, add 4 + 8 to get 12. You would then put 12 as the
TypeOfLevel value. NiGHTS mode, Mario mode, 2D mode, ERZ3 mode, and SRB1 mode do not work on their own and must be combined with other values.
|8||Tag/Hide and Seek|
|16||Capture the Flag|
TypeOfLevel = 12
This sets the weather used in your map:
|5||Thunder (No rain)|
|6||Thunderstorm (No lightning)|
Weather = 2
Making level headers
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 = 4096 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.