Python in Cinema 4D Manual

Introduction

Cinema 4D has a builtin Python interpreter which can be accessed via the Cinema 4D and c4dpy executable.

Our Python interpreter is based on a vanilla CPython interpreter but not fully identical to it. Using a standard CPython interpreter which is installed on a machine as the Python interpreter of Cinema 4D is therefore not possible. Most third party Python libraries are compatible with our interpreter, but especially C-based libraries can cause problems. The modules of the Cinema 4D Python API are overwhelmingly implemented in C++, the native Cinema 4D C++ API. We strive for feature parity where it is possible, but high-performance and back-end features are usually reserved for the C++ API.

See Python Resources for an overview of external Cinema 4D Python tutorials and learning material.

Version

The current Cinema 4D Python interpreter versions are:

• Windows: Python 3.11.4 (pipelines/893915622:c23be21, Jun 8 2023, 15:31:26) [MSC v.1929 64 bit (AMD64)]

• Mac OS: Python 3.11.4 (pipelines/893543668-dirty:1e04aba, Jun 8 2023, 11:27:02) [Clang 14.0.0 (clang-1400.0.29.202)]

Scripting

Cinema 4D loosely makes the distinction between scripting, small pieces of Python code that can be written in and executed from a running Cinema 4D executable, and plugins, more elaborate Python code that must already be present in the boot sequence of the executable. The most important manuals for getting started with scripting are:

• Python Script Manager Manual: Describes the Script Manager for editing and running scripts within Cinema 4D.

• Python Console Manual: Describes the console of Cinema 4D as central development tool.

• Python Libraries Manual: Describes how to expose third party Python libraries to the Python environments of Cinema 4D.

• c4dpy Manual. Describes the standalone Python interpreter of Cinema 4D.

Scripting Objects

In addition to plain scripts exist the so called ‘Scripting Objects’ which expose partially the functionalities of some plugin hooks in a simplified form. They are not only great for quick results and technical artist workflows, but are also an excellent learning tool for the Cinema 4D Python API.

• Python Generator Object Manual: Generate geometry, as for example a cube object.

• Python Programming Tag Manual: Modify parameters in a scene, as for example aligning a camera with a target.

• Python Effector Object Manual: Influence particles in a MoGraph setup the effector is part of.

• Python Field Object and Layer Manual: Drive the sampling of a field with Python.

• Python Xpresso Node Manual: Use the Python API inside the computation of an Xpresso graph.

• Python Interaction Tag Manual: Build complex interactive rigs using Python.

• Python Visual Selector Tag Manual: Automatically invoke Python scripts when using the Visual Selector tag to control a rig.

• Python Character Component Tag Manual: Modify and react to the components of character object.

• Python Sketch and Toon Material Manual: Drive the channels Color, Thickness, and Opacity in a Sketch material using Python.

Note

Some operations in scripting are not allowed due to functions being called in parallel, as for example inserting an object into the active document from the main function of a Python tag. See Threading Manual for more information on the subject.

Plugins

Plugins integrate seamlessly into Cinema 4D and are indistinguishable from native features. There exist multiple so called plugin hooks, classes which must be implemented to realize a certain type of functionality. Appart from a much deeper access to into the Cinema 4D API, plugins also provide support for multi-language interfaces and defining GUIs in markup files, the so called resource files.

• Plugin Structure: Describes the makeup of files and folders for a plugin, including multi-language support, and interacting with the boot sequence of Cinema 4D.

The most important plugin hooks are are:

• CommandData: Creates an a button which uppon being clicked, runs a piece of code. Is often combined with a GeDialog GUI. See Py-TextureBaker.

• ObjectData: Realizes any form of BaseObject, the entries with which the Object Manager is populated with. This can be:

  • A plugin that generates polygonal geometry akin to the builtin Cube object. See Py-RoundedTube.

  • A plugin that generates spline geometry akin to the builtin Circle spline object. See Py-DoubleCircle.

  • A plugin that deforms point objects such as splines and polygonal geometry. See Py-SpherifyModifier.

  • A plugin that deforms particles. See Py-Gravitation.

• TagData: Realizes a BaseTag which can drive parameters in a scene. See Py-LookAtCamera.

• ShaderData: Realizes a BaseShader which can be used in materials. See Py-Fresnel.

• ToolData Realizes a tool such as the builtin Move tool. See Py-LiquidPainter.

• MessageData: Realizes a message hook which can interact with the core message stream of Cinema 4D.

In additon to these most important plugin hooks exist more specialized hooks:

• SceneLoaderData: Realizes a scene file format importer.

• SceneSaverData Realizes a scene file format exporter. See Py-IESMeta.

• BitmapLoaderData Realizes a bitmap file format loader. See Py-Xample.

• BitmapSaverData Realizes a bitmap file format loader. See Py-Xample.

• SculptBrushToolData Realizes a brush tool for the sculpting system. See Py-Sculpt Grab Brush).

• PreferenceData: Relaizes an entry in the Preferences dialog Cinema 4D to expose settings of another plugin one has implemented. See Py-Preference.

• NodeData Realizes a generic plugin node. This is only useful for expert users, as a generic node on its own is not that useful.

• FalloffData: A legacy hook for falloff data which has been deprecated since R20. See Py-NoiseFalloff.