Cinema 4D SDK

C++ plugins for Cinema 4D must be compiled against its SDK which is shipped with each installation of Cinema 4D and located directly in the root directory of a Cinema 4D installation, e.g., C:\Program Files\Maxon Cinema 4D 2023\sdk.zip.

Each SDK has an Application Binary Interface (ABI) version expressed in the define MAXON_API_ABI_VERSION and plugins will only be upwards compatible with Cinema 4D releases which they share an ABI version with. ABI compatibility will usually be broken no sooner than a year since the change in an ABI version. And plugins are never downwards compatible, e.g., a plugin compiled for release 2023.1 will not work in 2023.0 although both versions share an ABI version. The ABI versions of major releases is expressed in the Development Environments table; releases which share an ABI version are ABI compatible.

Warning: Do not change any files in the frameworks directory of an SDK, as plugins compiled against such SDK might otherwise become incompatible with Cinema 4D.

Development Environments

To build C++ plugins for Cinema 4D, specific IDEs and compilers are required due to the makeup of the SDK itself and the output of the Project Tool. The supported compilers and IDEs are:

Visual Studio Community might work too for VS projects, but is not officially supported. For Xcode projects, it is also recommended to enable the legacy build system under "File/Project Settings/Section Shared Project Settings/Build System/Legacy Build System".

Release	ABI Version	Windows	macOS	Linux
2023	2022901	VS 2019	Xcode 12.5.1 (macOS 11.X), Xcode 13.X (macOS 12.X)	GCC 9.3.1.12, glibc 2.17, Python 3, Scon 3.1.2
S26	25004	VS 2019	Xcode 12	GCC 9.3.1.12, glibc 2.17, Python 3, Scon 3.1.2
R25	25004	VS 2019	Xcode 12	GCC 9.3.1.12, glibc 2.17, Python 3, Scon 3.1.2
S24	23004	VS 2019	Xcode 12	GCC 9.3.1.12, glibc 2.17, Python 3, Scon 3.1.2
R23	23004	VS 2019	Xcode 11	GCC 9.3.1.12, glibc 2.17, Python 3, Scon 3.1.2
S22	21014	VS 2019	Xcode 11	GCC 9.3.1.12, glibc 2.17, Python 3, Scon 3.1.2
R21	21014	VS 2017	Xcode 10	GCC 9.3.1.12, glibc 2.17, Python 3, Scon 3.1.2

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 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 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 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 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 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 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");

MAXON_DEPENDENCY_ON_MODULE

#define MAXON_DEPENDENCY_ON_MODULE(module)

Definition: module.h:719

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