Basics

A description resource contains information about the parameters of a node object. Cinema 4D uses this information to let the user edit and animate these parameters.
See Parameter Descriptions for more information.

Each description resource file must be named descriptionname.res and be placed within the description folder of the res folder in the plugin directory.
The file should be structured like this:

CONTAINER descriptionname // Like the filename without ".res"
{
  [NAME]
  [INCLUDE]
  [SHOW/HIDE]

  [Elements and groups]
}

There must also be a corresponding descriptionname.h file in the same directory, that contains an enum with all the IDs used in the description.
It is parsed by Cinema 4D, and can also be included into the C++ code. This is how the file should be structured:

#ifndef DESCRIPTIONNAME_H__
#define DESCRIPTIONNAME_H__

enum
{
  [IDs definition]
};

Note: Generally it is safe to use IDs above 1000 in a local context like this one.

The strings for the description are taken from descriptionname.str in the strings_xx folder for the current language.
Special for description string files is that a shorter name (only displayed in the Attributes Manager) can be optionally specified:

STRINGTABLE descriptionname
{
  descriptionname "Description Name";

  ELEMENT_1 "Long Name";
  ELEMENT_2 "Long Name" "Short Name";
}

Naming Convention

The descriptions in Cinema 4D are all named with an uppercase prefix and a lower case suffix, for example Tdisplay or Olight.
These are the prefixes used:

Prefix	Meaning
D	Data type.
F	Scene loader/saver.
GV	Graph View.
KE	Key.
M	Material.
O	Object.
SE	Sequence.
T	Tag.
TE	Track.
VP	Video post.
X	Shader.

Name Flag

The name of a description is specified using the flag:

Flag	Explanation
`NAME stringid`	Description name.

stringid should be an identifier from the string resource file that belongs to the description i.e. descriptionname.str.
It is not possible to specify a string directly. This ensures that all text within the description can be localized.

By convention the stringid parameter is always equal to descriptionname. Thus no extra ID need to be inserted into the header file for the name string:

STRINGTABLE descriptionname
{
  NAME descriptionname;

  ...
}

Include Flag

The description of parent nodes can be included with this flag:

Flag	Explanation
`INCLUDE parentdesc`	Parent description.

parentdesc should be the identifier for the parent description. All elements of the parent description are inserted before the elements of the plugin description, in the various groups.

Warning: The parent description must have been registered with Cinema 4D before the plugin description for the lookup to work.

Note: It is recommended to always include at least the base description for the node type plugin, for exampe Tbase for tags.

Show and Hide Flags

If an element in the parent description has been given the HIDDEN flag, or to hide one of its visible elements, the following flags can be used:

Flag	Explanation
`SHOW elementid`	Show the element.
`HIDE elementid`	Hide the element.

elementid is the identifier for the element to hide or show. When an element is hidden it is not displayed in Cinema 4D. It can still be accessed and animated by plugin code.

Groups

All elements, except for those in sub-descriptions, should be placed in a group. Groups are created like this:

GROUP [groupid]
{
  [DEFAULT 1 | 0;]
  [Elements]
}

groupid is a constant from the descriptionname.h file. It is used for the name of the group in the string table, and as an identifier for the group.
If no group ID is specified the group is just used for structuring.

Flag	Explanation
`DEFAULT 1 \| 0`	Specifies if the group is initially open (1) or closed (0).
`COLUMNS n`	Used to create multi-column groups. (See Tcompositing.res.)
`MATEDCOLUMNS n`	Number of columns in the Material Editor. (See Mmaterial.res.)

Groups can be nested within each other.
They can be also reused for included descriptions, so if there are elements in the parent description within a certain group they will be placed together with elements within that group of the plugin description.

Note: Always check if a parent group can be reused before creating a top-level group in the description.
For each node type there is a corresponding ID_NODETYPEPROPERTIES to use, for example ID_TAGPROPERTIES.

Layout Groups

Normally all elements in a description are placed in a linear layout from top to bottom. With LAYOUTGROUP it is possible to place the elements in columns.
This can be used for example to line up BOOL checkbox elements with their corresponding option. (See Tcompositing.res.)

The LAYOUTGROUP command is used inside a GROUP of its own and always followed by the COLUMNS command:

GROUP
{
  LAYOUTGROUP; COLUMNS n;

  GROUP
  {
    [First column's elements]
  }

  ...

  GROUP
  {
    [nth column's elements]
  }
}

The elements of each column are placed in a standard GROUP inside the layout group.

Flag	Explanation
`COLUMNS n`	The number of columns.

Note: Use LAYOUTGROUP sparingly to avoid making descriptions too wide.

Elements

The elements are the most important part of a description. Each element corresponds to an entry in a node's container. The elements are formatted like this:

ELEMENTTYPE elementid { [Flags] }

or

ELEMENTTYPE elementid
{
  [Flags]
}

elementid must be a constant from the descriptionname.h file. For some element types it is not needed, for instance SEPARATOR.

Element Flags

The element flags vary between the different element types, but these are common:

Flag	Explanation
`PARENTID parid`	Group the element visually with `parid`.
`HIDDEN`	Hide the element.
`ANIM ON \| OFF \| MIX`	Set the animation mode of the parameter:
`ON`	Parameter is animatable.
`OFF`	Parameter is not animatable.
`MIX`	Parameter is animatable, but needs to know the left and right data element. An example is the Target expression that interpolates the Name parameter. If `MIX` is specified, the expression can at any time call BaseList2D::GetAnimatedParameter() to get the left, right and mix values.
`OPEN`	Show the extended GUI by default.

The flags are separated with semi-colons, for example.

REAL CAMERAOBJECT_TARGETDISTANCE { UNIT METER; MINEX; MIN 0.0; }

GraphView Flags

There are also flags for GraphView:

Flag	Explanation
`INPORT`	This is an in port.
`OUTPORT`	This is an out port.
`STATICPORT`	This is a static port.
`NEEDCONNECTION`	Needs a connection.
`MULTIPLE`	Allow multiple instances per node.
`PORTONLY`	Only as port.
`CREATEPORT [n]`	Create this many ports.
`MINPORTS n`	Minimum number of ports.
`MAXPORTS n`	Maximum number of ports.
`NOTMOVABLE`	Not movable.
`EDITPORT`	Editable.

Element Types

Here are links to the valid description resource element types:

Custom Data Types

Custom data types, created with CustomDataTypeClass, can be included as elements in descriptions. Their identifier is given by CustomDataTypeClass::GetResourceSym().

Custom GUI

All elements have a default GUI, but it is also possible to specify alternative GUI representations for a data type.
These can be created with the CustomGuiData class. The custom GUI is specified with the CUSTOMGUI flag for each element:

ELEMENTTYPE elementid { [Flags;] CUSTOMGUI id; }

The id is a string name for the representation. For plugin GUIs this is CustomDataTypeClass::GetResourceSym().

Here are some built-in custom GUIs (not listing the defaults):

ID	Description
`REALSLIDER`	Edit field with slider for REAL.
`REALSLIDERONLY`	Slider only for REAL.
`LONGSLIDER`	Edit field with slider for LONG.
`MULTISTRING`	Multiple line edit field for STRING
`SUBDESCRIPTION`	Forced expanded view of sub channels, for all element types.

Table of Contents