Prerequisites

To follow this guide, you need the following software:

Cinema 4D C++ SDK: Download the extended SDK from the developers.maxon.net. The sdk.zip file shipped with Cinema 4D is insufficient for this guide.
Visual Studio: Install a version compatible with the SDK. The Community Edition is free and available on the Visual Studio website. See Technical Requirements for recommended versions.
Cinema 4D Installation: Download a trial version from the Maxon website.
Clang Components (optional): Install via Visual Studio if you plan to use Clang as the compiler.
Build Requirements: See Technical Requirements for detailed build requirements.

Note: The code and projectdefinition.txt instructions in this guide are identical across platforms. The only differences are in generating solution files and interacting with IDEs like Visual Studio, Xcode, or Eclipse.; This guide is accompanied by the YouTube playlist Getting Started with the Cinema 4D C++ SDK on Windows, which demonstrates the steps described here.

Building the SDK

Generating a Build System

The Cinema 4D SDK does not include a prebuilt build system. Instead, project files must be generated using CMake. The process involves two phases: configuration and generation. The video below demonstrates these steps on Windows.

Fig. I: Setting up Visual Studio build systems for Cinema 4D projects using CMake.

Configuration Phase

During this phase, you define basic inputs such as the project path, output path, and build system type. Cinema 4D projects use presets to simplify configuration. The following settings must be defined:

Option	Description
`Where is the source code`	Set this to the root folder of your project, not the `modules/plugins` folder.
`Preset`	Select the target build system. On Windows, choose between MSVC (e.g., `Visual Studio 2022 v143`) and Clang (e.g., `Visual Studio 2022 ClangCL`).
`Where to build the binaries`	Path for CMake to generate the build system. This is auto-populated when a preset is selected but can be customized.

Once these settings are defined, click the Configure button. A dialog will appear, but the preset will predefine most settings. Click Finish to proceed. CMake will copy relevant data and display output in its console. If successful, the Generate button will be enabled.

Warning: We only support the provided build system presets. Using different Visual Studio versions, build tools, or compilers may result in partial or non-functional builds. If deviations are necessary, start with a preset and modify the Configure dialog to match your environment.

Generation Phase

In this phase, you can configure Cinema 4D SDK-specific settings and generate the final project files. Key options include:

Option	Type	Description
`CMAKE_CXX_STANDARD`	CMake	Defines the C++ standard (default: `20`). Do not change this setting.
`MAXON_C4D_EXECUTABLE`	SDK	Path to the Cinema 4D executable for debugging plugin binaries. Optional.
`MAXON_FILTER_UNUSED_FRAMEWORKS`	SDK	Set to `true` to include only referenced frameworks, reducing build times.
`MAXON_MODULES_DIR`	SDK	Location of the `modules` folder (default: `plugins` folder in the project).
`MAXON_SDK_CUSTOM_PATHS_FILE`	SDK	File for custom module paths and aliases. See Custom Paths.
`MAXON_SDK_EXTERNAL_LIBS_DIR`	SDK	Location of the `libs` folder (default: `libs` folder in the project).

Warning: The default startup project is ALL_BUILD, which lacks debug options. If you set MAXON_C4D_EXECUTABLE, you must manually set a module project as the startup project to use preset debug options.

Note: You can manually set the debug application in Visual Studio. Right-click a project, select Set as Startup Project, then open Properties. Under Debugging, set the Command to the Cinema 4D executable and Command Arguments to the binary output path, e.g., g_additionalModulePaths=D:/documents/sdk/_build_v143/bin/Debug/plugins/.

Once all settings are configured, click Generate. CMake will display output in its console. If successful, the Open Project button will be enabled.

Compiling a Build System

Once you have generated a solution with CMake, you can open it in Visual Studio by clicking the Open Project button in CMake. The solution reflects the structure of the SDK and contains all the projects and files that are part of the SDK. The frameworks folder in the solution contains the content of the frameworks folder of the SDK, here you can find the definition of the Cinema 4D API. A framework bundles a section of the Cinema 4D API that is thematically related, the asset.framework contains for example the API for the underlying data types of the Asset Browser. Frameworks are also used to include aspects of the Cinema 4D API with a project, so that the header files of that framework can be included in a source file of that project.

