Level header

From SRB2 Wiki
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 stored in a SOC lump such as MAINCFG inside a WAD or PK3 file.

Example

This level header gives Greenflower Zone Act 1 its characteristics:

Level 1
Levelname = Greenflower
Act = 1
Music = GFZ1
TypeOfLevel = Singleplayer,Co-op,Competition,Race
NextLevel = 2
SkyNum = 1
RecordAttack = true
LevelSelect = 1
SaveGame = true
SkyboxScale = 64
FlickyList = Bluebird,Chipmunk

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

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. Usually, at least the parameters LevelName, Act, TypeOfLevel, NextLevel, Music and SkyNum should be set, to ensure that the level works as intended.

Act

Default setting: 0

This sets the act number, which is displayed along with the level name. The available numbers range from 1 to 99; 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. You cannot directly specify the exact bonuses that are awarded, but rather choose from one of the following combinations:

Value Description
Normal Used for regular levels. Awards a bonus for time and rings, as well as an additional perfect bonus if the player collected all rings.
Boss Used for boss levels. Awards a ring bonus, as well as a guard bonus for avoiding hits.
ERZ3 Used by Egg Rock Zone Act 3 in v2.1. Awards a ring bonus, a guard bonus and a perfect bonus. Useful for regular levels with a boss fight at the end.
NiGHTS Used by NiGHTS levels. Awards your total NiGHTS score as a bonus, and a lap bonus for extra laps done around each mare.
NiGHTSLink Old NiGHTS bonus used in SRB2 versions before v2.2. Awards a bonus based on your highest link, and a lap 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

FlickyList

Accepted alias: AnimalList
Default setting: Demo

This sets which animals can spawn when A_FlickySpawn is called in this level (usually after destroying an enemy). Accepts identifier strings for each of SRB2's built-in animals, but Object type constants can also be used. Custom Object types can also be specified. Multiple animals can be supplied in a comma-separated list. In this case, the game will randomly choose an animal from the list whenever one is spawned.

Identifier Object type(s) Notes
BlueBird MT_FLICKY_01 Used in Greenflower Zone, Azure Temple Zone and Christmas Chime Zone.
Rabbit MT_FLICKY_02 Used in Techno Hill Zone.
Chicken MT_FLICKY_03 Used in Techno Hill Zone.
Seal MT_FLICKY_04 Used in Deep Sea Zone and Frozen Hillside Zone.
Pig MT_FLICKY_05 Used in Red Volcano Zone.
Chipmunk MT_FLICKY_06 Used in Greenflower Zone.
Penguin MT_FLICKY_07 Used in Frozen Hillside Zone.
Fish MT_FLICKY_08 Used in Deep Sea Zone and Azure Temple Zone.
Ram MT_FLICKY_09 Used in Arid Canyon Zone.
Puffin MT_FLICKY_10 Used in Aerial Garden Zone and Christmas Chime Zone.
Cow MT_FLICKY_11 Currently unused.
Rat MT_FLICKY_12 Used in Castle Eggman Zone.
Bear MT_FLICKY_13 Used in Castle Eggman Zone.
Dove MT_FLICKY_14 Used in Aerial Garden Zone and Christmas Chime Zone.
Cat MT_FLICKY_15 Used in Red Volcano Zone.
Canary MT_FLICKY_16 Used in Arid Canyon Zone and Christmas Chime Zone.
Spider MT_SECRETFLICKY_01 Used in Haunted Heights Zone.
Bat MT_SECRETFLICKY_02 Used in Haunted Heights Zone.
Seed MT_SEED Previously used for the soniccd console variable.
Demo MT_FLICKY_02, MT_FLICKY_01, MT_FLICKY_12, MT_FLICKY_11, MT_FLICKY_03 Equivalent to Rabbit,BlueBird,Rat,Cow,Chicken. Corresponds to the animals that spawned in SRB2 versions before v2.2.
All MT_FLICKY_01, MT_FLICKY_02, MT_FLICKY_03, MT_FLICKY_04, MT_FLICKY_05, MT_FLICKY_06, MT_FLICKY_07, MT_FLICKY_08, MT_FLICKY_09, MT_FLICKY_10, MT_FLICKY_11, MT_FLICKY_12, MT_FLICKY_13, MT_FLICKY_14, MT_FLICKY_15, MT_FLICKY_16 Equivalent to BlueBird,Rabbit,Chicken,Seal,Pig,Chipmunk,Penguin,Fish,Ram,Puffin,Cow,Rat,Bear,Dove,Cat,Canary. All "standard" animals will be able to spawn. Used in Egg Rock Zone.
None N/A No animals will spawn.
Example: FlickyList = Ram,Cow

