Architecture

The architecture of Cinema 4D is divided into three main components:

Modules: Modules are libraries that provide the native and plugin functionalities of Cinema 4D. They are loaded and registered individually during startup and must reside in a module search path (e.g., a plugin search path defined by the user). Cinema 4D dynamically links module calls to its API against other modules implementing those API parts. Modules are dynamically linked libraries, but Cinema 4D does not use the native OS-provided DLL loaders. Compiled module binaries use the following extensions: .xdl64 (Windows), .xlib (macOS), or .xso64 (Linux). A module is identified by its module identifier and may fail to load if the identifier is not unique or invalid (see Build Systems: Common Settings for details).
Frameworks: Frameworks declare parts of the Cinema 4D API and typically do not contain implementations. They are compiled into static libraries, which modules link against automatically during a Cinema 4D build. Frameworks organize the API into logical units, such as the Cinema API, Maxon API, Nodes API, and Image API. Plugins usually do not define frameworks, as they are typically implemented as singular modules.
Resources: Resources define GUIs, icons, strings, and other assets used by a module, including external dependencies not part of the Cinema 4D API. Global resources are stored in the resources folder within the Cinema 4D installation. Plugin modules requiring resources must include them in a res folder next to the module binary. Resources are loaded at runtime and are not compiled into the plugin binary.

A module can implement zero to many plugins, which appear as tangible entities to the user. Each plugin must register with Cinema 4D using a function like RegisterObjectPlugin. Cinema 4D then instantiates, initializes, and executes the plugin as needed, integrating its output into the scene graph.

Fig. I: A simplified architecture of how plugins integrate into the Cinema 4D runtime environment. Cinema 4D registers and loads modules from its module search paths during startup. Each module can register zero to many plugin implementations. Built-in modules expose their functionalities as frameworks, which other modules can statically link against. Global resources are stored in the installation directory, while plugin resources are stored next to the plugin binary. Plugins follow the same architecture as Cinema 4D itself.

Plugin Types

Choosing the correct plugin type for your project is crucial, as it determines what you can achieve easily and what may require additional effort. The most commonly used plugin types are:

cinema::CommandData: Realizes a custom command that appears in the menus of Cinema 4D and invokes a function when clicked. This is one of the simplest plugin types.
cinema::ObjectData: Realizes a custom object that can be placed in the Object Manager. It can represent procedural spline and polygon geometry (generators), deformers, particle modifiers, and more.
cinema::TagData: Realizes a custom tag that can be placed on objects in the Object Manager. Tags can store additional information or modify object behavior.
cinema::VideoPostData: Realizes a custom render engine or post effect executed during rendering. This is the primary plugin type for implementing custom render engines.
cinema::MessageData: Realizes a hook to receive core messages from Cinema 4D, allowing reactions to events like scene changes, layout updates, and tool changes. This is a 'spider in the net' plugin type for monitoring Cinema 4D events.
cinema::SceneHookData: Realizes another 'spider in the net' plugin type, allowing hooks into the message stream broadcasted to a document. It can also handle keyboard events, viewport drawing, and more. Unlike other node types (e.g., ObjectData, TagData), SceneHookData is always present in every document scene graph without manual addition. Scene hooks are invisible scene elements, with exactly one instance per document.
cinema::ToolData: Realizes a custom tool that users can enable or disable. Tools are versatile and can perform various tasks but require a UI and are displayed in the Attribute Manager.
cinema::DescriptionToolData: Realizes a custom tool that uses descriptions as its UI paradigm, unlike ToolData, which uses dialogs embedded in the Attribute Manager.

Note: Common Plugin Concepts highlights common patterns employed by Cinema API plugins. See Interface Basics for an introduction to interfaces and references when implementing Maxon API interfaces.

A list of all plugin types sorted by context (types might be listed in multiple contexts):

Scene Elements

