name: godot-master description: “Godot 4.x专业游戏与应用开发的整合专家库。通过架构工作流程、反模式目录、性能预算和服务器API模式，协调86个专门蓝图。使用场景：(1) 启动新Godot项目，(2) 设计游戏或应用架构，(3) 构建实体/组件系统，(4) 调试性能或物理问题，(5) 选择2D/3D方法，(6) 实现多人游戏，(7) 优化绘制调用或脚本时间，(8) 跨平台移植。所有Godot开发任务的主要入口点。”

Godot大师：首席架构师知识中心

每个部分都通过关注知识差异来赚取代币——即Claude已知知识与从实际产品中获得的资深Godot工程师知识之间的差距。

🧠 第一部分：专家思维框架

“谁拥有什么？” —— 架构理智检查

在编写任何系统之前，为每个状态片段回答这三个问题：

谁拥有数据？（StatsComponent拥有健康值，而不是CombatSystem）
谁被允许更改它？（只有所有者通过像apply_damage()这样的公共方法）
谁需要知道它已更改？（任何监听health_changed信号的人）

如果你不能为每个状态变量回答所有三个问题，你的架构就有耦合问题。这不是OOP封装——这是Godot特定的，因为信号系统是执行机制，而不是访问修饰符。

Godot “分层蛋糕”

将每个功能组织成四层。信号向上传播，绝不向下：

┌──────────────────────────────┐
│  表示层（UI / VFX）         │  ← 监听信号，绝不拥有数据
├──────────────────────────────┤
│  逻辑层（状态机）           │  ← 协调转换，查询数据
├──────────────────────────────┤
│  数据层（资源 / .tres）     │  ← 单一真相源，可序列化
├──────────────────────────────┤
│  基础设施层（自动加载）      │  ← 信号总线，保存管理器，音频总线
└──────────────────────────────┘

关键规则：表示层绝不能直接修改数据层。基础设施层仅通过信号通信。如果一个Label节点调用player.health -= 1，架构就坏了。

信号总线分层架构

全局总线（自动加载）：仅用于生命周期事件（match_started，player_died，settings_changed）。调试蔓延是成本——限制事件到<15个。
作用域功能总线：每个功能文件夹有自己的总线（例如，CombatBus仅用于战斗节点）。这是可扩展的折衷方案。
直接信号：单个场景内的父-子通信。绝不跨场景边界。

🧭 第二部分：架构决策框架

主决策矩阵

场景	策略	强制技能链	权衡
快速原型	事件驱动单例	阅读：基础 → 自动加载。不要加载类型或平台参考。	快速启动，面条代码风险
复杂RPG	组件驱动	阅读：组合 → 状态 → RPG统计。不要加载多人游戏或平台参考。	重设置，无限扩展
大规模开放世界	资源流	阅读：开放世界 → 保存/加载。同时加载性能。	复杂I/O，超过10K单位的浮点精度抖动
服务器认证多人	确定性	阅读：服务器架构 → 多人游戏。不要加载单人游戏类型参考。	高延迟，反作弊安全
移动/网页移植	自适应响应	阅读：UI容器 → 适应桌面→移动 → 平台移动。	UI复杂性，广泛覆盖
应用 / 工具	应用组合	阅读：应用组合 → 主题。不要加载游戏特定参考。	不同于游戏的范式
浪漫 / 约会模拟	情感经济	阅读：浪漫 → 对话 → UI富文本。	高UI/叙事密度
秘密 / 彩蛋	故意混淆	阅读：秘密 → 持久性。	社区参与，调试风险
收集任务	搜寻逻辑	阅读：收集 → Marker3D放置。	玩家留存，探索驱动力
季节性事件	运行时注入	阅读：复活节主题 → 材质交换。	快速品牌化，无资源污染
魂系死亡率	风险奖励复活	阅读：复活/尸体跑 → 物理3D。	高紧张感，玩家挫败风险

"何时不使用节点"决策

最具影响力的专家独有决策之一。Godot文档明确说"避免对所有事情使用节点"：

