SDK Installation

The C++ SDK is part of every distribution of Cinema 4D and is stored in the sdk.zip file. It can be installed in any location on the file system. For details see SDK Overview.

Warning: Do not change anything in the API, or the created plugins might be incompatible with Cinema 4D.

Creating a New Plugin Project

A new plugin module is created by adding a new folder to the SDK's "plugins" directory. This folder needs to have two sub-folders:

project: This folder contains the projectdefinition.txt file and all generated project files.
source: This folder contains the plugin's source code.

Note: The Project Tool will add all source code files found in the project folder to the project file. The Source Processor will only process source code files in the "source" folder.

The new project also has to be added to the solution's projectdefinition.txt file ("plugins/project"). The project files of the new project and the updated solution can be created by running the Project Tool. The tool will create project files for the supported platforms which are currently Microsoft Windows and Apple macOS. See Development for Microsoft Windows, Development for macOS and Development for Linux.

Warning: Beginning with Cinema 4D R20 the suffixes for plug-ins are respectively, for Windows and macOS, .xdl64 and .xlib. Plug-ins using the old suffixes (.cdl64 or .dylib) are simply skipped during the loading process. This is done to avoid issues with plug-ins from previous versions, which would not work in Cinema 4D R20+ anyway.

Note: If project files are created by any different tool than the Project Tool, it is highly recommended to compare the custom-generated build settings and apply the needed changes in order to reflect the official settings. Please also note, MAXON's SDK Team only provides support for the official workflow and may not be able to help with issues arising from custom tool chains.

Plugin Resources

A res folder can contain resources used by the plugin. Such resources are typically dialog and Description resource files. See Resource Files Manual. The plugin path can be obtained with GeGetPluginPath().

The res folder typically has this structure:

within the res folder there might be a c4d_symbols.h header file which contains an enumeration for global symbol and string IDs.
a dialogs folder contains resource files for GeDialog based dialogs.
a description folder contains header and resource files for descriptions of NodeData based plugins. See Description Manual.
a strings_en-US folder contains string files for the default language (American English). The folder contains the sub-folders description and dialogs which include the string files for descriptions and dialogs. The folder may also contain a c4d_string.str file for global strings.

Further languages can be supported by creating new languages folders. Such a folder is constructed by using the language code (ISO 639-1) and a region ID. Please note that the region ID must be capitalized.

"ar-AE" - Arabic (U.A.E.)
"zh-CN" - Chinese (PRC)
"cs-CZ" - Czech
"de-DE" - German (Standard)
"it-IT" - Italian (Standard)
"ko-KR" - Korean (Republic of Korea)
"ja-JP" - Japanese
"pl-PL" - Polish
"ru-RU" - Russian
"es-ES" - Spanish (Standard)
"fr-FR" - French (Standard)
"en-US" - English (United States)

E.g. French language strings would be stored in a folder named "strings_fr-FR".

Note: Example resource files can be found in the cinema4dsdk example project.; MAXON API ALIASES descriptions are based on new interfaces, see Data Descriptions.

Classic Plugin Hooks

Classic plugin hooks are built upon classes derived from BaseData. These classes define a set of virtual functions that are called by Cinema 4D. To create a plugin, simply derive a class from one of the data classes and implement the virtual functions. To register the derived class with Cinema 4D there is a specific "Register" function for each class.

See General Plugin Information Manual and Plugin Types.

MAXON API Plugins

MAXON API ALIASES plugins are based on interfaces. A plugin is created by implementing such interfaces and registering these implementations at public registries. See Interface Basics and Registries.

Specific functionality of the MAXON API ALIASES is used by either directly using static functions or creating instances of specific classes. Such classes can either be standard C++ classes or reference classes that represent implementations of virtual interfaces. Such reference classes can also be obtained from extension points. See Entity Creation, Using Interfaces and Registry Usage.

Custom IDs

Every custom component - frameworks, plugins, interfaces, registries, implementations, etc. - must have a unique identifier. The MAXON API ALIASES uses the reverse-domain notation to define such IDs. This means that third parties should use their company domain name to create the ID. E.g. if the company domain is "examplecompany.com" the reverse-domain name of a component would be "com.examplecompany.something".

If no custom domain is available one can construct a custom ID by using the developer's user name used in the support forum in the form of "example.doesnotexist.<forum_username>.something".

Warning: Third parties cannot use "net.maxon" to name custom components.

Plugins, Modules and Dependencies

Modules and Hybrid Plugins

Based on its content a plugin may be classified as a "module". Such a "module" is a plugin that only uses the frameworks of the new MAXON API ALIASES and does not use the cinema.framework at all. Such a "module" must use the ".module" suffix in the folder name e.g. "example.module".

Warning: A module must not reference or depend on the classic API (cinema.framework) in any way.

A plugin that uses the "classic" API of cinema.framework is typically described as a "hybrid" plugin (since it uses both "classic" and "new" API).

Loading of Plugins

Modules and "hybrid" plugins are loaded in this order:

First pure MAXON API ALIASES modules are loaded.
Then "hybrid" plugins containing the string "config" are loaded.
Finally, all other "hybrid" plugins are loaded.

Dependencies

Typically the source processor manages the dependencies of modules and plugins. One can also define the dependencies of modules using the MAXON_DEPENDENCY_ON_MODULE() attribute in an arbitrary source code file of the dependent module.

E.g. if a module "net.example.module_b" depends on "net.example.module_a" a source code file of "module_b" can simply contain:

MAXON_DEPENDENCY_ON_MODULE("net.example.module_a");

This makes sure that "com.examplecompany.module_a" is loaded before "module_b".

Libraries

DLLs needed by a plugin can be placed in myplugin\res\libs\win64; DYLIBs can be placed in myplugin\res\libs\osx.

"config" Plugins

All "hybrid" plugin containing the string "config" in the name will be loaded before all other "hybrid" plugins. This allows such "config" plugins to modify the loading queue.

This is typically used to check the environment (library availability, keys, etc.) in order to enable or disable another plugin.

The plugin queue is edited by implementing a QueryStartupOrder() function:

extern "C" MAXON_ATTRIBUTE_DLL_PUBLIC void QueryStartupOrder(maxon::BaseArray<maxon::Url>& dllsToLoad)
{
  // check for some condition
 
  for (Int index = 0; index < dllsToLoad.GetCount(); index++)
  {
    maxon::String str = dllsToLoad[index].GetName().ToLower();
    if (str.StartsWith("someplugin"_s))
    {
      MAXON_WARN_MUTE_UNUSED dllsToLoad.Erase(index);
      break;
    }
  }
}

Plugin Execution

It is possible to install multiple versions of Cinema 4D and multiple versions of the SDK on the same system simultaneously. One has to define the plugin search path to make sure Cinema 4D will load custom plugins. The search path can be configured in the application's preferences or using a command line argument:

g_additionalModulePath: Defines one or more additional plugin search paths.

:: This example BATCH file starts Cinema 4D with two additional custom module paths
 
"Cinema 4D.exe" g_additionalModulePath=C:\stable_plugins;C:\test_plugins

Programming Advice

For general advice on how to program Cinema 4D plugins and how to debug them see Programming Advice and Debugging.

Table of Contents