cinema4d-mcp

What this skill does

# Cinema 4D MCP

## Source of Truth

This skill targets Vlad's fork of Cinema 4D MCP: [vladmdgolam/cinema4d-mcp](https://github.com/vladmdgolam/cinema4d-mcp).

Relevant fork additions:
- `inspect_redshift_materials` - read-only Redshift inspector for assignments, preview-derived colors, readable description/container fields, and best-effort graph probing. **Note:** this tool may skip RS materials as `not_redshift_like` (type 5703) — use `execute_python_script` with the `maxon` API for full RS node graph extraction instead (see Redshift Material Extraction section).
- Duplicate-safe material targeting - the inspector accepts `material_index` and returns stable scene indices plus duplicate-name hints when names collide.
- Redshift GraphView fallback - when node-space access fails but `import redshift` works, the inspector falls back to `redshift.GetRSMaterialNodeMaster(...)` and reports GraphView nodes plus resolved connections.
- The loaded C4D plugin may lag behind the repo copy. After plugin edits, restart Cinema 4D before trusting new tool behavior.

## Tool Selection

Use **structured MCP tools** (`get_scene_info`, `list_objects`, `add_primitive`, etc.) for simple operations.

Use **`execute_python_script`** as the primary path for non-trivial extraction. It avoids wrapper/schema mismatches, gives full `c4d` + `maxon` API access, and allows proper frame stepping control. This is especially important for **Redshift material extraction** — the `maxon` node-space API gives full access to RS node graphs, which other tools may miss.

Use **`inspect_redshift_materials`** as a quick overview of material assignments and preview colors, but be aware it may skip RS materials as `not_redshift_like` if they use type 5703 wrappers. For full RS node graph data, use `execute_python_script` with the `maxon` API pattern documented in the Redshift section.

## Health Check (Always First)

1. `get_scene_info` - verify connection
2. `execute_python_script` with `print("ok")` - verify Python works
3. If both work, extraction is possible even when other tools are broken

## Critical Rules

### 1. World vs Local Coordinates
`GeGetMoData()` returns cloner-local positions. Always apply global matrix:
```python
mg = cloner.GetMg()
world_pos = mg * m.off  # LOCAL -> WORLD
```
Missing this shifts everything by the cloner's global offset.

### 2. Visibility Constants Are Swapped
- `MODE_OFF = 1` (not 0!)
- `MODE_ON = 0` (not 1!)
- `MODE_UNDEF = 2` (default/inherit)

Always use `c4d.MODE_OFF` / `c4d.MODE_ON`, never raw integers.

### 3. Sequential Frame Stepping
MoGraph effectors accumulate state. Iterate 0->N sequentially:
```python
for frame in range(start, end + 1):
    doc.SetTime(c4d.BaseTime(frame, fps))
    doc.ExecutePasses(None, True, True, True, c4d.BUILDFLAGS_NONE)
    # NOW read data
```
Never jump to arbitrary frames. Never skip `ExecutePasses`.

### 4. Split Heavy Bakes
MCP scripts timeout on large frame ranges (~20-30s default, some forks 60s). Bake in chunks (e.g., frames 0-200, then 200-400), combine afterward. Log progress with `print()`.

### 5. Iterative Traversal Only
Use stack-based traversal. Recursive traversal hits Python recursion limits:
```python
def find_obj(name):
    stack = [doc.GetFirstObject()]
    while stack:
        obj = stack.pop()
        while obj:
            if obj.GetName() == name:
                return obj
            if obj.GetDown():
                stack.append(obj.GetDown())
            obj = obj.GetNext()
    return None
```

### 6. API Version Compatibility
Constants differ between C4D versions. Use defensive checks:
```python
if hasattr(c4d, "SCENEFILTER_ANIMATION"):
    ...
```

### 7. Check Render Visibility
Objects can be disabled via traffic lights (`GetRenderMode()`), RS Object tags, parent hierarchy inheritance, or Takes system.

## Complete Animation Bake Workflow

This is the authoritative end-to-end procedure. Follow it in order — each step gates the next.

### Step 1: Health Check
```python
# Tool call: get_scene_info
# Then:
import c4d
print(doc.GetDocumentName(), doc.GetFps(), doc.GetMaxTime().GetFrame(doc.GetFps()))
```
Confirm: scene name resolves, fps is correct (typically 24/25/30), max frame is the expected end frame.