ForceCharacter

Default setting: (none)

Specifies the skin name of a character that players are forced to use in the level. This is only enforced at the beginning of the level; players can change their 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

ForceResetMusic

Default setting: -1

Specifies whether the music resets when the level is reloaded after dying.

String Value Description
N/A -1 Use the user's preferred setting, set by the resetmusic console variable.
On 1 Music is always restarted. This is used by SRB2 for its boss stages.
Off 0 Music is never restarted.
Example: ForceResetMusic = On

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 = 0,20000,30000,90000,180000,260000

Hidden

Default setting: false

If set to true, the level will not appear in the multiplayer level select. This behavior is useful for secret maps.

Example: Hidden = true

HideInStats

Default setting: false

If set to true, the level will not be listed on the Statistics screen.

Example: HideInStats = true

InterScreen

Default setting: (none)

Specifies the lump name of the image to draw as the background on the score tally screen after the level ends in Single Player and Coop. This allows custom images to be used as the background. If this parameter is not specified, the last frame of gameplay will be used as the background instead.

Example: InterScreen = INTERSCRW

LevelFlags

Default setting: 0

An alternative way of setting various togglable level header parameters that affect the level in-game. 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
32 LF_SAVEGAME SaveGame
64 LF_MIXNIGHTSCOUNTDOWN MixNightsCountdown
128 LF_WARNINGTITLE WarningTitle
256 LF_NOTITLECARD NoTitleCard

For each parameter that should be set to true, add its value to the LevelFlags value. All other parameters will be set to false.

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

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, the level will be listed in. See Custom unlockables and emblems for more information on custom level selects. Level select 1 is used as the level select for completed save slots. If left at 0, the map will not be displayed in any level selects.

Example: LevelSelect = 2

MaxBonusLives

Default setting: -1

Sets the maximum number of extra lives the player can earn from score bonuses at the score tally screen. Set to -1 for no limit, and 0 to prevent bonus lives entirely. In SRB2, the unlockable NiGHTS stages set this to 0.

Example: MaxBonusLives = 0

MenuFlags

Default setting: 0

An alternative way of setting various togglable level header parameters that affect the level's appearance in menus. 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
32 LF2_WIDEICON WideIcon

For each parameter that should be set to true, add its value to the MenuFlags value. All other parameters will be set to false.

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

MixNightsCountdown

Default setting: false

If set to true, the "time up" jingle that is played when the NiGHTS timer reaches below 10 seconds is faded into from the level's music. If set to false, the level music is stopped before the jingle is played. SRB2 sets this to true for the NiGHTS bonus stages and false for the Special Stages.

Example: MixNightsCountdown = true

Music

Default setting: MAPxxM (where xx is the extended map number)

Specifies the name of the music track that is used in the level. Music tracks are identified by a name consisting of at most six characters, which is the same as name of the lump that stores the music, but without the O_ or D_ prefix. For example, if you want the music stored in the lump O_EXAMPL to be played, set this parameter to EXAMPL. If you set this parameter to None, no music will be played in the level.

You can either use the music supplied in SRB2 itself or supply a custom music lump. See Sound and music tutorial for an explanation of how to supply custom music, and List of music for a list of music tracks available in SRB2. If you omit this parameter, the music track will default to MAPxxM, where xx is the extended map number of the map.

Example: Music = VSBOSS

MusicInter

Default setting: (none)

Specifies the name of the music track to be played at the score tally screen after finishing the level in Single Player or Coop. If not specified, the game defaults to using _CLEAR. Note that this parameter will have no effect if MusicInterFadeOut is used to fade out the level music at the score tally screen.

MusicInterFadeOut

Default setting: 0

Sets the time in milliseconds that the level music takes to fade out to silence at the score tally screen displayed after finishing the level in Single Player or Coop. If set to 0, the music will not fade out and the score tally music (which can be changed via MusicInter) will be played instead.

