Skill: isonaei/godot-dev-guide (version 1.0.0)

--- name: godot-dev-guide description: "Godot 4.x 完整開發指南。涵蓋 GDScript 模式、文件格式（.gd/.tscn/.tres）、場景架構、物理/UI/音效、性能優化、多平台導出、測試。自動觸發於 Godot 相關開發。" autoInvoke: true priority: high triggers: - "godot" - "gdscript" - ".gd" - ".tscn" - ".tres" - "scene" - "node" - "CharacterBody" - "RigidBody" - "Area2D" - "Area3D" - "project.godot" --- # Godot Dev Guide Skill Godot 4.x 遊戲開發完整指南，專為 AI 輔助開發設計。 ## 核心原則 ### 1. 文件格式差異（最重要！） ``` .gd → GDScript 程式碼（完整語言） .tscn → 場景序列化（嚴格格式，非 GDScript） .tres → 資源序列化（嚴格格式，非 GDScript） ``` ⚠️ **AI PITFALL：混淆 GDScript 與資源格式** ```gdscript # ❌ WRONG in .tres/.tscn script = preload("res://script.gd") var items = [1, 2, 3] # ✅ CORRECT in .tres/.tscn [ext_resource type="Script" path="res://script.gd" id="1"] script = ExtResource("1") items = Array[int]([1, 2, 3]) ``` ### 2. 類型系統（永遠使用） ```gdscript # 變數類型 var health: int = 100 var speed: float = 200.0 var items: Array[Item] = [] var stats: Dictionary = {} # 函數簽名 func calculate_damage(base: int, multiplier: float) -> int: return int(base * multiplier) ``` ### 3. 架構模式 ``` 組合優先於繼承 信號用於解耦通信 資源用於數據配置 自動載入用於全局系統 ``` --- ## 快速參考 ### 項目結構 ``` res:// ├── project.godot ├── scenes/ # .tscn 場景 │ ├── player/ │ ├── enemies/ │ └── ui/ ├── scripts/ # .gd 腳本 ├── assets/ # 資源文件 ├── autoload/ # 單例腳本 ├── resources/ # .tres 資源 └── test/ # 測試 ``` ### 常用節點 | 2D | 3D | 用途 | |----|----|----| | CharacterBody2D | CharacterBody3D | 玩家/NPC 移動 | | RigidBody2D | RigidBody3D | 物理模擬 | | Area2D | Area3D | 碰撞檢測（無物理） | | Sprite2D | MeshInstance3D | 視覺渲染 | ### Export 變數 ```gdscript @export var speed: float = 5.0 @export_range(0, 100, 1) var health: int = 100 @export_file("*.tscn") var next_level: String @export_group("Combat") @export var damage: int = 10 ``` ### 信號模式 ```gdscript signal health_changed(current: int, maximum: int) signal died func take_damage(amount: int) -> void: health -= amount health_changed.emit(health, max_health) if health <= 0: died.emit() ``` ### 節點引用 ```gdscript @onready var sprite: Sprite2D = $Sprite2D @onready var anim: AnimationPlayer = $AnimationPlayer ``` --- ## 關鍵陷阱清單 | 陷阱 | 錯誤寫法 | 正確寫法 | |-----|---------|---------| | .tres 使用 preload | `preload("res://x.gd")` | `ExtResource("id")` | | .tres 使用 var | `var x = 5` | `x = 5` | | 未類型化陣列 | `[1, 2, 3]` in .tres | `Array[int]([1, 2, 3])` | | 缺少 ext_resource | 直接使用 id | 先宣告 ext_resource | | @onready 初始化 | 在宣告時存取其他節點 | 等到 _ready() | | 直接修改資源 | `resource.value = x` | `resource.duplicate()` | | 輸入處理 | UI 和遊戲混用 _input | UI 用 _gui_input | --- ## 參考文件 | 主題 | 路徑 | |------|------| | 項目結構 | `references/01-project-structure.md` | | GDScript 模式 | `references/02-gdscript-patterns.md` | | 文件格式 | `references/03-file-formats.md` | | 場景與節點 | `references/04-scenes-nodes.md` | | UI 與輸入 | `references/05-ui-input.md` | | 物理系統 | `references/06-physics.md` | | 音效與動畫 | `references/07-audio-animation.md` | | 性能優化 | `references/08-performance.md` | | 導出平台 | `references/09-export.md` | | 測試指南 | `references/10-testing.md` | --- ## CLI 快速命令 ```bash # 運行遊戲 godot --path . # 驗證腳本 godot --path . --check-only --script path/to/script.gd # 無頭測試 godot --path . --headless --quit # 導出 godot --path . --export-release "Preset Name" builds/game.exe ``` --- **Version:** 1.0.0 | **Last Updated:** 2026-02-17

