godot-performance-optimization

性能优化中绝对不要做的事

• 绝对不要在分析性能之前就进行优化——没有数据就说“我觉得物理运算很慢”？这是过早优化。务必使用 Debug → Profiler（F3）找出实际瓶颈 [20]。
• 绝对不要在发行版本中使用 print()——每帧调用 print() = 文件 I/O 瓶颈 + 日志刷屏。使用 @warning_ignore 或条件判断 if OS.is_debug_build(): [21]。
• 绝对不要忽略屏幕外实体的 VisibleOnScreenNotifier2D——敌人在屏幕外仍处理逻辑 = 浪费 CPU。在 screen_exited 时禁用 set_process(false) [22]。
• 绝对不要在热点循环中实例化节点——for i in 1000: var bullet = Bullet.new() = 1000 次分配。使用对象池，复用实例 [23]。
• 绝对不要在 _process() 中使用 get_node()——每秒调用 get_node("Player") 60 次 = 反复遍历场景树。通过 @onready var player := $Player 缓存 [24]。
• 绝对不要忘记批处理绘制调用——1000 个不同的精灵 = 1000 次绘制调用。使用 TextureAtlas（精灵表）+ MultiMesh 进行实例化渲染 [25]。
• 绝对不要因耗时操作阻塞主线程——避免使用 OS.delay_msec() 或长时间同步处理数据。使用 WorkerThreadPool 保持帧率稳定。
• 绝对不要在物理查询中使用复杂碰撞形状——高多边形凸形状的解析开销很大。优先使用简化的基本形状（Circle、Rectangle、Box）。
• 绝对不要忘记断开本地 lambda 信号——连接到全局信号的匿名 lambda，如果其捕获的对象被释放，可能导致内存泄漏。
• 绝对不要在未进行显存压缩的情况下使用大型纹理——显存有限。桌面平台（DirectX/Vulkan）使用 S3TC/BPTC，移动平台使用 ETC2。注意：像素艺术应禁用压缩，以避免出现瑕疵 [13]。
• 绝对不要在物理步骤中修改场景树——在 _inter_ray 或 _physics_process 期间添加/移除节点可能会锁定物理服务器。使用 call_deferred。
• 绝对不要在 Compatibility 渲染器中跳过着色器预热——与 Forward+ 不同，OpenGL 不支持 Ubershaders。在加载画面后，让每个网格/VFX 在摄像机前预实例化 1 帧，以避免卡顿 [21]。

---

Debug → Profiler（F3）

标签页：

• Time：函数调用耗时
• Memory：RAM 使用量
• Network：RPC、带宽
• Physics：碰撞检测

Profiler 标签页决策树

首先打开 Debug → Profiler。必须只加载与热点标签页/症状对应的脚本。

单次卡顿时，不要加载所有性能脚本。

Profiler / 症状	可能原因	脚本
Time — 同一脚本持续占用资源	分配 / get_node / 处理	object_pool_system.gd，缓存 @onready；custom_monitor_profiler.gd
Time — 屏幕外 AI/VFX	不可见时仍在处理	必须 manual_culling_logic.gd
Memory — 随时间持续增长	泄漏 / 唯一资源	shared_resource_strategy.gd；配合使用孤儿调试工具
Physics — 碰撞尖峰	查询/节点 RayCast 过于频繁	必须 low_level_physics_query.gd
GPU / 绘制调用	不同的精灵/网格	必须 multimesh_optimizer.gd / multimesh_foliage_manager.gd / texture_array_batching.gd
SceneTree 开销随规模增长	Canvas/网格项过多	必须 rendering_server_direct.gd
主线程卡顿（生成/解析）	同步执行耗时任务	必须 worker_thread_pool_manager.gd
群体寻路尖峰	导航 Agent 在同一帧运行	navigation_agent_optimization.gd
自定义游戏指标	缺少监视器	custom_performance_monitor.gd

可用脚本

object_pool_system.gd

热路径生成/销毁的强制要求——请复用，不要内联编写 Array 弹出池。

manual_culling_logic.gd

由 VisibilityNotifier 驱动，禁用屏幕外高 CPU 开销实体的处理。

rendering_server_direct.gd

当 SceneTree 开销占主导时，使用 RenderingServer 画布/网格路径。

low_level_physics_query.gd

直接进行空间状态查询，而非使用数百个 RayCast 节点。

worker_thread_pool_manager.gd

