c4d.plugins – the main module

To get an overview of the class members, check out the diagram.

Class

• GeResource
• BasePlugin
• BaseDrawHelp

• BaseData

  • CommandData

  • MessageData

  • BitmapLoaderData

  • BitmapSaverData

  • ToolData

  • NodeData

    • TagData
    • ObjectData
    • SceneLoaderData
    • SceneSaverData

Functions

• GeLoadString()
• GetToolData()

//Plugin Data

• GetWorldPluginData()
• SetWorldPluginData()

//Registered plugins

• GetFirstPlugin()
• FindPlugin()
• FilterPluginList()
• RemovePlugin()

//Register Methods

• RegisterToolPlugin()
• RegisterCommandPlugin()
• RegisterMessagePlugin()
• RegisterBitmapSaverPlugin()
• RegisterBitmapLoaderPlugin()
• RegisterTagPlugin()
• RegisterObjectPlugin()
• RegisterSceneSaverPlugin()
• RegisterSceneLoaderPlugin()

'__res__'

Global resources for your plugin. Is automatically set in your Python plugin.

c4d.plugins.GeLoadString(id[, p1[, p2[, p3[, p4]]]])

Note

To make this work, __res__ must be defined in your global scope.

Load a string and replace the first ‘#’ with the placeholder string.

In CINEMA 4D there is a convention that in strings ‘#’ is a placeholder for dynamic parts (this allows you to translate a whole sentence as sentence structure and word placement may be reverted in other language)

For example: If the string is named: “loading of file ‘#’ failed” then you can pass the actual filename (as string) as p1 and you’ll get the desired result.

Parameters:

• p1 (str) – The string to insert into the first placeholder.
• p2 (str) – The string to insert into the second placeholder.
• p3 (str) – The string to insert into the third placeholder.
• p4 (str) – The string to insert into the fourth placeholder.

Return type:

str

Returns:

The completed string.

c4d.plugins.GetToolData(doc, plugind)

Gets the tool data container for the tool with ID pluginid.

Parameters:

• doc (BaseDocument) – The document to get the settings for.
• pluginid (int) – The plugin ID of the tool.

Return type:

BaseContainer

Returns:

Tool data container.

c4d.plugins.GetWorldPluginData(id)

Retrieves a container stored with SetWorldPluginData() from the CINEMA 4D preferences. This can be used by any plugin to store preferences.

Parameter:id (int) – The plugin ID that the container should be associated with. Return type:BaseContainer Returns:The retrieved container

c4d.plugins.SetWorldPluginData(id, bc[, add=False])

Stores a container in the CINEMA 4D preferences. Can be used by any plugin to store preferences.

Parameters:

• id (int) – The plugin ID that the container should be associated with. Please use a unique ID from PluginCafe.
• bc (BaseContainer) – The container to store.
• add (bool) – If this is True the the container values are merged with the ones currently stored for this ID. Otherwise the previous values are lost.

Return type:

bool

Returns:

True if the container was stored, otherwise False.

c4d.plugins.GetFirstPlugin()

Returns the first plugin of Cinema 4D.

Return type:BasePlugin Returns:The first plugin.

c4d.plugins.FindPlugin(id[, type=0])

Returns the BasePlugin find by id.

Parameters:

• id (int) – The plugin id. Please obtain a serial from plugincafe.com
• type (int) – Optionally a plugin type.

Return type:

BasePlugin

Returns:

The plugin.

c4d.plugins.FilterPluginList(type, sortbyname)

Browses recursively through the plugin list looking for plugin of the specified type. For example, to find all bitmap savers you can write:

dest = plugins.FilterPluginList(plugins.C4DPL_BITMAPSAVER, True)

Parameters:

• type (int) –

  Plugin type filter:

  C4DPL_SHADER	2D Shader
  C4DPL_MATERIAL	3D Shader
  C4DPL_COMMAND	Command (menu) plugin.
  C4DPL_OBJECT	Object plugin.
  C4DPL_TAG	Tag plugin.
  C4DPL_BITMAPFILTER	Bitmap filter.
  C4DPL_VIDEOPOST	Videopost effect.
  C4DPL_TOOL	Tool Plugin.
  C4DPL_SCENEHOOK	Scene Hook.
  C4DPL_NODE	Node Plugin.
  C4DPL_LIBRARY	Library.
  C4DPL_BITMAPLOADER	Bitmap loader.
  C4DPL_BITMAPSAVER	Bitmap saver.
  C4DPL_SCENELOADER	Scene loader.
  C4DPL_SCENESAVER	Scene saver.
  C4DPL_COREMESSAGE	Core message.
  C4DPL_CUSTOMGUI	Custom GUI.
  C4DPL_CUSTOMDATATYPE	Custom datatype.
  C4DPL_RESOURCEDATATYPE	Resource datatype.
  C4DPL_CTRACK	Track plugin.
  C4DPL_MANAGERINFORMATION	Manager information plugin.

• sortbyname (bool) – If this is True then the found plugins are sorted alphabetically by name.

Return type:

list of BasePlugin

Returns:

The list.

c4d.plugins.RemovePlugin(plug)

Private.

c4d.plugins.RegisterToolPlugin(id, str, info, icon, help, dat)

Registers a ToolData plugin:

PLUGIN_ID = 1234567890
desc = plugins.GeLoadString(MY_TOOL_DESC)
plugins.RegisterToolPlugin(PLUGIN_ID, "MyTool", 0, None, desc, MyTool())

Parameters:

• id (int) – The plugin id. Please obtain a serial from plugincafe.com
• str (str) –

  The name.

  Note

  If you want to affect the order that your plugins are displayed in menus you can add #$n as a prefix to this name, where n is a number. Lower numbers are displayed before higher numbers. If you make the name “–” it will show up as a menu separator.

• info (int) –

  The settings for the plugin. Possible flags are:

  PLUGINFLAG_TOOL_EVALUATEHANDLES	Evaluate object handles when tool is active.
  PLUGINFLAG_TOOL_DRAW_MULTIPLANE	Draw multiple planes.
  PLUGINFLAG_TOOL_TWEAK	Tweak mode supported.
  PLUGINFLAG_TOOL_HIGHLIGHT	Hightlighting supported.
  PLUGINFLAG_TOOL_EDITSTATES	Edit states supported.
  PLUGINFLAG_TOOL_SNAPSETTINGS	Snap settings supported.
  PLUGINFLAG_TOOL_SINGLECLICK	Single click tool.
  PLUGINFLAG_TOOL_TWEAK_NO_HIGHLIGHT	Tweak mode with no hightlighting.

• icon (BaseBitmap) –

  The icon for the command. The bitmap is copied.

  Note

  The icon should be of size 32x32, but will be scaled if needed. It must also be 24 bits and should if possible include an alpha to support pattern backgrounds.

• help (str) –

  The tool tips and status bar help text for the command.

  Note

  When using strings it is advised to use the string resources files and the GeLoadString function. This keeps the plugin easy to localise for any language you wish to support and makes full use of the language features of CINEMA 4D.

• dat (ToolData) – A data instance for the plugin.

Return type:

bool

Returns:

True if the registration was succesful.

c4d.plugins.RegisterCommandPlugin(id, str, info, icon, help, dat)

Registers a CommandData plugin:

PLUGIN_ID = 1234567890
desc = plugins.GeLoadString(MY_TOOL_DESC)
plugins.RegisterCommandPlugin(PLUGIN_ID, "MyCommand", 0, None, desc, MyCommand())

Parameters:

• id (int) – A unique plugin ID. You must obtain this from http://www.plugincafe.com.
• name (str) –

  The name of the plugin.

  Note

  If you want to affect the order that your plugins are displayed in menus you can add #$n as a prefix to this name, where n is a number. Lower numbers are displayed before higher numbers. If you make the name “–” it will show up as a menu separator.

• info (int) –

  The settings for the plugin. Possible flags are:

  PLUGINFLAG_COMMAND_HOTKEY

  Command is a hotkey command. Hotkey commands can only work globally.

• icon (BaseBitmap) –

  The icon for the command. The bitmap is copied.

  Note

  The icon should be of size 32x32, but will be scaled if needed. It must also be 24 bits and should if possible include an alpha to support pattern backgrounds.

• help (str) –

  The tool tips and status bar help text for the command.

  Note

  When using strings it is advised to use the string resources files and the GeLoadString function. This keeps the plugin easy to localise for any language you wish to support and makes full use of the language features of CINEMA 4D.

• dat (ToolData) – A data instance for the plugin.

