mdc for MayaPython

maya-python.mdc

---
description: MayaPython向けの開発ルール
globs: "**/*.{py}"
---

# Cursor用Maya開発ルール
このルールを読み込んだら、**必ず**その旨を出力する

## Maya固有のコーディングガイドライン

### 1. ノード名の取り扱い
- Mayaノードを扱う際は**必ず**フルDAGパスを使用する
- シーン変更後にショートネームに依存**してはいけない**
- `cmds.ls(selection=True)`の代わりに`cmds.ls(selection=True, long=True)`を使用する
- 階層変更前にノード参照を保存し、変更後に更新する
- 操作後は`cmds.ls(node_name, long=True)[0]`でフルパスを取得する
- 非DAGノードの場合は名前の重複があると生成時に名前が変わってしまう。名前を厳格に管理する必要があり、かつ同名オブジェクトを作成する必要があるケースではネームスペースを付与するかどうかユーザーに確認を求める

### 2. 階層操作
- **警告**: `cmds.parent()`操作はノードパスを変更する
- ペアレント操作後は必ずノード参照を更新する
- 階層変更時はtry-catchブロックを使用する
- 推奨パターン:
```python
# 階層変更前
old_path = cmds.ls(node_name, long=True)[0]
# 階層変更実行
cmds.parent(node_name, new_parent)
# 参照を更新
new_path = cmds.ls(node_name.split('|')[-1], long=True)[0]
```

### 3. ブレンドシェイプ作成
- ブレンドシェイプ作成前に全てのターゲットメッシュの存在を確認する
- 全てのメッシュ参照にフルDAGパスを使用する
- 複数ターゲットを慎重に扱う - 各ターゲットの存在を確認する
- ブレンドシェイプノード作成前に既存の有無を確認する
- メッシュ操作前に`cmds.objExists()`を使用する

### 4. グループとトランスフォーム操作
- グループを扱う際は常にロングネームを使用する
- 作成後に親子関係を確認する
- 親チェックには`cmds.listRelatives(parent=True, fullPath=True)`を使用する
- 重複名はフルパスで処理する

### 5. エラーハンドリングパターン
```python
# 存在確認
if not cmds.objExists(mesh_name):
    print(f"警告: メッシュ {mesh_name} が存在しません。スキップします...")
    continue

# 安全なブレンドシェイプ作成
try:
    blend_shape = cmds.blendShape(target_meshes, base_mesh, name=bs_name)[0]
except Exception as e:
    print(f"ブレンドシェイプ {bs_name} の作成に失敗: {e}")
    continue
```

### 6. Maya API使用法
- 単純な操作には`maya.api`より`maya.cmds`を優先する
- パフォーマンス重視の操作には`maya.api.OpenMaya`を使用する
- スクリプトの先頭でMayaモジュールをインポートする
- アンドゥ可能な操作には`cmds.undoInfo(openChunk=True)`と`closeChunk=True`を使用する

### 7. 命名規則
- 説明的な変数名を使用: `mesh`ではなく`base_mesh`
- Maya命名規則に従う: `mesh_GRP`, `ctrl_CTRL`, `jnt_JNT`
- オブジェクトタイプごとに一貫したプレフィックスを使用する
- ハードコードされた名前を避け、変数と定数を使用する

### 8. シーン管理
- 操作前に必ずオブジェクトの存在を確認する
- クリーンなシーンには`cmds.file(new=True, force=True)`を使用する
- 関連オブジェクトを論理的にグループ化する
- 操作後に一時オブジェクトをクリーンアップする

### 9. パフォーマンス考慮事項
- 可能な限りバッチ操作を使用する
- 不要時は`cmds.select(clear=True)`で選択をクリアする
- バッチ操作中はビューポート更新を最小化する
- 重い操作には`cmds.refresh(suspend=True)`を使用する

### 10. デバッグとログ
- デバッグには説明的なprint文を使用する
- 成功した操作と失敗をログに記録する
- エラーメッセージにオブジェクト名とパスを含める
- 具体的なエラーハンドリングでtry-catchブロックを使用する

### 11. コード構造
- 検証ロジックと作成ロジックを分離する
- 再利用可能な操作には関数を使用する
- Maya固有の動作を説明するdocstringを含める
- 複雑な階層操作にコメントを付ける

### 12. テストパターン
- 各検証シナリオのテストケースを作成する
- 単純と複雑両方の階層でテストする
- 失敗した操作後のクリーンアップを確認する
- 既存・非既存オブジェクトでテストする

### 13. GUI
- GUIは原則としてPySideを使用する
- PySideは直接PySide6を使用せず、Qt.pyを使用する
- ツールのボタンやテキストの色はツールにおけるその要素の重要度に合ったものを設定する

### 14. ユーザーへのフィードバック
- 何か問題があって処理が中断された場合、何が原因で、どうすれば解決するのか具体的にダイアログでユーザーに対してフィードバックする
- ダイアログだけで説明するのが難しい場合、loggerを用いてスクリプトエディタを通して詳細を伝えてもよい

## 15. ユーザビリティの配慮
- 選択状態を変える処理がある場合、処理が完了したら出来る限りツール実行前の選択状態に戻す
- シーンを閉じる場合、シーンに変更がないか確認し、ユーザーに保存するかどうか、キャンセルするかどうかを確認する


## 避けるべき一般的なMayaの落とし穴
1. **ノード名変更**: ノード名が一定のままと仮定しない
2. **選択依存**: Mayaの現在の選択に依存しない
3. **アンドゥ問題**: 操作を必ずアンドゥチャンクで囲む
4. **メモリリーク**: 未使用ノードと参照をクリーンアップする
5. **パス区切り文字**: ファイルシステムパスではなくMayaの'|'区切り文字を使用する

## Mayaスクリプト必須インポート
```python
import maya.cmds as cmds
import maya.mel as mel
# 高度な操作用:
import maya.api.OpenMaya as om
import maya.api.OpenMayaAnim as oma
```

## ファイル構成
- ユーティリティ関数をメインロジックから分離する
- 一貫したモジュール構造を使用する
- 全てのパブリック関数に適切なエラーハンドリングを含める
- Mayaバージョン互換性を文書化する

これらのルールは、信頼性と保守性を確保するため、全てのMaya関連Pythonコードに適用すべきです。