Custom unlockables and emblems - SRB2 Wiki (2024)

SRB2 allows custom modifications to create their own unlockables and emblems via SOC. The system for unlockables and emblems is flexible and allows the user to create a wide variety of requirements and rewards.

Setting up the script

In order to modify unlockables and emblems, your modification needs its own gamedata file, so that it can save the player's progress. The gamedata file can be set with the GameData parameter in the MainCfg block, like this:

MainCfgGameData = supergame.dat

You might also want to remove SRB2's own unlockable and emblem data to prevent it from accidentally showing up in your own mod. This can be done by inserting Clear commands after the MainCfg block (not inside it!), like this:

Clear UnlockablesClear EmblemsClear ExtraEmblemsClear ConditionSets#Removes SRB2's level headers, which is not necessary for unlockables but useful in other contextsClear Levels#This does all of the previous actionsClear All

Map-specific emblems

These emblems are tied to a specific map, either being placed directly on the map for the player to collect, or being awarded for meeting a certain requirement after playing the map. They are defined with the following syntax:

• Emblem n is the header of each block. n optionally sets the number of the emblem. This is useful when overwriting an existing emblem, or if the emblem is referenced by a condition set. If no number is supplied, it defaults to the next free number.
• Hint sets the hint that is displayed for the emblem in the emblem hints menu. Leave this parameter out if no hint should be available. Unlike most other SOC parameters, lowercase letters are recognized as such here. Line breaks can be inserted with \\. This parameter supports custom colors, but be warned that the automatic green highlight that the text is given after the emblem has been collected will override any text colors specified.
• Type sets the type of the emblem. The Var parameter is used to further specify the requirement for each type of emblem. The following types are available:

• Tag is used to define where the emblem appears in the map if it is an in-map emblem. An emblem Thing must be placed in the map whose Angle value is equal to this value. The X, Y and Z position of the emblem Thing define where the emblem will appear. For emblems that are not placed directly in the map, this parameter can be omitted.
• MapNum sets the number of the map which the emblem belongs to, e.g., A1 for MAPA1.
• Sprite sets the frame number of the sprite that the emblem uses. The free slots can be used by importing a sprite with the name EMBM#0, where # is the frame number. The following frames are available:

• Color sets the color of the emblem as a SKINCOLOR_X constant, where X is the name of color, e.g., SKINCOLOR_RED. See List of skin colors for a full list of available colors.
• Var: See Type above.

Example

Emblem 1Hint = This is a hint.Type = SkinTag = 2MapNum = 1Sprite = UColor = SKINCOLOR_BLUEVar = 0

This emblem is the first one in the game. It is located in MAP01 and can only be collected as Sonic. It appears at the location of the emblem Thing with Angle value 2. It displays a blue Sonic logo.

Global emblems

Global emblems are not tied to a specific map and can be obtained by meeting a certain game-wide requirement. Limited to 48 total, they are defined with the following syntax:

• ExtraEmblem n is the header of each block. n optionally sets the number of the emblem. This is useful when overwriting an existing emblem, or if the emblem is referenced by a condition set. If no number is supplied, it defaults to the next free number. The numbering for both types of emblems is separate, so a global emblem may use the same number as a map-specific emblem.
• Name sets the name of the emblem, which is displayed on-screen when it is obtained. Max length: 19 characters.
• Objective sets the message that is displayed for the emblem on the Statistics screen.
• ConditionSet sets the number of the condition set that has to be met to obtain the emblem. See below for information on setting up condition sets.
• Sprite sets the frame number of the sprite that the emblem uses. See above for the possible values.
• Color sets the color of the emblem. See above for the possible values.

Examples

ExtraEmblem 1Name = PerfectObjective = Perfect Test Map AConditionSet = 11ExtraEmblem 2Name = UltimatimObjective = Beat Test Map A on UltimateConditionSet = 12

Unlockables

Limited to a total of 80, unlockables are defined with the following syntax:

• Unlockable n is the header of each block. n sets the number of the unlockable. The unlockables will appear on the extras checklist in the order in which they are numbered.
• Name is the name of the unlockable as it is displayed on the extras checklist, and in the extras menu once it is unlocked. This parameter supports custom colors, but they will only display on the extras checklist.
• Objective sets the message that is displayed for the unlockable on the extras checklist. This parameter also supports custom colors.
• Height sets the vertical position of the unlockable in the extras menu. To properly space out the items, the height should be a multiple of 10.
• ConditionSet sets the number of the condition set that has to be met to unlock the unlockable. See below for information on setting up condition sets. For unlockables that are already unlocked when the game is started, use -1.
• NoCecho determines whether an on-screen message is displayed when the unlockable in unlocked (false) or not (true). The default value is false.
• NoChecklist determines whether the name of the unlockable is visible on the extras checklist (false) or replaced with question marks (true) before unlocking. The default value is false.
• Type determines the type of the unlockable. The Var parameter is used by the types LevelSelect and Warp for further specification. The following types are available:

• Var: See Type above.

