Custom unlockables and emblems
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:
MainCfg GameData = 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 Unlockables Clear Emblems Clear ExtraEmblems Clear ConditionSets #Removes SRB2's level headers, which is not necessary for unlockables but useful in other contexts Clear Levels #This does all of the previous actions Clear 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. TheVar
parameter is used to further specify the requirement for each type of emblem. The following types are available:
Value | Description | Var |
---|---|---|
Global
|
The emblem is hidden in the map and can be collected by any character. | Flags for alternative behaviors in NiGHTS maps:
The two flags can be combined with the bitwise OR operator (|), i.e., |
Skin
|
The emblem is hidden in the map and can only be collected by a specific character. | Specifies the skin number of that character: Sonic is 0, Tails is 1, Knuckles is 2, Amy is 3, Fang is 4, and Metal Sonic is 5. |
Score
|
The emblem is awarded for achieving a certain score in Record Attack. | Specifies the score to achieve. |
Time
|
The emblem is awarded for achieving a certain time in Record Attack. | Specifies the time to achieve in tics. Multiply the value with the constant TICRATE (35) to convert it to seconds.
|
Map
|
The emblem is awarded for completing the specified level. | Flags for extra conditions:
These flags can be combined with the bitwise OR operator (|), e.g., |
Rings
|
The emblem is awarded for collecting a certain amount of rings in Record Attack. | Specifies the amount of rings to collect. |
NGrade
|
The emblem is awarded for achieving a certain grade in NiGHTS Mode. | Specifies the grade to reach as a GRADE_X constant, where X is the grade (S, A, B, C, D, E or F).
|
NTime
|
The emblem is awarded for achieving a certain time in NiGHTS Mode. | Specifies the time to achieve in tics. Multiply the value with the constant TICRATE (35) to convert it to seconds.
|
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
forMAPA1
.Sprite
sets the frame number of the sprite that the emblem uses. The free slots can be used by importing a sprite with the nameEMBM#0
, where # is the frame number. The following frames are available:
Color
sets the color of the emblem as aSKINCOLOR_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
: SeeType
above.
Example
Emblem 1 Hint = This is a hint. Type = Skin Tag = 2 MapNum = 1 Sprite = U Color = SKINCOLOR_BLUE Var = 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 1 Name = Perfect Objective = Perfect Test Map A ConditionSet = 11 ExtraEmblem 2 Name = Ultimatim Objective = Beat Test Map A on Ultimate ConditionSet = 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 isfalse
.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 isfalse
.Type
determines the type of the unlockable. TheVar
parameter is used by the typesLevelSelect
andWarp
for further specification. The following types are available:
Value | Description | Var |
---|---|---|
None
|
Used internally by the game for unlockables which are not accessible via the extras menu, but may appear in the checklist. Unmodified SRB2 uses this for the entries associated with unlockable characters, but this is not mandatory. | N/A |
ItemFinder
|
The emblem radar in the emblem hints menu. | N/A |
EmblemHints
|
The emblem hints in the pause menu. | N/A |
Pandora
|
Pandora's Box | N/A |
Credits
|
The "Play Credits" entry in the extras menu that allows the user to play the credits at any time. | N/A |
RecordAttack
|
Record Attack | N/A |
NightsMode
|
NiGHTS Mode | N/A |
Header
|
Not an actual unlockable, but a custom header in the extras menu, which can be used for layout purposes. | N/A |
LevelSelect
|
A custom level select. | The number of the level select. For example, if Var is set to 2, all levels that have a LevelSelect = 2 entry in their level header will appear in the level select. Multiple level selects can be defined in this manner.
|
Warp
|
A secret level. | The map number of the level, e.g., A1 for MAPA1 .
|
SoundTest
|
A sound test entry. To make music tracks display on the sound test page, a MUSICDEF entry is required.
|
N/A |
Skin
|
A playable character. Due to the way skins are set up in SRB2, this type only works for the first 32 unlockables. | The name of the unlocked character, as it appears in the name parameter of the character's S_SKIN . Only one character can be unlocked per unlockable.
|
Var
: SeeType
above.
Examples
Unlockable 1 Name = Custom Sound Test Objective = Beat Test Map A with All Emeralds Type = SoundTest Height = 20 ConditionSet = 1 Unlockable 2 Name = Custom Warp 1 Objective = Earn an Emblem Type = Warp Var = 2 Height = 110 ConditionSet = 2 [...] Unlockable 10 Name = Custom Header Height = 100 [...] Unlockable 20 Type = RecordAttack NoCecho = true NoChecklist = true ConditionSet = -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 1 Condition1 = MapBeaten A1 Condition1 = GameClear 2 Condition2 = MapRings A2 500 Condition2 = 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
MainCfg GameData = smallgame.dat Clear Unlockables Clear Emblems Clear ExtraEmblems Clear ConditionSets ExtraEmblem 1 Name = Double Complete Objective = Complete the game twice ConditionSet = 2 Unlockable 1 Name = Sound Test Objective = Complete the game Type = SoundTest Height = 20 ConditionSet = 1 ConditionSet 1 Condition1 = GameClear ConditionSet 2 Condition1 = GameClear 2
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 |