Custom unlockables and emblems

From SRB2 Wiki
(Redirected from Custom unlock)
Jump to navigation Jump to search

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. The Var 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:
  • GE_NIGHTSPULL: The emblem can be pulled by a paraloop.
  • GE_NIGHTSITEM: The emblem is invisible until paralooped, like a NiGHTS power-up.

The two flags can be combined with the bitwise OR operator (|), i.e., GE_NIGHTSPULL|GE_NIGHTSITEM.

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., ME_ALLEMERALDS|ME_PERFECT. In this case, the player is allowed to fulfill each condition on a different playthrough.

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 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:
Frame Image Description
A Used by SRB2 for in-map emblems
B Used by SRB2 for in-map emblems
C Used by SRB2 for in-map emblems
D Used by SRB2 for in-map emblems
E Used by SRB2 for in-map emblems
F Used by SRB2 for the global "Conquer the Challenge Levels!" emblem
G Guard/shield symbol, unused in SRB2
H Used by SRB2 for the global "Complete 1P Mode with all Emeralds" emblem
I Invincibility symbol, unused in SRB2
J Armageddon symbol, unused in SRB2
K Chain/Link symbol, unused in SRB2
L Used by SRB2 for in-map NiGHTS emblems
M Used by SRB2 for in-map NiGHTS emblems
Frame Image Description
N Free slot
O Repeat/loop symbol, unused in SRB2
P Perfect Bonus symbol, unused in SRB2
Q Used by SRB2 for the A rank NiGHTS emblems
R Used by SRB2 for the map-specific ring emblems
S Used by SRB2 for the map-specific score emblems
T Used by SRB2 for the map-specific time emblems
U Used by SRB2 for the global "Complete 1P Mode" emblem; can be used for Sonic-only in-map emblems
V Can be used for Tails-only in-map emblems
W Can be used for Knuckles-only in-map emblems
X Can be used for Metal Sonic-only in-map emblems
Y Can be used for Fang-only in-map emblems
Z Can be used for Amy-only in-map emblems
  • 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 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 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:
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: See Type 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
Retrieved from "https://wiki.srb2.org/w/index.php?title=Custom_unlockables_and_emblems&oldid=114476"