Godot Engine 最新版官方文档（简体中文完整翻译 精简梳理）

Godot Engine 最新版官方文档（简体中文完整翻译 & 精简梳理）

该页面是Godot 引擎最新版本官方英文文档，下文按原文结构逐板块翻译、整理核心内容：

一、开篇与总览

1. 介绍与前置内容

• 简介：入门前必读内容、Godot 引擎整体介绍、文档目录结构、本文档说明、引擎完整功能列表、支持平台
• 编辑器核心模块：编辑器、渲染系统、2D 图形 / 工具 / 物理、3D 图形 / 工具 / 物理、着色器、脚本、音频、资源导入、输入系统、导航、网络、国际化、窗口与系统适配、移动端、扩展现实（AR/VR）、图形界面、动画、文件格式及其他功能

2. 运行配置要求

分为编辑器运行和导出后项目运行两大类，分别标注台式机、笔记本、手机 / 平板的最低配置与推荐配置。

3. 常见问题（FAQ）

涵盖引擎用途、使用费用、开源协议、支持平台、编程语言、GDScript 脚本介绍、各语言运行速度、3D 模型格式、第三方 SDK 支持、引擎扩展方式；系统安装（Windows/macOS/Linux）、便携版编辑器说明、引擎设计理念（精简核心功能）、多分辨率素材适配、版本选择与升级建议、渲染器选型；社区贡献、功能提报、非游戏应用开发、引擎作为库调用、底层技术选型（编译工具、不使用 STL / 异常、无 ECS 架构等）；捐赠支持、开发团队与联系方式。

4. 开源协议规范

协议定义、使用要求、协议展示（片尾协议界面、日志、附属文件、手册、协议链接）、第三方组件协议说明。

5. 版本发布规则

版本命名规则、版本支持周期、新项目版本选择、版本升级建议、跨版本兼容标准；文档更新日志：记录从 Godot 3.0 ~ 4.6 每个版本新增文档板块，包含编辑器、脚本、2D/3D、物理、渲染、移植、XR 等内容。

二、入门教程

1. 基础入门

Godot 简介、引擎能力、界面与运行逻辑、支持编程语言、前置知识；在线 GDScript 学习工具、引擎核心概念（场景、节点、场景树、信号）。

2. 编辑器上手

项目管理器、编辑器五大主界面、内置类参考手册、学习方法、社区教程；引擎设计思想：面向对象 + 组合架构、一体化套件、开源社区驱动、编辑器本身基于 Godot 制作、2D/3D 引擎相互独立。

3. 实操入门（分步教程）

1. 节点与场景：节点 / 场景概念、创建首个场景、属性编辑、运行与实例化、场景复用设计思路
2. 脚本语言：主流语言对比（GDScript、.NET/C#、C++ GDExtension）、语言选型建议
3. 首个脚本：脚本创建、基础语法、物体旋转 / 移动、输入监听
4. 信号系统：编辑器 / 代码两种信号连接方式、自定义信号
5. 制作 2D 小游戏：项目搭建、玩家 / 敌人制作、动画、碰撞、怪物生成、UI、音效、项目打包分享
6. 制作 3D 小游戏：场景搭建、玩家控制、怪物 AI、跳跃 / 踩踏物理、计分、重玩、动画、音乐等完整流程

三、开发最佳实践与排错

1. 开发规范与技巧

面向对象写法、脚本运行机制、场景架构设计、节点树选型、场景与脚本取舍、匿名 / 自定义类型、性能对比；自动加载节点使用场景、功能与数据共享方案、避免滥用节点的技巧；引擎接口调用、对象引用、生命周期函数（_process/_physics_process/_ready等）区别；数据类型选型（数组 / 字典 / 对象、动画组件对比）、资源加载策略、大型场景搭建方案、项目目录规范。

2. 版本控制

版本控制插件、官方 Git 插件、需忽略的文件、Windows 下 Git 使用、Git 大文件管理（Git LFS）及问题排查。

3. 编辑器常见故障排查

编辑器高占用、高刷显示器闪烁、启动缓慢、窗口异常图标 / 文字、休眠后花屏 / 卡死；编辑器运行正常但导出项目文件加载失败、项目频繁崩溃等问题解决方案。

四、编辑器全功能详解

1. 基础功能

项目管理器、项目创建 / 导入 / 模板下载、标签管理、恢复模式；检查器面板、项目设置（常规设置、手动编辑配置文件、高级设置）。

2. 各类编辑面板

脚本编辑器、2D/3D 编辑器、文本编辑器、输出面板、调试器、文件浏览器、场景树、动画轨道、瓦片地图、网格地图等专用编辑器。

3. 界面自定义

