277 lines
13 KiB
Markdown
277 lines
13 KiB
Markdown
> **Language:** [English](skills.md) | 日本語 | [Português (BR)](skills.pt-br.md) | [Español](skills.es.md) | [Русский](skills.ru.md) | [简体中文](skills.zh.md) | [हिन्दी](skills.hi.md)
|
||
|
||
# Godot MCP Pro — AIアシスタント向けスキル
|
||
|
||
> このファイルをGodotプロジェクトルートの `.claude/skills.md` にコピーすると、Claude CodeがGodot MCP Proを効果的に活用するためのコンテキストを得られます。
|
||
|
||
## Godot MCP Proとは？
|
||
|
||
Godot 4エディタに直接接続する169のMCPツールを利用できます。シーンの作成、スクリプトの記述、プレイヤー入力のシミュレーション、実行中のゲームの検査など、ユーザーがこの会話から離れることなく、すべての操作が可能です。すべての変更はGodotのUndoRedoシステムを通じて行われるため、いつでもCtrl+Zで元に戻せます。
|
||
|
||
## 基本ワークフロー
|
||
|
||
### 1. プロジェクトの調査
|
||
|
||
変更を加える前に、まずプロジェクトの全体像を把握しましょう：
|
||
|
||
```
|
||
get_project_info → プロジェクト名、Godotバージョン、レンダラー、ビューポートサイズ
|
||
get_filesystem_tree → ディレクトリ構造（filter: "*.tscn" や "*.gd" が使えます）
|
||
get_scene_tree → 現在開いているシーンのノード階層
|
||
read_script → 任意のGDScriptファイルを読む
|
||
get_project_settings → プロジェクト設定の確認
|
||
```
|
||
|
||
### 2. 2Dシーンの構築
|
||
|
||
```
|
||
create_scene → .tscnファイルをルートノードタイプ指定で作成
|
||
add_node → プロパティ付きの子ノードを追加
|
||
create_script → ゲームロジック用のGDScriptを作成
|
||
attach_script → ノードにスクリプトをアタッチ
|
||
update_property → position、scale、modulateなどを設定
|
||
save_scene → ディスクに保存
|
||
```
|
||
|
||
**例 — プレイヤーの作成：**
|
||
1. `create_scene` でroot_type `CharacterBody2D`、path `res://scenes/player.tscn` を指定
|
||
2. `add_node` でtextureプロパティ付きの `Sprite2D` を追加
|
||
3. `add_node` で `CollisionShape2D` を追加
|
||
4. `add_resource` でCollisionShape2Dにシェイプ（例：`RectangleShape2D`）を割り当て
|
||
5. `create_script` で移動ロジックを記述
|
||
6. `attach_script` でルートノードにアタッチ
|
||
7. `save_scene`
|
||
|
||
### 3. 3Dシーンの構築
|
||
|
||
```
|
||
create_scene → root_type: Node3D
|
||
add_mesh_instance → プリミティブ（box、sphere、cylinder、plane）の追加、または.glb/.gltfのインポート
|
||
setup_lighting → DirectionalLight3D、OmniLight3D、SpotLight3Dの追加
|
||
setup_environment → スカイ、アンビエントライト、フォグ、トーンマップ
|
||
setup_camera_3d → カメラ（オプションでSpringArm3Dによる三人称視点）
|
||
set_material_3d → PBRマテリアル（albedo、metallic、roughness、emission）
|
||
setup_collision → 物理ボディにコリジョンシェイプを追加
|
||
setup_physics_body → 質量、摩擦、重力の設定
|
||
```
|
||
|
||
### 4. スクリプトの作成と編集
|
||
|
||
```
|
||
create_script → 新規.gdファイルを作成（完全な内容を提供）
|
||
edit_script → 既存スクリプトを編集
|
||
- `replacements: [{search: "old code", replace: "new code"}]` で部分的な編集
|
||
- `content` でファイル全体を置換
|
||
- `insert_at_line` + `text` でコードを挿入
|
||
validate_script → 実行せずに構文エラーをチェック
|
||
read_script → 編集前に現在の内容を確認
|
||
```
|
||
|
||
### 5. プレイテストとデバッグ
|
||
|
||
```
|
||
play_scene → ゲームを起動（mode: "current"、"main"、またはファイルパス）
|
||
get_game_screenshot → ゲームの現在の見た目を確認
|
||
capture_frames → 複数フレームをキャプチャして動きやアニメーションを観察
|
||
get_game_scene_tree → 実行時のシーンツリーを検査
|
||
get_game_node_properties → ランタイムの値を読み取り（position、health、stateなど）
|
||
set_game_node_property → 実行中のゲームの値を変更
|
||
simulate_key → キー入力（WASD、SPACEなど）をduration指定で実行
|
||
simulate_mouse_click → ビューポート座標でクリック
|
||
simulate_action → InputMapアクション（move_left、jumpなど）をトリガー
|
||
get_editor_errors → ランタイムエラーの確認
|
||
stop_scene → ゲームを停止
|
||
```
|
||
|
||
**プレイテストループ：**
|
||
1. `play_scene` → ゲームを開始
|
||
2. `get_game_screenshot` → 現在の状態を確認
|
||
3. `simulate_key` / `simulate_action` → ゲームを操作
|
||
4. `capture_frames` → 時間経過での挙動を観察
|
||
5. `get_game_node_properties` → 特定の値を確認
|
||
6. `stop_scene` → 完了したら停止
|
||
7. スクリプトの問題を修正 → 繰り返し
|
||
|
||
### 6. アニメーション
|
||
|
||
```
|
||
# シーンにAnimationPlayerノードが存在することを確認
|
||
create_animation → 長さとループモード付きの新規アニメーション
|
||
add_animation_track → property/transform/methodトラックの追加
|
||
set_animation_keyframe → 特定時間にキーフレームを挿入
|
||
get_animation_info → 既存アニメーションの情報を取得
|
||
```
|
||
|
||
**例 — バウンドするスプライト：**
|
||
1. `create_animation` でname `bounce`、length `1.0`、loop_mode `1`（リニアループ）
|
||
2. `add_animation_track` でtrack_path `Sprite2D:position`、track_type `value`
|
||
3. `set_animation_keyframe` でtime `0.0`、value `Vector2(0, 0)`
|
||
4. `set_animation_keyframe` でtime `0.5`、value `Vector2(0, -50)`
|
||
5. `set_animation_keyframe` でtime `1.0`、value `Vector2(0, 0)`
|
||
|
||
### 7. UI / HUD
|
||
|
||
```
|
||
add_node → Control、Label、Button、TextureRectなど
|
||
set_anchor_preset → Controlの配置（full_rect、center、bottom_wideなど）
|
||
set_theme_color → font_colorなどの変更
|
||
set_theme_font_size → テキストサイズの調整
|
||
set_theme_stylebox → 背景、ボーダー、角丸
|
||
connect_signal → buttonのpressed、value_changedなどを接続
|
||
```
|
||
|
||
### 8. TileMap
|
||
|
||
```
|
||
tilemap_get_info → タイルセットのソースとアトラスレイアウトを確認
|
||
tilemap_set_cell → 個別タイルの配置
|
||
tilemap_fill_rect → 矩形領域を塗りつぶし
|
||
tilemap_get_used_cells → 配置済みセルの確認
|
||
tilemap_clear → 全セルをクリア
|
||
```
|
||
|
||
### 9. オーディオ
|
||
|
||
```
|
||
add_audio_bus → オーディオバスの作成（SFX、Music、UI）
|
||
set_audio_bus → ボリューム、ソロ、ミュートの調整
|
||
add_audio_bus_effect → リバーブ、ディレイ、コンプレッサーなどの追加
|
||
add_audio_player → AudioStreamPlayer(2D/3D)ノードの追加
|
||
```
|
||
|
||
### 10. プロジェクト設定
|
||
|
||
```
|
||
set_project_setting → ビューポートサイズ、物理設定などの変更
|
||
set_input_action → 入力マッピングの定義（move_left → KEY_Aなど）
|
||
add_autoload → Autoloadシングルトンの登録
|
||
set_physics_layers → コリジョンレイヤーの命名（player、enemy、worldなど）
|
||
```
|
||
|
||
## 重要なルールと注意点
|
||
|
||
### プロパティ値
|
||
|
||
プロパティは文字列から自動パースされます。以下のフォーマットを使用してください：
|
||
- Vector2: `"Vector2(100, 200)"`
|
||
- Vector3: `"Vector3(1, 2, 3)"`
|
||
- Color: `"Color(1, 0, 0, 1)"` または `"#ff0000"`
|
||
- Bool: `"true"` / `"false"`
|
||
- 数値: `"42"`、`"3.14"`
|
||
- Enum: 整数値を使用（例：最初のenum値は `0`）
|
||
|
||
### project.godotを直接編集しないこと
|
||
|
||
Godotエディタは `project.godot` を常に上書きします。プロジェクト設定の変更には必ず `set_project_setting` を使用してください。
|
||
|
||
### GDScriptの型アノテーション
|
||
|
||
型なし配列に対する `for` ループでは、明示的な型アノテーションを使用してください：
|
||
```gdscript
|
||
# NG — エラーの原因になる
|
||
for item in some_untyped_array:
|
||
var x := item.value # 型推論が失敗
|
||
|
||
# OK
|
||
for i in range(some_untyped_array.size()):
|
||
var item: Dictionary = some_untyped_array[i]
|
||
var x: int = item.value
|
||
```
|
||
|
||
### スクリプト変更にはリロードが必要
|
||
|
||
スクリプトの作成や大幅な変更の後は、`reload_project` を使用してGodotに変更を反映させましょう。特に `create_script` の後は重要です。
|
||
|
||
### simulate_keyのコツ
|
||
- 精密な移動には**短いduration**（0.3〜0.5秒）を使用
|
||
- 長いduration（1秒以上）はオーバーシュートの原因に
|
||
- ゲームプレイのテストでは、InputMapアクションが定義されている場合は `simulate_key` より `simulate_action` を推奨
|
||
|
||
### simulate_mouse_click
|
||
- デフォルトの `auto_release: true` はpressとreleaseの両方を送信 — UIボタンに必須
|
||
- UIボタンはreleaseで発火するため、両方のイベントが必要
|
||
|
||
### execute_game_scriptの制限事項
|
||
- ネストされた関数（`func` 内の `func`）は不可 — コンパイルエラーになる
|
||
- 動的アクセスには `.property` ではなく `.get("property")` を使用
|
||
- ランタイムエラーはデバッガーを一時停止させる（自動再開されるが、できれば避けること）
|
||
|
||
### コリジョンとピックアップエリア
|
||
- 収集アイテムにはArea3D/Area2Dで半径1.5以上を使用
|
||
- 小さい半径ではシミュレーション入力でのトリガーがほぼ不可能
|
||
|
||
### こまめに保存する
|
||
|
||
大きな変更を行った後は `save_scene` を呼んでください。保存していない変更はエディタのリロード時に失われる可能性があります。
|
||
|
||
## 分析とデバッグツール
|
||
|
||
問題が発生した場合、以下のツールで調査できます：
|
||
|
||
```
|
||
get_editor_errors → スクリプトエラーとランタイム例外を確認
|
||
get_output_log → print()出力と警告を読む
|
||
analyze_scene_complexity → パフォーマンスのボトルネックを特定
|
||
analyze_signal_flow → シグナル接続を可視化
|
||
detect_circular_dependencies → 循環参照するスクリプト/シーンを検出
|
||
find_unused_resources → 未使用ファイルのクリーンアップ
|
||
get_performance_monitors → FPS、メモリ、ドローコール、物理統計
|
||
```
|
||
|
||
## テストとQA
|
||
|
||
```
|
||
run_test_scenario → 自動テストシーケンスの定義と実行
|
||
assert_node_state → ノードプロパティが期待値と一致するか検証
|
||
assert_screen_text → 画面にテキストが表示されているか検証
|
||
compare_screenshots → ビジュアル回帰テスト（base64ではなくファイルパスを使用）
|
||
run_stress_test → 多数のノードを生成してパフォーマンスをテスト
|
||
```
|
||
|
||
## 高度なパターン
|
||
|
||
### クロスシーン操作
|
||
```
|
||
cross_scene_set_property → 現在開いていないシーンのノードを変更
|
||
find_node_references → パターンを参照しているすべてのファイルを検索
|
||
batch_set_property → 特定タイプの全ノードにプロパティを設定
|
||
```
|
||
|
||
### シェーダーワークフロー
|
||
```
|
||
create_shader → GLSL風のシェーダーコードを記述
|
||
assign_shader_material → ノードに適用
|
||
set_shader_param → 実行時にuniformを調整
|
||
get_shader_params → 現在の値を取得
|
||
```
|
||
|
||
### ナビゲーション（3D）
|
||
```
|
||
setup_navigation_region → 歩行可能エリアの定義
|
||
bake_navigation_mesh → ナビメッシュの生成
|
||
setup_navigation_agent → キャラクターにパスファインディングを追加
|
||
```
|
||
|
||
### AnimationTreeとステートマシン
|
||
```
|
||
create_animation_tree → ステートマシンまたはブレンドツリーでAnimationTreeをセットアップ
|
||
add_state_machine_state → ステートを追加（idle、walk、run、jump）
|
||
add_state_machine_transition → ステート間のトランジションを定義
|
||
set_tree_parameter → ブレンドパラメータを制御
|
||
```
|
||
|
||
## 推奨ワークフロー順序
|
||
|
||
ゲームをゼロから構築する場合の推奨順序：
|
||
|
||
1. **プロジェクトセットアップ** — `get_project_info`、`set_project_setting`（ビューポート、物理）
|
||
2. **入力マッピング** — `set_input_action` で全プレイヤー操作を定義
|
||
3. **メインシーン** — `create_scene` でメインシーンとして設定
|
||
4. **プレイヤー** — スプライト、コリジョン、スクリプト付きのプレイヤーシーンを作成
|
||
5. **レベル/ワールド** — 環境を構築（TileMap、3Dメッシュなど）
|
||
6. **ゲームロジック** — 敵、アイテム、UIのスクリプト
|
||
7. **オーディオ** — バスのセットアップ、オーディオプレイヤーの追加
|
||
8. **プレイテスト** — `play_scene` でシミュレーション入力によるテスト、バグ修正
|
||
9. **ポリッシュ** — アニメーション、パーティクル、シェーダー、テーマ
|
||
10. **エクスポート** — `list_export_presets`、`export_project`
|