Type	Description
cinema::NodeData	Realizes the base class of custom scene elements. Only useful for experts on its own, but its manual explains fundamentals for all scene elements.
cinema::ObjectData	Realizes a custom object for the Object Manager.
cinema::TagData	Realizes a custom tag that can be placed on objects in the Object Manager.
cinema::EffectorData	Realizes a custom MoGraph effector.
cinema::FalloffData	(Deprecated) Realizes a custom falloff.
cinema::FieldData	Realizes a custom MoGraph field object.
cinema::FieldLayerData	Realizes a custom MoGraph field layer.
cinema::MaterialData	Realizes a custom non-node material for the Standard Renderer.
cinema::ShaderData	Realizes a custom non-node shader for the Standard Renderer.
cinema::VideoPostData	Realizes a custom post effect or render engine.
cinema::SceneHookData	Realizes a custom scene hook, a scene element which is present exactly once in each scene.
cinema::CTrackData	Realizes a custom animation track.
cinema::GvOperatorData	Realizes a custom Xpresso node.
maxon::corenodes::BasicMicroNode	Realizes a custom core node.
maxon::CustomDataTagClassInterface	Realizes a custom CustomDataTag.
maxon::CustomDataTagDisplayInterface	Realizes a custom CustomDataTag.
maxon::MeshAttributeClassInterface	Realizes a custom mesh attribute.

Commands and Tools

Type	Description
cinema::CommandData	Realizes a custom command that shows up in menus and palettes.
cinema::ToolData	Realizes a custom tool using a dialog GUI.
cinema::DescriptionToolData	Realizes a custom tool using a description GUI (usually used for modeling tools).
cinema::BrushToolData	Realizes a custom character animation brush.
cinema::SculptBrushToolData	Realizes a custom sculpting brush.
cinema::SculptBrushModifierData	Realizes a custom sculpting brush modifier.
maxon::CommandClassInterface	Realizes a custom Maxon API command.

GUI and User Interaction

Type	Description
cinema::GeDialog	Realizes a custom dialog window.
cinema::GeUserArea	Realizes a custom GUI element to be used in a GeDialog.
cinema::CustomGuiData	Realizes a custom GUI element that can be used in dialogs and descriptions.
cinema::PrefsDialogObject	Realizes a new preference category in the Cinema 4D Preferences dialog.
maxon::CustomDataTagDisplayInterface	Realizes a custom CustomDataTag.

Rendering

Type	Description
cinema::VideoPostData	Realizes a custom post effect or render engine.
maxon::FilterInterface	Realizes a custom render filter.
maxon::FilterContextInterface	Realizes a custom render filter.
maxon::FilterImageInterface	Realizes a custom render filter.

Import and Export

Type	Description
cinema::SceneLoaderData	Realizes a custom scene import format for Cinema 4D.
cinema::SceneSaverData	Realizes a custom scene export format for Cinema 4D.
cinema::BitmapLoaderData	Realizes a custom image format loader for Cinema 4D.
cinema::BitmapSaverData	Realizes a custom image format saver for Cinema 4D.
maxon::MediaInputInterface	Realizes a custom media loader.
maxon::MediaSessionFileFormatHandlerInterface	Realizes a custom media input from a file.
maxon::MediaOutputUrlInterface	Realizes a custom media output to a file.
maxon::FileFormatInterface	Realizes a custom file format.

Messages, Events, and Hooks

Type	Description
cinema::MessageData	Realizes a hook to receive core messages from Cinema 4D.
cinema::SceneHookData	Realizes a custom scene hook.
maxon::ObserverObjectInterface	Realizes a custom observer.

Custom Data Types

Type	Description
cinema::CustomDataTypeClass	Realizes a custom data type in the Cinema API that can be used in Cinema API descriptions and containers.
maxon::DataType	Realizes a custom data type in the Maxon API that can be used in Maxon API descriptions and containers.
cinema::ResourceDataTypeClass	Realizes an alias of Cinema API custom data type that implies certain options in descriptions. `COLOR` is, for example, an alias for the datatype `VECTOR`.

Miscellaneous

Type	Description
cinema::PrefsDialogObject	Realizes a new preference category in the Cinema 4D Preferences dialog.
cinema::SnapData	Realizes a custom snap mode for the classic snap system of Cinema 4D.
maxon::AutoWeightInterface	Realizes a custom weighting algorithm for the Weight Manager.
maxon::BlendFunctionInterface	Realizes a custom blend function.
maxon::StreamConversionInterface	Realizes a custom data conversion algorithm, usually used to realize things like compression or encryption.

Frameworks

The frameworks are the high-level organizational units of the Cinema 4D API, dividing it into larger sections organized by subject. A framework includes the public declarations of interfaces and other usable classes, structures, functions, enums, symbols, etc. To use entities from a framework, the framework must be explicitly included with each module that uses it (see Common Settings). The following frameworks are shipped with the public SDK, ordered by importance:

Framework	Description
cinema.framework	Provides the majority of the Cinema API. When you are new to the Cinema 4D API, you will likely start here.
core.framework	Provides the basic building blocks of the Maxon API. It is the most important framework for the Maxon API and also often relevant in Cinema API contexts.
cinema_hybrid.framework	Provides API elements that are tied both to the Cinema API and Maxon API.
math.framework	Provides commonly required mathematical concepts.
nodes.framework	Provides interfaces for the Nodes API. The Nodes API is the backend of the Node Editor of Cinema 4D. It is used to realize custom node spaces, node systems, and nodes. Often included in tandem with other frameworks.
graph.framework	Part of the Nodes API.
nodespace.framework	Part of the Nodes API.
corenodes.framework	Part of the Nodes API.
neutron.framework	Part of the Nodes API.
asset.framework	Provides interfaces for accessing and storing content as assets in asset databases. Does not contain the Asset Browser implementation (which is non-public) but the data structures that stand behind it. See Asset API.
image.framework	Provides the Image API to handle image and media data and carry out color management. See Images Manual, Color Management Manual.
image_ocio.framework	Provides the Open Color IO (OCIO) part of the Image API. See OpenColorIO Manual (OCIO).
render_filter.framework	Provides interfaces for implementing pixel based effects applied in post to a rendering. See Render Filter Implementation for details.
network.framework	Provides interfaces to interact with web services.
misc.framework	Provides minor tooling from a non-unified subject area such as SQL, XML, GML, unit tests and more.
volume.framework	Provides interfaces to handle volume data, relevant for interacting with things like the volume builder or Pyro, or for loading your own volume data. See Volumes Overview.
python.framework	Provides interfaces to execute Python code. See Python.
crypt.framework	Provides additional interfaces for data encryption based on stream conversions.
exchange.framework	Provides interfaces to define custom behaviors for import and export operations on node materials. Mostly relevant for users of the Maxon API.
modeling_geom.framework	Provides interfaces for geometry operations. Mostly relevant for users of the Maxon API.
mesh_misc.framework	Provides minor tooling for working with meshes.
animation.framework	Provides interfaces for custom weight algorithms. Much less important than its name implies. See CAWeightMgr Manual.
command.framework	Defines the interface for generic commands. See Commands Manual.
system.framework	Provides internal system functions. Third-party developers must not use this.

API Features

The Cinema 4D API was built to ensure easy software development, allow the simple creation of extensions, and provide access to state-of-the-art technologies.

Software Development

The Cinema 4D API provides several tools and concepts to make writing plugins as simple and safe as possible:

Easy-to-use API due to strict naming schemes and consistent concepts.
Safe code creation using a strict and powerful error-handling system, reference-counting, and type safety tools. See Error Handling and References.
Powerful debugging tools such as stack traces, type viewer, debugging output, and display of any type as a string. See also Debug and Output Functions.
Source processor to analyze the source code. See Source Processor.
Automatic dependency analysis eliminates the need for manual registration in the correct order.

Interfaces & Plugins

The Maxon 4D API is based on interfaces. See Interface Basics. It delivers:

Consistent and powerful interface concept, combining interfaces at runtime.
Public interfaces are 100% the same as what MAXON programmers use.
Code can be moved around freely, no need for manual initialization/free functions.

New plugins are registered using registries and IDs. See Registries. This approach guarantees:

Consistent registration concept.
Reverse domain name notation instead of IDs.

Technologies

The Maxon 4D API uses multiple modern concepts and technologies:

Extremely fast and efficient algorithms, high performance in all areas.
Powerful set of standardized classes (maps, arrays, lists, iterators, etc.)
Built-in reference-counting, see References.
Extremely powerful, yet simple to use threading system, see Threading.
Use of modern C++11 concepts, like lambdas. See page_maxonapi_cpp.
Powerful I/O system that allows you to write complex data (lists, maps, references) easily, implicit support for JSON/XML.
Unified I/O concept - no matter if the source is http, ftp, the content of a ZIP file, etc. See Maxon API Files & Media.
4-byte Unicode handling. See Strings & Texts.
Easy configuration of code via command line, text file, or environment variables. See Configuration Variables.
Automatic data types, e.g., maxon::BaseArray automatically builds itself without any additional code from the programmer.
Observer concept. See Observables.
Powerful math/geometry libraries.
Powerful bitmap I/O, support for many new features.

Table of Contents

Architecture

Plugin Types

Frameworks

API Features