DECORATE format specifications

Warning: DECORATE has been deprecated since GZDoom 2.3.0 and is currently completely superseded by ZScript. Authors should avoid using DECORATE for new projects. All DECORATE methods and features are still available and function the same way in ZScript, and DECORATE knowledge can easily be applied to ZScript with minimal syntax changes.

This page describes the format to create a new actor in the DECORATE lump:

actor classname [ : parentclassname] [replaces replaceclassname] [doomednum]
{
  properties
  flags
  ...
}

• classname
  • The name this new actor is referenced by in the game. While ZDoom will accept a much larger range of values for the name, this should for best compatibility be a valid identifier (alphanumeric plus underscores, but not starting with a digit).
• parentclassname
  • The name of a parent class this new actor inherits its attributes from (optional). If none is specified, the parent class is Actor.
• replaceclassname
  • The name of the class this class replaces (optional). This works at a higher level than using duplicate doomednums and will affect all attempts to spawn the replaced actor in the map. However, this does not affect effect that create the actor through other means, such as giving an inventory item directly to a player. Player actors are handled differently from other actors, so this method also does not work for custom player classes. Skill definitions may specify other replacement for an actor, and occurs prior to Decorate replacement.
• doomednum
  • Editor number for this actor (optional). This is the number used to distinguish the actor from other things in map. If the actor is intended to be placed in a map editor, it should have an editor number. The actual number value is generally arbitrary but should avoid conflicting with already used numbers.

An actor definition consists of properties, flags and state definitions. In the state definitions you can call Action functions.

Actor properties and flags define the general behavior of an actor.

States define the various sprite animations of an actor.

Action functions (also known as "code pointers") cause the actor to perform some particular action when the frame that calls them is shown. They form the basis of almost all enemy and weapon behavior in the game. Instead of using one of the special action functions you can also use almost any action special that is available in ACS.

Comments are supported. Both types of C-style comments (// to end of line, and /* to */) are allowed. While not part of the specification, certain editing tools, such as Doom Builder and SLADE 3, make use of specific comments for special purposes, these usually start with //$.

Including Decorate scripts into others

Using the #include "<full_path_and_lump_name>" directive, you can include other Decorate scripts, for example, if you wanted to organize your data into subfolders; a common practice is to place Decorate lumps into actors/ subfolder of a PK3-file, leaving only the main decorate.txt in the root directory, that includes them. That also allows to precisely set the loading order of lumps, in case of some actors used in several places, in order to avoid loading errors. The directive may appear in any place other than actor definition.