Custom unlockables and emblems

From SRB2 Wiki
Jump to: navigation, 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 reaching a certain requirement in Record Attack. They are defined with the following syntax:

  • Emblem n is the header of each block. n sets the number of the emblem.
  • Hint sets the hint that is displayed for the emblem in the Emblem Hints menu. Unlike most other SOC parameters, lowercase letters are recognized as such here. Leave this parameter out if no hint should be available. 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. N/A
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, and Knuckles is 2.
Score The emblem is awarded for reaching a certain score in Record Attack. Specifies the score to reach.
Time The emblem is awarded for reaching a certain time in Record Attack. Specifies the time to reach in tics. Multiply the value with the constant TICRATE (35) to convert it to seconds.
Rings The emblem is awarded for collecting a certain amount of rings in Record Attack. Specifies the amount of rings to reach.
NGrade The emblem is awarded for reaching a certain grade in NiGHTS Mode. Specifies the grade to reach, i.e. GRADE_X, where X is the rank (S, A, B, C, D, E or F).
NTime The emblem is awarded for reaching a certain time in NiGHTS Mode. Specifies the time to reach in tics. Multiply the value with the constant TICRATE (35) to convert it to seconds.
  • X, Y and Z, for emblems that are hidden in the map, define the location where the emblem will appear. These are map coordinates measured in fracunits as they can be found in map editors. X and Y are the position on the X and Y axis, while Z sets the height.
  • 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 EMBMA0.png Used by SRB2 for in-map emblems
B EMBMB0.png Used by SRB2 for in-map emblems
C EMBMC0.png Used by SRB2 for in-map emblems
D EMBMD0.png Used by SRB2 for in-map emblems
E EMBME0.png Used by SRB2 for in-map emblems
F EMBMF0.png Free slot
G EMBMF0.png Free slot
H EMBMF0.png Free slot
I EMBMF0.png Free slot
J EMBMF0.png Free slot
K EMBMK0.png Kanji symbol for score, unused in SRB2
L EMBMF0.png Free slot
M EMBMF0.png Free slot
Frame Image Description
N EMBMN0.png Used by SRB2 for in-map NiGHTS emblems
O EMBMO0.png Used by SRB2 for the global SRB1 Remake emblem
P EMBMP0.png Used by SRB2 for the global Perfect Bonus emblem
Q EMBMQ0.png Used by SRB2 for the A rank NiGHTS emblems
R EMBMR0.png Used by SRB2 for the map-specific ring emblems
S EMBMS0.png Used by SRB2 for the map-specific score emblems
T EMBMT0.png Used by SRB2 for the map-specific time emblems
U EMBMF0.png Free slot
V EMBMV0.png Used by SRB2 for the global "Complete the game with all emeralds" emblem
W EMBMW0.png Used by SRB2 for the global NiGHTS mastery emblem
X EMBMX0.png Used by SRB2 for the global "Complete the game" emblem; can be used for Sonic-only in-map emblems
Y EMBMY0.png Can be used for Tails-only in-map emblems
Z EMBMZ0.png Can be used for Knuckles-only in-map emblems
  • Color sets the color of the emblem in the format SKINCOLOR_X, 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
X = 5000
Y = -2000
Z = 1024
MapNum = 1
Sprite = X
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 5000 on the X-axis, -2000 on the Y-axis, and at a height of 1024 fracunits. 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. They are defined with the following syntax:

  • ExtraEmblem n is the header of each block. n sets the number of the emblem. 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.
  • 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

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 secrets checklist in the order in which they are numbered.
  • Name is the name of the unlockable as it is displayed on the secrets checklist, and in the secrets menu once it is unlocked. This parameter supports custom colors, but they will only display on the secrets checklist.
  • Objective sets the message that is displayed for the unlockable on the secrets checklist. This parameter also supports custom colors.
  • Height sets the vertical position of the unlockable on the secrets 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 unlockable appears on the secrets checklist (false) or not (true). 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 secrets menu, but may appear in the checklist. 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 secrets 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 secrets 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. N/A
  • 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 number of the condition. # 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 on 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 on 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 beat the specified score on the specified map. This must be done in Record Attack.
  • MapTime [map number] [tics]: Requires the player to beat 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 make this condition true, 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 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
  Sonic Object Configuration [view]
General ClearMainCfg
Objects ObjectStateSoundFreeslot
Unlockable content EmblemExtraEmblemUnlockableConditionSet
Miscellaneous WipesCharacterLevelCutscene / SceneHudItem
Related links ActionsConstantsObject creation tutorial