MusicPos

Default setting: 0

Sets the position in the level's music track, given as a time in milliseconds, that the level will begin playing the track from. If set to 0, the music track will be played from the beginning.

MusicPostBoss

Default setting: (none)

Specifies the name of the music track that the level switches to after all bosses in the map have been defeated. Omit this parameter if the music should stay the same.

Example: Music = GFZ1

MusicPostBossFadeIn

Default setting: 0

Sets the time in milliseconds that the post-boss music takes to fade in, after the boss music stops. If set to 0, no fade-in will be used.

MusicPostBossPos

Default setting: 0

Sets the position in the post-boss music track, given as a time in milliseconds, that the level will begin playing the track from. If set to 0, the music track will be played from the beginning.

MusicPostBossTrack

Default setting: 0

Specifies the subtrack to play from the level's post-boss music lump. This is only relevant for music formats that support multiple tracks in the same file, such as modules and specific formats supported by GME.

MusicSlot

Default setting: (same as map number)

This parameter is deprecated and only exists for backwards compatibility. If you are creating a new level, use Music instead.

When porting a level from a previous version that uses this parameter, you can convert the slot number specified here to a music track name as follows: If the number is between 1 and 1035, then the music track is MAPxxM, where xx is the extended map number corresponding to the slot number. For example, MusicSlot = 1 is equivalent to Music = MAP01M, while MusicSlot = 100 is equivalent to Music = MAPA0. If the number is between 1036 and 1050, then it refers to one of the following special tunes:

Slot number Lump name Music
1036 _TITLE Title screen
1037 _INTRO Introduction
1038 _CLEAR Score tally screen
1039 _INV Invincibility
1040 _SHOES Super Sneakers
1041 _MINV Mario invincibility
1042 _DROWN Drowning
1043 _GOVER Game Over
1044 _1UP Extra life
1045 _CONTI Continue screen
1046 _SUPER Super Sonic
1047 _CHSEL Character select screen
1048 _CREDS Credits
1049 _INTER Multiplayer intermission
1050 _STJr Sonic Tear Jr. intro

MusicTrack

Default setting: 0

Specifies the subtrack to play from the level's music lump. This is only relevant for music formats that support multiple tracks in the same file, such as modules and specific formats supported by GME.

NextLevel

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

This sets the level that the game will warp to after this one ends. Both extended map numbers and integers are accepted (as well as the special values listed below). Leading zeroes are not necessary. For example, if you want the next level to be MAP02, specify 2. Note that the value set here may be overridden by a custom exit inside the map itself.

If this parameter is omitted, it will default to this level's map number, plus one. If no map exists in that slot, the game will print an error in the console and warp to MAP01. An exception to this is MAPZZ. If no NextLevel value is specified for a map in this slot, the game will crash when trying to warp to the next level.

The following values have special meanings. Both the string and integer versions are accepted:

String Integer Meaning
TITLE 1100 Warps to the title screen.
EVALUATION 1101 Warps to the evaluation screen, i.e., the screen that shows the player how many emeralds they have collect and which secrets they have unlocked. Single Player/Coop only.
CREDITS 1102 Warps to the credits.
ENDING 1103 Warps to the ending sequence, which is followed by the credits.
Example: NextLevel = 2

NightsAttack

Default setting: false

If set to true, the level will be accessible in NiGHTS Mode. Note that NiGHTS Mode will not be accessible by default in mods with a custom gamedata. To make it accessible, a custom unlockable must be created for it.

Example: NightsAttack = true

NoReload

Default setting: false

When enabled, the level geometry will not be reloaded when the player dies in Single Player. All Things will be respawned, but dynamic level elements such as linedef executors or moving floors will not be reset. This is useful for creating buttons or switches that stay activated after the player dies. An example of this are the Mystic Shrines in Mystic Realm.

Example: NoReload = true

NoSSMusic

Default setting: false

If set to true, the Super Sonic music will not play when the player turns Super.

Example: NoSSMusic = true

NoTitleCard

Default setting: false

If set to true, this disables the title card normally shown on level load.

Example: NoTitleCard = true

NoVisitNeeded

Default setting: false

