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. Like all other SOC blocks, level headers are typically stored in the WAD file's MAINCFG lump.

Contents

Example

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

Header

The level header block must begin with a Level n statement, where n is the map number. The map number may be referred to with an integer number, where MAP01 is 1 and MAPA1 is 101, according to the list of extended map numbers.

Examples: LEVEL 1, LEVEL 101

Alternatively, the two-character map name can be used to refer to a level, which requires no conversions. Simply take the last two letters from the MAP## lump and use it in place of the integer number.

Examples: LEVEL 01, LEVEL A1

Do note that overriding a level header that already exists, whether from one of SRB2's own maps or another mod that has been previously added, will cause the entire header to be reset. If you want to change only one parameter, you will have to repeat the rest of the original header as well.

Parameters

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.

Act

Default setting: 0

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 left at 0, no act number is shown.

Example: Act = 0

BonusType

Default setting: Normal

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.

Example: BonusType = Boss

Countdown

Default setting: 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, much like in the classic Sonic games. If left at 0, the countdown timer is disabled.

Example: Countdown = 600

CutsceneNum

Default setting: 0

Specifies the number of a cutscene to display after the level. If left at 0, no cutscene is displayed.

Example: CutsceneNum = 1

ForceCharacter

Default setting: (none)

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

GradesX

Default setting: (none)

Sets the score requirements for each rank on the specified mare in a NiGHTS levels. X specifies the number of the mare, e.g. Grades1 for the first mare, Grades2 for the second mare, and so forth. If the map has only one mare, only specify Grades1. At most 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. Any values that are omitted will result in that rank being unachievable.

Example: Grades1 = 45000,70000,90000,100000,125000,200000

Hidden

Default setting: false

If set to true, the level will not appear in the list of maps presented when creating a server. This behavior is useful for secret maps.

Example: Hidden = true

HideInStats

Default setting: false

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

Example: HideInStats = true

InterScreen

Default setting: (none)

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. If left not set, the last frame of gameplay will be used as the intermission screen's background instead.

Example: InterScreen = INTERSCRW

LevelFlags

Default setting: 0

An alternative way of setting the parameters ScriptIsFile, SpeedMusic, NoSSMusic, NoReload and NoZone. As opposed to toggling each parameter individually, this sets all the parameters at once. The value is calculated as follows:

Value Flag Parameter
1 LF_SCRIPTISFILE ScriptIsFile
2 LF_SPEEDMUSIC SpeedMusic
4 LF_NOSSMUSIC NoSSMusic
8 LF_NORELOAD NoReload
16 LF_NOZONE NoZone

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

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

Alternatively, the flags may be combined with a bitwise OR operator (|) using their flag names listed above.

Example: LevelFlags = LF_NOZONE|LF_NOSSMUSIC|LF_SPEEDMUSIC

Note that any flag that is not set is automatically assumed to be false, regardless of previous parameters.

LevelName

Default setting: (none)

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 level name is limited to 21 characters; if it is longer, a warning will be displayed and the name will be truncated to fit.

Example: LevelName = Green Hill

LevelSelect

Default setting: 0

Determines which level select, if any, that the level will be shown in. See Custom unlockables and emblems for more information on custom level selects. LevelSelect 1 is also used as the level select for completed save games. If left at 0, the map will not be displayed in any level selects.

Example: LevelSelect = 2

MenuFlags

Default setting: 0

An alternative way of setting the parameters Hidden, HideInStats, RecordAttack, NightsAttack and NoVisitNeeded. As opposed to toggling each parameter individually, this sets all the parameters at once. The value is calculated as follows:

Value Flag Parameter
1 LF2_HIDEINMENU Hidden
2 LF2_HIDEINSTATS HideInStats
4 LF2_RECORDATTACK RecordAttack
8 LF2_NIGHTSATTACK NightsAttack
16 LF2_NOVISITNEEDED NoVisitNeeded

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

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

Alternatively, the flags may be combined with a bitwise OR operator (|) using their flag names listed above.

Example: MenuFlags = LF_HIDEINMENU|LF_RECORDATTACK|LF_NIGHTSATTACK

Note that any flag that is not set is automatically assumed to be false, regardless of previous parameters.

MusicSlot

Default setting: (same as map number)
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

MusicSlotTrack

Default setting: 0

Subsong to play. Only really relevant for music modules and specific formats supported by GME.

NextLevel

