WAD file

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.

Format

A WAD file consists of three components: a header, a directory that lists all the lumps in the file, and the lump data itself.

Header

A WAD file always starts with a 12-byte header. It contains three values:

Bytes	Data type	Content
0x00–0x03	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.
0x04–0x07	Unsigned 32-bit integer	Specifies the number of lumps in the WAD file.
0x08–0x0b	Unsigned 32-bit integer	Stores the offset to the start of the directory in the file.

Directory

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:

Bytes	Data type	Content
0x00–0x03	Unsigned 32-bit integer	Stores the offset to the start of the lump's data in the file.
0x04–0x07	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.
0x08–0x0f	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.

IWAD

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. Since v2.2, SRB2 no longer uses an IWAD because the main resources are stored in a PK3 file called srb2.pk3. In previous versions, the IWAD was called srb2.srb. Unlike in most Doom-based games, the IWAD only contained part of the data for the game, mainly graphics and sound effects. Other data, such as player sprites, maps and music, were stored in additional WAD files.

PWAD

A patch WAD, or PWAD, is a WAD file that is added to the game after the IWAD has been loaded. Since SRB2 no longer includes an IWAD, most WAD files are PWADs, including the resource files music.dta and player.dta, as well as most 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.

ZWAD

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, 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

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.

Contents

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

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
F_START	F_END	Flat delimiters.
FF_START	FF_END	Flat delimiters. (alternative)
P_START	P_END	Patch delimiters. These are not actually recognised by SRB2 itself – patches can be placed freely in a WAD file without use of these markers.
S_START	S_END	Sprite delimiters.
SS_START	SS_END	Sprite delimiters. (alternative)
TX_START	TX_END	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.
FA_START	FA_END	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

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

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 MAINCFG or OBJCTCFG or 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_INIT and 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 ExecCfg parameter in the MainCfg block), or inside a level (with linedef type 415).

Graphics

• Flats: These are the graphics displayed on floors and ceilings. They should be placed between the marker lumps F_START and F_END.
• 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_START and TX_END. Composite textures that consist of multiple images can be defined in the TEXTURES lump, while additional images for these composite textures can be stored between the marker lumps P_START and P_END.
• Sprites: These are the graphics displayed by in-game Objects. They should be placed between the marker lumps S_START and S_END.
• 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 FA_START and FA_END.
• 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 playdemo console command.
• Palettes: See Palette > Technical information for more information.

Special lumps

Some lump names are reserved for special purposes, some of which include:

• MAINCFG, OBJCTCFG and 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. LUA_GAME or LUA_INIT.
• 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 addfile console command:

Option a) Open the console and enter addfile filename.wad.

Option b) Add the line addfile filename.wad to the autoexec.cfg file in your SRB2 directory (you may need to create the file yourself if it does not exist already). Note that this method will load the WAD file every time you run the game. If you are attempting this method with SRB2Kart, please note Kart uses "kartexec.cfg" instead.

• Method 3) Use the -file command 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.

• Method 4) Use a custom launcher program, such as LauncherBlast2 reBoot.

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.

PK3

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 released via the Addons & More section on the SRB2 Message Board must follow specific naming conventions. The filename should be prefixed with the following letters depending the type of content included in the file:

• V – Used to be required by all vanilla SRB2 files, but is now deprecated. Newly made files should not use this prefix.
• K – Required by all SRB2Kart files.
• X – Required for mods that support both SRB2 and SRB2Kart.
• S – Contains a map for Single Player, Cooperative or Competition.
• M – Contains a map for Match/Team Match or Tag/Hide & Seek.
• R – Contains a map for use in Race only, or an SRB2Kart track.
• F – Contains a map for Capture the Flag.
• B – Contains a map for Battle Mode in SRB2Kart.
• C – Contains a custom character.
• L – Contains a Lua script.

If multiple prefixes apply, they are listed in the order given here.

The name of the file must then be followed with a dash and a version number, such as -v2.2.

For example, version 2.0 of a map pack for vanilla SRB2 containing a character, a Lua script, a Single Player map, a Match map, a Capture the Flag map, and a Race map would be named SMRFCL_MyCreativeFileName-v2.0.pk3. For SRB2 Kart, the first release of a file containing a Lua-equipped character, a race track, and a Battle arena would be named KRBCL_MyKartContent-v1.0.pk3.

External links

• WAD – The Doom Wiki
• Download for Wadzip, a WAD file compression tool