A Level Header, also called a map header, is a type of configuration 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 wadfile as the map, or they can be stored in the wadfile'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 MAINCFG, 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 integer map number (NOT the double-digit number), without leading zeros. So, if you want to set the properties of MAP09, you would write LEVEL 9. Note that n is an integer, and hence the extended map numbers must be converted to such to be used here.
LEVEL 1
This sets the act number, which goes along with the levelname. 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.
| Value | Character |
|---|---|
| -1 | Turn off |
| 0 | Sonic |
| 1 | Tails |
| 2 | Knuckles |
| 255 | Disabled |
4 and up will force the characters in the order they were added to the game. -1 is useful if your level is replacing a level that already has this in its level header like Knothole Base Zone Act 1.
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 lumpname 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.
InterPic = INTPIC01
Indicate the image used to replace Intermission time
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
This sets the music that's used in the level. SRB2 comes with a wide selection of musicslots to choose from, from its own level music, to less exclusive gems such as Green Hill Zone, the Mario theme, and Disco Zombies. You can also 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.
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:
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 the player the Perfect Bonus, case he 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
Specifies which Cutscene to display before the level. Set to 0 to disable.
PreCutsceneNum = 1
Runs a SOC on level's load. The SOC must be inside the wadfile.
RunSOC = EGGEXTRA
Use with 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 wadfile.
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 wadfile itself.
ScriptName = SCRIPT01
This sets the sky that's used in the level. SRB2 comes with a wide selection of skies, and most of the time, the levels use this selection. However, you can also supply your own, but the way to store them is a little complex. What SkyNum does is search for a texture SKYxx, xx being the double-digit number specified. If it's found, it displays that texture as the sky picture. If not, it displays REDWALL. To supply a custom sky, just add an entry to the TEXTURE1 lump as such.
The below is a listing of skies that come with SRB2:
| Skynum | Description |
|---|---|
| 1 | Greenflower Zone |
| 4 | Techno Hill Zone |
| 7 | Deep Sea Zone |
| 8 | Starry Sky |
| 10 | Castle Eggman Zone (New) |
| 11 | Castle Eggman Zone (Old) |
| 13 | Arid Canyon Zone |
| 17 | Blue Mountain Zone/Christmas Hunt/Old Christmas Demo |
| 21 | Egg Rock Zone Act 1 |
| 22 | Egg Rock Zone Act 2/3 |
| 29 | Spring Hill Zone |
| 30 | Mario Koopa Blast 1 |
| 50 | Special Stage 1 |
| 51 | Special Stage 2 |
| 52 | Special Stage 3 |
| 53 | Special Stage 4 |
| 54 | Special Stage 5 |
| 55 | Special Stage 6 |
| 56 | Special Stage 7 |
| 57 | Special Stage 8 |
| 64 | Wood Zone |
| 66 | Blackness (Xtreme Sky) |
| 103 | Great Forest Zone |
| 107 | Ice Palace Zone |
| 117 | Robotopolis[sic] Zone |
| 127 | Athenos Zone |
| 132 | Hidden Palace |
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 SHOES music. Note however, that in version 2.0.4, 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
If set to 1, this level is counted in totaling up Time Attack data. Use this in mods to create a Time Attack unlockable.
TimeAttack = 1
This is a ShufflarB2/SRB2CB level heading feature. It allows the level to have a night cycle used with any computer's internal clock. 1 enables the feature; 0 disables it.
timeofday = 1
Daytonight = 0
This sets the gametype(s) that the level plays under. Usually, more than one is specified.
| Value | Mode |
|---|---|
| 1 | Cooperative |
| 2 | Race |
| 4 | Match |
| 8 | Tag/Hide and Seek |
| 16 | Capture the Flag |
| 64 | NiGHTS |
| 256 | Mario |
| 512 | 2D |
| 4096 | Singleplayer |
| 8192 | Sonic Robo Blast 1 |
To combine modes, you must add up the numbers for each mode the level supports. If you wanted a Match and Tag level, for instance, add 4 + 8 to get 12. You would then put 12 as the TypeOfLevel.
TypeOfLevel = 12
Sets the weather:
| Value | Effect |
|---|---|
| 0 | None |
| 1 | Thunder Storm |
| 2 | Snow |
| 3 | Rain only |
| 4 | Preloaded Rain |
| 5 | Lightning (No rain) |
Weather = 2
There are two ways of making Level Headers: by using SRB2 Doom Builder and by using a Lump Editor.
Open up a wadfile 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.
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 and use any lump editor, including XWE or SLumpEd to insert the header into the wad.