Fig. II: Compiling and exploring the SDK in Visual Studio.

Before you can build the solution, you must select the configuration you want to build. The configuration can be either Release or Debug. A debug build will give you better debugging capabilities but will be slower than a release build, and plugins compiled with a debug configuration should never be shipped to customers.

Fig. III: The configuration of a solution can be selected in the toolbar of Visual Studio. The configuration can be either Release or Debug.

Once the configuration has been selected, you can build the solution by pressing F7 or selecting Build Solution from the Build menu. The SDK now starts building and doing it for the first time can take a while. When the build has finished you can see the message 'Build: XY succeeded, 0 failed, 0 up-to-date, 0 skipped' in the Visual Studio output window. There should not be any failed projects. If there are, the error messages can also be found in the output window. Feel free to ask for help on the Maxon Developer Forum if you encounter any issues.

Fig. IV: The output window of Visual Studio shows the build progress and any errors that might have occurred during the build. The error window of Visual Studio is often not a reliable source for identifying build errors but can be a useful tool for beginners as the build output can be overwhelming. But you will always find all error messages in the build output and the error window is just a more convenient way to access them which sometimes omits some of the information.

Once the build has finished, you can find the compiled plugins binaries in the respective project folders in the sdk/{build}/bin/{config}/plugins folder of the SDK. E.g., the binaries for a MSVC debug build of the example.main project would be located by default in sdk/_build_v143/bin/Debug/plugins/example.main/example.main.xdl64. On Windows, the compiled module files are .xdl64 files, on macOS .xlib files, and on Linux .xso64 files. Generated is also the manifest file for each plugin which is used to describe the plugin to Cinema 4D. Additionally generated are the .pdb files which are the debug symbols for the plugins. These files are used by the debugger to map the compiled code back to the source code.

Debugging the SDK

Now that you have built the Cinema 4D C++ SDK, you can debug its binaries in Visual Studio. Debugging allows you to set breakpoints, inspect variables, and utilize Cinema 4D's debugging features.

Fig. V: Debugging the Cinema 4D C++ SDK in Visual Studio.

Configuring the Debugger

When you have followed the CMake instructions in the previous sections, you have already set the MAXON_C4D_EXECUTABLE option in CMake, which will have set the debug configurations for you. You can therefore skip this section and go directly to the next section. When you have skipped this option, you must now manually setup the debugger for at least one project in Visual Studio. Select one project from the plugins section in the Visual Studio Solution explorer and open its properties by right-clicking it and selecting Properties from the context menu.

In the project properties, navigate to the Debugging section and set the Command to a Cinema 4D executable that matches the used SDK. When you would now start debugging, Cinema 4D would start, but it would not load your plugin because it would not know that your plugin does exist. To fix this, set the Command Arguments to the string shown below which will tell Cinema 4D to load all plugins in the sdk/plugins/ folder. Alternatively, you could also set the plugin path in the preferences of that Cinema 4D installation.

Note: You can always debug a plugin binary with a Cinema 4D version that exactly matches the SDK version the plugin has been compiled. To learn more about the compatibility between compiled plugin binaries and different Cinema 4D versions, see the ABI Compatibility .

g_additionalModulePath=$(SolutionDir)\..\

Fig. VI: On the left, the selected startup project in bold. On the right, the project properties with the Cinema 4D executable set as the command and the additional module path set as the command arguments.

Attaching the Debugger

Before we can actually start the debugger, we must first set the startup project of the solution. The startup project is the project that will be started when you press F5 or the green 'Local Windows Debugger' button in the toolbar of Visual Studio. You can set the startup project by right-clicking the project in the Solution Explorer and selecting Set as Startup Project from the context menu. When you have manually configured the debugger for a project, you must set that project as the startup project. When you have set the MAXON_C4D_EXECUTABLE option in CMake, you can pick any project in the plugins section as the startup project, you could for example pick example.main.

