c4d.plugins

class c4d.plugins

Provides classes to implement and functions to register plugins.

Note

  • See Plugin Structure for information how to setup a plugin project in a folder.

  • The ID passed to plugin registration functions has to be globally unique. Attempting to reuse an identifier will cause only one of the plugins that tries to claim that identifier to be successfully loaded on the startup of Cinema 4D. Please make sure to always obtain identifiers for plugins from the Plugin ID generator on Plugin Café to avoid identifier collisions. You must create an account with Plugin Café in order to use the generator.

Types

Functions Signatures

Plugin Data Functions

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.

c4d.plugins.ReadPluginInfo(pluginid, size)

Read private serial information for a plugin. Cinema 4D will store this data encrypted.

c4d.plugins.ReadRegInfo(pluginid, size)

Reads user-specific data (e.g. login data for a user account).

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

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

c4d.plugins.WritePluginInfo(pluginid, buffer)

Write private serial information for a plugin. Cinema 4D will store this data encrypted.

c4d.plugins.WriteRegInfo(pluginid, buffer)

Writes user-specific data (e.g. login data for a user account).

Register Functions

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

Registers a BitmapLoaderData plugin.

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

Registers a BitmapSaverData plugin.

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

Registers a CommandData plugin.

c4d.plugins.RegisterDescription(id, str[, res])

Registers a description for a plugin ID.

c4d.plugins.RegisterFalloffPlugin(id, str, info, g, ...)

Registers a FalloffData plugin.

c4d.plugins.RegisterHiddenToken(key, help, example, hook)

This function registers a hidden token that is not displayed in Render Settings.

c4d.plugins.RegisterManagerInformation(id, str, info)

Registers manager information for use when registering shortcuts with AddShortcut().

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

Registers a MessageData plugin.

c4d.plugins.RegisterNodePlugin(id, str, info, g, icon)

Registers a NodeData plugin.

c4d.plugins.RegisterObjectPlugin(id, str, g, ...[, ...])

Registers an ObjectData plugin.

c4d.plugins.RegisterPluginHelpCallback(pluginid, callback)

Registers a callback for plugin help support.

c4d.plugins.RegisterPreferencePlugin(id, g, name, ...)

Registers a new preference in the Cinema 4D preferences dialog.

c4d.plugins.RegisterSceneLoaderPlugin(id, str, g, info, ...)

Registers a SceneLoaderData plugin.

c4d.plugins.RegisterSceneSaverPlugin(id, str, g, info, ...)

Registers a SceneSaverData plugin.

c4d.plugins.RegisterSculptBrushPlugin(id, str, info, icon, ...)

Registers a SculptBrushToolData.

c4d.plugins.RegisterShaderPlugin(id, str, info, g, ...)

Registers a ShaderData plugin.

c4d.plugins.RegisterTagPlugin(id, str, info, g, ...)

Registers a TagData plugin:

c4d.plugins.RegisterToken(key, help, example, hook)

Registers a new Token that can be used in a render filename, the token is displayed in the render setting and can be selected by the user.

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

Registers a ToolData plugin.

Registered Plugins Functions

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:

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

Returns the BasePlugin found by id.

c4d.plugins.GetFirstPlugin()

Returns the first plugin of Cinema 4D.

Uncategorized

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

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

c4d.plugins.GetToolData(doc, pluginid)

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

Functions Documentation

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.

See also

This script that shows how to effectively access and change the settings of an importer/exporter.

Parameters

id (int) – The plugin ID that the container should be associated with.

Return type

c4d.BaseContainer

Returns

The retrieved container

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

bytes

Returns

The data buffer.

c4d.plugins.ReadRegInfo(pluginid, size)

Reads user-specific data (e.g. login data for a user account).

Note

Use this method instead of WritePluginInfo() in a license server environment.

Parameters

  • pluginid (int) – The plugin ID the data is associated with.

  • size (int) – The buffer size

Return type

bytes

Returns

The data buffer.

c4d.plugins.SetWorldPluginData(id, bc, add=True)

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

See also

This script that shows how to effectively access and change the settings of an importer/exporter.

