Freeslot

From SRB2 Wiki
(Redirected from Freeslots)
Jump to: navigation, search

Freeslots are additional empty slots for Object types, states, sprites and sounds. These slots allows SOCs and Lua scripts to create completely new resources without overwriting old ones, which allows for new types of Objects to be created in addition to all the already existing ones. There are 256 freeslots for Object types and sprites, 2048 for states, and 800 for sounds. If freeslots are not used, the modified Object types will change their behavior when such a SOC is loaded, even if that might not be desirable. For example, if a pushable version of an intangible scenery Object is created by simply making the original Object type pushable, all instances of the Object type will become pushable, even in maps where that might not desirable. Creating a copy of the Object type and, if necessary, its states in the freeslot locations prevents this issue.

Declaring freeslot names

Since v2.1, SRB2 allows declaration of custom names for freeslots, which enables use of them as named constants representing a number (similar to FRACUNIT, TICRATE and also existing names for Object types/states/sprites/sounds) later in the same script or in following scripts, whether SOC or Lua. As such there are two main ways of declaring them:

SOC

In SOC lumps such as the MAINCFG, freeslot names are declared using the Freeslot header. Anything below this header will be turned into a freeslot name for a particular type of freeslot, as long the prefixes of the names are one of the following:

  • MT_ – for Object type names.
  • S_ – for state names.
  • SPR_ – for sprite names. The name following this must be 4 characters long.
  • sfx_ – for sound names. The name following this can be any length up to 6 characters long maximum. If the corresponding sound lump in a WAD is called DSCUSTOM, for example, then the respective sound name here should be sfx_custom.

The newly declared freeslot name will automatically take up the next available numbered free slot for the type set. Ideally any name following the prefix should be unique to this freeslot (and never repeated within freeslot declarations elsewhere in the script or in the rest of the WAD) so as to not cause any conflicts, whether with freeslots declared in other WAD files or freeslots declared in the same WAD file.

Example usage:

Freeslot
MT_OBJECTTYPE
MT_OBJECTTYPE2
S_STATENAME
S_STATENAME2
S_STATENAME3
SPR_SPRT
sfx_custm1
sfx_custm2

It does not matter what order the different types of freeslot names are placed relative to each other in a freeslot block; names for Object types, states, sprites and sounds can be freely mixed together in any order. The ordering of freeslot names of the same type (e.g. states) relative to each other does not strictly matter either, but it will affect how actions such as A_RandomStateRange interpret their values.

In SOC, it doesn't matter which letter case the names are declared in, as they will be converted to the correct case internally. It does not matter whereever the freeslot block is placed in a SOC lump, as long as it comes before any and every instance of any of the names being used in the script.

Warning icon.png Note that if any freeslot name has already been declared in a Lua script, it should not be re-declared in SOC as well – this just makes the game declare two freeslots with the same name, which can cause issues and wastes available freeslots. Lua scripts are always loaded before SOCs and therefore take priority over them regarding freeslots.

Lua

Lua's version of freeslot name declaration is similar to SOC's, except making use of the base function freeslot() instead:

freeslot(
"MT_OBJECTYPE",
"S_STATENAME",
"SPR_SPRT",
"sfx_custom"
)

Here, all new freeslot names must be declared as strings, so quotation marks (") are needed around every individual name. The names must also be separated by commas (,) so to separate each freeslot name declared. Other than these points, the choice of formatting is slightly more flexible: freeslot names can be laid out as a vertical list as shown above, or all laid out in the same line as below:

freeslot("MT_OBJECTYPE", "S_STATENAME", "SPR_SPRT", "sfx_custom")

However, unlike in SOC, Lua is case-sensitive with names – Object type, state and sprite names are all expected to be in all-uppercase, while sound names should be in all-lowercase.

  Sonic Object Configuration [view]
General ClearMainCfg
Objects ObjectStateSoundFreeslot
Unlockable content EmblemExtraEmblemUnlockableConditionSet
Miscellaneous WipesCharacterLevelCutscene / SceneHudItem
Related links ActionsConstantsObject creation tutorial