Now you can press F5 or green 'Local Windows Debugger' button in the toolbar of Visual Studio to start the debugger. The debugger will boot Cinema 4D which will also load your plugin. Once Cinema 4D has started, you can check its Extensions menu to see if the C++ SDK has been loaded.

Fig. VII: When you have done everything correctly, the C++ SDK will be loaded into Cinema 4D and you see it in the Extensions menu. Congratulations, you have successfully built the Cinema 4D C++ SDK!

Without closing Cinema 4D and without stopping the debugger in Visual Studio, you now return to Visual Studio. There you navigate to the file modules/example.main/source/object/roundedtube.cpp in the solution explorer and open it by double-clicking it. In the file, you open the search by pressing CTRL+F and search for the definition of the method RoundedTubeData::GetVirtualObjects. Here you set a breakpoint by left-clicking left of a line number of one of the lines of the method. The breakpoint should lie within the scope, the curly braces, of the method. The line should now be marked by a red dot.

Fig. VIII: Setting a breakpoint in the RoundedTubeData::GetVirtualObjects() method while the debugger is running. You can also set a breakpoint when the debugger is not running, we just do it here in one go so that you do not have to reboot Cinema 4D between debugging the SDK for the first time and setting your first breakpoint.

Back in Cinema 4D, you can now invoke the Rounded Tube code example from the Commander by pressing SHIFT+C and typing Rounded Tube and then hitting Enter. Cinema 4D will now create an instance of the RoundedTubeData object which will try to build its geometry cache. The debugger will halt on your breakpoint because you have set it in RoundedTubeData::GetVirtualObjects(), the method which is responsible for building the geometry of that plugin.

You can now step through the code by pressing F10 to step over the current line or F11 to step into the current line. You can also inspect variables by hovering over them with your mouse or by adding them to the watch window by right-clicking them and selecting Add Watch.

Fig. VIV: Your breakpoint is being triggered, you can see the values of variables of the current scope in the 'Autos' window at the bottom in the middle. You can also inspect variables by hovering over them with the mouse or by adding them to the watch window. At bottom right, you can see the stack trace, the series of function calls that led to the call of the current function.

Advanced Techniques

You can now stop the debugger by pressing SHIFT+F5 or selecting Stop Debugging from the Debug menu. We will now learn how to print (debug) messages in the Cinema 4D API to its various consoles and how to invoke debug stops from code.

To do that, first remove your breakpoint by clicking on the red dot in the code editor of the modules/example.main/source/object/roundedtube.cpp file.Then insert the code shown below into the RoundedTubeData::GetVirtualObjects the file so that the snip marks line up with the existing code.

// Existing code ...
if (!dirty)
  return op->GetCache();
 
// --- Snip -----------------------------------------------------------------------------
 
// Prints to the console of Cinema 4D, the debug console of Visual Studio, and
// the maxon console of Cinema 4D (when attached).
ApplicationOutput("Application: @", op->GetName());
 
// Prints to the debug console of Visual Studio and the maxon console of Cinema 4D 
// (when attached).
DiagnosticOutput("Diagnostic: @ (dirty = @)", op->GetName(), dirty);
 
// Halts like a breakpoint when debugging a debug config binary.
if (true)
  DebugStop("This should not happen!"_s);
 
// Halts like a breakpoint even when debugging a release config binary.
if (true)
  CriticalStop("Upsy-daisy!"_s);
 
// --- Snip -----------------------------------------------------------------------------
 
// Also existing code ...
BaseContainer* data = op->GetDataInstance();

Now rebuild the solution by pressing F7 and after that start the debugger again by pressing F5. In Cinema 4D, create again an instance of the Rounded Tube object. The debugger will now halt on its own on the first manual halt in your code, the DebugStop, and then on the second manual halt, the CriticalStop. Press F5 to continue the execution of the program after each halt, or press the green 'continue' button in the toolbar of Visual Studio.

Fig. X: The debugger ist halting on the second manual halt in your code, the CriticalStop. In the lower right corner you see the Visual Studio output window which shows the output of the ApplicationOutput and DiagnosticOutput calls, as well as the messages of both DebugStop and CriticalStop. The ApplicationOutput call is also shown in the Cinema 4D console, superimposed in the bottom left corner.