Return type:

bool

Returns:

True if the registration was succesful.

c4d.plugins.RegisterMessagePlugin(id, str, info, dat)

Registers a MessageData plugin:

PLUGIN_ID = 987665431
plugins.RegisterMessagePlugin(PLUGIN_ID, "MyMessagePlugin", 0, MyMessagePlugin())

Parameters:

• id (int) – A unique plugin ID. You must obtain this from http://www.plugincafe.com.
• name (str) –

  The name of the plugin.

  Note

  If you want to affect the order that your plugins are displayed in menus you can add #$n as a prefix to this name, where n is a number. Lower numbers are displayed before higher numbers. If you make the name “–” it will show up as a menu separator.

• info (int) –

  The settings for the plugin. Possible flags are:

  PLUGINFLAG_COMMAND_HOTKEY

  Command is a hotkey command. Hotkey commands can only work globally.

• dat (MessageData) – A data instance for the plugin.

Return type:

bool

Returns:

True if the registration was succesful.

c4d.plugins.RegisterBitmapSaverPlugin(id, str, info, dat, suffix)

Registers a BitmapSaverData plugin:

PLUGIN_ID = 1234567890
desc = plugins.GeLoadString(MY_SAVER_DESC)
RegisterBitmapSaverPlugin(PLUGIN_ID, "MySaver", plugins.PLUGINFLAG_BITMAPSAVER_SUPPORT_8BIT|plugins.PLUGINFLAG_BITMAPSAVER_FORCESUFFIX, MySaver(), ".my")

Parameters:

• id (int) – A unique plugin ID. You must obtain this from http://www.plugincafe.com.
• str (str) –

  The name of the plugin.

  Note

  If you want to affect the order that your plugins are displayed in menus you can add #$n as a prefix to this name, where n is a number. Lower numbers are displayed before higher numbers. If you make the name “–” it will show up as a menu separator.

• info (int) –

  The settings for the plugin.

  PLUGINFLAG_BITMAPSAVER_SUPPORT_8BIT	Support 8-bit bitmaps.
  PLUGINFLAG_BITMAPSAVER_SUPPORT_16BIT	Support 16-bit bitmaps.
  PLUGINFLAG_BITMAPSAVER_SUPPORT_32BIT	Support 32-bit bitmaps.
  PLUGINFLAG_BITMAPSAVER_SUPPORT_8BIT_LAYERS	Support 8-bit layered bitmaps
  PLUGINFLAG_BITMAPSAVER_SUPPORT_16BIT_LAYERS	Support 16-bit layered bitmaps.
  PLUGINFLAG_BITMAPSAVER_SUPPORT_32BIT_LAYERS	Support 32-bit layered bitmaps.
  PLUGINFLAG_BITMAPSAVER_MOVIE	Support movies.
  PLUGINFLAG_BITMAPSAVER_ALLOWOPTIONS	Flag for C4D to identify the savers that have “Edit...” enabled.
  PLUGINFLAG_BITMAPSAVER_FORCESUFFIX	Ensure that saved files always get the specified suffix.

• dat (BitmapSaverData) – A data instance for the plugin.
• suffix (str) – The format’s file suffix.

Return type:

bool

Returns:

True if the registration was succesful.

c4d.plugins.RegisterBitmapLoaderPlugin(id, str, info, dat)

Registers a BitmapLoaderData plugin.

Parameters:

• id (int) – A unique plugin ID. You must obtain this from http://www.plugincafe.com.
• str (str) –

  The name of the plugin.

  Note

  If you want to affect the order that your plugins are displayed in menus you can add #$n as a prefix to this name, where n is a number. Lower numbers are displayed before higher numbers. If you make the name “–” it will show up as a menu separator.

• info (int) –

  The settings for the plugin. Possible flags are:

  PLUGINFLAG_BITMAPLOADER_MOVIE

  Support movies.

• dat (BitmapSaverData) – A data instance for the plugin.

Return type:

bool

Returns:

True if the registration was succesful.

c4d.plugins.RegisterTagPlugin(id, str, info, g, description, icon[, disklevel=0][, res])

Note

To make this work, __res__ must be defined in your global scope.

Registers a TagData plugin:

dir, file = os.path.split(__file__)
bmp = c4d.BaseBitmap()
bmp.InitWith(os.path.join(dir, "res", "image_name.tif"))
plugins.RegisterTagPlugin(id=PLUGIN_ID, name="MyTag", obj=MyTag,
                         description="your_identifier", icon=bmp,
                         info=plugins.TAG_MULTIPLE|plugins.TAG_EXPRESSION|plugins.TAG_VISIBLE)

Parameters:

• id (int) – A unique plugin ID. You must obtain this from http://www.plugincafe.com.
• str (str) –

  The name of the plugin.

  Note

  If you want to affect the order that your plugins are displayed in menus you can add #$n as a prefix to this name, where n is a number. Lower numbers are displayed before higher numbers. If you make the name “–” it will show up as a menu separator.

• info (int) –

  The settings for the plugin. Possible flags are:

  TAG_VISIBLE	The tag can be seen in the object manager.
  TAG_MULTIPLE	Multiple copies of the tag allowed on a single object.
  TAG_HIERARCHICAL	The tag works hierarchical, so that sub-objects inherit its properties (e.g. the material tag).
  TAG_EXPRESSION	The tag is an expression.
  TAG_TEMPORARY	Private.

• g (any) – The class name which inherits from TagData
• description (str) – The name of the description resource file to use for your plugin without .res, for example Ttagname. The name has to be unique, i.e. Tdisplay cannot be used for two different descriptions. See Description resource for more information.
• icon (BaseBitmap) –

  The icon for the command. Can be None. The bitmap is copied.

  Note

  The icon should be of size 32x32, but will be scaled if needed. It must also be 24 bits and should if possible include an alpha to support pattern backgrounds.

• disklevel (int) –

  The plugin level is similar to a version number for your settings. The default level is 0, you can then increase this for new revisions of your plugin, this allows for forward and backward compatibility.

  As an example you may have updated your plugin, if you now need to write additional information for new settings or changed types for old settings you can increase the level. During loading either a 0 is passed (if the file was written using your old plugin) or 1 (if the file was written by the new plugin). This allows you to easily save/read new values.

  Important

  For forward and backward compatibility to work you must not change any existing read order from a given level, CINEMA will skip any new settings automatically if they have not been read for your plugin.

  Note

  If you only use containers for all your values, you don’t have to deal with the disklevel.

• res (GeResource) – The optional resource.

Return type:

bool

Returns:

True if the registration was succesful.

c4d.plugins.RegisterObjectPlugin(id, str, g, description, info, icon[, disklevel][, res][, groupname[, group]])

Note

To make this work, __res__ must be defined in your global scope.

Registers an ObjectData plugin.

Parameters:

• id (int) – A unique plugin ID. You must obtain this from http://www.plugincafe.com.
• str (str) –

  The name of the plugin.

  Note

  If you want to affect the order that your plugins are displayed in menus you can add #$n as a prefix to this name, where n is a number. Lower numbers are displayed before higher numbers. If you make the name “–” it will show up as a menu separator.

• g (any) – The class name which inherits from ObjectData
• description (str) – The name of the description resource file to use for your plugin without .res, for example Ttagname. The name has to be unique, i.e. Tdisplay cannot be used for two different descriptions. See Description resource for more information.
• info (int) –

  One of the following flags

  OBJECT_MODIFIER	Modifier object. Deforms the surrounding object. (E.g. bend.)
  OBJECT_HIERARCHYMODIFIER	Hierarchical modifier. Deforms the surrounding objects together with other instances in a hierarchy chain. Only the top-most instance of the plugin in a chain is called. (E.g. bones.)
  OBJECT_GENERATOR	The tag works hierarchical, so that sub-objects inherit its properties (e.g. the material tag).
  OBJECT_INPUT	Used in combination with OBJECT_GENERATOR. Specifies that the generator uses builds a polygon or spline, using its subobjects as input. (E.g. Sweep NURBS, Boolean.)
  OBJECT_ISSPLINE	The object is a spline.
  OBJECT_USECACHECOLOR	If this flag is specified, the generator object itself controls the objects’ colors (the ones that determine the wireframe/shaded color). Normally these are automatically overwritten by the generator objects settings. E.g. if the instance object is set to green, automatically all of its cache objects get the green color. By setting this flag an instance object could individually color objects.
  OBJECT_CAMERADEPENDENT	Camera dependent.
  OBJECT_POINTOBJECT	Point Object
  OBJECT_POLYGONOBJECT	Polygon object.
  OBJECT_NO_PLA	Objects derived from PointObject will not use auto-keyframing (e.g. Joints can contain points and PLA auto-keyframing is not useful for them)
  OBJECT_DONTFREECACHE	Objects’ (generators) caches will not be be deleted - users must maintain caches themselves.

