Level header

From SRB2 Wiki
(Redirected from Level headers)
Jump to navigation Jump to 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
Keywords = GFZ1
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.

Level name

These parameters are for everything related to the level's name.

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

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

NoZone

Default setting: false

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

Example: NoZone = 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 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

Keywords

Default setting: (none)

This allows players to warp to the map by specifying keywords with the map command, without using the MAP## format or any words in the level name.

Example: Keywords = GFZ1


General level parameters

These parameters are applicable to any type of map.

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 collected 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

MarathonNext

Default setting: 0

Works the same as NextLevel, but specifically takes effect in Marathon Run. This can be used to allow speedruns of non-linear campaigns, such as level packs with a hub world.

Example: MarathonNext = 3

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

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.

Gravity

Default setting: 0.5

This sets the global gravity for the entire map. It replaces the deprecated Custom Global Gravity sector type. For individual sectors, the gravity can be overridden with linedef type 1 in Binary maps. In UDMF Maps individual sectors can have their gravity adjusted directly.

Example: Gravity = 0.25

Gametype-specific

These parameters are for setting more specific gameplay & gametype options.

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_NOTITLECARDFIRST The title card is not shown when the level is newly loaded; see ShowTitleCardFor.
512 LF_NOTITLECARDRESPAWN The title card is not shown when the level is reloaded (e.g., after dying and respawning); see ShowTitleCardFor.
1024 LF_NOTITLECARDRECORDATTACK The title card is not shown in Record Attack; see ShowTitleCardFor.
1792 LF_NOTITLECARD NoTitleCard (combination of the above three)

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)

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

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.

Example: FlickyList = Ram,Cow,Fish,Fish

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

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

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

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

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

NumLaps

Default setting: 4

Sets the number of laps for Circuit maps.

Example: NumLaps = 3

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

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

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

SpecialStageTime

Default setting: 90

If the level is a non-NiGHTS Special Stage, this specifies the time limit in seconds. Together with SpecialStageSpheres, this replaces the deprecated Special Stage Time/Spheres Parameters sector type.

Example: SpecialStageTime = 120

SpecialStageSpheres

Default setting: 1

If the level is a non-NiGHTS Special Stage, this specifies the blue sphere requirement. Together with SpecialStageTime, this replaces the deprecated Special Stage Time/Spheres Parameters sector type.

Example: SpecialStageSpheres = 200

Sky & weather

These parameters control everything related to the sky(box) and weather.

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

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.

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, rain and lightning)
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


Menu & level select

These parameters change how levels are handled within menus and level selection screens.

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)

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

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

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

NoVisitNeeded

Default setting: false

If set to true, the level will be 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

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. Do make sure to include a small picture as well, as there will always be some places where a small picture is required. 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

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

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. The text should not exceed the maximum length of 21 characters.

Example: SelectHeading = Bonus Levels


Music & sound

These parameters all relate to a map's music.

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

MusicSlot

Note: This parameter is removed. 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:

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.

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.

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

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.

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: MusicPostBoss = 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.

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

NoSSMusic

Default setting: false

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

Example: NoSSMusic = true

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


Title card

These parameters control the title card's appearance.

NoTitleCard

Default setting: false

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

Example: NoTitleCard = true

ShowTitleCardFor

Default setting: All

Specifies the situations in which the title card is shown.

Value Description
First The title card is shown when the level is newly loaded.
Respawn The title card is shown when the level is reloaded (e.g., after dying and respawning).
Record Attack The title card is shown in Record Attack.
All The title card is shown in all of the above situations. This has the same effect as NoTitleCard = false.
None The title card is never shown. This has the same effect as NoTitleCard = true.
Example: ShowTitleCard = RecordAttack

TitleCardActDiamond

Default setting: (none)

Specifies the lump name of the custom image to draw instead of the diamond graphic behind the act number on the title card. If this parameter is not specified, the default graphic will be used instead.

Example: TitleCardActDiamond = GRAPHIC

TitleCardZigZag

Default setting: (none)

Specifies the lump name of the custom image to draw instead of the "zig zag" graphic on the title card. If this parameter is not specified, the default graphic will be used instead.

Example: TitleCardZigZag = GRAPHIC

TitleCardZigZagText

Default setting: (none)

Specifies the lump name of the custom image to draw instead of the "SONIC ROBO BLAST 2" text graphic on the title card. If this parameter is not specified, the default graphic will be used instead.

Example: TitleCardZigZagText = GRAPHIC

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

Cutscenes & scripts

These parameters involve custom scripts & cutscenes. See also custom parameters for Lua-created parameters.

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

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

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

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

Custom parameters

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)


  SOC [view]
General Clear • MainCfg
Objects Object • State • Sound • Sprite2 • SpriteInfo • Sprite2Info • Freeslot
Unlockable content Emblem • ExtraEmblem • Unlockable • ConditionSet
Miscellaneous Wipes • Character • Level • Cutscene / Scene • Prompt • Menu • HudItem
Related links Actions • Constants • Custom Object tutorial
Retrieved from "https://wiki.srb2.org/w/index.php?title=Level_header&oldid=115748"