Birthright: The Gorgon's Alliance Modding Reference

Reference information for creating new adventures, modifying textures, and other modding. This may get split into multiple documents in the future. It is currently under construction and may change often.

Definitions

Thing

A collectible object, decoration, or person in an adventure. This term comes from Doom’s WAD format, which is used for adventure maps.

Pascal case

Text formatted with no spaces, and capitalizing the first letter of each word. Ex: QuestTypeThing.

Setting up a development environment

There are several options for building Doom levels. My testing has mostly been done using SLADE 3 and the ZenNode (v1.2.1) node builder. Here is information on the setup I use for you to replicate if you chose.

To duplicate my setup, install Slade 3 and unzip ZenNode to a permanent place. Then, follow these steps:

1. Open SLADE.
2. Ignore these steps for now. I’m still working on the feature in BRUT that will build Birthright.wad.
   1. Click Edit → Set Base Resource Archive.
   2. Click the Add Archive button.
   3. Find and open Birthright.wad, then click OK.
3. Click Edit → Preferences….
4. Expand Map Editor, then select Node Builder.
5. Set the Node Builder: field to ZenNode.
6. Click Browse and find and open ZenNode.exe.
7. In the Options section, check Vanilla Optimized, and click OK.

Testing maps

You can launch directly into your WAD when starting Birthright by using the following command line options:

WINBR.EXE w C:\BIRTHRT\WADS\MYWAD.WAD

There will be no sound, actions, or living enemies, but you can wander around the map live in the game. These features come from the scene file, which isn’t loaded this way.

If you use Ultimate Doom Builder, you can configure the “Test Map” feature to run your map directly in Birthright.

1. Go to Tools → Game Configurations → Testing.
2. Click the + button to add a new testing engine.
3. Give the egine a name and browse to WINBR.EXE on your computer.
4. Check Customize parameters.
5. Enter w %F into the Parameters field and check the checkbox for Use short paths and file names (MSDOS 8.3 format).

SLADE unfortunately uses path variables with quotes and Linux-style path separaters, which Birthright doesn’t understand.

Format documentation: Adventure maps (.WAD)

The WAD file format (Birthright uses vanilla PWADs) was created to store game data for Doom and the Doom family of games. It is a well defined file type. Please review the format information on DoomWiki.

Note: Birthright uses PWADs and does not have an IWAD. See Setting up a development environment for more information.

Format documentation: Scenes (.SCN)

Scene files use a format that resembles INI files. There are many options listed in the template that may not be usable, as they refer to a World Map feature that seems absent from the game.

Scene files appear to be the entry point into Dynamix’s Nova engine. They are used for adventures and battles. SCENES\TEMPLATE.SCN contains developer documentation on the scene file format, but it is unclear how up to date this documentation is. For this reason, there are keywords mentioned in that file that are not referenced here.

Comments

Comments must be placed on an empty line, starting with the number sign (#). If a scene file is edited using the scene editor (SCENED), all comments are lost.

Keywords

Keywords are variable names written using Pascal casing (ex: QuestThingType). These are used by Nova to initialize adventures.

Required keywords

• Version: Always 1.0

Optional keywords

• Type:
  • 1: A custom adventure.
• Music:
• Demo:
• Panorama:
• QuestThingType: The Thing ID of the item that will complete the quest. This must come before [Wad].
• Wad: The WAD file to load. Only one WAD file can be loaded per scene.
• Exit: A list of exit line IDs and the scene to move to. This is used to link different WADs together. Each WAD needs a corresponding scene file.
• Pallet: The PCX palette to use to load textures.

Mod-heavy keywords

These keywords can be used in custom adventures, but require making modifications to more game assets. This would be useful for total conversions where the resource files are already being replaced.

• Notes: Notes are scrolls in an adventure that can be opened to read a message inside. These reference messages found in STRDAT.DAT.
• OpeningDialog: This opens a dialog at the start of the adventure with the indicated message found in STRDAT.DAT.

Format documentation: Descriptions (.TXT, .ADV)

Format documentation: Character stats (.AVA)

Format documentation: Resources (.RES)

 

The resource file management software and its associated C# library BRUT can be used to manage resource files.

Resource files hold most of the images, textures, UI elements, animations, and sounds used in the game. They are similar to ZIP files.

Files are stored either uncompressed or compressed via LZSS. PCX files are pre-processed and uncompressed into a bitmap format (not the standard BMP file) before being compressed with LZSS and stored.

Note: It is impossible to restore PCX files losslessly, as resource files do not store some file metadata, including the color palette. A standardized set of color palettes is used internally. BRUT uses the most common palette to attempt to recover these files.

The files begin with a file header describing the file version, the number of resources contained within, and the offset of the directory.

The directory contains one meta entry for each resource contained in the file.

Hash

The entry begins with a hash that identifies the file. This has is either generated from a “CRC” of the filename (case sensitive) plus a null byte, or by copying an ID number directly from the filename.

Extension identifier

The list of supported extensions is hard-coded into Birthright as an array. The extension identifier is the index of the file’s extension in that array.

Each file is then stored as follows:

Resource identifier

The resource identifier is the integer representation of the string “RSRC”.

The original RESUTIL used to create the resource files allowed adding the same file multiple times, appending it each time. Retrieving the file would only reference the first instance.

Thing reference

Each Thing has an ID number, which is used to all things related to it. (Art, descriptions, etc.) Troops are presumably used in the battle maps. They don’t seem to appear when used in adventures.