Macro

From DoomWiki.org

Revision as of 11:21, 4 December 2014 by Quasar (talk | contribs) (Initial revision)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

A macro is a form of compiled script used by the Doom 64 port. Similar to ACS in function, albeit significantly more limited, it provides the ability to execute groups of linedef specials. Virtually all specials in the Doom 64 engine can be executed from a macro, and there are numerous specials implemented in the game engine which are provided expressly for the purpose of setting variables or controlling the execution of macros, and therefore only work properly when used in that manner.

Language

The original language used to generate the MACROS lumps for Doom 64 is unfortunately unknown, but some of its qualities can be inferred from statements made by mappers Randy Estrella and Tim Heydelaar in public interviews. They stated that the language was somewhat similar to BASIC. As the original language is unknown, tools provided with the Doom64 EX source port provide an independent implementation for generating new macros which is purely conjectural.

Capabilities

In terms of capabilities, the scripting itself is not Turing complete, as basic numeric and logical operations cannot be directly carried out. There is also no ability to jump or loop; all apparently looping macros are actually executing an unrolled set of instructions a preset number of times. Thus various traps such as darts shooting from walls can always be waited out and will eventually cease. An additional trigger must be provided in order to restart such a trap after it has finished.

Commands in each macro list the tag and special to execute, and are grouped into batches. Each batch of line actions occurs simultaneously, and the next batch will not execute until all actions in the current batch have finished. This is the only form of flow control implemented.

Use of certain tags on macro trigger lines will cause their macros to be executed at level start, much like ACS open scripts.

The game engine also has a fundamental and severe limitation: only one macro is allowed to execute at a time, globally. The game will forget about the execution of any other macros if one is currently running. As a result, this can allow speedrunners to abuse faster-than-intended movement to block execution of troublesome traps. It can also occasionally result in game-breaking glitches, as the layouts of levels can become non-negotiable if some macros fail to execute.

Format

The MACROS lump is an essential and required feature of the Doom 64 map format. It is a flat file of binary structures with the following layouts. All numeric fields are little endian.

There is exactly one lump header, at offset zero in the lump:

Lump Header
Offset Width Purpose
0 2 Number of macros in lump
2 2 Total number of commands in all macros

For every macro enumerated in the first field of the lump header, the macro header structure occurs between lists of commands associated with that macro. The header for the next command occurs after one plus the number of commands counted in this header, as there is always one "junk" command at the end of each macro which contains apparently uninitialized data and must be ignored by the reading application:

Macro Header
Offset Width Purpose
0 2 Number of commands

As mentioned above, each macro header is followed by a list of "number of commands" + 1 of the following structure. The final command not included in the macro header's count of commands is garbage data.

Macro Command
Offset Width Purpose
0 2 Batch number
2 2 Line tag
4 2 Line special