Examples

Unlockable 1Name = Custom Sound TestObjective = Beat Test Map A with All EmeraldsType = SoundTestHeight = 20ConditionSet = 1Unlockable 2Name = Custom Warp 1Objective = Earn an EmblemType = WarpVar = 2Height = 110ConditionSet = 2[...]Unlockable 10Name = Custom HeaderHeight = 100[...]Unlockable 20Type = RecordAttackNoCecho = trueNoChecklist = trueConditionSet = -1

Condition sets

Condition set define the requirements for earning unlockables and global emblems. Up to 128 condition sets can be specified.

Each condition set consists of a header, followed by a number of conditions with the syntax Condition# = [Condition name] <parameters>. # indicates the ID of the condition, which can be used to group several conditions together to create a more complex requirement. If multiple conditions share the same ID, all of them have to be met. If there are multiple conditions with different IDs, only one of them has to be met. Consider the following example:

ConditionSet 1Condition1 = MapBeaten A1Condition1 = GameClear 2Condition2 = MapRings A2 500Condition2 = TotalEmblems 10

For this condition set to be met, either Condition1 or Condition2 has to be satisfied. Condition1 can be satisfied by beating MAPA1 and beating the game twice. Condition2 can be satisfied by collecting 500 rings on MAPA2 and collecting 10 emblems.

Below is a list of all the conditions, their syntax, and what they mean. [Brackets] designate a required parameter, and <angled brackets> designate an optional parameter.

• PlayTime [tics]: Requires the player to accumulate at least the specified amount of total play time in the game to unlock.

• GameClear <x times>: Requires the player to clear the game the specified number of times. Defaults to 1 if the parameter is omitted.

• AllEmeralds <x times>: Requires the player to clear the game with all emeralds the specified number of times. Defaults to 1 if the parameter is omitted.

• UltimateClear <x times>: Requires the player to clear the game in Ultimate mode the specified number of times. Defaults to 1 if the parameter is omitted.

• OverallScore [score]: Requires the player's total score in all Record Attack maps to be above the specified score.

• OverallTime [tics]: Requires the player's total time in all Record Attack maps to be below the specified time.

• OverallRings [rings]: Requires the player's total rings in all Record Attack maps to be above the specified amount.

• MapVisited [map number]: Requires the player to visit the specified map. Does not require them to complete the map, however.

• MapBeaten [map number]: Requires the player to complete the specified map.

• MapAllEmeralds [map number]: Requires the player to complete the specified map with all emeralds.

• MapUltimate [map number]: Requires the player to complete the specified map in Ultimate mode.

• MapPerfect [map number]: Requires the player to complete the specified map with a perfect bonus.

• MapScore [map number] [score]: Requires the player to achieve the specified score on the specified map. This must be done in Record Attack.

• MapTime [map number] [tics]: Requires the player to achieve the specified time on the specified map. This must be done in Record Attack.

• MapRings [map number] [rings]: Requires the player to collect the specified amount of rings on the specified map. This must be done in Record Attack.

• NightsScore [map number] <mare> [score]: Requires the player to achieve the specified score on the specified NiGHTS map, either overall (if the second parameter is omitted) or on a specific mare. This does not need to be achieved in NiGHTS Mode, and can in fact be achieved when playing the game normally.

• NightsTime [map number] <mare> [tics]: Requires the player to achieve the specified time on the specified NiGHTS map, either overall (if the second parameter is omitted) or on a specific mare. This does not need to be achieved in NiGHTS Mode, and can in fact be achieved when playing the game normally.

• NightsGrade [map number] <mare> [grade]: Requires the player to achieve the specified grade on the specified NiGHTS map, either overall (if the second parameter is omitted) or on a specific mare. This does not need to be achieved in NiGHTS Mode, and can in fact be achieved when playing the game normally. 0 is F, 1 is E, 2 is D, 3 is C, 4 is B, 5 is A, and 6 is rainbow A.

• Trigger [trigger number]: Used in tandem with the Condition Set Trigger linedef executor to allow events inside of a map to fulfill conditions. To fulfill this condition, include a Condition Set Trigger linedef with the same trigger number in a linedef executor chain and activate it.

• TotalEmblems [number of emblems]: Requires the specified number of emblems to be collected. This counts both map-specific and global emblems.

• Emblem [emblem number]: Requires the specified map-specific emblem to be collected.

• ExtraEmblem [extra emblem number]: Requires the specified global emblem to be earned.

• ConditionSet [condition set number]: Requires a previous condition set to already be achieved.

Overall example

MainCfgGameData = smallgame.datClear UnlockablesClear EmblemsClear ExtraEmblemsClear ConditionSetsExtraEmblem 1Name = Double CompleteObjective = Complete the game twiceConditionSet = 2Unlockable 1Name = Sound TestObjective = Complete the gameType = SoundTestHeight = 20ConditionSet = 1ConditionSet 1Condition1 = GameClearConditionSet 2Condition1 = GameClear 2

Retrieved from ""