Macro
From DoomWiki.org
A macro is a form of compiled script used by Doom 64. 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.[1] 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 words, 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 |
References[edit]
- ↑ Heydelaar, Tim (18 January 2019). "Early and unused DOOM 64 Level Designs." Doomworld Forums. Retrieved 22 January 2019.