面板拖拽缩放、独立窗口拆分、布局保存、编辑器个性化设置；游戏内嵌运行、XR 编辑器、安卓端编辑器、网页版编辑器（浏览器兼容、限制、项目编辑）。

4. 命令行工具

命令行参数、项目 / 编辑器 / 游戏启动、调试、导出、外部编辑器联动、官方插件、LSP 调试协议、编辑器功能配置文件。

5. 版本迁移指南

1. Godot 3 → Godot 4：升级利弊、前置准备、升级工具使用、节点 / 脚本 / 着色器 / 资源兼容修复、配置迁移
2. 小版本迭代（4.0~4.6）：每个子版本的破坏性变更、功能调整、默认参数改动，覆盖核心模块、动画、界面、物理、渲染、XR、安卓平台等。

五、2D 开发模块

1. 2D 基础：工作区、坐标系、视口、Node2D/Control 节点、3D 内容嵌入 2D、图层与画布变换、自定义输入事件
2. 光影与网格：2D 光源（点光源 / 方向光）、阴影、法线贴图、精灵转网格、像素绘制优化
3. 动画系统：逐图动画、精灵图集动画、多类动画组件用法
4. 粒子系统：粒子参数、材质、生成规则、自定义粒子效果
5. 画质优化：抗锯齿（MSAA 等）、自定义图形绘制、动态线条 / 形状绘制
6. 视差滚动：视差原理、滚动参数、无限循环、分屏预览
7. 物理与移动：八方移动、跟随鼠标、点击移动等多种移动方案
8. 瓦片地图：瓦片集 (TileSet)、瓦片层 (TileMapLayer) 制作、拼接、碰撞 / 导航配置、随机绘制、缺损瓦片处理

六、3D 开发模块

1. 3D 基础：工作区、坐标系、视角操控、Blender 快捷键、Node3D 节点、3D 资源类型、2D 内容嵌入 3D、相机与环境光
2. 坐标变换：欧拉角缺陷、变换矩阵、四元数、坐标插值、精度问题处理
3. 程序化几何：ArrayMesh、网格工具、即时几何体、各类建模工具选型
4. 3D 文字：Label3D、TextMesh、投影 UI 三种文字方案的优劣对比
5. 渲染与材质：渲染限制、标准材质 / ORM 材质全参数、透明、自发光、法线、阴影、公告牌等配置
6. 光源与特效：各类 3D 光源、阴影图集、贴花 (Decal)、物理光照 / 相机参数、体积雾
7. 粒子系统：3D 粒子、子粒子、轨迹、湍流、引力、碰撞、复杂发射形态
8. 画质与性能：HDR 高动态光照、全局光照方案、多种抗锯齿技术（TAA/FSR2/FXAA 等）及选型
9. 性能优化：多网格实例 (MultiMesh)、细节层级 (LOD/HLOD)、遮挡剔除、分辨率缩放、可变着色率
10. 原型工具：CSG 组合几何体、网格地图 (GridMap)、第三人称弹簧臂相机

七、动画、音视频与资源管线

1. 动画系统

关键帧动画、动画库、轨道类型、洋葱皮视图、动画标记；剪影动画、骨架、IK 反向运动学、2D 骨骼变形、动画树 (AnimationTree)、根运动、代码控制动画。

2. 视频与录屏

视频播放（格式、3D 曲面播放、循环、编码优化）、色度键抠像；引擎录屏功能、输出格式、高清渲染、视频格式转换、剪辑、帧率调整、动态模糊。

3. 资源导入管线

通用导入规则、参数修改、批量重导入、文件夹忽略；图片资源：格式、纹理压缩、Mipmap、法线图、SVG 导入、高清贴图优化；音频资源：格式、采样率、单声道、循环、节拍、音质与体积平衡；翻译资源：多语言文件导入；3D 模型：主流格式 (glTF/FBX/OBJ 等)、Blender 导出配置、碰撞 / 导航 / 动画批量设置、骨架重定向、3D 场景导出。

4. 音频系统

音频总线、音量分贝、音效插件（混响 / 延迟 / 均衡 / 失真等）、音频流、3D 空间音效、多普勒效应；音画同步、麦克风录音、语音合成、常见问题与最佳实践。

八、项目导出、IO 与国际化

1. 项目导出

导出用途、PC / 移动端导出菜单、导出模板、资源配置、命令行导出；PCK/ZIP 资源包、补丁包、模组制作、安全与版权说明；分平台导出教程：Windows、Linux、macOS、Android、iOS、visionOS、网页端（PWA）；图标修改、代码签名、安卓 Gradle 编译、一键部署、专用服务器导出。

2. 文件与数据读写

资源异步加载、路径规则（项目目录res://、用户数据user://）、日志、绝对路径转换；游戏存档、序列化（JSON / 二进制）、各类文件（图片 / 音视频 / 模型 / 字体）读写、二进制序列化协议。