Default setting: (this level's map number, plus one)

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.

Do note that if no NextLevel is specified for MAPZZ and the player completes a map in that slot, the game will crash. In addition, the value set here may be overridden by a custom exit inside the map itself.

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

NightsAttack

Default setting: false

If set to true, the level is accessible in NiGHTS Mode.

Example: NightsAttack = true

NoReload

Default setting: false

When enabled, the level will not be reset when a player dies. Collectible items will return, but any linedef executors, moving sectors, etc. will not be reset. This is useful for switches, for instance. Mystic Realm, in particular, uses this parameter.

Example: NoReload = true

NoSSMusic

Default setting: false

If set to true, this will prevent the Super Sonic music from playing when the player turns Super.

Example: NoSSMusic = true

NoVisitNeeded

Default setting: false

If set to true, the level will accessible in Record Attack/NiGHTS Mode without requiring the player to visit the level beforehand. This can be used to make unlockables that add additional levels to Record Attack or NiGHTS Mode; for example, Black Hole Zone and Spring Hill Zone both use this.

Example: NoVisitNeeded = true

NoZone

Default setting: false

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

Example: NoZone = true

NumLaps

Default setting: 4

Sets the number of laps for Circuit maps.

Example: NumLaps = 3

Palette

Default setting: 0

This changes the palettes used for the map, affecting all flats, textures and sprites. The available numbers range from 1 to 10000. The palette used will be PAL#### (instead of PLAYPAL), and the colormap used will be CLM#### (instead of COLORMAP), where #### is the palette number given, minus one. If left at 0, the default palette and colormap will be used.

Keep in mind that the palette and colormap changes affect everything that the game displays, including all textures, the HUD, and the menus.

Example: Palette = 10, which would load the lumps PAL0009 and CLM0009.

PreCutsceneNum

Default setting: 0

Specifies the number of a cutscene to display before the level. If left at 0, no cutscene will be played.

Example: PreCutsceneNum = 1

RecordAttack

Default setting: false

If set to true, the level is accessible in Record Attack. Use this in mods to create a Record Attack unlockable.

Example: RecordAttack = true

For compatibility with older versions of SRB2, TimeAttack can also be used to refer to this parameter.

Example: TimeAttack = true

RunSOC

Default setting: (none)

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

ScriptIsFile

Default setting: false

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

ScriptName

Default setting: (none)

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

SkyboxScale

Default setting: 16

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.

This parameter is a shortcut to set all three of the skybox parameters listed below, and thus will overwrite them if it is used.

Example: SkyboxScale = -4, which makes the skybox move at 1/4th of the player's movement

SkyboxScaleX

Default setting: 16

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

SkyboxScaleY

Default setting: 16

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

SkyboxScaleZ

Default setting: 16

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

SkyNum

Default setting: (same as map number)
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.

Example: SkyNum = 7

SpeedMusic

Default setting: false

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).

Example: SpeedMusic = true

SubTitle

Default setting: (none)

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. Because this text is displayed in the game's normal font, this field also supports custom colors.

Example: SubTitle = Super Level 1

TypeOfLevel

Default setting: (none)

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
NiGHTS NiGHTS
ERZ3 mode Oldbrak
Christmas NiGHTS Xmas, Christmas, Winter
Example: TypeOfLevel = Singleplayer,Co-op,Competition,Race

Unlockable

Default setting: 0

Specifies the number of an unlockable that has to be unlocked for players to warp to this level through the console, command line, or level select. If left at 0, no unlockable is required. Otherwise, the number should match a custom unlockable that has been previously defined. Note that players can still enter the level if a previous level's NextMap parameter or custom exit points to it.

Example: Unlockable = 3

Weather

Default setting: PRECIP_NONE

This sets the weather used in your map:

Value Flag Effect
0 PRECIP_NONE None
1 PRECIP_STORM Storm (thunder and rain)
2 PRECIP_SNOW Snow
3 PRECIP_RAIN Rain
4 PRECIP_BLANK Preloaded precipitation
5 PRECIP_STORM_NORAIN Thunder (no rain)
6 PRECIP_STORM_NOSTRIKES Storm (no direct lightning)
Example: Weather = 2 or Weather = PRECIP_SNOW

Custom parameters

ToDoIcon.png To do
Elaborate a bit more.

Lua scripts can make use of custom map header parameters. To add a custom map header parameter, prefix its name with Lua., including the period at the end.

Example: Lua.CustomVal = 1

When this is done, the custom parameter will be accessible to Lua as if it were any other map header parameter. Note that the parameter name must be a valid variable name in Lua, and it must not match any of the game's default parameter names. In addition, the case of the parameter name in the level header is ignored; Lua must refer to it in all lowercase letters.

Example: print(mapheaderinfo[gamemap].customval)
Personal tools
Namespaces

Variants
Actions
Navigation
SRB2
Modification
Community
Toolbox