Macros

Macros are a unique scripting system used in Doom 64 which allow the you to script events to make the gameplay more dynamic. Macros are a series of actions executed in batches which can transform geometry, modify walls, and spawn or remove actors.

BLAM is used to compile macros into a executable format for Doom 64 (in a format similar to BASIC). It is included with and automatically used by Doom Builder 64. The page icon on Doom Builder 64 will open the script editor where you can add macros. This script editor can also be found from the "View" menu. In the script editor, the page icon with the lightning bolt will compile the macro scripts. All available macro actions can be found on the page below, along with the types of values they take (height, thing tag, etc).

Each macro action corresponds to a line action. When referencing a macro from a line action, that macro must exist (even if it has no actions within) or a map can crash while loading. Only one macro can be executed at a time, but if you want to trigger a macro from a macro, you can set one macro to trigger another macro by crushing a barrel at the end. The barrel's delayed "death" triggers the second macro which ensures the original macro isn’t active when the second one is triggered. Also monster tunnels can replace many macros and multiple can be executed at once.

It's possible to decompile already compiled macros from a map using BLAM as described in the page below.

Macro Basics

A macro script has three parts: the "includes" at the start, the "macros" themselves, and the "actions" within each macro. Macros are referenced numerically, i.e. "macro 1", "macro 2", and ect. In EX-based engines, macros must be sequential without skipping any numbers. In Remaster-based engines, macros can skip numbers.

The following is a basic overview of a script:

includes

macro 1
{
	action;
	action;
}

macro 2
{
	action;
	action;
	action;
}

The link below leads to a tutorial on how to build and debug macros. The following sections will describe macros more in depth which can help with the tutorial.

Proper macro ordering has macros increasing incrementally without skipping a number. Putting two macros with the same number twice in a row (for example a macro 3 followed another macro 3) will not cause an error, but only the last macro with the same number will be used. It is as if the previous macro with the same number did not exist.

Structure of a Macro

A basic macro script in looks something like this:

// my first macro script

#setdir "c:\Doom Builder 64\Compilers\Doom64\"
#include "common.txt"

macro 1
{
	Door_Open(20);
	wait;
	Door_Open(40);
}

The following items are explained below:

// my first macro script

This is a comment line. Comments don't affect the behavior of the script, they serve only as notes or short explanations of what the script does.

#setdir "c:\Doom Builder 64\Compilers\Doom64\"

This tells BLAM (the script compiler) "where" to look for files when using #include. #setdir 'must' be used before #include, otherwise #include will look in the folder where the wad itself is located. #setdir must also begin and end with quotes.

#include "common.txt"

The "#include" command instructs the compiler to open the given file and process it's contents before continuing on through the rest of the script. #include Must begin and end with quotes. In essense #setdir defines "where" to look for files, and #include tells "what" files to look for.

The file "common.txt" is a standard file which contains all basic macro definitions, for use with Doom Builder 64's scripting system. It's required for Doom Builder 64 to know what macro commands are available. Always #include the file in your script.

Common.txt can be found at: "('where you installed Doom Builder 64')\Compilers\Doom64\"

Common.txt does not need to be distributed with your wad however, as it is just a list of commands for use with Doom Builder 64's script compiler (BLAM). For those who are curious common.txt contains human readable translations for the numerical macro scripting commands used by Doom 64. It would be possible to make macro scripts in Doom Builder 64 without common.txt, but would be quite painful as everything would just be different sets of numbers. Doom 64 itself does not use common.txt at all.

macro 1
{

This is the beginning of a macro definition. This macro's identification number is 1. Script numbers can be 1-255, and is referenced by line types 256-511. You must have an open bracket "{" at the start of each macro, and must use a close bracket "}" to end each macro definition. Forgetting either bracket will result in errors.

Door_Open(20);

This is an action statement. "Door_Open" is the pre-defined name that executes the door open action. Inside the parenthesis "()" is where you put information needed for the action. In this case the "20" is the tag number for the sector(s) that should be treated as a door. Finally, a semicolon ";" ends the action. Note that "all actions 'must' end with a semicolon". Forgetting a semicolon will cause errors, and is also one of the most common causes of errors.

Note that #include and #setdir are different from actions, and do not need semicolons.

wait;

This is a built-in statement that tells the script to wait until the most-recent action that was executed is finished. The rest of the macro will only continue running after that action completes.

Door_Open(40);

Any sector(s) with a tag of 40 will open like a door. In the example above, because of the 'wait;' statement before it, the door tagged 40 will not open until the door tagged 20 has opened completely. If the 'wait;' statement had not been there, both doors would open simultaneously. This means that without a 'wait;' command, actions within a macro will happen right after each other without delay.

}

And this closing bracket is the end of the macro definition. The macro is now complete.

Comments

Comments are parts of the macro script which are ignored by the script compiler (aka BLAM). They simply do nothing. Their purpose is to allow macro writers to insert notes, descriptions, or reminders into their scripts.

BLAM supports 2 styles of comments:

The first one, known as line comment, begins with a pair of slash signs (//) and ends at the end of the line. This means that the next line 'will not' be ignored when using a line comment. Unless that line contains a comment as well. The second one, known as block comment, starts at "/*" characters and ends at the first appearance of "*/" characters.

/* As you can see this is a block comment so it can continue through
   more than
   just one line */
   
#include "common.txt"
macro 1
{
	Door_Open(20);
	wait;
	Door_Open(40);
}

When using a block comment 'always' make sure not to forget the "*/" at the end, or the entire rest of the script will get ignored.

Custom Macro Actions

Any line action in Doom 64 can be used in a macro, even if it is not a pre-defined macro action in Doom Builder 64. The general way to define a custom macro action is below.

#define name(value)  lineaction:value

Where "name" is whatever you want to name the macro, "value" is a number you want to use (which can be a tag or macro integer), and then "lineaction" is the line action number. For example, the definition and macro below allows one of the artifact switch lines to be activated from a macro (this map has it in action).

#include "common.txt"

// Custom macro action definition
#define Orange_Artifact_Open(tag)  90:tag

macro 1
{
    
    // activate the artifact linedef, which is actually tagged 10
    Orange_Artifact_Open(9);
    
}

You can also combine multiple line actions into one referenced macro action. This is how the macro actions which require two values are created. For example, below is how the "Line_CopyTextures" macro action is defined.

#define Line_CopyTextures(dsttag, srctag)  PushVar(srctag); 219:dsttag

The full list of pre-defined macro actions are in the "common.txt" file which comes with Doom Builder 64. You could also modify this or create a custom version of this text file to add your own definitions.