使用 WorkerThreadPool 分担繁重任务。

multimesh_optimizer.gd / multimesh_foliage_manager.gd

对密集网格/植被使用硬件实例化。

texture_array_batching.gd

使用 Texture2DArray 批处理以减少材质切换。

shared_resource_strategy.gd

权衡共享资源与场景本地资源的内存开销。

navigation_agent_optimization.gd

为人群错开路径更新。

custom_monitor_profiler.gd / custom_performance_monitor.gd

使用 Performance.get_monitor / 自定义监视器检测游戏特有的性能峰值。

专家提示（保持简短）

• Compatibility 渲染器：预热管线（使用隐藏摄像机和独特网格/材质，持续一帧）。Forward+/Mobile：Ubershader 仍需检测首次实例化。
• VRAM：桌面端使用 S3TC/BPTC，移动端使用 ETC2；像素艺术请跳过压缩。
• AStar/路径预算应放在 navigation_agent_optimization.gd 中——不要把频繁抖动的队列代码片段当作推荐方案粘贴进来。

深入探讨（按需）

• 路径分时处理、Compatibility 着色器预热、VRAM 编解码器表 → profiler-budgets-and-prewarm.md

参考资料

渐进式披露：仅在研究特定 API 时打开官方文档链接；仅在需要转至相关领域时加载相关技能——不要预先加载整个技能网络。

官方文档

• 通用优化 — 以性能分析器为先的工作流：在更改代码前测量时间、内存和物理性能。
• CPU 优化 — 进程开销、节点查找、内存分配，以及热路径模式为何会主导帧耗时。
• GPU 优化 — 绘制调用、过度绘制和可降低渲染开销的显存压缩选项。
• 使用 MultiMesh — 对数千个网格进行硬件实例化，以及空间分割为何能恢复剔除效果。
• 使用 Servers 和 Resources — 当 SceneTree 开销成为瓶颈时，使用 RenderingServer/PhysicsServer 直接 API。
• 使用多线程 — WorkerThreadPool 任务模型，可将繁重工作移出主线程。
• 线程安全 API — 哪些引擎 API 可在工作线程任务中安全调用，哪些调用仅限 SceneTree。
• 管线编译 — 着色器/管线卡顿的成因，以及针对不同渲染器的预热策略。
• 优化 3D 性能 — 3D 场景中的 LOD、剔除距离和网格复杂度预算。
• 遮挡剔除 — 当仅靠视锥剔除不足以满足需求时，OccluderInstance3D 的利弊。
• 性能 — 内置监视器与自定义指标，可用于构建针对游戏的瓶颈仪表板。
• 优化导航性能 — 大型人群中的 Agent 更新预算和烘焙开销。

相关技能

前置要求

• godot-project-foundations — 场景树、资源和导入基础知识；掌握这些内容后，性能分析或对象池模式才有意义。
• godot-gdscript-mastery — 类型化热路径、可调用对象和 @onready 缓存，确保优化脚本正确运行。
• godot-resource-data-patterns — 共享资源与场景局部资源的所有权模式，会影响内存占用和唯一实例之间的权衡。

补充

• godot-2d-physics — 碰撞层、查询和物体数量，这些都会导致 Physics 分析器出现峰值。
• godot-physics-3d — 优化模拟密集型场景时的 3D 形状开销和 RigidBody 预算。
• godot-raycasting-queries — 可替代大量 RayCast 节点堆叠的直接空间状态查询模式。
• godot-shaders-basics — 可减少 GPU 状态切换的材质／着色器复杂度和 Texture2DArray 批处理。
• godot-scene-management — 可防止流式加载期间出现卡顿峰值的线程加载和场景打包。
• godot-navigation-pathfinding — 与错峰 AI 更新配合使用的 Agent 路径预算和异步烘焙。
• godot-3d-world-building — 决定绘制调用预算上限的 GridMap／LOD／遮挡层级布局。

下游／使用方

• godot-adapt-desktop-to-mobile — 可在性能较弱的 GPU 上应用这些预算的分辨率／着色器回退和电池模式。
• godot-export-builds — 导出预设和渲染器选择，其中压缩和 Compatibility 预热十分重要。
• godot-genre-open-world — 大规模使用 MultiMesh、剔除和线程池模式的区块流式加载与 HLOD 系统。

主模块

• godot-master — 用于跨技能发现的库路由器和镜像模块入口。