Parameters

  • id (int) – The plugin ID that the container should be associated with. Please use a unique ID from PluginCafe.

  • bc (c4d.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.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 (bytes) – The data buffer.

c4d.plugins.WriteRegInfo(pluginid, buffer)

Writes user-specific data (e.g. login data for a user account).

Note

Use this method instead of WritePluginInfo() in a license server environment.

Parameters

  • pluginid (int) – The plugin ID the data is associated with.

  • buffer (bytes) – The data buffer.

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

Registers a BitmapLoaderData plugin.

See also

Py-XampleLoader a BitmapLoaderData plugin example.

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:

    • Plugin General Flags

    PLUGINFLAG_HIDE

    Hide the plugin.

    PLUGINFLAG_SMALLNODE

    Create a small node.

    PLUGINFLAG_HIDEPLUGINMENU

    Hide the plugin’s menu entry.

    PLUGINFLAG_REFRESHALWAYS

    Deprecated. Legacy plugin flag.

    • Bitmap Loader Plugin Flags

    PLUGINFLAG_BITMAPLOADER_MOVIE

    Support movies.

  • dat (c4d.plugins.BitmapLoaderData) – A data instance for the plugin.

Return type

bool

Returns

True if the registration was successful.

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

Registers a BitmapSaverData plugin.

See also

Py-XampleSaver a BitmapSaverData plugin example.

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.

    • Plugin General Flags

    PLUGINFLAG_HIDE

    Hide the plugin.

    PLUGINFLAG_SMALLNODE

    Create a small node.

    PLUGINFLAG_HIDEPLUGINMENU

    Hide the plugin’s menu entry.

    PLUGINFLAG_REFRESHALWAYS

    Deprecated. Legacy plugin flag.

    • Bitmap Saver Plugin Flags

    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 Cinema 4D to identify the savers that have “Edit…” enabled.

    PLUGINFLAG_BITMAPSAVER_FORCESUFFIX

    Ensure that saved files always get the specified suffix.

    PLUGINFLAG_BITMAPSAVER_SUPPORT_SOUND

    New in version R19: Ensure that saved files always get the specified suffix.

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

  • suffix (str) – The format’s file suffix.

Return type

bool

Returns

True if the registration was successful.

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

Registers a CommandData plugin.

See also

Py-TextureBaker a CommandData plugin example.

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:

    • Plugin General Flags

    PLUGINFLAG_HIDE

    Hide the plugin.

    PLUGINFLAG_SMALLNODE

    Create a small node.

    PLUGINFLAG_HIDEPLUGINMENU

    Hide the plugin’s menu entry.

    PLUGINFLAG_REFRESHALWAYS

    Deprecated. Legacy plugin flag.

    • Command Plugin Flags

    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.

    PLUGINFLAG_COMMAND_ICONGADGET

    Command can be dragged into an icon bar and delivers its own dialogs instead of icons.

  • icon (Optional[c4d.bitmaps.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 (c4d.plugins.CommandData) – A data instance for the plugin.

Return type

bool

Returns

True if the registration was successful.

c4d.plugins.RegisterDescription(id, str, res=None)

Registers a description for a plugin ID.

New in version R16.021.

Note

Not needed for plugin types whose Register() functions have a description parameter.

Parameters

  • id (int) – The plugin ID. If this is a standalone description, use a unique ID.

  • str (str) –

    The name of the description resource file to use for your plugin without .res extension, for example “registered”.
    The name has to be unique, i.e. Tdisplay cannot be used for two different descriptions.

  • res (Optional[c4d.plugins.GeResource]) – Pass to search in a specific resource class. Otherwise the default path is used.

Return type

bool

Returns

True if the registration was successful.

c4d.plugins.RegisterFalloffPlugin(id, str, info, g, description, res=None)

Registers a FalloffData plugin.

See also

Py-NoiseFalloff a FalloffData plugin example.

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_HIDEPLUGINMENU

    Hide the plugin’s menu entry.

    PLUGINFLAG_REFRESHALWAYS

    Deprecated. Legacy plugin flag.

  • g (c4d.plugins.FalloffData) – The class which inherits from FalloffData.

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

  • res (Optional[c4d.plugins.GeResource]) – The optional resource.

Return type

bool

Returns

True if the registration was successful.

c4d.plugins.RegisterHiddenToken(key, help, example, hook)

This function registers a hidden token that is not displayed in Render Settings.

New in version R21.

See also

Py-RenderToken a hidden Token callback example.

Note

The key is the identifier for the Token and has to be unique.
For this reason identify your plugin in the Token key as a prefix.

Example: “myplug.pass” instead of just “pass” as it will collide wit the generic “pass” Token definition.
Parameters

  • key (str) – The key string for the Token itself without the “$”.

  • help (str) – An help string used to show the Token in the menu.

  • example (str) – An example string for the use of the Token.

  • hook (function(data)) –

    A function used to define the string to replace the Token.

    The expected function signature is functionName(data) and parameters correspond to:

    • data: (c4d.BaseContainer) A baseContainer with the next data:

      • data[0] (c4d.documents.BaseDocument) The BaseDocument used for rendering, can be a clone of original document.

      • data[1] (c4d.documents.RenderData) The RenderData used for rendering.

      • data[2] (c4d.BaseContainer) The BaseContainer with the render settings (can be different from _rData->GetDataInstance() eg. RQ change paths).

      • data[3] (c4d.modules.takesystem.BaseTake) The BaseTake used for rendering.

      • data[4] (int) The frame number used for rendering or NOTOK if the frame is not yet recognized.

      • data[5] (str) The pass user name if multipass is activated.

      • data[6] (str) The pass type name if multipass is activated.

      • data[7] (int) The pass ID used for rendering or NOTOK if multipass is not active or not yet recognized.

      • data[8] (bool) True if the pass is a separated light pass.

      • data[9] (int) The light number id.

      • data[10] (bool) True if the pass is a separated reflectance material pass.

      • data[11] (str) if data[9] is True or data[10] is True store here the object scene name.

      • data[12] (bool) if True warning strings will be used for the Tokens that cannot be resolved.

      • data[13] (c4d.BaseList2D) An owner node for certain tokens such as MoGraph cache tokens. Can be None.

Return type

str

Returns

The string that will replace the Token.

c4d.plugins.RegisterManagerInformation(id, str, info)

Registers manager information for use when registering shortcuts with AddShortcut().

Parameters

  • id (int) –

    A unique plugin ID. You must obtain this from PluginCafe.com

  • str (str) – Manager name.

  • info (int) –

    The settings for the plugin. Possible flags are:

    PLUGINFLAG_HIDE

    Hide the plugin.

    PLUGINFLAG_SMALLNODE

    Create a small node.

    PLUGINFLAG_HIDEPLUGINMENU

    Hide the plugin’s menu entry.

    PLUGINFLAG_REFRESHALWAYS

    Deprecated. Legacy plugin flag.

Return type

bool

Returns

True if the registration was successful.

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

Registers a MessageData 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) –

    The settings for the plugin.

    • Plugin General Flags

    PLUGINFLAG_HIDE

    Hide the plugin.

    PLUGINFLAG_SMALLNODE

    Create a small node.

    PLUGINFLAG_HIDEPLUGINMENU

    Hide the plugin’s menu entry.

    PLUGINFLAG_REFRESHALWAYS

    Deprecated. Legacy plugin flag.

    • Message Plugin Flags

    PLUGINFLAG_MESSAGE_SYNCEVENT

    New in version R17.032: Sync messages will also be received by the message plugin.

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

Return type

bool

Returns

True if the registration was successful.

c4d.plugins.RegisterNodePlugin(id, str, info, g, icon, disklevel=0)

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_HIDEPLUGINMENU

    Hide the plugin’s menu entry.

    PLUGINFLAG_REFRESHALWAYS

    Deprecated. Legacy plugin flag.

  • g (any) – The class which inherits from NodeData

  • icon (Optional[c4d.bitmaps.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 (Optional[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 4D 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 do not have to deal with the disklevel.

Return type

bool

Returns

True if the registration was successful.

c4d.plugins.RegisterObjectPlugin(id, str, g, description, info, icon, disklevel=0, res=None)

Registers an ObjectData plugin.

Note

To use this function, __res__ must be defined in your global scope.

See also

Py-RoundedTube an ObjectData plugin example.

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.

  • info (int) –

    One of the following flags:

    • Plugin General Flags

    PLUGINFLAG_HIDE

    Hide the plugin.

    PLUGINFLAG_SMALLNODE

    Create a small node.

    PLUGINFLAG_HIDEPLUGINMENU

    Hide the plugin’s menu entry.

    PLUGINFLAG_REFRESHALWAYS

    Deprecated. Legacy plugin flag.

    • Object Plugin 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

    Generator object. Produces a polygonal or spline representation on its own. (E.g. primitive cube.)

    OBJECT_INPUT

    Used in combination with OBJECT_GENERATOR. Specifies that the generator builds a polygon or spline, using its sub-objects as input. (E.g. Sweep Subdivision Surface, 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().

    OBJECT_NOCHILDEXPRESSIONS

    New in version R20: Don’t execute expression tags on the children of the object.

    OBJECT_FIELDOBJECT

    New in version R20: Field object. Can’t be created in Python.

  • icon (Optional[c4d.bitmaps.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 4D 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 do not have to deal with the disklevel.

  • res (Optional[c4d.plugins.GeResource]) – The optional resource.

Return type

bool

Returns

True if the registration was successful.

c4d.plugins.RegisterPluginHelpCallback(pluginid, callback)

Registers a callback for plugin help support.

New in version R19.

Parameters

  • pluginid (int) –

    The plugin id. Please obtain a serial from PluginCafe.com

  • callback (function(opType, baseType, group, property)) –

    The help callback for the plugin. Useful to display context sensitive help when the user selects “Show Help” for a node or attribute.
    The passed arguments are:
    opType: str: The node type name, for example “OATOM”.
    baseType: str: The name of the base object type that opType is derived from, usually the same as opType.
    group: str: The name of the group in the attribute manager, for example “ID_OBJECTPROPERTIES”.
    property: str: The name of the property, for example “ATOMOBJECT_SINGLE”.
    The callback function returns True if help has been provided, otherwise False.

    Warning

    Only return True for the registered plugin types.

Return type

bool

Returns

True if successful, otherwise False.

c4d.plugins.RegisterPreferencePlugin(id, g, name, description, parentid, sortid)

Registers a new preference in the Cinema 4D preferences dialog.

New in version R19.

See also

Py-Preference a Preference plugin example.

Parameters

  • id (int) –

    A unique plugin ID. You must obtain this from PluginCafe.com

  • g (any) – The class which inherits from PreferenceData

  • name (str) – The name of the preference.

  • 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.

  • parentid (int) – The ID of the preference parent hook. Should be usually set to 0.

  • sortid (int) –

    The ID of the parent category in the preferences tree or 0 to create a top-level category. The internal categories are:

    PREFS_THEME

    Interface Colors.

    PREFS_COLORNEW

    Editor Colors.

    PREFS_MOUSE

    Input Devices.

    PREFS_OPENGL

    OpenGL.

    PREFS_VIEW

    Viewport.

    PREFS_FILES

    Files.

    PREFS_UNITS

    Units.

    PREFS_MEMORY

    Memory.

    PREFS_COMMUNICATION

    Communication.

    PREFS_RENDERERNEW

    Renderer.

    PREFS_NEWPREFS

    Interface.

    PREFS_BP

    Bodypaint 3D.

    PREFS_MATMANAGER

    Material.

    PREFS_IMPORTEXPORT

    Import/Export.

    PREFS_LINUX

    Linux Command Line.

    PREFS_SCHEMECOLORS

    Color Scheme.

    PREFS_HAIR_COLOR

    Hair Color.

    PREFS_NAVIGATION

    Navigation.

    PREFS_PLUGINS

    Plugins.

    PREFS_GPURENDERER

    ProRender.

    PREFS_LIVELINK

    PREFS_EXTENSIONS

c4d.plugins.RegisterSceneLoaderPlugin(id, str, g, info, description, res=None)

Registers a SceneLoaderData plugin.

Note

To use this function, __res__ must be defined in your global scope.

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 which inherits from SceneLoaderData

  • info (int) –

    The settings for the plugin. Possible flags are:

    • Plugin General Flags

    PLUGINFLAG_HIDE

    Hide the plugin.

    PLUGINFLAG_SMALLNODE

    Create a small node.

    PLUGINFLAG_HIDEPLUGINMENU

    Hide the plugin’s menu entry.

    PLUGINFLAG_REFRESHALWAYS

    Deprecated. Legacy plugin flag.

    • Scene Loader Plugin Flags

    Symbol ID

    Description

    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_SCENELOADER_URL_AWARE

    New in version S24: Scene loader plugin flag to signal that the scene loader is capable to deal with urls not in the file system e.g. asset:///

    PLUGINFLAG_SCENELOADER_SUPPORT_ASYNC

    New in version S26: Signals that a scene loader should run asynchronously.

    • Scene Filter Plugin Flags

    PLUGINFLAG_SCENEFILTER_DIALOGCONTROL

    By default the scene loader/saver displays its own description 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 (Optional[c4d.plugins.GeResource]) – The optional resource.

Return type

bool

Returns

True if the registration was successful.

c4d.plugins.RegisterSceneSaverPlugin(id, str, g, info, description, suffix, res=None)

Registers a SceneSaverData plugin.

Note

To use this function, __res__ must be defined in your global scope.

See also

Py-IesMeta a SceneSaverData plugin example.

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 which inherits from SceneSaverData

  • info (int) –

    The flags are

    • Plugin General Flags

    PLUGINFLAG_HIDE

    Hide the plugin.

    PLUGINFLAG_SMALLNODE

    Create a small node.

    PLUGINFLAG_HIDEPLUGINMENU

    Hide the plugin’s menu entry.

    PLUGINFLAG_REFRESHALWAYS

    Deprecated. Legacy plugin flag.

    • Scene Filter Plugin Flags

    PLUGINFLAG_SCENEFILTER_DIALOGCONTROL

    By default the scene loader/saver displays its own description 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 (Optional[c4d.plugins.GeResource]) – The optional resource.

Return type

bool

Returns

True if the registration was successful.

c4d.plugins.RegisterSculptBrushPlugin(id, str, info, icon, help, sculptparams, dat, res)

Registers a SculptBrushToolData.

See also

The next SculptBrushToolData plugins examples:

Py-SculptGrabBrush, Py-SculptPaintBrush, Py-SculptPullBrush and Py-SculptTwistBrush

New in version R16.021.

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:

    • Plugin General Flags

    PLUGINFLAG_HIDE

    Hide the plugin.

    PLUGINFLAG_SMALLNODE

    Create a small node.

    PLUGINFLAG_HIDEPLUGINMENU

    Hide the plugin’s menu entry.

    PLUGINFLAG_REFRESHALWAYS

    Deprecated. Legacy plugin flag.

    • Tool Plugin Flags

    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.

    PLUGINFLAG_TOOL_SWITCHACTION

    New in version R17.032: Allow the tool to switch to a different tool on modifier.

    PLUGINFLAG_TOOL_IS_SELECTION

    New in version S22: The tool is a selection tool, will be used to toggle the tool accordingly.

    PLUGINFLAG_TOOL_NO_TOPOLOGY_EDIT

    New in version S22: | The tool do not affect the polygon object topology (for example is a transform tool). | It is used internally to allow advance UV display in the 3d viewport.

  • icon (Optional[c4d.bitmaps.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.

  • sculptparams (c4d.modules.sculpting.SculptBrushParams) – The brush parameters.

  • dat (c4d.plugins.SculptBrushToolData) – A data instance for the plugin.

  • res (c4d.plugins.GeResource) – The optional resource.

Return type

bool

Returns

True if the registration was successful.

c4d.plugins.RegisterShaderPlugin(id, str, info, g, description, disklevel=0, res=None)

Registers a ShaderData plugin.

See also

Py-Fresnel a ShaderData plugin example.

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_HIDEPLUGINMENU

    Hide the plugin’s menu entry.

    PLUGINFLAG_REFRESHALWAYS

    Deprecated. Legacy plugin flag.

  • 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.

  • 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 4D 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 do not have to deal with the disklevel.

  • res (Optional[c4d.plugins.GeResource]) – The optional resource.

Return type

bool

Returns

True if the registration was successful.

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

Registers a TagData plugin:

Note

To use this function, __res__ must be defined in your global scope.

See also

Py-LookAtCamera a TagData plugin example.

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:

    • Plugin General Flags

    PLUGINFLAG_HIDE

    Hide the plugin.

    PLUGINFLAG_SMALLNODE

    Create a small node.

    PLUGINFLAG_HIDEPLUGINMENU

    Hide the plugin’s menu entry.

    PLUGINFLAG_REFRESHALWAYS

    Deprecated. Legacy plugin flag.

    • Tag Plugin Flags

    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.

    TAG_ADDTOTAKEGROUP

    New in version R17.032: The tag is added to the Take override groups system.

    TAG_IMPLEMENTS_DRAW_FUNCTION

    New in version S22: The tag implements the TagData.Draw() function.

  • 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.

  • icon (Optional[c4d.bitmaps.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 4D 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 do not have to deal with the disklevel.

  • res (Optional[c4d.plugins.GeResource]) – The optional resource.

Return type

bool

Returns

True if the registration was successful.

c4d.plugins.RegisterToken(key, help, example, hook)

Registers a new Token that can be used in a render filename, the token is displayed in the render setting and can be selected by the user.

New in version R21.

See also

Py-RenderToken a Token callback example.

Note

The key is the identifier for the Token and has to be unique.
For this reason identify your plugin in the Token key as a prefix.

Example: “myplug.pass” instead of just “pass” as it will collide wit the generic “pass” Token definition.
Parameters

  • key (str) – The key string for the Token itself without the “$”.

  • help (str) – An help string used to show the Token in the menu.

  • example (str) – An example string for the use of the Token.

  • hook (function(data)) –

    A function used to define the string to replace the Token.

    The expected function signature is functionName(data) and parameters correspond to:

    • data: (c4d.BaseContainer) A baseContainer with the next data:

      • data[0] (c4d.documents.BaseDocument) The BaseDocument used for rendering, can be a clone of original document.

      • data[1] (c4d.documents.RenderData) The RenderData used for rendering.

      • data[2] (c4d.BaseContainer) The BaseContainer with the render settings (can be different from _rData->GetDataInstance() eg. RQ change paths).

      • data[3] (c4d.modules.takesystem.BaseTake) The BaseTake used for rendering.

      • data[4] (int) The frame number used for rendering or NOTOK if the frame is not yet recognized.

      • data[5] (str) The pass user name if multipass is activated.

      • data[6] (str) The pass type name if multipass is activated.

      • data[7] (int) The pass ID used for rendering or NOTOK if multipass is not active or not yet recognized.

      • data[8] (bool) True if the pass is a separated light pass.

      • data[9] (int) The light number id.

      • data[10] (bool) True if the pass is a separated reflectance material pass.

      • data[11] (str) if data[9] is True or data[10] is True store here the object scene name.

      • data[12] (bool) if True warning strings will be used for the Tokens that cannot be resolved.

      • data[13] (c4d.BaseList2D) An owner node for certain tokens such as MoGraph cache tokens. Can be None.

Return type

str

Returns

The string that will replace the Token.

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

Registers a ToolData plugin.

See also

Py-LiquidPainter a ToolData plugin example.

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:

    • Plugin General Flags

    PLUGINFLAG_HIDE

    Hide the plugin.

    PLUGINFLAG_SMALLNODE

    Create a small node.

    PLUGINFLAG_HIDEPLUGINMENU

    Hide the plugin’s menu entry.

    PLUGINFLAG_REFRESHALWAYS

    Deprecated. Legacy plugin flag.

    • Tool Plugin Flags

    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.

    PLUGINFLAG_TOOL_SWITCHACTION

    New in version R17.032: Allow the tool to switch to a different tool on modifier.

    PLUGINFLAG_TOOL_IS_SELECTION

    New in version S22: The tool is a selection tool, will be used to toggle the tool accordingly.

    PLUGINFLAG_TOOL_NO_TOPOLOGY_EDIT

    New in version S22: | The tool do not affect the polygon object topology (for example is a transform tool). | It is used internally to allow advance UV display in the 3d viewport.

  • icon (Optional[c4d.bitmaps.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 (c4d.plugins.ToolData) – A data instance for the plugin.

Return type

bool

Returns

True if the registration was successful.

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:

import c4d

pluginList = c4d.plugins.FilterPluginList(c4d.PLUGINTYPE_BITMAPSAVER, True)
for plugin in pluginList:
    print plugin
Parameters

  • type (int) –

    Plugin type filter:

    PLUGINTYPE_ANY

    Any.

    PLUGINTYPE_SHADER

    2D Shader. (ShaderData)

    PLUGINTYPE_MATERIAL

    3D Shader.

    PLUGINTYPE_COMMAND

    Command. (CommandData)

    PLUGINTYPE_OBJECT

    Object. (ObjectData)

    PLUGINTYPE_TAG

    Tag. (TagData)

    PLUGINTYPE_BITMAPFILTER

    Bitmap filter. (BitmapLoaderData, BitmapSaverData)

    PLUGINTYPE_VIDEOPOST

    Videopost effect.

    PLUGINTYPE_TOOL

    Tool. (ToolData)

    PLUGINTYPE_SCENEHOOK

    Scene hook.

    PLUGINTYPE_NODE

    Node. (NodeData)

    PLUGINTYPE_LIBRARY

    Library.

    PLUGINTYPE_BITMAPLOADER

    Bitmap loader. (BitmapLoaderData)

    PLUGINTYPE_BITMAPSAVER

    Bitmap saver. (BitmapSaverData)

    PLUGINTYPE_SCENELOADER

    Scene loader. (SceneLoaderData)

    PLUGINTYPE_SCENESAVER

    Scene saver. (SceneSaverData)

    PLUGINTYPE_COREMESSAGE

    Core message. (MessageData)

    PLUGINTYPE_CUSTOMGUI

    Custom GUI.

    PLUGINTYPE_CUSTOMDATATYPE

    Custom datatype.

    PLUGINTYPE_RESOURCEDATATYPE

    Resource datatype.

    PLUGINTYPE_MANAGERINFORMATION

    Manager information plugin.

    PLUGINTYPE_CTRACK

    Track.

    PLUGINTYPE_FALLOFF

    Falloff. (FalloffData)

    PLUGINTYPE_PREFS

    Preference hook. (PreferenceData)

    PLUGINTYPE_SNAP

    Snap.

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

Return type

List[c4d.plugins.BasePlugin]

Returns

The list.

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

Returns the BasePlugin found by id.

Parameters

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

  • type (int) –

    Optionally a plugin type filter:

    PLUGINTYPE_ANY

    Any.

    PLUGINTYPE_SHADER

    2D Shader. (ShaderData)

    PLUGINTYPE_MATERIAL

    3D Shader.

    PLUGINTYPE_COMMAND

    Command. (CommandData)

    PLUGINTYPE_OBJECT

    Object. (ObjectData)

    PLUGINTYPE_TAG

    Tag. (TagData)

    PLUGINTYPE_BITMAPFILTER

    Bitmap filter. (BitmapLoaderData, BitmapSaverData)

    PLUGINTYPE_VIDEOPOST

    Videopost effect.

    PLUGINTYPE_TOOL

    Tool. (ToolData)

    PLUGINTYPE_SCENEHOOK

    Scene hook.

    PLUGINTYPE_NODE

    Node. (NodeData)

    PLUGINTYPE_LIBRARY

    Library.

    PLUGINTYPE_BITMAPLOADER

    Bitmap loader. (BitmapLoaderData)

    PLUGINTYPE_BITMAPSAVER

    Bitmap saver. (BitmapSaverData)

    PLUGINTYPE_SCENELOADER

    Scene loader. (SceneLoaderData)

    PLUGINTYPE_SCENESAVER

    Scene saver. (SceneSaverData)

    PLUGINTYPE_COREMESSAGE

    Core message. (MessageData)

    PLUGINTYPE_CUSTOMGUI

    Custom GUI.

    PLUGINTYPE_CUSTOMDATATYPE

    Custom datatype.

    PLUGINTYPE_RESOURCEDATATYPE

    Resource datatype.

    PLUGINTYPE_MANAGERINFORMATION

    Manager information plugin.

    PLUGINTYPE_CTRACK

    Track.

    PLUGINTYPE_FALLOFF

    Falloff. (FalloffData)

    PLUGINTYPE_PREFS

    Preference hook. (PreferenceData)

    PLUGINTYPE_SNAP

    Snap.

Return type

c4d.plugins.BasePlugin

Returns

The plugin.

c4d.plugins.GetFirstPlugin()

Returns the first plugin of Cinema 4D.

Return type

c4d.plugins.BasePlugin

Returns

The first plugin.

c4d.plugins.GeLoadString(id, p1='', p2='', p3='', p4='')

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).

Warning

To use this function, __res__ must be defined in your global scope.

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 (Optional[str]) – The string to insert into the first placeholder.

  • p2 (Optional[str]) – The string to insert into the second placeholder.

  • p3 (Optional[str]) – The string to insert into the third placeholder.

  • p4 (Optional[str]) – The string to insert into the fourth placeholder.

Return type

str

Returns

The completed string.

c4d.plugins.GetToolData(doc, pluginid)

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

Parameters
Return type

c4d.BaseContainer

Returns

Tool data container.