类型	何时使用	成本	专家用例
`Object`	自定义数据结构，手动内存管理	最轻。必须手动调用`.free()`。	自定义空间哈希映射，ECS类数据存储
`RefCounted`	瞬态数据包，自动删除的逻辑对象	当没有剩余引用时自动删除。	`DamageRequest`，`PathQuery`，`AbilityEffect` — 不需要场景树的逻辑包
`Resource`	可序列化数据，支持检查器	比RefCounted稍重。处理`.tres` I/O。	`ItemData`，`EnemyStats`，`DialogueLine` — 任何设计者应在检查器中编辑的数据
`Node`	需要`_process`/`_physics_process`，需要存在于场景树中	最重——每个节点的SceneTree开销。	仅用于需要每帧更新或空间变换的实体

专家模式：对所有逻辑包和数据容器使用RefCounted子类。为必须存在于空间树中的事物保留Node。这为复杂系统减半场景树开销。

🔧 第三部分：核心工作流程

工作流程1：专业脚手架

从空项目到生产就绪容器。

强制——阅读整个文件：基础

按功能组织（/features/player/，/features/combat/），而不是按类类型。一个player/文件夹包含玩家的场景、脚本、资源和测试。
阅读：信号架构 — 创建GlobalSignalBus自动加载，事件<15个。
阅读：GDScript精通 — 在项目设置 → GDScript → 调试中启用untyped_declaration警告。
应用**项目模板** 用于基础.gitignore、导出预设和输入映射。
使用**MCP场景构建器** 如果可用，以程序化生成场景层次结构。 不要加载 战斗、多人游戏、类型或平台参考在脚手架期间。

工作流程2：实体编排

构建模块化、可测试的角色。

强制链——阅读所有：组合 → 状态机 → CharacterBody2D 或物理3D → 动画树 不要加载 UI、音频或保存/加载参考用于实体工作。

状态机查询InputComponent，绝不直接处理输入。这允许AI/玩家交换零重构。
状态机仅处理转换。逻辑属于组件。MoveState告诉MoveComponent行动，而不是反过来。
每个实体必须通过F6测试：按“运行当前场景”（F6）必须工作而不崩溃。如果崩溃，你的实体有场景外部依赖。

工作流程3：数据驱动系统

通过资源连接战斗、库存、统计。

强制链——阅读所有：资源模式 → RPG统计 → 战斗 → 库存

创建一个ItemData.gd扩展Resource。实例化为100个.tres文件而不是100个脚本。
HUD绝不直接引用玩家。它监听信号总线上的player_health_changed。
在所有@export Resource变量上启用“局部到场景”，或在_ready()中调用resource.duplicate()。不这样做是第8部分的Bug #1。

工作流程4：持久性管道

强制：自动加载架构 → 保存/加载 → 场景管理

使用字典映射序列化。旧保存文件在添加新字段时绝不能损坏——使用.get("key", default_value)。
对于程序化世界：保存种子加上修改的增量列表，而不是整个地图。一个100MB的世界变成50KB的保存。

工作流程5：性能优化

强制：调试/性能分析 → 性能优化

诊断优先方法（绝不盲目优化）：

高脚本时间 → 使用内置性能分析器分析。检查是否在数百个节点上调用_process。移动到单管理器模式或服务器API（见第6部分）。
高绘制调用 → 对重复几何使用MultiMeshInstance。用ORM纹理批处理材质。
物理卡顿 → 简化碰撞到原始形状。加载2D物理或3D物理。检查是否使用_process代替_physics_process进行移动。
VRAM过用 → 将纹理切换到VRAM压缩（桌面用BPTC/S3TC，移动用ETC2）。绝不发布原始PNG。
间歇帧尖峰 → 通常是GC传递、同步load()或NavigationServer重新计算。使用ResourceLoader.load_threaded_request()。

工作流程6：跨平台适应

强制：输入处理 → 适应桌面→移动 → 平台移动 也阅读：平台桌面、平台网页、平台控制台、平台VR 根据需要。

