Development Requirements

Describes the technical requirements for building plugins with the Cinema 4D SDK.

ABI Compatibility

Each SDK has an Application Binary Interface (ABI) which determines with which versions of Cinema 4D plugins are compatible with which have been compiled with that SDK.

Warning
An SDK being ABI incompatible to a certain version of Cinema 4D cannot be circumvented by only using parts of an API which have not changed. A plugin compiled against an incompatible SDK will not be loaded by an unsupported version of Cinema 4D. 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.

The Cinema 4D ABI will remain upwards compatible for one major version. This means for example that a plugin compiled with the Cinema 4D SDK for release 2023.1 will also work in the releases 2023.2 and 2023.3, etc. but not in 2024.0. The ABI version of an SDK is expressed by the define MAXON_API_ABI_VERSION. The ABI version of major releases is also expressed in the Development Environments table.

Note
In the old version scheme of Cinema 4D an R/S version pair counted as one major version. The Cinema 4D R25.000 SDK is for example ABI compatible up to Cinema 4D S26.110.
Fig. I: Demonstrates the concept of ABI compatibility with the three fictional plugins Plugin A, Plugin B, and Plugin C and how they are compatible with different Cinema 4D releases. Boxes in dark grey are the Cinema 4D SDK releases for which a plugin has been compiled. The arrows outgoing from a plugin release indicate up to which release of Cinema 4D such plugin binary is compatible.

As an example and as shown in Fig. I, the developers of Plugin A always compile their plugin for the first version of a major Cinema 4D release. With plugin binaries compiled with for the 2023.0.0, 2024.0.0, and 2025.0.0 Cinema 4D SDKs, they can cover all Cinema 4D releases of 2023, 2024, and 2025.

The authors of Plugin B also compile for the first version of a major Cinema 4D release. But they also want to support a new feature of Cinema 4D 2024.2.0. To do that, they ship two plugin binaries for Cinema 4D 2024. One version which has been compiled for the Cinema 4D 2024.0.0 SDK. This plugin can be used with every version of Cinema 4D 2024. And another version which has been compiled for the Cinema 4D 2024.2.0 SDK. This plugin can be used with all Cinema 4D versions between 2024.2.0 and the last release of Cinema 4D 2024. Only the latter version of their 2024 plugin can support the new features of Cinema 4D 2024.2.0. But customers of Plugin B who do not want to update their installation to the 2024.2.0 SDK version of the plugin could still use it up to the end of the 2024 release cycle.

The authors of Plugin C have only compiled their plugin for Cinema 4D 2024.0.2 and 2025.0.0. The plugin binary for the 2025.0.0 SDK will be fully compatible with all 2025 releases. But the plugin binary compiled for the Cinema 4D 2024.0.2 SDK will not work in Cinema 4D 2024.0.0 or 2024.0.1. Cinema 4D 2023 is not supported at all by Plugin C as its authors have never compiled their plugin for any 2023 SDK.

Note
Plugins must be compiled separately for macOS, Windows, and Linux. The example lined out above ignores this for simplicity in its wording. Plugin A would require for example two binaries for each the major Cinema 4D releases it supports, if the authors wanted to support macOS and Windows.

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

ReleaseABI VersionWindowsmacOSLinux
20242023904VS 2019 & 2022Xcode 13.xGCC 9.3.1.12, glibc 2.17, Python 3, Scon 3.1.2
20232022901VS 2019Xcode 13.xGCC 9.3.1.12, glibc 2.17, Python 3, Scon 3.1.2
S2625004VS 2019Xcode 12GCC 9.3.1.12, glibc 2.17, Python 3, Scon 3.1.2
R2525004VS 2019Xcode 12GCC 9.3.1.12, glibc 2.17, Python 3, Scon 3.1.2
S2423004VS 2019Xcode 12GCC 9.3.1.12, glibc 2.17, Python 3, Scon 3.1.2
R2323004VS 2019Xcode 11GCC 9.3.1.12, glibc 2.17, Python 3, Scon 3.1.2
S2221014VS 2019Xcode 11GCC 9.3.1.12, glibc 2.17, Python 3, Scon 3.1.2
R2121014VS 2017Xcode 10GCC 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 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 example.main 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 Common Plugin Concepts 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.

See also Plugin Types.

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");
#define MAXON_DEPENDENCY_ON_MODULE(module)
Definition: entity.h:408

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:

{
// check for some condition
for (Int index = 0; index < dllsToLoad.GetCount(); index++)
{
maxon::String str = dllsToLoad[index].GetName().ToLower();
if (str.StartsWith("someplugin"_s))
{
break;
}
}
}
Definition: basearray.h:415
ResultPtr< T > Erase(Int position, Int eraseCnt=1)
Definition: basearray.h:1006
MAXON_ATTRIBUTE_FORCE_INLINE Int GetCount() const
Definition: basearray.h:585
Definition: string.h:1237
Py_ssize_t * index
Definition: abstract.h:374
void * str
Definition: bytesobject.h:77
maxon::Int Int
Definition: ge_sys_math.h:60
#define MAXON_ATTRIBUTE_DLL_PUBLIC
Definition: apibase.h:99
#define MAXON_WARN_MUTE_UNUSED
The MAXON_WARN_MUTE_UNUSED macro is deprecated. Please use iferr_ignore or iferr_cannot_fail and spec...
Definition: compilerdetection.h:311
void(*)(BaseArray< Url > &dllsToLoad) QueryStartupOrder
Definition: dll.h:119

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
BATCH
Definition: corenodes_instances.h:5
PyObject * module
Definition: import.h:14
D
Quality D.
Definition: macros.h:4
C
Quality C.
Definition: macros.h:3
const char const char const char * file
Definition: object.h:439

Programming Advice

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

Further Reading