Note: To see the output of the ApplicationOutput calls in the Cinema 4D console, you must have the Cinema 4D console open. You can open the Cinema 4D console by selecting Extensions > Console from the Cinema 4D menu. To see output in the maxon console, you must run Cinema 4D with the command line argument g_console=true or g_consoleDebugger=true. The former will only show the Cinema 4D console when no debugger is attached, the latter will always show the Cinema 4D console.

ApplicationOutput is a relatively expensive call and you should avoid it in production code for everything but critical messages which are meant to be seen by the end-user. When you spam the Cinema 4D console with messages, you not only render it unusable for others but also eat up considerable system resources as rendering the console takes time. DiagnosticOutput is a less expensive call than ApplicationOutput and should be used for messages that are meant for developers and not for end-users.

There are more output functions available in the Cinema 4D API, see the Console Output for more information. The Output functions all support the maxon string output syntax which is described in the Output Syntax page. The general idea is that the \@ character is used to insert variables into the string and you can pass as many variables as you want to these functions as they are all variadic functions.

DebugStop and CriticalStop are used to halt the execution of the program just like a breakpoint would. DebugStop will only halt the program when it is being debugged in a debug configuration, CriticalStop will halt the program in all configurations. These functions can be useful to bake breakpoints into your code to halt a debugger when something truly critical happens that you did not expect to happen. For end-users these functions will not do anything, they are only active when the program is being debugged.

But you might also run into these two functions without using them yourself as they are often used in the Cinema 4D frameworks to halt the program when something unexpected happens. When you hit a DebugStop or worse, a CriticalStop, in the frameworks while debugging your plugin, it usually means that you either do something truly wrong or have found a bug in Cinema 4D. Most of our debug stops unfortunately are not very informative and do not have an error message attached. But you can look at the framework code to get a sense of what is going wrong. When you hit a wall in such cases, do not hesitate to ask for help on the Maxon Developer Forum.

Extending the SDK

Now that you have built and debugged the Cinema 4D C++ SDK, it is time to add your first custom plugin.

Note: This section focuses on the steps to create a new module and plugin. For specific plugin types, refer to the code examples.

To add a new plugin, create a new module folder in the plugins directory. The folder name determines the plugin binary name. Inside this folder, create a project folder containing a projectdefinition.txt file and a source folder with a main.cpp file.

Fig. XI: Implementing a new module and plugin in the Cinema 4D C++ SDK.

Adding a Project

First you must create a new module folder in the plugins folder of your solution. The name of the new folder will determine of the plugin binary into which your module will be compiled. In this folder, you must create a project folder and in that folder a projectdefinition.txt file. You also need a source folder in the project folder and in that folder a main.cpp file.

Fig. XII: The example.hello_world project provides an example for the minimal setup of a new Cinema 4D module. The projectdefinition.txt file contains the instructions for CMake to generate the project files for the module. The main.cpp file contains the code of the module, in this case a simple command plugin which opens a message dialog with the text "Hello World!" when invoked.

Setting up a Project

Now you must fill the projectdefinition.txt file of your new project with instructions for the CMake.

// The platforms this project is targeting - can be [Win64;OSX;Linux].
Platform=Win64;OSX;Linux
 
// Type of project - can be [Lib;DLL;App], DLL is for (plugin) modules, lib for static libraries,
// effectively frameworks, and App for standalone applications (not possible for plugins).
Type=DLL
 
// The frameworks dependencies of this module. One can only include header files from frameworks
// which are listed here. The selection here is a good starting point for most projects.
APIS=\
asset.framework;\
cinema.framework;\
cinema_hybrid.framework;\
core.framework
 
// Enable Cinema API features for this module, and then reenable style checks again (because 
// C4D=true disables them).
C4D=true
stylecheck.level=3 
 
