A WAD file is a data library for any program that runs on the Doom engine, including SRB2. The term "WAD" is an acronym for Where's All the Data?. WAD files can contain a wide variety of resources, such as maps, scripts, graphics, sound effects or music. An individual piece of data in a WAD file is called a lump, and programs that allow the user to manage the lumps of a WAD file are called lump editors.
With the exception of SRB2's included resource files, WAD files are typically added as modifications to the game; when one is added, the game will detect this and mark itself as "modified". Exceptions to this are WAD files purely consisting of digital/MIDI music, sounds, select HUD-related graphics, and/or custom palettes, all of which will affect only the user's end and are therefore able to be added by the user within netgames. WAD files with custom gamedata files (determined via the
MainCfg SOC block) can also partially bypass the game's modification check – any WADs added previously to these will also not count as modifying the game afterwards.
- 1 Format
- 2 Types of WAD files
- 3 Contents
- 4 Loading WAD files
- 5 Creating and editing WAD files
- 6 References
- 7 External links
A WAD file consists of three components: a header, a directory that lists all the lumps in the file, and the lump data itself.
A WAD file always starts with a 12-byte header. It contains three values:
||4-character ASCII string||Designates the type of WAD file, i.e., "IWAD", "PWAD", "ZWAD" or "SDLL". See Types of WAD files for an explanation.|
||Unsigned 32-bit integer||Specifies the number of lumps in the WAD file.|
||Unsigned 32-bit integer||Stores the offset to the start of the directory in the file.|
The directory lists the names of all lumps in the WAD files and links them to the associated lump data via a pointer. The number of entries in the directory is therefore the number of lumps as set in the header. Each entry has a length of 16 bytes and consists of the following values:
||Unsigned 32-bit integer||Stores the offset to the start of the lump's data in the file.|
||Unsigned 32-bit integer||The size of the lump in bytes. If the size is 0, the lump is a marker lump that has no data and merely serves to organize the WAD file.|
||8-character ASCII string||The lump's name, which can have up to 8 characters. The string must be null-terminated if shorter than 8 bytes.|
Types of WAD files
There are four types of WAD files that can be used in SRB2: IWAD, PWAD, ZWAD and SDLL. The type is specified in the first four bytes of the header, e.g., the first four bytes of a PWAD file are
PWAD. To view and change the type of a WAD file, it must be opened with a hex editor.
The internal WAD, or IWAD, is the main WAD file for a Doom-based game. It normally contains all of the basic resources for the game, and is the first WAD file to be loaded upon starting the game. In the original Doom, this file is called
DOOM.WAD. In SRB2's case (Prior to 2.2), it was called
srb2.srb. Unlike most Doom-based games, SRB2 only stores some of its data in the IWAD, mainly graphics and sound effects. Other data, such as player sprites, maps and music, is stored in additional WAD files.
A patch WAD, or PWAD, is a WAD file that is added to the game after the IWAD has been loaded. This includes all of SRB2's resource WADs except for
srb2.srb, as well as addon files that are loaded by the user. A PWAD may supply additional resources or replace resources from the IWAD. PWAD is the most common type of WAD file, and files that are newly created by WAD editors will always have this type.
A ZWAD is a compressed PWAD. The external tool Wadzip can create ZWADs as well as convert them back to PWADs. ZWADs cannot be opened directly by standard WAD editors such as SLADE or XWE, and cannot be directly converted to other WAD file types with a hex editor due to being compressed – for these reasons, they are therefore sometimes used for obfuscation.
SDLL is a special type that can be used to obfuscate WAD files, usually to hide secret resources. SDLL files are structurally identical to PWADs, but due to the different header, WAD editors cannot open them (unless the type is manually changed to PWAD with a hex editor). SDLLs were used in old versions of SRB2 to disguise WAD files that were used for date-activated secrets as DLL files. For example, the resources for Christmas mode were stored in a file called
3drend.dll, which was actually an SDLL file with a changed file extension. Several community members also used SDLLs to hide secret data in a similar fashion. Since the secrets that made use of SDLL files have since been removed from SRB2, they are no longer used officially.
WAD files are organized as a collection of lumps – these are pieces of data such as graphics, music, sounds, maps and various other types of resources. Each lump is identified by a name that consists of eight characters or less. If two lumps with the same name are loaded by the game, the one that was loaded last will replace the first one (except in a few special cases). This makes it possible for addons to replace SRB2's native resources by giving the replacement lump the same name as the original lump from SRB2's resource files.
This section details the various types of lumps that are recognised by SRB2, giving brief details on each:
Markers are lumps that do not contain any content and are merely used to organize the contents of a WAD file. However, certain pairs of marker names have special significance to lump editors (such as SLADE) as well as SRB2 itself in most cases:
|Start marker||End marker||Usage|
||Flat delimiters. (alternative)|
||Patch delimiters. These are not actually recognised by SRB2 itself – patches can be placed freely in a WAD file without use of these markers.|
||Sprite delimiters. (alternative)|
||Texture delimiters – all graphics located between these are converted into single-patch textures. The names of the newly-created textures will be the lump names of their respective graphic lumps.|
||Screen fade fading mask delimiters – these markers are not actually recognised by SRB2 itself, but are needed by SLADE to identify fading mask graphics as the correct type of lump.|
Maps are stored as a collection of several consecutive lumps that must follow each other in a strict order. These map blocks start out with a header that indicates the map number, after which several lumps that contain specific data for the map follow. Map editors provide a graphical interface that is able to read these lumps and display the map data in an easy-to-edit format, and to automatically create and modify these lumps upon saving a map.
Scripts are text lumps that have special significance in SRB2, the contents of which are run immediately on loading them into the game. There are three main types of scripts in SRB2:
- SOCs: These scripts can be used to define certain types of custom data, such as Objects, level headers or cutscenes. Any lump whose name is
OBJCTCFGor starts with the prefix
SOC_, such as
SOC_OBJS, is interpreted as a SOC script and loaded automatically when a WAD file is added.
- Lua scripts: These scripts contain Lua code. Any lump with the prefix
LUA_, such as
LUA_GAME, is interpreted as a Lua script and loaded automatically when a WAD file is added.
- Console scripts: These scripts automatically execute console commands. While these can be created as external files, they are often integrated into WAD files as lumps to be executed either upon loading the WAD file (via the
ExecCfgparameter in the
MainCfgblock), or inside a level (with linedef type 415).
- Flats: These are the graphics displayed on floors and ceilings. They should be placed between the marker lumps
- Textures: These are the graphics displayed on walls. Textures that consist of a single image (or a "patch") are located between the marker lumps
TX_END. Composite textures that consist of multiple images can be defined in the
TEXTURESlump, while additional images for these composite textures can be stored between the marker lumps
- Sprites: These are the graphics displayed by in-game Objects. They should be placed between the marker lumps
- Screen fades: These are a type of special effect that use graphic lumps known as "fading masks" to transition from one screen to another. The fading masks should be placed between the marker lumps
- Other graphics: Graphics are also used for various other purposes, such as the title screen, menus, cutscenes and the heads-up display. These graphics can be stored anywhere in a WAD file. See List of graphics for a full list of miscellaneous graphics used in SRB2.
Other types of lumps
- Playable characters: Playable characters consist of two components: The character metadata, such as the name and the stats, is defined in a text lump called
S_SKIN. The sprites for the characters should be placed immediately after this lump. Unlike normal sprites, no marker lumps are needed for these.
- Sound effects and music: Sound and music files can be stored as lumps in WAD files in various formats, including WAV, Ogg, MP3, MIDI, IT and MOD. See the sound and music tutorial for more information.
- Demos: Recorded playback demos, such as the ones used for Record Attack or on the title screen, can be stored as lumps in WAD files as well. Players can play back these demos with the
- Palettes: See Palette > Technical information for more information.
Some lump names are reserved for special purposes, some of which include:
SOC_name: SOC lumps with these names are automatically loaded when the WAD file is added to the game.
LUA_name: The prefix
LUA_is used for Lua scripts. The rest of the lump name is flexible and can be anything, e.g.
S_SKIN: This is a text lump that defines a playable character skin. The lump name is partially flexible; "S_SKIN1", "S_SKIN2", and so on can all be used too, as the game will only search for the "S_SKIN" part of the name to load it. See the custom character tutorial for more information on creating a playable character.
TEXTURES: This lump is used to define composite textures, which are textures that consist of more than one image.
ANIMDEFS: This lump is used to define animated flats and textures. See the custom textures tutorial for more information.
PLAYPAL: This lump defines the default palette of 256 colors that is used by the game.
COLORMAP: This lump defines how the palette colors are adjusted for different light levels by default.
PALxxxx: This lump defines a custom palette for a map. See Level header > Palette for more information. xxxx is a four-digit number between 0000 and 9999.
CLMxxxx: This lump defines the colormap adjustments for the corresponding palette in
PALxxxx. See Level header > Palette for more information. xxxx is a four-digit number between 0000 and 9999.
DEMO_xxx: These are the playback demos that are played on the title screen. See MainCfg > Title screen demos for more information. xxx is a three-digit number between 000 and 999.
MAPxxMS: These are special replays for Metal Sonic to use to move through a level, for races against Metal Sonic himself such as in Egg Rock Zone Act 3. xx is the two-digit form of the map number; for slots above 99, extended map numbers must be used. See Metal Sonic race tutorial for more information.
Loading WAD files
To add WAD files to SRB2, the files must either be in the same directory as SRB2 or in a subdirectory. There are several different methods of adding a WAD file to the game:
- Method 1) Use the Addons menu, which can be accessed from the main menu. Browse to the file you want to load and then press Enter to add it.
- Method 2) Use the
- Method 3) Use the
-filecommand line parameter:
- Option a) Under Windows, go to Start Menu → Run and type in
(SRB2 directory name)\srb2win -file filename.wad. You must enter the directory name as the DOS command prompt would display it.
- Option b) Create a batch file with the contents
srb2win -file filename.wad, and execute it.
- Option a) Under Windows, go to Start Menu → Run and type in
- Method 4) Use a custom launcher program, which can be found on the Miscellaneous releases page on the Message Board. Programs like startSRB2 by Shardvevx or SRB2 Launcher by SonicFreak94 are a few examples of what you can find.
To remove a WAD file from the game, the game must be restarted.
Creating and editing WAD files
To create WAD files and manage their contents, you need a lump editor. The most commonly used lump editor in the SRB2 community is SLADE. The lump editor will allow you to easily create a new WAD file and import your data. For raw resources such as music, all you need to do is import the data into your WAD file. For other types of data, additional steps may be required. Consult the following articles for further help:
- Level design – For custom levels.
- Custom character tutorial – For custom characters.
- SOC – For SOCs.
- Lua – For Lua scripts.
- Custom textures tutorial (SLADE) and Custom textures tutorial (XWE) – For custom textures.
- Sound and music tutorial – For custom sound effects or and music.
If you want to replace data that is already present in the game (such as changing the title screen, for example), simply give the replacing lump the same name as the lump that you want to replace, and store it in a new WAD file. Once you load that WAD file, the game will replace the original resource with the contents of your new lump.
A PK3 is a special type of compressed file that contains the same type of data that WAD files do, but data can easily be organized into folders and all data is compressed, much like an actual zip file you would open with your favorite .ZIP viewer. (In fact, PK3 files themselves can be opened with one!) However, PK3 files must still be opened or created and edited within a lump editor, otherwise the correct header information will not be generated, and the game will not load the file. As of Version 2.2, SRB2's data has been moved to a special PK3 called an IPK3, named
srb2.pk3. PK3s also support MD2 models for OpenGL, and can even contain internal PWADs. (In
zones.pk3, each map is stored within its own individual WAD file.) It is recommended to use the PK3 format when creating content for 2.2 or Kart, as the folder structure makes it easier than ever to organize and correctly replace content, and can be directly uploaded to and downloaded from the Message Board. Some content can't be replaced or added without one, such as Skies.
Naming conventions for content
WAD files and PK3 files are generally expected to be named with any of the following letters, representing gametypes and other content supported within the file, as a prefix followed by the name of the WAD or PK3:
- V – Used to be required by all Vanilla SRB2 files. This rule was changed in June 21st, and newly made mods should not use this prefix.
- K – Required by all SRB2 Kart files.
- X – Required for mods that support both SRB2 and SRB2 Kart.
- S – Contains a map for Single Player, Cooperative, and Competition
- M – Contains a map for Match/Team Match and Tag/Hide & Seek
- R – Contains a map for use in Race only, as well as SRB2 Kart tracks.
- F – Capture the Flag
- B – Contains a map for Battle Mode in SRB2 Kart.
- C – Contains a Character
- L – Contains Lua scripting.
(The order is important!)
The name of the file must then be followed with a dash and a version number, such as
For example, if you were to, say, have a map pack containing a character, Lua, a single player map, a match map, a Capture the Flag map, and a race map for vanilla SRB2, and it were a version 2.0 for said pack, the name would be
For SRB2 Kart, a file containing a Lua equipped character, a race track, and a battle arena would be named
For more information, see the announcement on filename conventions in the SRB2MB's Submissions forum.