# Bug Report — Hair (`.ccHair`) cannot be applied to an avatar via the RLPy API

**Component:** cc5-mcp-server bridge (RLPy / Character Creator 5 Python API)
**Severity:** High — blocks automated character dressing (hair only)
**Status:** Reproducible; manual UI workaround exists

---

## Summary
When driving Character Creator 5 programmatically (via the cc5-mcp-server bridge, which
calls the RLPy Python API), there is **no working way to apply a hair asset (`.ccHair`)
to an avatar**. Clothing (`.cccloth`) and shoes (`.ccshoes`) conform correctly through the
same code path, but hair does not attach — and the one avatar method capable of applying it
**hard-crashes CC5 to desktop**.

## Environment
- Character Creator 5 (CC5.1 RLPy API), Windows 11
- cc5-mcp-server (Node MCP server + in-CC5 Qt/RLPy bridge plugin), exec/dev mode enabled
- Hair assets: Reallusion "Antique Rome" wigs (`.cchair`), authored for the CC base body
- Base avatar: `CC4 Kevin.ccAvatar` (CC-native)

## Expected behavior
Applying a hair asset to the current/selected avatar via the API attaches and conforms it —
identical to double-clicking the wig thumbnail in the Content Manager with the avatar selected.

## Actual behavior — three approaches, none work

### 1. `RLPy.RFileIO.LoadFile(hair_path)` — silently no-ops for hair
- Returns success, raises nothing.
- `avatar.GetHairs()` stays **empty**; no hair object appears in the scene; avatar stays bald.
- The **same `LoadFile` call correctly conforms CLOTHING and SHOES** to the avatar — only hair fails.
- Selecting the avatar first (`RScene.ClearSelectObjects()` then `RScene.SelectObject(avatar)`)
before `LoadFile` does **not** help; hair still does not attach.

### 2. `RIAvatar.LoadAccessoryWithTransferSkinWeight(path, kTemplateType)` — CRASHES CC5
- The only apply/conform method exposed on `RIAvatar` (aside from `GetHairs`).
- Documented signature: `(kFilePath: str, kTemplateType: str) -> RStatus`.
- Called with a `.cchair` path, it **crashes Character Creator 5 to desktop, reproducibly**,
for every `kTemplateType` value tried (`""`, `"Hair"`, `"Group"`, `"Accessory"`, …).
- No Python exception is raised — the whole application terminates (the bridge HTTP
connection drops mid-call). Reproduced twice.

### 3. Manual Content Manager double-click — WORKS
- Selecting the avatar and double-clicking the same wig in the Content Manager applies and
conforms it correctly (`GetHairs()` then returns 1 item). Confirms the asset is valid and
the operation is possible; only the scripted path is broken.

## Reproduction
1. Start CC5 with the bridge plugin; connect the MCP server (dev/exec mode on).
2. `load_asset` a base `.ccAvatar` (e.g. CC4 Kevin).
3. `load_asset` a `.cchair` → query `list_hair` (`GetHairs()`) → **0 items** (bald).
4. `exec_python`: `RLPy.RScene.GetAvatars()[0].LoadAccessoryWithTransferSkinWeight("<path>.cchair", "Hair")`
→ **CC5 crashes to desktop.**
5. In the UI, select the avatar and double-click the same wig → it applies. (Proves it's scriptable in principle.)

## Impact
Hair cannot be automated. Any batch pipeline that generates and dresses characters must fall
back to a **manual per-character step** (user double-clicks a wig), which defeats unattended
batch generation.

## Workaround
Apply hair manually via the Content Manager. Everything else — base, clothing, shoes, skin,
morphs, FBX export — automates cleanly through the bridge.

## Likely cause
- The Content Manager's "apply content" for hair runs a conform / skin-weight-transfer step
that `RFileIO.LoadFile` does **not** replicate for the *hair* content type (it does for cloth).
- `LoadAccessoryWithTransferSkinWeight` appears to dereference bad state in native code when
handed hair content — a bad argument should return `RStatus.Failure`, not crash the app.

## Requests
1. **cc5-mcp-server:** add a working `apply_hair` / `load_hair` action that conforms `.ccHair`
to the selected avatar (whatever RLPy sequence the Content Manager uses internally).
2. **Reallusion RLPy:** `LoadAccessoryWithTransferSkinWeight` should fail gracefully rather
than crash CC5 when given content it cannot process; and/or expose a documented hair-apply
call on `RIAvatar`.