Development Requirements

Table of Contents

• ABI Compatibility
• Development Environments
• Creating a New Plugin Project
• Plugin Resources
• Classic Plugin Hooks
• MAXON API Plugins
• Custom IDs
• Plugins, Modules and Dependencies
  • Modules and Hybrid Plugins
  • Loading of Plugins
  • Dependencies
  • Libraries
  • "config" Plugins
• Plugin Execution
• Programming Advice
• Further Reading

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, depending on the SDK version they have been compiled against.

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:

• Windows: Visual Studio (VS)
• macOS: Xcode
• Linux: GNU Compiler Collection (GCC)

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
2024	2023904	VS 2019 & 2022	Xcode 13.x	GCC 9.3.1.12, glibc 2.17, Python 3, Scon 3.1.2
2023	2022901	VS 2019	Xcode 13.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 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");

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 SDK Programming Advice and Debugging Techniques.

Further Reading

• Development Overview
• Plugin Types
• Project Tool
• C++ Techniques
• Code Style Guide
• Development for Windows
• Development for macOS
• Development for Linux
• SDK Programming Advice
• Debugging Techniques