Editor keys

From ZDoom Wiki
Jump to navigation Jump to search

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. Ultimate Doom Builder also supports editor keys in DEHACKED, however in that format they start with #$, not //$.

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.
Retrieved from "https://zdoom.org/w/index.php?title=Editor_keys&oldid=52814"