Follow me to the Inheritance diagramm.
This document contains classes to create your own plugins. To get information about the plugin structure, check out Plugin Structure.
Functions
Register Functions
- c4d.plugins.GeLoadString(id[, p1[, p2[, p3[, p4]]]])
-
Note
To use this function, __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: |
- id (int) – The ID of the string to get.
- 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.
| Parameters: |
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 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.ReadRegInfo(pluginid, size)
-
Reads user-specific data (e.g. login data for a user account).
| Parameters: |
- pluginid (int) – The plugin ID the data is associated with.
- size (int) – The buffer size
|
| Return type: |
ByteSeq
|
| Returns: |
The data buffer.
|
- c4d.plugins.WriteRegInfo(pluginid, buffer)
-
Writes user-specific data (e.g. login data for a user account).
| Parameters: |
- pluginid (int) – The plugin ID the data is associated with.
- buffer (ByteSeq) – The data buffer.
|
- c4d.plugins.ReadPluginInfo(pluginid, size)
-
Read private serial information for a plugin. CINEMA 4D will store this data encrypted.
| Parameters: |
- pluginid (int) – The plugin ID the data is associated with.
- size (int) – The buffer size
|
| Return type: |
ByteSeq
|
| Returns: |
The data buffer.
|
- c4d.plugins.WritePluginInfo(pluginid, buffer)
-
Write private serial information for a plugin. CINEMA 4D will store this data encrypted.
| Parameters: |
- pluginid (int) – The plugin ID the data is associated with.
- buffer (ByteSeq) – The data buffer.
|
- 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 found by id.
| Parameters: |
|
| 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(c4d.PLUGINTYPE_BITMAPSAVER, True)
| Parameters: |
-
type (int) –
Plugin type filter:
| PLUGINTYPE_ANY |
Any. |
| PLUGINTYPE_SHADER |
2D Shader. |
| PLUGINTYPE_MATERIAL |
3D Shader. |
| PLUGINTYPE_COMMAND |
Command (menu) plugin. |
| PLUGINTYPE_OBJECT |
Object plugin. |
| PLUGINTYPE_TAG |
Tag plugin. |
| PLUGINTYPE_BITMAPFILTER |
Bitmap filter. |
| PLUGINTYPE_VIDEOPOST |
Videopost effect. |
| PLUGINTYPE_TOOL |
Tool Plugin. |
| PLUGINTYPE_SCENEHOOK |
Scene Hook. |
| PLUGINTYPE_NODE |
Node Plugin. |
| PLUGINTYPE_LIBRARY |
Library. |
| PLUGINTYPE_BITMAPLOADER |
Bitmap loader. |
| PLUGINTYPE_BITMAPSAVER |
Bitmap saver. |
| PLUGINTYPE_SCENELOADER |
Scene loader. |
| PLUGINTYPE_SCENESAVER |
Scene saver. |
| PLUGINTYPE_COREMESSAGE |
Core message. |
| PLUGINTYPE_CUSTOMGUI |
Custom GUI. |
| PLUGINTYPE_CUSTOMDATATYPE |
Custom datatype. |
| PLUGINTYPE_RESOURCEDATATYPE |
Resource datatype. |
| PLUGINTYPE_MANAGERINFORMATION |
Manager information plugin. |
| PLUGINTYPE_CTRACK |
Track plugin. |
| PLUGINTYPE_FALLOFF |
Falloff plugin. |
| PLUGINTYPE_PREFS |
Preference hook. |
- 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_HIDE |
Hide the plugin. |
| PLUGINFLAG_SMALLNODE |
Create a small node. |
| PLUGINFLAG_COFFEE |
C.O.F.F.E.E. plugin. |
| PLUGINFLAG_HIDEPLUGINMENU |
Hide the plugin’s menu entry. |
| PLUGINFLAG_REFRESHALWAYS |
In 8.5 CINEMA 4D uses cached descriptions for higher speed.... |
| 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 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_HIDE |
Hide the plugin. |
| PLUGINFLAG_SMALLNODE |
Create a small node. |
| PLUGINFLAG_COFFEE |
C.O.F.F.E.E. plugin. |
| PLUGINFLAG_HIDEPLUGINMENU |
Hide the plugin’s menu entry. |
| PLUGINFLAG_REFRESHALWAYS |
In 8.5 CINEMA 4D uses cached descriptions for higher speed.... |
| PLUGINFLAG_COMMAND_HOTKEY |
Command is a hotkey command. Hotkey commands can only work globally. |
| PLUGINFLAG_COMMAND_OPTION_DIALOG |
Command has additional options. The user can access them through a small gadget. |
| PLUGINFLAG_COMMAND_STICKY |
Command is a “sticky” command. This means CommandData.Execute() is called when the user presses an assigned hotkey and when the hotkey is released. Otherwise the command would be called continously. |
-
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 (CommandData) – A data instance for the plugin.
|
| Return type: |
bool
|
| Returns: |
True if the registration was succesful.
|
- c4d.plugins.RegisterFalloffPlugin(id, str, info, g, description[, res])
-
New in version R13.016.
Registers a FalloffData plugin:
| Parameters: |
|
| 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: |
|
| 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: |
|
| Return type: |
bool
|
| Returns: |
True if the registration was succesful.
|
- c4d.plugins.RegisterBitmapLoaderPlugin(id, str, info, dat)
-
Registers a BitmapLoaderData plugin.
| Parameters: |
|
| Return type: |
bool
|
| Returns: |
True if the registration was succesful.
|
- c4d.plugins.RegisterTagPlugin(id, str, info, g, description, icon[, disklevel=0][, res])
-
Note
To use this function, __res__ must be defined in your global scope.
Registers a TagData plugin:
dir, file = os.path.split(__file__)
bmp = c4d.bitmaps.BaseBitmap()
bmp.InitWith(os.path.join(dir, "res", "image_name.tif"))
plugins.RegisterTagPlugin(id=PLUGIN_ID, str="MyTag", g=MyTag,
description="your_identifier", icon=bmp,
info=c4d.TAG_MULTIPLE|c4d.TAG_EXPRESSION|c4d.TAG_VISIBLE)
| Parameters: |
-
id (int) –
A unique plugin ID. You must obtain this 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.
-
info (int) –
The settings for the plugin. Possible flags are:
| PLUGINFLAG_HIDE |
Hide the plugin. |
| PLUGINFLAG_SMALLNODE |
Create a small node. |
| PLUGINFLAG_COFFEE |
C.O.F.F.E.E. plugin. |
| PLUGINFLAG_HIDEPLUGINMENU |
Hide the plugin’s menu entry. |
| PLUGINFLAG_REFRESHALWAYS |
In 8.5 CINEMA 4D uses cached descriptions for higher speed.... |
| 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 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.RegisterShaderPlugin(id, str, info, g, description[, disklevel][, res])
-
New in version R13.016.
Registers a ShaderData plugin.
| Parameters: |
-
id (int) –
A unique plugin ID. You must obtain this 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.
-
info (int) –
One of the following flags:
| PLUGINFLAG_HIDE |
Hide the plugin. |
| PLUGINFLAG_SMALLNODE |
Create a small node. |
| PLUGINFLAG_COFFEE |
C.O.F.F.E.E. plugin. |
| PLUGINFLAG_HIDEPLUGINMENU |
Hide the plugin’s menu entry. |
| PLUGINFLAG_REFRESHALWAYS |
In 8.5 CINEMA 4D uses cached descriptions for higher speed.... |
- g (any) – The class which inherits from ShaderData
- description (str) – The name of the description resource file to use for your plugin without .res, for example “Xshadername”. The name has to be unique, i.e. “Tdisplay” cannot be used for two different descriptions. See Description resource for more information.
-
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 use this function, __res__ must be defined in your global scope.
Registers an ObjectData plugin.
| Parameters: |
-
id (int) –
A unique plugin ID. You must obtain this 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 which inherits from ObjectData
- description (str) – The name of the description resource file to use for your plugin without .res, for example Oobjectname. 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:
| PLUGINFLAG_HIDE |
Hide the plugin. |
| PLUGINFLAG_SMALLNODE |
Create a small node. |
| PLUGINFLAG_COFFEE |
C.O.F.F.E.E. plugin. |
| PLUGINFLAG_HIDEPLUGINMENU |
Hide the plugin’s menu entry. |
| PLUGINFLAG_REFRESHALWAYS |
In 8.5 CINEMA 4D uses cached descriptions for higher speed.... |
| 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_PARTICLEMODIFIER |
Particle modifier. |
| 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. |
| OBJECT_CALL_ADDEXECUTION |
Must be set to call ObjectData.Execute() in the priority pipeline specified by ObjectData.AddToExecution(). |
-
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.RegisterNodePlugin(id, str, info, g, icon[, disklevel])
-
New in version R13.016.
Registers a NodeData plugin.
Note
Normally you won’t use this function directly, but rather the specific registration functions for each NodeData child class.
| Parameters: |
-
id (int) –
A unique plugin ID. You must obtain this 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.
-
info (int) –
One of the following flags:
| PLUGINFLAG_HIDE |
Hide the plugin. |
| PLUGINFLAG_SMALLNODE |
Create a small node. |
| PLUGINFLAG_COFFEE |
C.O.F.F.E.E. plugin. |
| PLUGINFLAG_HIDEPLUGINMENU |
Hide the plugin’s menu entry. |
| PLUGINFLAG_REFRESHALWAYS |
In 8.5 CINEMA 4D uses cached descriptions for higher speed.... |
- g (any) – The class which inherits from NodeData
-
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.
|
| Return type: |
bool
|
| Returns: |
True if the registration was succesful.
|
- c4d.plugins.RegisterManagerInformation(id, str, info)
-
New in version R13.016.
Registers manager information for use when registering shortcuts with AddShortcut().
| Parameters: |
|
| Return type: |
bool
|
| Returns: |
True if the registration was succesful.
|
- c4d.plugins.RegisterSceneLoaderPlugin(id, str, g, info, description[, res])
-
Note
To use this function, __res__ must be defined in your global scope.
Registers a SceneLoaderData plugin.
| Parameters: |
|
| Return type: |
bool
|
| Returns: |
True if the registration was succesful.
|
- c4d.plugins.RegisterSceneSaverPlugin(id, str, g, info, description, suffix[, res])
-
Note
To use this function, __res__ must be defined in your global scope.
Registers a SceneSaverData plugin.
| Parameters: |
|
| Return type: |
bool
|
| Returns: |
True if the registration was succesful.
|