If set to true, the level will accessible in Record Attack, NiGHTS Mode, and the multiplayer level select without requiring the player to visit the level beforehand. This can be used to create unlockable levels that are only accessible via Record Attack or NiGHTS Mode, such as Black Hole Zone. It can also be used to add custom levels to the multiplayer level select without needing to add them to the campaign.

Example: NoVisitNeeded = true

NoZone

Default setting: false

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

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 graphics displayed by the game, including flats, textures, sprites, the HUD, and the menus. The available numbers range from 1 to 10000. The palette lump used will be PAL#### (instead of PLAYPAL), and the colormap lump 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.

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

Accepted alias: TimeAttack
Default setting: false

If set to true, the level will be accessible in Record Attack. Note that Record Attack will not be accessible by default in mods with a custom gamedata. To make it accessible, a custom unlockable must be created for it.

Example: RecordAttack = true

RunSOC

Default setting: (none)

Specifies the name of a SOC file or lump to run on level load. If the SOC is an external file, both the file and the value supplied to this parameter should end with .soc. Otherwise, the SOC must be a lump inside one of the currently loaded WAD or PK3 files.

Example: RunSOC = EGGEXTRA

SaveGame

Default setting: false

If set to true, the game's progress will be saved in Single Player when the level is loaded. This setting will be ignored in certain cases: The game will never save in Ultimate mode or in Special Stages, but it will always save if you are playing on a completed save slot.

Example: SaveGame = true

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 or PK3 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 or PK3 file.

Example: ScriptName = SCRIPT01

SelectHeading

Default setting: (none)

Specifies the heading that this level is listed under in the level select. Maps with the same heading are grouped together. If no heading is specified, the level will be listed under its zone name, i.e., its LevelName value, plus "Zone" unless NoZone is set.

Example: SelectHeading = Funny Levels

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 movement at equal speed.

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 speed

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 graphic that is displayed 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 graphic instead.

Example: SkyNum = 7

SpeedMusic

Default setting: false

If set to true, the level music will be sped up when the player busts open a Super Sneakers Monitor, rather than playing the Super Sneakers music. Note: This feature only works for music tracks in a format supported by the Game Music Emu library.

Example: SpeedMusic = true

StartRings

Default setting: 0

Sets the number of rings every player starts with. In SRB2, boss levels have this set to 10.

Example: StartRings = 10

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 afterwards 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 level type(s) that the level can be played under. For each supported level type, add one of the corresponding identifiers to the TypeOfLevel value (for level types with multiple identifiers, only one of them needs to be used). Separate different level types using commas. Custom mode, 2D mode, Mario mode, NiGHTS, ERZ3 mode and Christmas NiGHTS do not work on their own and must be combined with other level types.

Mode Identifiers
Single Player Solo, SP, Singleplayer, or Single
Cooperative Coop, or Co-op
Competition Competition
Race Race
Match Match
Tag Tag
Capture the Flag CTF
Custom (Lua-scripted) Custom
2D mode 2D
Mario mode Mario
NiGHTS NiGHTS
ERZ3 mode Oldbrak
Christmas NiGHTS Xmas, Christmas, or 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 NextLevel parameter or custom exit points to it.

Example: Unlockable = 3

WarningTitle

Default setting: false

If set to true, the title card will be red and will read "WARNING" instead of "SONIC ROBO BLAST 2". In SRB2, this is used for boss acts.

Example: WarningTitle = true

Weather

Default setting: PRECIP_NONE

This sets the type of weather that is used in the map. Both integers and the internal weather constants prefixed with PRECIP_ are accepted:

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

WideIcon

Default setting: false

If set to true, the level will use a wide level select picture instead of a small one, provided there is enough space to display it. The lump name for the wide level select picture is MAPxxW, where xx is the extended map number. The picture should be 564×100 pixels in size instead of 160×100 pixels.

Example: WideIcon = true

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. Note that parameters are always stored and passed in as strings; any value expected to be of a different type should be converted manually from the string representation.

Example: print(mapheaderinfo[gamemap].customval)


  Sonic Object Configuration [view]
General ClearMainCfg
Objects ObjectStateSoundSprite2SpriteInfoSprite2InfoFreeslot
Unlockable content EmblemExtraEmblemUnlockableConditionSet
Miscellaneous WipesCharacterLevelCutscene / ScenePromptMenuHudItem
Related links ActionsConstantsCustom Object tutorial