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 ZScript/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.

Editor keys can be used both in DECORATE and ZScript.

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: Color — integer variable, shows color selection dialog 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

Examples

A big version of the Zombieman with editor keys:

class BigZombieman : Zombieman
{
    Default
    {
        //$Title "Big Zombieman"
        //$Angled
        //$Category "Monsters"
        health 1000;
        scale 1.5;
        radius 30;
        height 56;
        speed 6;
    }
}

A particle fountain using PlasmaBall sprites created with SpawnParticle with editor keys:

class ParticlePlasmaFire : Actor
{
	int freqPerTic;

	Default
	{
		//$Title "Plasmafall"
		//$Category "Decoration"
		//$Arg0 "Particles per tic"
		//$Arg0Tooltip "Determines the number of particles spawned per tic"
		+NOINTERACTION
		+NOBLOCKMAP
		radius 16;
	}

	override void PostBeginPlay()
	{
		Super.PostBeginPlay();
		// make frequency per tic equal to the value of
		// the first argument, but clamp between 1-40:
		freqPerTic = Clamp(args[0], 1, 40);
	}

	override void Tick()
	{
		super.Tick();
		if (isFrozen())
			return;
		
		FSpawnParticleParams fp;
		fp.texture = TexMan.CheckForTexture('PLSSB0');
		fp.flags = SPF_FULLBRIGHT|SPF_ROLL|SPF_REPLACE;
		fp.color1 = "";
		for (int i = freqPerTic; i > 0; i--)
		{
			fp.lifetime = random[fp](40, 80);
			
			fp.pos.x = pos.x + frandom[fp](-radius, radius);
			fp.pos.y = pos.y + frandom[fp](-radius, radius);
			fp.pos.z = pos.z + frandom[fp](0, 16);
			
			fp.vel.xy = (frandom[fp](-2, 2), frandom[fp](-2, 2));
			fp.vel.z = frandom[fp](2, 4);
			fp.accel.xy = -(fp.vel.xy * 0.035); //acceleration is aimed to the opposite of velocity
			fp.accel.z = -(fp.vel.z / fp.lifetime);

			fp.size = random[fp](4, 10);
			fp.sizeStep = -(fp.size / fp.lifetime); //size reduces to 0 over lifetime
			fp.startalpha = frandom[fp](0.75, 1.0);
			fp.fadestep = -1;
			fp.startRoll = frandom[fp](0, 360);
			fp.rollvel = frandom[fp](-15, 15);
			fp.rollacc = -(fp.rollvel / fp.lifetime); //rollvel reduces to 0 over lifetime

			Level.SpawnParticle(fp);
		}
	}
}

Note: Examples above imply that you've given these actors DoomEdNums, otherwise they won't appear in the map editor.