使用一个InputManager自动加载，将所有输入类型转换为标准化操作。绝不直接读取Input.is_key_pressed()——它阻止控制器和触摸支持。
移动触摸目标：最小44px物理大小。使用MarginContainer和Safe Area逻辑用于缺口/切割设备。
网页导出：Godot的AudioServer在首次播放前需要用户交互（浏览器策略）。用“点击开始”屏幕处理。

工作流程7：程序化生成

强制：程序化生成 → Tilemap精通或 3D世界构建 → 导航

始终使用具有固定seed的FastNoiseLite资源进行确定性生成。
绝不主线程上烘焙NavMesh。使用NavigationServer3D.parse_source_geometry_data() + NavigationServer3D.bake_from_source_geometry_data_async()。
对于无限世界：区块加载必须在后台线程使用WorkerThreadPool。在树外构建场景区块，然后在主线程上add_child.call_deferred()。

工作流程8：多人游戏架构

强制——阅读所有：多人游戏网络 → 服务器架构 → 适应单→多 不要加载 单人游戏类型蓝图。

客户端发送输入，服务器计算结果。客户端绝不决定伤害、位置增量或库存变化。
使用客户端预测与服务器协调：本地预测，从服务器快照纠正。隐藏高达~150ms的延迟。
MultiplayerSpawner在Godot 4中处理复制。每个场景配置它，而不是全局。

工作流程9：高级UI/UX

强制：UI主题 → UI容器 → 补间 → 富文本

绝不在检查器中覆盖颜色。创建一个.theme资源作为全局皮肤的单真相源。
每个交互元素应有微动画：按钮上的Tween缩放脉冲，伤害数字上的RichTextEffect，面板转换上的AnimationPlayer。
使用Control.FOCUS_MODE_ALL并测试完整的键盘/游戏手柄导航。不可访问的UI阻止控制台认证。

工作流程10：图形与氛围

强制：3D照明 → 3D材质 → 着色器基础 → 粒子

使用GPUParticles3D用于环境效果（雨、雾、火）。仅当脚本必须读取/写入单个粒子位置时使用CPUParticles。
始终手动设置GPU粒子的visibility_aabb。自动计算的AABB经常错误，导致发射器离屏时粒子消失。
对于风格化外观：使用带有screen_texture的CanvasItem着色器用于2D后处理。在3D中，使用带有自定义Environment资源的WorldEnvironment。
ReflectionProbe vs VoxelGI vs SDFGI：探针便宜/静态，VoxelGI中等/烘焙，SDFGI昂贵/动态。根据你的平台预算选择（见第5部分）。

🚫 第四部分：专家绝不列表

每个规则包括非显而易见的原因——只有发货经验教的东西。

绝不使用get_tree().root.get_node("...") — 绝对路径在ANY祖先重命名或重新父化时中断。使用%UniqueNames、@export NodePath或基于信号的发现。
绝不使用load()在循环或_process中 — 同步磁盘读取阻塞整个主线程。对小资产使用脚本顶部的preload()，对大资产使用ResourceLoader.load_threaded_request()。
绝不queue_free()当外部引用存在时 — 持有引用的父节点或数组将获得“已删除对象”错误。在_exit_tree()中清理引用，并在释放前设置为null。
绝不将游戏逻辑放入_draw() — _draw()在渲染线程上调用。突变游戏状态导致与_physics_process的竞争条件。
绝不使用Area2D用于1000+重叠对象 — 每个重叠检查有O(n²)宽相成本。对弹幕模式使用ShapeCast2D、PhysicsDirectSpaceState2D.intersect_shape()或服务器API。
绝不变更外部状态从组件 — 如果HealthComponent调用$HUD.update_bar()，删除HUD会崩溃游戏。组件发出信号；监听器决定如何响应。
绝不使用await在_physics_process中 — await产生执行，意味着物理步骤跳过帧。将异步操作移动到由信号触发的单独方法。
绝不使用String键在热路径字典查找中 — 字符串哈希是O(n)。对O(1)指针比较使用StringName（&"key"），或整数枚举。
绝不存储Callable引用到已释放对象 — 静默崩溃或抛出错误。在_exit_tree()中断开信号或使用CONNECT_ONE_SHOT。
绝不使用_process用于1000+实体 — 每个_process调用有每个节点的SceneTree开销。使用单个Manager._process迭代数据结构数组（数据导向模式），或直接使用服务器API。
绝不使用Tween在可能被释放的节点上 — 如果节点在Tween运行时queue_free()，它会错误。在_exit_tree()中杀死补间，或绑定到SceneTree：get_tree().create_tween()。
绝不请求数据FROM RenderingServer或PhysicsServer在_process中 — 这些服务器异步运行。调用getter函数强制同步停滞，杀死性能。API故意设计为在热路径中只写。
绝不使用call_deferred()作为初始化顺序错误的创可贴 — 它掩盖了架构问题（依赖树顺序）。用显式初始化信号或@onready修复实际依赖。
绝不创建循环信号连接 — 节点A连接到B，B连接到A。这在第一次发出时创建无限循环。使用调解者模式（信号总线）打破循环。
绝不让继承超过3级 — 超过3级，调试super()链是噩梦。使用组合（Node子节点）来添加行为。

