MainCfg

From SRB2 Wiki
Jump to navigation Jump to search
"MAINCFG" redirects here. For the WAD file lump called MAINCFG, see SOC#Script execution.
To do
Describe unique parameters

The MainCfg block is a special SOC block that allows the user to modify a variety of global game settings, such as the timers of various power-ups and other timed effects, the name of the gamedata and save files, the location of the Special Stages and the first Single Player stage, and other miscellaneous settings. It is commonly used in level packs and other addons that extensively modify the game.

The MainCfg block should not be confused with the MAINCFG lump. Although both share the same name and are related to SOCs, they are not otherwise connected. MAINCFG is a reserved lump name in SRB2 – if a WAD file contains a lump with that name, SRB2 will recognize it as a SOC lump and load its contents upon loading the WAD file. Because of this, SOC code that should be executed immediately is often placed in the MAINCFG lump – including the MainCfg block.

Because it contains globally relevant information, the MainCfg block is usually placed at the top of a SOC lump or file. This causes it to be loaded before all other SOC blocks. This is especially relevant due to the ResetData parameter, which can cause previously loaded SOC data to be erased. But even if the ResetData parameter is not set, it is advised to place the MainCfg block first for better organization.

Header

The header of the MainCfg block simply consists of a single line that reads MainCfg. Unlike most other SOC blocks, it contains no slot number, since the data it modifies is global and exists only once.

Parameters

The following is a list of all parameters that can be set in the MainCfg block. Not all of these have to be specified; if a parameter is left out, it will revert to its default value.

Data handling

  • GameData defines which data file is used to save game progress, such as unlocked secrets. Modifications with custom unlockables need to set this parameter. For example, if GameData = s_mymod.dat is set, then the file used to save data is s_mymod.dat in the SRB2 directory. The file extension must be .dat.
  • ResetData resets the sprite, state or Object type tables upon loading the file. This means that any changes made to these tables by previously loaded SOC files will be reverted. The value determines which tables to reset: Add 1 to reset the sprite table, 2 to reset the state table, and 4 to reset the Object type table. The values can be combined. No freeslot declarations, state definitions or Object type definitions should be placed above this line in the SOC lump, as they will be erased as well.

Map locations

These parameters determine which slots certain special maps are placed in.

  • SPStage_Start sets the map number of the first map in the Single Player campaign. This is the map the game warps to when starting a new Single Player game. Unlike the Special Stages, the Single Player maps do not have to be placed in successive map slots, because the individual level headers determine which map is loaded next. This parameter merely tells the game where the first level is. Defaults to 1 if the parameter is omitted.
  • SPMarathon_Start sets the map number of the first map in Marathon Run. Useful for non-linear campaigns, where this can be used to set a speedrun's starting point, after which each map can utilize the MarathonNext parameter to create a set order of maps. Defaults to SPStage_Start's value if the parameter is omitted.
  • SStage_Start sets the map number of the first Single Player Special Stage. All other Single Player Special Stages must be clustered together in the immediately following map slots. For example, if SStage_Start = 50, then the first Special Stage should be in MAP50, the second in MAP51, and the seventh in MAP56. Defaults to 50 if the parameter is omitted.
  • SMPStage_Start sets the map number of the first Coop Special Stage. All other Coop Special Stages must be clustered together in the immediately following map slots. Set this to the same value as SStage_Start to use the same stages in both gametypes. Defaults to 60 if the parameter is omitted.
  • TitleMap sets the map number to display as a background for the title screen. If set to 0, no title map is used and the TITLESKY lump is displayed as a background graphic instead. Defaults to 0 if the parameter is omitted, although SRB2's own resource files set this to 99.
  • TutorialMap sets the map number of the tutorial map, which is accessed via the "Tutorial" option in the Single Player option menu. Set this to 0 to disable the tutorial. Defaults to 0 if the parameter is omitted, although SRB2's own resource files set this to Z0.
  • BootMap sets the map number to warp to immediately when starting the game. If set to 0, the game does not warp to a map on startup. Defaults to 0 if the parameter is omitted.

Cutscenes

These parameters can be used to change the cutscenes that are used for the intro and credits.

  • IntroToPlay determines the number of the cutscene to play as the intro, replacing the existing intro cutscene SRB2 uses. For example, if IntroToPlay = 2 is set, then the game will search for a cutscene block with a header of Cutscene 2 to be played as the intro.
  • CreditsCutscene determines the number of the cutscene to use for the credits.
  • UseBlackRock determines whether the Black Rock cutscene is used upon completing the Single Player campaign (true) or not (false), and also toggles the Black Rock being present in the Marathon Run menu. Defaults to true if the parameter is omitted.