3. 国际化与多语言

翻译配置、文本占位符、复数规则、双向文本、数字 / 图标本地化；CSV/PO 翻译文件使用、伪本地化测试、语言代码对照表。

九、输入、数学、导航、网络

1. 输入系统

输入事件、输入映射、键盘 / 鼠标 / 触摸 / 手柄 / 摇杆适配、按键防抖、震动、传感器（陀螺仪 / 加速度计）、退出事件处理。

2. 数学工具

向量运算、平面、矩阵、坐标变换、插值、贝塞尔曲线、随机数、噪声、加密随机数。

3. 导航寻路

2D/3D 导航服务器、导航网格烘焙、导航区域 / 代理 / 障碍物 / 链接、寻路 / 跟随 / 避障、性能优化与排错。

4. 网络功能

多人联机（高低层 API）、房间系统、远程调用、专用服务器、安全设计；HTTP 请求、TLS 证书、WebSocket、WebRTC 实时通信、简易服务端 / 客户端示例。

十、性能优化与物理系统

1. 性能优化

通用优化思路、性能分析工具、引擎服务调用；CPU 优化：缓存、多线程、脚本效率；GPU 优化：绘制批次、着色器、透明渲染、多平台适配、MultiMesh、着色器预编译；3D 场景优化（剔除、LOD、光照烘焙、动画）、大场景海量实体渲染方案。

2. 物理系统

物理基础、碰撞体、碰撞形状、物理层与掩码；各类物理节点（Area2D、刚体、角色体）、Jolt 物理引擎对比、关节、射线检测；布娃娃系统、软体 3D、超大世界坐标、物理插值；物理常见问题：高速穿透、堆叠抖动、缩放碰撞失效、载具不稳等故障排查。

十一、平台适配、插件与扩展

1. 各平台专属功能

Linux（Wayland/X11）、Android（引擎库、插件、内购、崩溃调试）、iOS 插件、网页端（JS 交互、浏览器接口）。

2. 插件开发

编辑器插件、导入插件、3D 手柄 gizmo 插件、检视面板插件、可视化着色器插件；@tool工具脚本、编辑器临时脚本、场景实例化。

3. 渲染系统

渲染器选型（正向 +/ 移动端 / 兼容渲染器）、渲染驱动（Vulkan/Direct3D/Metal/OpenGL）、视口、多分辨率适配；画面卡顿 / 输入延迟排查、合成器、HDR 高动态输出、色调映射。

十二、脚本编程

1. GDScript

语法参考、数据类型、运算符、类、导出属性、属性读写器、内存管理、信号、静态类型、代码规范、格式化字符串、注解。

2. C# / .NET

C# 脚本入门、与 GDScript 差异、NuGet 包、代码诊断报错、API 使用、编码规范。

3. C++ (godot-cpp / GDExtension)

C++ 扩展模块、编译流程、类与属性 / 信号绑定、第三方库调用。

十三、着色器系统

着色器分类、着色语言语法、内置函数、预处理器；2D 画布着色器、3D 空间着色器、粒子 / 天空 / 雾着色器；自定义着色器案例、可视化着色器编辑器、计算着色器、屏幕纹理读取；GLSL 转 Godot 着色器教程、着色器编码规范、视口纹理复用、后处理特效。

十四、UI 界面与应用开发

UI 基础组件、容器布局、锚点、自定义控件、界面主题 / 皮肤、字体系统；富文本标签 BBCode、图文特效；非游戏类应用开发、单元测试、单文件程序、便携版、安装包制作。

十五、XR（扩展现实）

VR/AR 术语、OpenXR 配置、安卓 XR 部署、会话状态、透视模式、动作映射、空间定位、手部 / 身体追踪、空间锚点、平面 / 标记追踪、XR 工具集。

十六、引擎底层、编译与开发

1. 引擎架构

整体架构、核心类型、Variant 变体、对象生命周期、资源管理、2D/3D 渲染底层、坐标系、单元测试。

2. 引擎扩展

C++ 原生模块、GDExtension 扩展、自定义资源格式、自定义音频流、自定义平台移植。

3. 源码编译

编译工具（SCons/CMake）、多平台源码编译（Windows/Linux/macOS/ 安卓 /iOS/ 网页）、导出模板编译、体积优化、内存检测工具。

4. 编辑器开发

编辑器源码结构、图标制作、界面开发、调试。

十七、文件格式与资源商店

引擎文件格式（TSCN 场景文件）、社区资源商店：资源上传、检索、付费资源规则、资源提交规范、社区交流渠道。

十八、类参考手册

文档最后为全引擎节点、类、方法、信号、枚举的详细 API 参考，包含所有内置组件的属性、用法、示例与说明。