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. Click Edit → Set Base Resource Archive.
3. Click the Add Archive button.
4. Find and open BIRTHRT.WAD, then click OK.
5. Click Edit → Preferences….
6. Expand Map Editor, then select Node Builder.
7. Set the Node Builder: field to ZenNode.
8. Click Browse and find and open ZenNode.exe.
9. 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.

Playing Birthright maps in GZDoom

You can play Birthright levels in GZDoom by loading the WAD file along with BIRTHRT.WAD.

gzdoom.exe -iwad DOOM.WAD -file C:\path\to\BIRTHRT.WAD C:\BIRTHRT\WADS\ENDIE_MW.WAD

Obtaining BIRTHRT.WAD

 

This section is currently a placeholder. There are a few development tasks that must be implemented in BRUT before these steps can be completed.

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

• 0: The default. A game adventure.
• 1: A custom adventure.

Music

Demo

Panorama

Wad

The WAD file to load. Only one WAD file can be loaded per scene.

Difficulty

The difficulty of the adventure in a range of 1 to 4.

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.

Unusuable keywords

These keywords can not be used in custom adventures. Some would require making modifications to more game assets if overriding a game adventure. This would be useful for total conversions where the resource files are already being replaced.

QuestThingType

The Thing ID of the item that will complete the quest. This must come before [Wad]. This appears to be buggy when used in custom adventures. In my testing, it either doesn’t work at all, or the game crashes when the item is picked up.

Notes

Notes are scrolls in an adventure that can be opened to read a message inside. These reference messages found in STRDAT.DAT. Not usable in custom adventures.

OpeningDialog

This opens a dialog at the start of the adventure with the indicated message found in STRDAT.DAT. Not usable in custom adventures.

Format documentation: Descriptions (.TXT, .ADV)

Description files in Birthright are simple text files used to add descriptions for items, people, and adventures. Some simple formatting is allowed.

^F00

Birthright comes with various fonts and different styles thereof.

^T0

Text can be made translucent. Values from ^T0 (fully opaque) to ^T4 (fully translucent).

^U

Toggle underlined.

^B

Toggle bold.

^I

Toggle italics. I haven’t seen this work yet, but it’s listed in the code. Maybe it’s context sensitive.

^W000

Word wrap. This appears to be very buggy. In some cases it doesn’t reset properly.

^C000

Text color. Despite taking numbers that appear to be 0 to 255 values, only specific values work (ex: 64 for blue, 188 for green, etc.).

^CA000

Anti-aliasing color. Untested.

^CN

Toggles color remapping. Unclear what this means. Untested.

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.

Doom specials reference

Doom’s linedefs and sectors allow setting special attributes, which allow extra functionality like doors, movable floors, teleports, and keys.

Note from the developers regarding the “Informational message” specials:

"Walkover-activated and switch-activated doors did not used to have anything special about their line segments. Their sectors had the same tag as the distant line segment that activated the door, but their line segments had special = 0. That meant the lines did not get put into the global variable "first_seg," and so activate_seg did nothing when you stood in front of them and pressed the spacebar. SO: for a walkover-activated or switch-activated door, set up the walkover or switch as before and also give the lines on both sides of the door one of the following special values."

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.