Title screen

These parameters affect different properties of the title screen.

  • LoopTitle determines whether to loop the title screen music (true) or play it just once (false). Defaults to false if the parameter is omitted.
  • TitleScrollXSpeed (or TitleScrollSpeed) sets the speed at which to scroll the title screen background rightwards or, if a title map is used, the speed at which to spin the title map's camera counterclockwise. Use negative values for leftward scrolling or clockwise spinning, respectively. For scrolling the background, a value of 1 equals 1/16th of a pixel per tic. For spinning the title map camera, a value of 1 equals 1/64th of a degree per tic. The default value is 20, which gives a speed of 1.25 pixels per tic or slightly below 11 degrees per second.
  • TitleScrollYSpeed sets the speed at which to scroll the title screen background downwards. Use negative values for upward scrolling. A value of 1 equals 1/16th of a pixel per tic. The default value is 0, which gives no scrolling. If a title map is used, this parameter has no effect.
  • TitlePicsMode determines how graphics are overlaid on top of the title screen background or title map. If set to Hide, Hidden or None, no extra graphics are displayed. If set to Alacroix, the animated SRB2 logo is displayed. If set to Old, a still image of the SRB2 logo is displayed. If set to User, a custom animation or still image is displayed. The parameters used for configuring this are listed below. Defaults to Old if the parameter is omitted, although SRB2's own resource files set this to Alacroix.
  • TitlePicsHide or HideTitlePics determines whether extra graphics are overlaid on top of the title screen background or title map (true) or not (false). Setting this to true is equivalent to setting TitlePicsMode = Hide. Defaults to false if the parameter is omitted.
  • TitlePicsScale sets the scaling of the title screen graphics. Possible values range from 1 to 8. For a specified value x, the scale of the graphics will be 1/x, e.g., TitlePicsScale = 8 will scale the graphics down to 1/8th of their original size. This setting is not used if TitlePicsMode = Alacroix is set. Defaults to 1 if the parameter is omitted.
  • TitlePicsName sets the lumps to use for the title screen graphics when setting TitlePicsMode = User. To use a still image, set this to the name of the graphics lump to use. To create an animated sequence, set this to a lump name prefix with at most six letters, e.g., NEWTS. The game will then search for lumps NEWTS00 through NEWTS99 to make up the frames of the animation. The length of the animation depends on how many lumps are supplied.
  • TitlePicsTics sets the number of tics to show each image in the title screen animation when setting TitlePicsMode = User and using an animated sequence. For example, a value of 3 will make the animation advance to the next frame every 3 tics. Defaults to 1 if the parameter is omitted.
  • TitlePicsLoop set the frame number that the title screen animation will loop back to when setting TitlePicsMode = User and using an animated sequence. Using the previous NEWTS example, a value of 16 will make the animation loop back to NEWTS16 after showing the last frame. If set to -1, the animation will not loop. Defaults to -1 if the parameter is omitted.
  • TitlePicsX and TitlePicsY set the coordinates at which the title screen graphics are placed when setting TitlePicsMode = User. Both parameters default to 0 if they are omitted.
  • TitlePicsScalesAvailable sets which graphics exist for each scale when setting TitlePicsMode = Alacroix. Possible values range from 1 to 6 and are separated by commas, e.g., TitlePicsScalesAvailable = 2,3,6 means there are graphics for 1/2 scale, 1/3 scale, and 1/6 scale.

Title screen demos

These parameters affect the demos that are played back at the title screen.

  • NumDemos sets the number of demos that are played back at the title screen. The demo lumps to be played should have the lump names DEMO_xxx, with xxx starting at 001 and continuing up until the value of this parameter. The default value is 0, although SRB2's own resource files set this to 4.
  • DemoDelayTime sets the amount of time that the game will stay on the title screen between playing back demos. The default value is 15*TICRATE (15 seconds).
  • DemoIdleTime sets the additional amount of time that the game will stay on the title screen if the DemoDelayTime was depleted while the console was open or the user was in a menu. Once the console or menu is closed, the game will additionally deplete the DemoIdleTime before playing back a demo. The default value is 3*TICRATE (3 seconds).

Customization