📊 第五部分：性能预算（具体数字）

指标	移动目标	桌面目标	专家笔记
绘制调用	< 100 (2D), < 200 (3D)	< 500	对树叶/碎片使用`MultiMeshInstance`
三角形计数	< 100K可见	< 1M可见	超过500K必须使用LOD系统
纹理VRAM	< 512MB	< 2GB	VRAM压缩：ETC2（移动），BPTC（桌面）
脚本时间	< 4ms每帧	< 8ms每帧	将热循环移动到服务器API
物理体	< 200活跃	< 1000活跃	对大规模模拟使用`PhysicsServer`直接API
粒子	< 2000总计	< 10000总计	GPU粒子，手动设置`visibility_aabb`
音频总线	< 8同时	< 32同时	使用音频系统总线路由
保存文件大小	< 1MB	< 50MB	种子 + 增量模式用于程序化世界
场景加载时间	< 500ms	< 2s	`ResourceLoader.load_threaded_request()`

⚙️ 第六部分：服务器API — 专家性能逃生口

这是大多数Godot开发者从未学习的知识。当场景树成为瓶颈时，使用Godot的低级服务器API完全绕过它。

何时下降到服务器API

10K+渲染实例（精灵、网格）：使用RenderingServer与RID而不是Sprite2D/MeshInstance3D节点。
弹幕 / 粒子系统与脚本交互：使用PhysicsServer2D体创建而不是Area2D节点。
大规模物理模拟：直接使用PhysicsServer3D用于布娃娃场、碎片或流体类模拟。

RID模式（专家）

服务器API通过RID（资源ID）通信——服务器端对象的不透明句柄。关键规则：

# 创建服务器端画布项（无节点开销）
var ci_rid := RenderingServer.canvas_item_create()
RenderingServer.canvas_item_set_parent(ci_rid, get_canvas_item())

# 关键：保持资源引用活跃。RID不算作引用。
# 如果Texture资源被GC，RID会静默无效。
var texture: Texture2D = preload("res://sprite.png")
RenderingServer.canvas_item_add_texture_rect(ci_rid, Rect2(-texture.get_size() / 2, texture.get_size()), texture)

与服务器的线程

场景树不是线程安全的。但服务器API（RenderingServer，PhysicsServer）在项目设置中启用时是线程安全的。
你可以在工作线程上构建场景块（实例化 + add_child），但必须使用add_child.call_deferred()将它们附加到活动树。
GDScript字典/数组：跨线程读取和写入是安全的，但调整大小（追加、删除、调整大小）需要Mutex。
绝不从多个线程同时加载相同的Resource——使用一个加载线程。

🧩 第七部分：专家代码模式

组件注册表

class_name Entity extends CharacterBody2D

var _components: Dictionary = {}

func _ready() -> void:
    for child in get_children():
        if child.has_method("get_component_name"):
            _components[child.get_component_name()] = child

func get_component(component_name: StringName) -> Node:
    return _components.get(component_name)

死实例安全信号处理器

func _on_damage_dealt(target: Node, amount: int) -> void:
    if not is_instance_valid(target): return
    if target.is_queued_for_deletion(): return
    target.get_component(&"health").apply_damage(amount)