// The ID of the module which is being compiled. One should use the reversed domain notation, derived
// from a domain name you own, followed by plugin qualifiers, e.g, "net.mycompany.mymodule" or
// "net.mycompany.mysuite.mymodule". It is important that this ID is unique, as Cinema 4D will
// not load two modules with the same ID. Please note that Cinema 4D will also not load modules
// with a "net.maxon" domain, as this domain is reserved for Maxon modules.
ModuleId=com.mycompany.my_project

CMake will generate the solution files for the project based on the information in the projectdefinition.txt files it finds in each module. The projectdefinition.txt file must contain at least the following information:

The platforms the project is targeting, e.g., Platform=Win64;OSX;Linux.
The type of the project, usually Type=DLL.
The frameworks the project uses, e.g., APIS=cinema.framework;cinema_hybrid.framework;core.framework.
The module identifier of the project, e.g., ModuleId=net.maxonexample.hello_world.

To learn more about projectdefinition.txt files, see the Configuring Build Systems.

Warning: You cannot use module identifiers in the domain "net.maxon." as they are reserved for Maxon Computer. Plugins using such identifiers will not be loaded by Cinema 4D.

See also: Configuring Build Systems for more information on the projectdefinition.txt file.

Note: Frameworks for details on the Cinema 4D API frameworks and how to use them.

Writing the Plugin

Now it is time to finally fill your main.cpp file with the code of your plugin. This section is mostly about the boilerplate code you need to get a plugin up and running and uses the minimal code necessary to implement a plugin. The plugin will be a simple command that opens a message dialog with the text "Hello World!" when invoked.

Note: This section demonstrates how to implement Cinema API plugins which make up the vast majority of plugin types such as commands, tools, messages handlers, scene hooks, objects, tags, (Cinema API legacy) materials, (Cinema API legacy) shaders and more. Plugins in the Maxon API are implemented entirely differently and are not covered in this section. The Maxon API primarily covers plugins that implement custom assets for the Asset API and plugins that implement custom node spaces, node systems, and node templates for the Node API. See Plugin Types for an overview of the different plugins types.

Most plugins also split up their code into multiple files, the main.cpp file and one or multiple files that implement the actual plugin. The main.cpp is usually only used to handle plugin messages sent to the module the main.cpp is the entry point of, while the actual plugin code is implemented in other files. This example condenses all the code into the main.cpp file for simplicity.

The content of the main.cpp file in the plugins/myplugin/project/source folder should look like as shown below:

/* Realizes a simple command plugin that opens a message dialog with the text "Hello World!" once it 
has been invoked.
 
The main focus of this example is to get the plugin message infrastructure up and running that is 
required to register all Cinema API plugins.
*/
 
// -------------------------------------------------------------------------------------------------
// This section contains the code that is usually placed in the main.cpp file of a project. It is
// custom to separate a project into a main.cpp file - which handles all the module messages
// for its plugins - and one or multiple files which realize the actual plugins.
// -------------------------------------------------------------------------------------------------
#include "c4d_plugin.h"
#include "c4d_resource.h"
 
// Forward declaration of the the #RegisterMyPlugin() function we implement below, so we can use
// the function in #PluginStart below.
bool RegisterMyPlugin();
 
// Called by Cinema 4D in its boot sequence when this module is being loaded. This is the entry
// point to register Cinema API plugins. A plugin which does not register itself or whose 
// registration fails will not be accessible to users.
cinema::Bool cinema::PluginStart()
{
  // Attempt to register our plugin.
  if (!RegisterMyPlugin())
    return false;
  return true;
}
 
// Called by Cinema 4D in its shutdown sequence when this module is about to be unloaded. Most 
// plugins use the empty implementation shown here as they do not have to free resources.
void cinema::PluginEnd()
{
}
 
// Called by Cinema 4D when a plugin message is sent to this module. There are several messages but
// all modules must implement at least C4DPL_INIT_SYS as shown below. Otherwise the module and its 
// plugins will not work.
cinema::Bool cinema::PluginMessage(cinema::Int32 id, void* data)
{
  switch (id)
  {
    // g_resource is a global variable that is used to manage resources in Cinema 4D. It is 
    // defined in the c4d_resource.h file which we include above. We cannot start our module
    // if the resource management has not been initialized.
    case C4DPL_INIT_SYS:
    {
      if (!cinema::g_resource.Init())
        return false;
      return true;
    }
  }
  return false;
}
 