path: BUILD_REPORT.md
content: # Godot Mastery Skill - 製作報告

## 概述

成功建立 `godot-mastery` skill，整合了三個來源的精華：

1. **本地材料** `/home/isonaei/下載/godot-expert/` - 完整開發指南
2. **GitHub gdscript-patterns** - GDScript 模式與架構
3. **FastMCP godot skill** - 文件格式專業知識與 AI 陷阱

## 文件結構

```
skills/godot-mastery/
├── SKILL.md                     # 主文件 (~120 行)
├── BUILD_REPORT.md              # 本報告
└── references/
    ├── 01-project-structure.md  # 項目結構
    ├── 02-gdscript-patterns.md  # GDScript 模式 ★重點
    ├── 03-file-formats.md       # 文件格式 ★重點
    ├── 04-scenes-nodes.md       # 場景與節點
    ├── 05-ui-input.md           # UI 與輸入 ★重點
    ├── 06-physics.md            # 物理系統
    ├── 07-audio-animation.md    # 音效與動畫
    ├── 08-performance.md        # 性能優化
    ├── 09-export.md             # 導出平台
    └── 10-testing.md            # 測試指南
```

## AI PITFALL 標註統計

| 文件 | AI PITFALL 數量 | 重點陷阱 |
|------|-----------------|----------|
| 01-project-structure | 2 | 路徑錯誤、自動載入順序 |
| 02-gdscript-patterns | 4 | 資源修改、信號連接、@onready、is_instance_valid |
| 03-file-formats | 4 | preload、未宣告資源、未類型化陣列、實例覆蓋 |
| 04-scenes-nodes | 3 | 節點路徑、_init 存取、queue_free |
| 05-ui-input | 3 | mouse_filter、_input vs _gui_input、輸入順序 |
| 06-physics | 4 | PhysicsServer API、move_and_slide、碰撞層 |
| 07-audio-animation | 2 | Tween 生命週期、animation_finished |
| 08-performance | 2 | get_node 快取、記憶體分配 |
| 09-export | 2 | 平台 API、路徑分隔符 |

**總計：26 個 AI PITFALL 標註**

## 核心價值

### 1. 文件格式專業知識
- 清晰區分 .gd / .tscn / .tres 語法差異
- 完整的 ExtResource / SubResource 使用指南
- 常見格式錯誤的預防與檢測

### 2. GDScript 模式
- 狀態機完整實現
- 物件池模式
- 組件系統
- 事件總線

### 3. 實用代碼範例
- 所有代碼都是 Godot 4.x 可用語法
- 包含類型提示
- 遵循官方命名規範

## 與來源材料的差異

1. **去重** - 三個來源有大量重複內容，已整合為單一版本
2. **結構優化** - 按主題重新組織，而非來源
3. **AI 導向** - 增加大量 AI 陷阱標註
4. **精簡** - 去除冗餘解釋，保留核心代碼

## Frontmatter

```yaml
name: godot-mastery
description: "Godot 4.x 完整開發指南..."
autoInvoke: true
priority: high
triggers:
  - godot, gdscript, .gd, .tscn, .tres
  - scene, node, CharacterBody, RigidBody
  - Area2D, Area3D, project.godot
```

## 建議使用方式