异步资源加载器

func _load_level_async(path: String) -> void:
    ResourceLoader.load_threaded_request(path)
    while ResourceLoader.load_threaded_get_status(path) == ResourceLoader.THREAD_LOAD_IN_PROGRESS:
        await get_tree().process_frame
    var scene: PackedScene = ResourceLoader.load_threaded_get(path)
    add_child(scene.instantiate())

状态机转换守卫

func can_transition_to(new_state: StringName) -> bool:
    match name:
        &"Dead": return false  # 终端状态
        &"Stunned": return new_state == &"Idle"  # 只能恢复到Idle
        _: return true

线程安全区块加载器（服务器API模式）

func _load_chunk_threaded(chunk_pos: Vector2i) -> void:
    # 在活动树外构建场景块（线程安全）
    var chunk := _generate_chunk(chunk_pos)
    # 仅从主线程附加到活动树
    _world_root.add_child.call_deferred(chunk)

🔥 第八部分：Godot 4.x陷阱（仅限老兵）

@export资源默认共享：多个场景实例都共享相同的Resource。在_ready()中使用resource.duplicate()或启用“局部到场景”复选框。这是新手在Godot 4中报告最多的Bug #1。
信号语法静默失败：connect("signal_name", target, "method")（Godot 3语法）编译但Godot 4中什么也不做。必须使用signal_name.connect(callable)。
Tween不再是节点：通过create_tween()创建，绑定到创建节点的生命周期。如果那个节点被释放，Tween死亡。对持久补间使用get_tree().create_tween()。
PhysicsBody层与掩码：collision_layer = “我是什么”。collision_mask = “我扫描什么”。将两者设置为相同值导致自碰撞或错过检测。
StringName vs String在热路径中：StringName（&"key"）使用指针比较（O(1)）。String使用字符比较（O(n)）。始终在_process中对字典键使用StringName。
@onready时机：在_init()之后但在_ready()期间运行。如果你需要构造器时间设置，使用_init()。如果你需要树访问，使用@onready或_ready()。混合它们导致空值。
服务器查询停滞：在_process中调用RenderingServer或PhysicsServer getter函数强制同步管道刷新。这些服务器异步运行——从它们请求数据停滞整个管道直到服务器赶上。
move_and_slide() API更改：返回bool（是否发生碰撞）。速度现在是属性，不是参数。在调用move_and_slide()之前velocity = dir * speed。

📂 第九部分：模块目录（86个蓝图）

[!重要] 仅加载当前工作流程所需的模块。使用第2部分的决策矩阵来确定要遵循的链。

🐛 第十部分：专家诊断模式

“隐形节点”Bug

症状：节点存在于树中但不渲染。 专家诊断链：visible属性 → z_index → 父CanvasLayer错误层 → modulate.a == 0 → 在相机near剪辑后面（3D） → SubViewport.render_target_update_mode未设置 → CanvasItem不在任何CanvasLayer中（渲染在所有东西后面）。

“输入被吞噬”Bug

症状：点击或按键间歇性忽略。 专家诊断：另一个Control节点与mouse_filter = STOP重叠目标。或，模式PopupMenu消耗未处理输入。或，另一个脚本中的_unhandled_input()调用get_viewport().set_input_as_handled()。

“物理抖动”Bug

症状：角色在表面接触处振动。 专家诊断：Safe Margin太大。或，使用_process进行移动而不是_physics_process（插值不匹配）。或，碰撞形状在生成时重叠（永久推彼此分开）。

“内存泄漏”

症状：游戏期间RAM稳定增长。 专家诊断：调用queue_free()但引用保持在数组/字典中。或，信号以CONNECT_REFERENCE_COUNTED连接而没有清理。使用性能分析器“对象”选项卡查找孤儿实例。搜索没有父节点的Node实例。

“帧尖峰”

症状：平滑FPS但周期性下降。 专家诊断：GDScript GC传递。或，大资源的同步load()。或，NavigationServer重新烘焙。或，服务器API查询停滞（在_process中从RenderingServer请求数据）。使用内置性能分析器 → 寻找函数级尖峰。