// -------------------------------------------------------------------------------------------------
// This section contains the code that is usually placed in a myplugin.cpp and/or myplugin.h file.
// It contains the actual plugin implementation and usually also the registration function for the
// plugin as these functions must have access to the plugin class.
// -------------------------------------------------------------------------------------------------
 
#include "c4d.h"
#include "c4d_gui.h"
 
// Realizes the most basic plugin possible, a command that opens a message dialog with the text
// "Hello World!" once it has been invoked.
class MyPluginCommand : public cinema::CommandData
{
public:
 
  // Called by Cinema 4D when this command is being invoked, either by a user pressing a menu item, 
  // a button, or by a CallCommand() call made from C++ or Python code.
  virtual cinema::Bool Execute(cinema::BaseDocument* doc, cinema::GeDialog* parentManager)
  {
    cinema::MessageDialog("Hello World from 'my_project'!"_s);
    return true;
  }
};
 
// The ID to register the plugin with. This ID must be unique to this registration call and new IDs 
// must be obtained from https://developers.maxon.net/forum/pid .
const cinema::Int32 g_plugin_id = 1065315;
 
// Calls the registration function for a CommandData plugin with an instance of our command class.
cinema::Bool RegisterMyPlugin()
{
  return cinema::RegisterCommandPlugin(
    g_plugin_id, "Hello World Command (my_project)"_s, 0, nullptr, "Hello World Tooltip (my_project)"_s, 
    NewObjClear(MyPluginCommand));
}

The important aspects of getting a module and plugin up an running are:

The cinema::PluginStart function is the entry point for registering all Cinema API plugins and called when your module is being loaded. A plugin that does not register itself or whose registration fails will not be accessible to users as it will not be loaded. This function must be implemented in the main.cpp file of a project.
The cinema::PluginEnd function is called by Cinema 4D when a module is about to be unloaded. Most plugins use the empty implementation shown here as they do not have to do any manual cleanup. This function is usually implemented in the main.cpp file of a project.
The PluginMessage function is called by Cinema 4D when a plugin message is sent to the module. There are several messages but all plugins must implement at least C4DPL_INIT_SYS as shown here. Otherwise, the module and its plugins will not work. See Plugin Messages for more information on the plugin message system.
All plugins must register themselves with Cinema 4D by using the specific registration functions intended for their plugin type. In this case, the RegisterCommandPlugin function is used to register a command plugin. One or multiple of these registration function calls are then usually bundled up in a RegisterMyPlugin() function that is called from PluginStart() in the module. The RegisterMyPlugin() function is often implemented in one of the plugin files, e.g., myplugin.cpp and is then 'included' in the main.cpp file as a forward declaration.

The arguments passed to plugin registration functions such as RegisterCommandPlugin differs from plugin type to plugin type but there are some commonalties:

The first argument is the identifier of the plugin. This identifier must be unique and new identifiers must be obtained from developers.maxon.net.
Passed are so usually also a plugin label, a tooltip, and some form of icon (there some plugin types which do not have an icon or tooltip).
And finally either an instance of the plugin class or a function that returns an instance of the plugin class. The plugin class must inherit from a specific plugin hook of the Cinema 4D API, e.g., CommandData for a command plugin.

Warning: You can 'invent' plugin identifiers for a plugins you use only for testing purposes. But when you want to ship a plugin or plan to uses it for a prolonged time, you must obtain a plugin identifier from developers.maxon.net. Otherwise you risk identifier conflicts with other plugins which will lead to one of the plugins not being loaded.

To run your plugin, you must now rebuild the solution by pressing F7. Make sure that you have no build errors and then start the debugger by pressing F5. In Cinema 4D, you can now find the plugin as Extensions > MyPlugin Menu Label. When you click the item, a message dialog with the text "Hello World!" will open.

Fig. XIV: The plugin is being invoked from the Extensions menu.

Table of Contents