Macro Scripting

From Doom64EX

Jump to: navigation, search

Macros are a unique scripting system used in Doom64.

Contents

Introduction

Similar to ACS, macros allow the user to script events to make the gameplay feel more dynamic and open ended. Macros are basically a series of line actions executed in batches, which provides the flexibility to move sectors separately, simultaneously, in the same or opposite directions, and to any height or depth. It also allows the user to modify walls, flags, textures and even how switches can be interacted with as well as spawning or removing actors.

Instead of ACS, Doom 64 EX uses BLAM. It is included with and automatically used by Doom Builder 64, so no separate download or setup is needed.

Advantages

Like with any scripting system, macros gives the designer complete freedom to do creative events and sequences, making the gameplay more open ended.

Disadvantages

Macros is considered to be more of a 'pseudo' scripting system: it basically just invokes line actions and nothing else. This means that it cannot do expressions, variables, nor conditional statements. Another drawback is that only one macro can be executed at a time meaning only one scripted event can occur. If two or more macros are executed, then all other macros will be queued until the current one finishes.

Basics

Getting Started

A macro script has three parts. The includes at the start, the macros themselves, and the actions within each macro.

Overview of a script:

   includes
   
   macro 1
   {
       action;
       action;
   }
   
   macro 2
   {
       action;
       action;
       action;
   }

Structure of a macro script

Scripting macros in BLAM is almost identical to ACS.

A basic macro script 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. See the comments section below for more info.


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

  • #setdir can be left out, if you do the following: Put any files you're #including (in most cases this will be just common.txt, which is described below) into the same folder where your wad is located. If you do that the files will be automatically found, and #setdir can be left out of your script.
    • There is one caveat to this. If you are leaving #setdir out of your script, you must save the map at least once (in the folder where you put common.txt) before compiling the macro script. Otherwise there will be an error, because the compiler will be looking for common.txt in a temporary folder where common.txt does not exist.


#include "common.txt"

This is always required.

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.

To simplify things, #setdir defines where to look for files, and #include tells what files to look for.

If you want to include more than one file, each file needs it's own #include statement. Only very advanced people would ever need anything more than just common.txt, however.


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

You also cannot skip macro numbers. Having a macro 3 followed by macro 5 would lead to an error.


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.

Do not get confused. #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.


}

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:

   // line comment
   /* block comment */

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!

Writing a script

List of All Macro Actions

All macro actions can be found on the Macros page, along with the types of values they take (height, thing tag, etc).

It's recommended to have the list of actions open while scripting, for reference and to copy action names so as to avoid typos in your script.

Compiling & Scripting Tutorial

When you're done writing a macro, the script must be compiled before the macro can be run in-game.

For a walk-through tutorial on this and scripting in general, see Macro Scripting and Compiling with Doom Builder 64

Converting an old macro to the new system

It's possible to convert the macros lump from a map using the old macro system into the new script based one. This is only needed if you want to continue working on an old map after switching to a new version of Builder 64, which has the new scripting system.

Macro extraction

The first step is to extract the MACROS lump from the map. Slade is recommended.

The extracted MACROS.lmp will not be editable text, so it must be decompiled to make it a script which can be edited.

Decompiling a MACROS lump

Blam.exe is used to decompile a macros lump into editable text.

Blam is found in the same folder as common.txt: (install path)\Doom Builder 64\Compilers\Doom64

Put MACROS.lmp into that folder.

From here, there's a couple ways to make blame.exe decompile the lump.

Using a batch file to decompile

Create a new text file (in the same folder as blam.exe and the macros.lmp) and open it.

Copy this into the text file:

cd /d %~dp0

START cmd /c "blam.exe macros.lmp macros.01.txt -d"

After saving, rename the text file to decompile.bat

Note: You must be able to view file extensions or renaming won't actually change it into a batch file.

Running the batch file (it can be double clicked to run) should now decompile macros.lmp to a txt file.

Creating a shortcut to decompile

Create a shortcut to blam.exe (right click and choose "create shortcut")

Right click the shortcut and choose "properties"

In the properties window that comes up, select the "Shortcut" tab, if it isn't already.

In the "Target:" field, go to the end (after where it says "...\blam.exe") and type " macros.lmp macros.txt -d" (minus the quotes).

Hit Okay. Running the shortcut with MACROS.lmp in the folder should now decompile the script to a txt file.

Importing into Doom Builder 64

There's two ways to get decompiled macros back into Doom Builder.

Choosing "open file" in Doom Builder's script editor, which will load all the decompiled macros into the script editor.

Alternatively, the decompiled text file can simply opened in a text editor and macros copy/pasted to the script editor as needed.

However, if you are copying macros selectively, you must make sure to renumber the macros in the script editor. Macros must be numbered sequentially in a script. No numbers can be skipped or there will be problems.

Example: after if macro 5 in a script there was a macro 7, with no macro 6 between, that would lead to an error.

Personal tools