Editor keys
Editor keys, also called DECORATE keys, are special comments in code that allows to provide editors with metadata. Essentially, they allow the editor to automatically complete the game configuration with the loaded resources.
Editors originally only loaded their own configuration files, leading people to need to create mod-specific configuration files for mods featuring custom content. Furthermore, each editor having their own configuration format (often incompatible between different versions), this made providing mod-specific configurations for every editor out there a hassle. Some editors, such as Doom Builder and SLADE, started including a DECORATE parser allowing them to detect custom things in loaded resources, removing the need to provide a custom configuration. To provide editors with additional metadata over actor code without tripping the game with unknown keys, a special comment format is used: //$. The double slash signals the game that the rest of the line should be ignored; but the following dollar sign tells the editor that this comment is actually a key with meaning for it.
With the arrival of ZScript and the externalisation of actor data to other control lumps (notably editor numbers to MAPINFO, editor keys are not necessarily limited to being just "DECORATE keys".
List of keys
In this table, "DB" refers to the latest iteration of Doom Builder (currently: Ultimate Doom Builder) and SLADE likewise refers to SLADE 3. A green checkmark (☑) means that the editor supports this key; a red x mark (☒) means that it does not. Unless otherwise stated, all keys must be present in an actor's definition block, just like regular actor properties: from the perspective of the editor, they are actor properties. In ZScript, they should be within the actor's Default sub-block.
| Key | Meaning | DB | SLADE |
|---|---|---|---|
| //$Angled | Specifies that the direction matters, and the actor should be represented with a direction arrow. | ☑ | ☑ |
| //$Arg0Str | Allows to mark this actor as supporting arg0str in UDMF format. An alternate name can optionally be specified for when string version is used (in a similar way to "Script number"/"Script name"). | ☑ | ☒ |
| //$ArgN | Allows to override default argument names for this actor. N is the argument number, ranging from 0 to 4, so you would use for example //$Arg0. | ☑ | ☒ |
| //$ArgNDefault | Allows to set the default value for this argument. This property can only be used in conjunction with //$ArgN property. N is the argument number, ranging from 0 to 4. | ☑ | ☒ |
| //$ArgNEnum | Allows to specify an enum for this argument. This can be either a name of an enum defined in the Game Configuration, or an explicit enum definition. This property can only be used in conjunction with //$ArgN property. N is the argument number, ranging from 0 to 4. | ☑ | ☒ |
| //$ArgNRenderColor | Allows to specify a custom color for //$ArgNRenderStyle. The color is specified as RRGGBB hexadecimal value. N is the argument number, ranging from 0 to 4. | ☑ | ☒ |
| //$ArgNRenderStyle | Allows to specify visual representation for this argument when event lines are enabled, much like visual radius for dynamic lights. Supported values are Circle and Rectangle which result in that shape with the argument used for shape's radius. N is the argument number, ranging from 0 to 4. | ☑ | ☒ |
| //$ArgNTooltip | :Allows to override tooltip for the argument of this actor. Newline character ("\n") can be used to format the text. This property can only be used in conjunction with //$ArgN property. N is the argument number, ranging from 0 to 4. | ☑ | ☒ |
| //$ArgNType | Allows to specify an argument type for this argument. This property can only be used in conjunction with "//$ArgN" property. N is the argument number, ranging from 0 to 4. | ☑ | ☒ |
| //$Category | Specifies in which category (Monsters, Weapons, etc.) it should be sorted. By default, a custom actor not identified in a configuration file will be put in the Decorate category. You can have hierarchical subgroups, using the backslash separator. For example: //$Category "Decorations/Tech" will put the actor within the "Tech" subgroup of the "Decorations" group. | ☑ | ☑ |
| //$ClearArgs | Clears inherited arguments (from either game configuration or parsed ZScript/DECORATE base classes). | ☑ | ☒ |
| //$Color | Allows to override category color for this actor. Possible values range from 0 to 19, see Color table below. | ☑ | ☑ |
| //$Colour | Allows to override group color for this actor. Values are indicated either as a CSS-style syntax (RGB(red, green, blue) with decimal values in the 0-255 range for red, green, and blue) or as HTML-like hexadecimal value (#RRGGBB with hexadecimal values in the 00-FF range for red, green, and blue). If both the //$Color and the //$Colour keys are provided, //$Colour will be favored. This allows to adapt to the different colors used by both editors. | ☒ | ☑ |
| //$EditorSprite | See //$Sprite below. This is a SLADE-specific alias, placing it after the //$Sprite key allows to specify different sprites for both editors. | ☒ | ☑ |
| //$Icon | Specifies which editor icon to use to represent the actor in the editor. This is useful for spriteless actors; if a sprite is defined it will be used instead. | ☒ | ☑ |
| //$IgnoreRenderstyle | The actor's RenderStyle property will be ignored by the editor. Helpful when you want to see the sprite of an invisible actor in Visual mode. | ☑ | ☒ |
| //$IsDecoration | Tells that the actor is a decoration. This is used for filtering things in 3D mode, as it is possible to cycle between showing all things, only decorations, and no things at all with the thing filter key (T by default). | ☒ | ☑ |
| //$Group | See //$Category above. Since the default categories depend on editor configurations and differ between Doom Builder and SLADE, you can use //$Category for the DB configuration and follow it by //$Group for the SLADE 3 configuration. | ☒ | ☑ |
| //$GZDB_SKIP | This key should not be in an actor block. The parser will stop parsing a file after encountering this comment. This can be used to speed up the parsing process by skipping files which do not contain placeable actor definitions. | ☑ | ☒ |
| //$NotAngled | Specifies that the direction does not matter, and the actor should not have a direction arrow. | ☑ | ☑ |
| //$Obsolete | Marks the thing as obsolete. It will be detected by "Check obsolete things" Map Analysis Mode check and will be marked in the Thing Properties Window and the Thing Info panel. | ☑ | ☒ |
| //$Sprite | Specifies which image to use to represent the actor in the editor. By default, a custom actor not identified in a configuration file will attempt to use the first suitable sprite it finds in the actor definition, trying first the states in the sequence Idle, See, Inactive, Spawn, and if all these fail, the first defined state. This key is therefore especially useful for stateless actor definitions. You should specify the actual lump name, for example if you use sprite mirroring and your sprite lump is named JUNKA0D0, you need to put JUNKA0D0, JUNKA0 or JUNKD0 will not work. | ☑ | ☑ |
| //$Title | Specifies which name to give to the actor. By default, a custom actor not identified in a configuration file will use the Tag property, and if not present, will default to the class name. | ☑ | ☑ |
| //$UserReinterpret | Specifies uncommon editor control type for the user variable defined directly under the comment. Supported types:
Note: only supported in ZScript as of now. |
☑ | ☒ |
| //$UserDefaultValue | Specifies default value for the user variable defined directly under the comment.
Note: only supported in ZScript as of now. |
☑ | ☒ |
Color table
Possible values for the //$Color key.
| Index | Config Name | System Name | Index | Config Name | System Name | Index | Config Name | System Name | Index | Config Name | System Name | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0 | ██ | Dark Gray | DimGray | 5 | ██ | Magenta | DarkViolet | 10 | ██ | Light Green | LimeGreen | 15 | ██ | White | WhiteSmoke | |||
| 1 | ██ | Blue | RoyalBlue | 6 | ██ | Brown | DarkGoldenrod | 11 | ██ | Light Cyan | PaleTurquoise | 16 | ██ | Pink | LightPink | |||
| 2 | ██ | Green | ForestGreen | 7 | ██ | Gray | Silver | 12 | ██ | Light Red | Tomato | 17 | ██ | Light Orange | DarkOrange | |||
| 3 | ██ | Cyan | LightSeaGreen | 8 | ██ | Light Gray | Gray | 13 | ██ | Light Magenta | Violet | 18 | ██ | Light Brown (default) | DarkKhaki | |||
| 4 | ██ | Red | Firebrick | 9 | ██ | Light Blue | DeepSkyBlue | 14 | ██ | Yellow | Yellow | 19 | ██ | Orange | Goldenrod | |||
Argument types
Possible values for the //$ArgNType key.
- 0 = Integer (default)
- 4 = Action special
- 5 = Sector effect
- 8 = Angle in degrees
- 10 = XXRRGGBB color
- 11 = Enum option
- 12 = Enum bits
- 13 = Sector tag
- 14 = Thing tag
- 15 = Linedef tag
- 22 = Byte angle
- 23 = Thing Radius
- 24 = Thing Height