1. **新項目** - 參考 01-project-structure.md 建立結構
2. **寫腳本** - 查閱 02-gdscript-patterns.md 的模式
3. **編輯場景/資源** - 必讀 03-file-formats.md 避免陷阱
4. **導出前** - 檢查 09-export.md 的平台檢查清單

---

**製作完成時間：** 2026-02-17
**總文件大小：** ~45KB
**代碼範例：** 全部為 Godot 4.x 語法


path: references/01-project-structure.md
content: # 01 - 項目結構

## 標準佈局

```
res://
├── project.godot           # 項目配置
├── export_presets.cfg      # 導出模板
│
├── scenes/                 # .tscn 文件（按類型組織）
│   ├── player/
│   │   ├── player.tscn
│   │   └── player_hud.tscn
│   ├── enemies/
│   │   ├── enemy_base.tscn
│   │   └── enemy_flying.tscn
│   ├── levels/
│   │   ├── level_01.tscn
│   │   └── level_02.tscn
│   └── ui/
│       ├── main_menu.tscn
│       ├── pause_menu.tscn
│       └── game_over.tscn
│
├── scripts/                # .gd 文件（鏡像 scenes/ 結構）
│   ├── player/
│   │   └── player.gd
│   ├── enemies/
│   │   ├── enemy_base.gd
│   │   └── enemy_flying.gd
│   ├── managers/
│   │   ├── game_manager.gd
│   │   └── audio_manager.gd
│   └── utils/
│       └── helpers.gd
│
├── assets/
│   ├── sprites/            # 2D 圖形
│   │   ├── characters/
│   │   └── environment/
│   ├── models/             # 3D 模型
│   ├── audio/
│   │   ├── sfx/
│   │   └── music/
│   ├── fonts/
│   └── shaders/
│
├── autoload/               # 單例腳本
│   ├── globals.gd
│   ├── events.gd
│   └── save_manager.gd
│
├── resources/              # .tres 文件
│   ├── themes/
│   └── data/
│
├── addons/                 # 插件
│   └── gdunit4/            # 測試框架
│
└── test/                   # GDUnit 測試
    ├── player/
    └── enemies/
```

## project.godot 配置

```ini
[application]
config/name="My Game"
config/version="1.0.0"
run/main_scene="res://scenes/ui/main_menu.tscn"
config/features=PackedStringArray("4.3", "GL Compatibility")
config/icon="res://assets/icon.svg"

[autoload]
Globals="*res://autoload/globals.gd"
Events="*res://autoload/events.gd"
SaveManager="*res://autoload/save_manager.gd"
AudioManager="*res://autoload/audio_manager.gd"

[display]
window/size/viewport_width=1920
window/size/viewport_height=1080
window/stretch/mode="canvas_items"
window/stretch/aspect="expand"

[input]
move_left={...}
move_right={...}
jump={...}
attack={...}

[rendering]
renderer/rendering_method="gl_compatibility"
textures/vram_compression/import_etc2_astc=true
```

## 命名規範

| 類型 | 規範 | 範例 |
|------|------|------|
| 場景 | snake_case.tscn | player_controller.tscn |
| 腳本 | snake_case.gd | player_controller.gd |
| 類名 | PascalCase | PlayerController |
| 函數 | snake_case | move_and_slide() |
| 變數 | snake_case | max_health |
| 常數 | SCREAMING_SNAKE | MAX_SPEED |

---

## ⚠️ AI PITFALL：路徑錯誤

```gdscript
# ❌ WRONG - 絕對路徑或相對路徑混用
var scene = load("/home/user/project/scenes/player.tscn")

# ✅ CORRECT - 使用 res:// 前綴
var scene = load("res://scenes/player.tscn")
```

## ⚠️ AI PITFALL：自動載入順序

```gdscript
# ❌ WRONG - 在 Globals 中存取 Events（如果 Events 在後面加載）
# globals.gd
func _ready():
    Events.something.connect(...)  # Events 可能還不存在

# ✅ CORRECT - 使用 call_deferred 或確保加載順序
func _ready():
    call_deferred("_connect_signals")

func _connect_signals():
    Events.something.connect(...)
```


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)