Macro

From DoomWiki.org

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[edit]

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[edit]

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.

Macros are also able to store and use a single global variable. There is a special (204) that allows to set it to an arbitrary value, and several specials that will refer to this value for their effects. Some of the specials using this value interpret it as a fixed point 16.16 value, in other word, 1.0 is expressed as 65536.

The game engine also has a fundamental and severe limitation: only one macro is allowed to execute at a time, globally. The game will queue the execution of any other macros if one is currently running, up to a currently unknown limit. 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[edit]

Doom level format

Extensions:

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

Macro specials[edit]

Line specials starting from 200 are meant to be used with macros.

Special Effect Description
200 Clear Camera View Reset camera to player mobj
201 Set Camera Set camera view to tagged thing
202 Invoke Dart Shoot dart from tagged thing
203 Delay Timer Delay timer by tag value
204 Set Macro Integer Set the macro variable to tag value
205 Modify Sector Floor Color Set color ID to tag value
206 Modify Sector Ceiling Color Set color ID to tag value
207 Modify Sector Thing Color Set color ID to tag value
208 Modify Sector Upper Wall Color Set color ID to tag value
209 Modify Sector Lower Wall Color Set color ID to tag value
210 Custom Ceiling Move tagged sector ceiling by the macro variable amount (read as 16.16 fixed point)
212 Custom Floor Move tagged sector floor by the macro variable amount (read as 16.16 fixed point)
214 Move Elevator Move tagged sector floor and ceiling by the macro variable amount (read as 16.16 fixed point)
218 Change Line Flags Set tagged line flags to copy that of line tagged by the macro variable
219 Modify Line Texture Set tagged line textures to copy that of line tagged by the macro variable
220 Modify Sector Flags Set tagged sector flags to copy that of sector tagged by the macro variable
221 Modify Sector Specials Set tagged special to copy that of sector tagged by the macro variable
222 Modify Sector Lights Set tagged sector lights to copy that of sector tagged by the macro variable
223 Modify Sector Flats Set tagged sector flats to copy that of sector tagged by the macro variable
224 Spawn Thing Spawn tagged thing (which should have the "delayed spawning" flag set)
225 Quake Create an earthquake effect lasting tag value tics (30 tics per second in Doom 64)
226 Custom Ceiling Fast Move tagged sector ceiling by the macro variable amount (read as 16.16 fixed point)
227 Custom Ceiling Instant Move tagged sector ceiling by the macro variable amount (read as 16.16 fixed point)
228 Custom Floor Fast Move tagged sector floor by the macro variable amount (read as 16.16 fixed point)
229 Custom Floor Instant Move tagged sector floor by the macro variable amount (read as 16.16 fixed point)
230 Modify Line Special Set tagged line special to copy that of line tagged by the macro variable
231 Invoke Revenant Missile Shoot missile from tagged thing
232 Fast Ceiling Crush & Raise Quickly lower then raise once tagged sector's ceiling, dealing crush damage
233 Freeze Player Freezes the player for tag value tics (30 tics per second in Doom 64) by simply setting the player's reactiontime to that value
234 Change Light by Light Tag Gradually change tagged light to copy that of light tagged by the macro variable (this is the only use of light tags in the game)
235 Modify Light Data Gradually change tagged sector lights to copy that of sector tagged by the macro variable
236 Custom Down/Up Platform Lower, then raise tagged sector by the macro variable amount (read as 16.16 fixed point)
237 Custom Down/Up Platform Fast Lower, then raise tagged sector by the macro variable amount (read as 16.16 fixed point)
238 Custom Up/Down Platform Raise, then lower tagged sector by the macro variable amount (read as 16.16 fixed point)
239 Custom Up/Down Platform Fast Raise, then lower tagged sector by the macro variable amount (read as 16.16 fixed point)
240 Trigger Random Lines Activate the special of a randomly-chosen line among the tagged lines
241 Split Open Sector Raise tagged sector ceiling and lower tagged sector floor by the macro variable amount (read as 16.16 fixed point)
242 Fade Out Thing Fade out and remove tagged things, prevent them from being picked up or executing death special
243 Move and Aim Camera Set camera view to tagged thing
244 Set Floor Height Set tagged sector floor to the macro variable height (read as 16.16 fixed point)
245 Set Ceiling Height Set tagged sector ceiling to the macro variable height (read as 16.16 fixed point)
246 Restart Macro at Script Restart macro indexed by the macro variable
247 Move Floor by Height Move tagged sector floor to the macro variable height (read as 16.16 fixed point)
248 Suspend Macro Script Suspend macro numbered with tag value
249 Telefrag to Dest Silently teleport tagged thing even if something is in the way
250 Toggle Macros On Start macro numbered with tag value
251 Toggle Macros Off Stop macro numbered with tag value
252 Move Ceiling by Height Move tagged sector floor to the macro variable height (read as 16.16 fixed point)
253 Unlock Cheat Menu Set the flag allowing to use the "Features" menu
254 Morph Logo on F_SKYG Sky Effect used on the introduction scene