These parameters customize various minor game settings.

  • RedTeam sets the skin color of players on the red team in Team Match and Capture the Flag games in the format SKINCOLOR_X, where X is the name of the color, e.g., SKINCOLOR_RED. The default value is SKINCOLOR_RED. See List of skin colors for a full list of available colors.
  • BlueTeam sets the skin color of players on the blue team in Team Match and Capture the Flag games in the format SKINCOLOR_X, where X is the name of the color, e.g., SKINCOLOR_RED. The default value is SKINCOLOR_BLUE.
  • RedRing sets the color of the red ring thrown in Match and other combative gametypes in the format SKINCOLOR_X, where X is the name of the color, e.g., SKINCOLOR_RED. The default value is SKINCOLOR_SALMON.
  • BlueRing sets the skin color of the rings thrown by players on the blue team in Team Match and Capture the Flag games in the format SKINCOLOR_X, where X is the name of the color, e.g., SKINCOLOR_RED. The default value is SKINCOLOR_CORNFLOWER.
  • DisableSpeedAdjust determines whether to change the player character's animations according to the player's velocity, for example when Sonic's walking animation speeds up as he walks faster (false), or not (true). Defaults to false if the parameter is omitted. Note that this will affect all characters in the game. To set this for specific characters, use the SF_NOSPEEDADJUST skin flag.
  • Use1UpSound determines whether to play the sound effect sfx_oneup (true) or the music track mus_xtlife (false) when earning an extra lives. Defaults to false if the parameter is omitted.
  • MaxXtraLife determines the maximum number of extra lives that can be earned from collecting rings. An extra life is awarded for each 100 rings that the player collects, until the maximum is reached. Defaults to 2 if the parameter is omitted, which means that no more extra lives are awarded for collecting 300 rings and above.
  • StartChar sets the character select entry that the character select screen highlights initially. Defaults to 0 if the parameter is omitted.
  • UseContinues determines whether continues can be earned (true) or not (false) from a Special Stage in the Single Player campaign. Defaults to false if the parameter is omitted.

Timers

These parameters control how long the effects of certain power-ups and other timers last. They are measured in tics, of which 35 equal one second. Multiply the values with the constant TICRATE (35) to convert them to seconds.

  • InvulnTics sets how long the Invincibility power-up lasts. The default value is 20*TICRATE (20 seconds).
  • SneakerTics sets how long the Super Sneakers power-up lasts. The default value is 20*TICRATE (20 seconds).
  • FlashingTics sets how long a player flashes and is invincible after taking damage. The default value is 3*TICRATE (3 seconds).
  • TailsFlyTics sets how long Tails can fly before getting tired. The default value is 8*TICRATE (8 seconds).
  • UnderwaterTics sets how long the player can stay underwater before drowning. Note that this value includes the drowning countdown, not just the period before it. To retain the full countdown, this value should be at least 11.5 seconds. The default value is 30*TICRATE (30 seconds). Setting this value to 0 completely disables the drowning system, including the aquaphobia sound effect.
  • SpacetimeTics sets how long the player can survive in a space countdown before suffocating. Note that the timer can actually be expanded beyond just the countdown, so that there is a period before the countdown starts, like in water. The default value is 11*TICRATE + (TICRATE/2) (11.5 seconds).
  • ExtraLifeTics sets how long the extra life music plays. Note that this value is completely separate from the length of the actual extra life tune. If this value is shorter than the length of the tune, the tune will be cut off. If it is longer, the remaining time will be filled with silence. If a custom extra life tune is used, this parameter should be adjusted to match the length of the custom tune. The default value is 4*TICRATE (4 seconds).
  • NiGHTSLinkTics sets how long it takes for a NiGHTS link to fade out. The default value is 2*TICRATE (2 seconds).
  • GameOverTics sets how long the game stays at a Game Over screen before switching to the continue screen or the title screen. This only affects Single Player mode, where the game eventually switches to another screen. In other applicable modes, such as Coop and Competition, the Game Over screen will be displayed indefinitely until the other players complete the level. The default value is 11*TICRATE (11 seconds).
  • AmmoRemovalTics sets how long the ammo removal warning will be displayed when shooting a weapon ring without regular rings in Match and related gametypes. The default value is 2*TICRATE (2 seconds).

Netgame

  • ShareEmblems determines if the game should share emblems across players instead of client sided. (true) or not (false)

Miscellaneous

  • ExecCfg sets the file name of a console script to be executed when the WAD or PK3 file is loaded.
  • CustomVersion replaces the "v2.2.x" version string in the bottom-left corner of the game menus with a customized version string. This parameter supports custom colors.

Example

MainCfg
SpStage_Start = A1
SStage_Start = B1
GameData = s_mymod.dat
ResetData = 7
TailsFlyTics = 10*TICRATE
CustomVersion = v1.1
  SOC [view]
General ClearMainCfg
Objects ObjectStateSoundSprite2SpriteInfoSprite2InfoFreeslot
Unlockable content EmblemExtraEmblemUnlockableConditionSet
Miscellaneous WipesCharacterLevelCutscene / ScenePromptMenuHudItem
Related links ActionsConstantsCustom Object tutorial