### Step 2: Discover Animation Tracks
Before baking, confirm the cloner actually has animated effectors:
```python
import c4d

def find_obj(name):
    stack = [doc.GetFirstObject()]
    while stack:
        obj = stack.pop()
        while obj:
            if obj.GetName() == name:
                return obj
            if obj.GetDown():
                stack.append(obj.GetDown())
            obj = obj.GetNext()
    return None

fps = doc.GetFps()
cloner = find_obj("MyClonerName")  # replace with actual name

# Check direct tracks on cloner
for t in cloner.GetCTracks():
    did = t.GetDescriptionID()
    ids = [int(did[i].id) for i in range(did.GetDepth())]
    curve = t.GetCurve()
    key_count = curve.GetKeyCount() if curve else 0
    print(f"Track IDs: {ids}, keys: {key_count}")

# Check effector children for their own tracks
child = cloner.GetDown()
while child:
    for t in child.GetCTracks():
        did = t.GetDescriptionID()
        ids = [int(did[i].id) for i in range(did.GetDepth())]
        print(f"  Effector '{child.GetName()}' track IDs: {ids}")
    child = child.GetNext()
```
If no tracks appear, the animation may be driven by fields or expressions — proceed to bake anyway; `ExecutePasses` will resolve those.

### Step 3: Bake MoGraph (Sequential Frame Stepping)
```python
import c4d
from c4d.modules import mograph as mo
import json

def find_obj(name):
    stack = [doc.GetFirstObject()]
    while stack:
        obj = stack.pop()
        while obj:
            if obj.GetName() == name:
                return obj
            if obj.GetDown():
                stack.append(obj.GetDown())
            obj = obj.GetNext()
    return None

def vec(v):
    return [float(v.x), float(v.y), float(v.z)]

fps = doc.GetFps()
start = 0
end = int(doc.GetMaxTime().GetFrame(fps))
cloner = find_obj("MyClonerName")
mg = cloner.GetMg()  # global matrix for LOCAL->WORLD

frames_data = {}

for frame in range(start, end + 1):
    doc.SetTime(c4d.BaseTime(frame, fps))
    doc.ExecutePasses(None, True, True, True, c4d.BUILDFLAGS_NONE)

    md = mo.GeGetMoData(cloner)
    if md is None:
        print(f"Frame {frame}: no MoData")
        continue

    matrices = md.GetArray(c4d.MODATA_MATRIX)
    clone_indices = md.GetArray(c4d.MODATA_CLONE)

    frame_clones = []
    for i, m in enumerate(matrices):
        world_pos = mg * m.off
        scale = (m.v1.GetLength() + m.v2.GetLength() + m.v3.GetLength()) / 3.0
        frame_clones.append({
            "index": i,
            "position": vec(world_pos),
            "scale": float(scale),
            "clone_index": float(clone_indices[i]) if clone_indices else None
        })

    frames_data[frame] = frame_clones
    if frame % 50 == 0:
        print(f"Baked frame {frame}/{end}")

print(f"Done. Total frames baked: {len(frames_data)}")
```

### Step 4: Extract Keyframes (Optional — for sparse data)
If you need keyframe-only data rather than every-frame bake:
```python
import c4d

fps = doc.GetFps()
obj = find_obj("MyObject")

keyframe_data = {}
for t in obj.GetCTracks():
    did = t.GetDescriptionID()
    ids = [int(did[i].id) for i in range(did.GetDepth())]
    curve = t.GetCurve()
    if not curve:
        continue
    keys = []
    for k in range(curve.GetKeyCount()):
        key = curve.GetKey(k)
        keys.append({
            "frame": key.GetTime().GetFrame(fps),
            "value": float(key.GetValue())
        })
    keyframe_data[str(ids)] = keys

print(json.dumps(keyframe_data))
```

### Step 5: Export JSON
```python
import json

output = {
    "scene": doc.GetDocumentName(),
    "fps": fps,
    "start_frame": start,
    "end_frame": end,
    "clone_count": len(frames_data.get(start, [])),
    "frames": frames_data
}

import tempfile, os
export_p