• icon (BaseBitmap) –

  The icon for the command. Can be None. The bitmap is copied.

  Note

  The icon should be of size 32x32, but will be scaled if needed. It must also be 24 bits and should if possible include an alpha to support pattern backgrounds.

• res (GeResource) – The optional resource.
• disklevel (int) –

  The plugin level is similar to a version number for your settings. The default level is 0, you can then increase this for new revisions of your plugin, this allows for forward and backward compatibility.

  As an example you may have updated your plugin, if you now need to write additional information for new settings or changed types for old settings you can increase the level. During loading either a 0 is passed (if the file was written using your old plugin) or 1 (if the file was written by the new plugin). This allows you to easily save/read new values.

  Important

  For forward and backward compatibility to work you must not change any existing read order from a given level, CINEMA will skip any new settings automatically if they have not been read for your plugin.

  Note

  If you only use containers for all your values, you don’t have to deal with the disklevel.

• group (int) – If you will develop more plugins in the future, you can use this optional argument to group all plugins. Obtain an id from plugincafe.com and put this ID to all plugins which you want to group in your own menu.
• groupname (str) – If the argument group is given, you should pass a string for the groupname. If the groupname between all grouped plugins is different, the first one is used. If no groupname in the grouped plugins was found, ‘#naname: id’ is used. Don’t use more than 18 chars.

Return type:

bool

Returns:

True if the registration was succesful.

c4d.plugins.RegisterSceneLoaderPlugin(id, str, info, g, description[, res])

Note

To make this work, __res__ must be defined in your global scope.

Registers a SceneLoaderData plugin.

Parameters:

• id (int) – The plugin id. Please obtain a serial from plugincafe.com
• str (str) –

  The name of the plugin.

  Note

  If you want to affect the order that your plugins are displayed in menus you can add #$n as a prefix to this name, where n is a number. Lower numbers are displayed before higher numbers. If you make the name “–” it will show up as a menu separator.

• g (any) – The class name which inherits from SceneLoaderData
• info (int) –

  The settings for the plugin. Possible flags are:

  PLUGINFLAG_SCENELOADER_MERGEORIGINAL	If this flag is set, the original (existing) document will be passed to the scene loader instead of a new (empty) one. This allows the importer to change existing data, merge data or to make other modifications based on the existing scene.
  PLUGINFLAG_SCENEFILTER_DIALOGCONTROL	By default the scene loader/saver displays its own desciption dialog during importing/exporting of scene files. By setting this flag it will surpress this behaviour allowing to display another extended dialog for example.

• description (str) – The name of the description resource file to use for your plugin without .res, for example Ffiltername. The name has to be unique, i.e. Tdisplay cannot be used for two different descriptions.
• res (GeResource) – The optional resource.

Return type:

bool

Returns:

True if the registration was succesful.

c4d.plugins.RegisterSceneSaverPlugin(id, str, g, info, description, suffix[, res])

Note

To make this work, __res__ must be defined in your global scope.

Registers a SceneSaverData plugin.

Parameters:

• id (int) – The plugin id. Please obtain a serial from plugincafe.com
• str (str) –

  The name of the plugin.

  Note

  If you want to affect the order that your plugins are displayed in menus you can add #$n as a prefix to this name, where n is a number. Lower numbers are displayed before higher numbers. If you make the name “–” it will show up as a menu separator.

• g (any) – The class name which inherits from SceneSaverData
• info (int) –

  The flags are

  PLUGINFLAG_SCENEFILTER_DIALOGCONTROL

  By default the scene loader/saver displays its own desciption dialog during importing/exporting of scene files. By setting this flag it will surpress this behaviour allowing to display another extended dialog for example.

• description (str) – The name of the description resource file to use for your plugin without .res, for example Ffiltername. The name has to be unique, i.e. Tdisplay cannot be used for two different descriptions.
• suffix (str) – The format’s file suffix.
• res (GeResource) – The optional resource.

Return type:

bool

Returns:

True if the registration was succesful.