Add a primitive object to the Cinema 4D scene.

Args:
    primitive_type: Type of primitive (cube, sphere, cone, cylinder, plane, etc.)
    name: Optional name for the new object
    position: Optional [x, y, z] position
    size: Optional [x, y, z] size or dimensions

Modify properties of an existing object.

Args:
    object_name: Name of the object to modify
    properties: Dictionary of properties to modify (position, rotation, scale, etc.)

If this tool returns a validation error, use execute_python_script as a fallback
to traverse the object hierarchy manually via the c4d API.

Create a new material in Cinema 4D.

Args:
    name: Name for the new material
    color: Optional [R, G, B] color (values 0-1)
    properties: Optional additional material properties

Apply a material to an object.

Args:
    material_name: Name of the material to apply
    object_name: Name of the object to apply the material to

Inspect Redshift materials with best-effort fallbacks.

This tool is read-only and is designed to be useful even when the Redshift
Python runtime is unavailable. It can still report names, assignments,
preview-derived colors, readable description/container fields, and will
attempt graph inspection only when Cinema 4D exposes that data.

Args:
    material_name: Optional material name filter
    include_assignments: Include texture-tag assignments in the scene
    include_preview: Include sampled preview bitmap color data
    include_description: Include readable description entries
    include_container: Include safe BaseContainer values
    include_graph: Attempt node-graph inspection when available

Render the current frame.

Args:
    output_path: Optional path to save the rendered image
    width: Optional render width in pixels
    height: Optional render height in pixels

Set a keyframe for an object property.

Args:
    object_name: Name of the object
    property_name: Name of the property to keyframe (e.g., 'position.x')
    value: Value to set at the keyframe
    frame: Frame number to set the keyframe at

Save the current Cinema 4D scene.

Args:
    file_path: Optional path to save the scene to

Load a Cinema 4D scene file.

Args:
    file_path: Path to the scene file to load

Create a MoGraph Cloner object of specified type.

Args:
    cloner_type: Type of cloner (grid, radial, linear)
    name: Optional name for the cloner

Add a MoGraph Effector to the scene.

Args:
    effector_type: Type of effector (random, shader, field)
    name: Optional name for the effector
    target: Optional target object (e.g., cloner) to apply the effector to

Create and apply a MoGraph Field.

Args:
    field_type: Type of field (spherical, box, cylindrical, linear, radial, noise)
    target: Optional target object to apply the field to
    field_name: Optional name for the field
    parameters: Optional parameters for the field (strength, falloff)

Add soft body dynamics to the specified object.

Args:
    object_name: Name of the object to convert to a soft body

Add dynamics (rigid or soft) to the specified object.

Args:
    object_name: Name of the object to apply dynamics to
    dynamics_type: Type of dynamics to apply (rigid, soft)

Create an organic, abstract shape.

Args:
    shape_type: Type of shape (blob, metaball)
    name: Optional name for the shape

Create a new camera in the scene.

Args:
    name: Optional name for the new camera.
    position: Optional [x, y, z] position.
    properties: Optional dictionary of camera properties (e.g., {"focal_length": 50}).

Add a light to the scene.

Args:
    light_type: Type of light (area, dome, spot)
    name: Optional name for the light

Create and apply a specialized shader material.

Args:
    shader_type: Type of shader (noise, gradient, fresnel, etc)
    material_name: Optional name of material to apply shader to
    object_name: Optional name of object to apply the material to

Create a camera animation.

Args:
    animation_type: Type of animation (wiggle, orbit, spline, linear)
    camera_name: Optional name of camera to animate
    positions: Optional list of [x,y,z] camera positions for keyframes
    frames: Optional list of frame numbers for keyframes

Execute a Python script in Cinema 4D's Python environment.

This is the most reliable tool for non-trivial operations — it gives full access
to the c4d API and avoids wrapper/schema mismatches that can affect other tools.

Args:
    script: Python code to execute in Cinema 4D. Has access to `c4d` and
        `c4d.modules.mograph` modules.

Important usage notes:
    - For animated/MoGraph data, always call doc.ExecutePasses() after SetTime():
        doc.SetTime(c4d.BaseTime(frame, fps))
        doc.ExecutePasses(None, True, True, True, c4d.BUILDFLAGS_NONE)
    - For MoGraph/effector data, iterate frames sequentially (0..N) rather than
      jumping directly to a later frame — sequential stepping produces more
      faithful results.
    - Security restrictions block certain keywords: import os, subprocess, exec(, eval(.
      Keep scripts within the c4d API surface.
    - For heavy operations (dense frame loops, complex MoGraph scenes), split work
      into multiple smaller scripts rather than one large monolith.
    - Use print() to return results — output is captured and returned.

Group multiple objects under a null object.

Args:
    object_names: List of object names to group
    group_name: Optional name for the group

Render the current view and return a base64-encoded preview image.

Args:
    width: Optional preview width in pixels
    height: Optional preview height in pixels
    frame: Optional frame number to render

Create a snapshot of the current scene state.

Args:
    file_path: Optional path to save the snapshot
    include_assets: Whether to include external assets in the snapshot