读Godot4.4文档有感（长期更新）

本文参考Godot4.4中文文档中

• 关于
• 入门
• 手册
  的内容进行了总结改进，去除了个人感觉无用的部分

关于

特性列表

平台

可运行编辑器以及导出项目的：
Windows macOS Linux Android（实验） Web（实验）

可运行导出的项目：
iOS 主机

编辑器

特性：
场景树编辑器
脚本编辑器
支持VS Code、VIM 等外部文本编辑器
GDScript 调试器（支持多线程调试）
可视化（性能）分析器
性能监视工具（可自定义）
脚本热重载
场景热编辑
远程检查器
实时相机复制（移动编辑器中的相机，并在正在运行的项目中查看结果）
内置离线类参考文档

插件：
编辑器插件
使用 GDScript 来创建插件
资产库下载项目并直接导入

渲染

1. Forward+。最先进的渲染器，仅适用于桌面端。
2. Mobile。功能较少，但渲染简单场景的速度更快。适用于移动平台和桌面平台。(移动平台默认使用)
   以上渲染器使用 Vulkan、Direct3D 12 或 Metal 作为渲染驱动，使用 RenderingDevice 后端。
3. Compatibility，最低级的图形后端，在 OpenGL 3.3、OpenGL ES 3.0 和 WebGL 2.0 以上运行。(在 Web 平台上默认使用)

2D 图形

精灵、多边形和线条渲染。

• 用于绘制线和多边形的高级工具，例如 Polygon2D 和 Line2D，支持纹理。
  AnimatedSprite2D 辅助制作动画精灵。
  视差层。
• 伪 3D 支持，可在编辑器中进行预览。
  带有法线贴图和镜面反射贴图的 2D 光照。
• 2D 点光源（全向灯/聚光灯）和定向光源。
• 硬阴影或软阴影（可根据每个光源进行调整）。
• 自定义着色器可以访问一个基于 LightOccluder2D 节点的，由实时 SDF 表示的 2D 场景，它可以用于改进 2D 照明效果，包括 2D 全局光源。
  字体渲染使用位图，光栅化使用 FreeType 或多通道有符号距离场（MSDF）。
• 位图字体可以使用 BMFont 等工具导出，也可以从图像导入（仅适用于等宽字体）。
• 动态字体支持单色字体以及彩色字体（例如用于表情符号）。支持的格式有 TTF、OTF、WOFF1 和 WOFF2。
• 动态字体支持宽度和颜色可调的可选字体轮廓。
• 动态字体支持可变字体和 OpenType 功能，包括连字（ligatures）。
• 当字体文件缺少粗体和斜体样式时，动态字体支持模拟这些样式。
• 动态字体支持超采样, 以在更高的分辨率下保持字体的清晰度.
• 动态字体支持亚像素定位（subpixel positioning），使字体在小尺寸下更清晰。
• 动态字体支持 LCD 亚像素优化，使字体在小尺寸下更加清晰。
• 带符号距离场字体可以按任意分辨率缩放，而无需重新光栅化。与单色带符号距离场字体相比，利用多通道可使带符号距离场字体能够更好地缩小到较小的大小。
  基于 GPU 的粒子，支持自定义粒子着色器。
  基于 CPU 的粒子。
  用于更好的辉光功能的可选 2D HDR 渲染。

2D 工具

TileMap 用于由 2D 图块构建的关卡设计。
2D 相机，拥有内置平滑和拖动边距。
Path2D 节点，用于代表 2D 空间中的一条路径。

• 可以在编辑器中绘制或者程序化生成。
• PathFollow2D 节点，用于使节点跟随一个 Path2D。
  2D 几何辅助类。

2D 物理

物理体：
静态物体
可动画物体
刚体
角色体
关节
区域（检测实体进入或离开）

碰撞检测：
内置形状：线条、框体、圆圈、胶囊、世界边界（无限平面）。
碰撞多边形（可以人工绘制，或者在编辑器中根据精灵生成）。

3D 图形

使用 sRGB 进行 HDR 渲染。
透视、正交以及视锥偏移摄像机。
使用 Forward+ 渲染器时，通过深度预通道来提高复杂场景中的性能，从而减少过度绘制的成本。
在 Forward+ 和 Mobile 渲染器中，支持的 GPU 上可以使用可变速率着色。

1. 基于物理的渲染（内置材质特性）：
   遵循迪士尼 PBR 模型。
   支持 Burley、Lambert、Lambert Wrap（half-Lambert）、Toon 漫反射着色模式。
   支持 Schlick-GGX、Toon 和 Disabled 镜面反射着色模式。
   使用粗糙度金属度工作流，支持 ORM 纹理。
   使用地平线镜面反射遮蔽（Filament 模型）提升材质外观。
   法线贴图。
   具有基于距离的自动细节层次的视差/浮雕贴图。
   反照率及法线贴图的细节贴图。
   次表面散射和透射率。
   支持材质粗糙度的屏幕空间折射（产生模糊折射）。
   邻近淡出（软粒子）和距离淡出。
   距离淡出可以使用透明度混合或抖动以避免穿过透明管线。
   抖动可以根据每个像素或每个对象来确定。

2. 实时光照：
   定向光（日光/月光）。每个场景最多 4 个。
   全向光。
   可调整锥角和衰减的聚光。
   镜面反射、间接光和体积雾能量可以根据每个光源进行调整。
   可调节的灯光 “大小” 用于伪造面光（也会使阴影更模糊）。
   可选的距离淡化系统（distance fade system）可以淡化远处的灯光及其阴影，从而提高性能。
   使用 Forward+ 渲染器（桌面平台默认）时，光源通过集群前向优化渲染，以减少其单独的成本。集群渲染还消除了对网格上可使用的光源数量的任何限制。
   使用 Mobile 渲染器时，每个网格资源最多可以显示 8 个全向光源和 8 个聚光灯。如果需要，可以使用烘焙光照来克服这一限制。

3. 阴影贴图：
   DirectionalLight：正交（最快）、PSSM 2 分割和 4 分割。支持分割之间的混合。
   OmniLight：双抛物面（快速）或立方映射（较慢但更精确）。支持全景形式的彩色投影纹理。
   SpotLight：单个纹理。支持彩色投影纹理。
   要缓解可见的阴影失真和阴影悬浮的情况，可以调整阴影的法线偏移量偏置以及阴影压平。
   类似 PCSS 的阴影模糊是基于光源大小和距阴影投射表面的距离。
   根据每个灯光调整阴影模糊。

4. 具有间接照明的全局光照：
   烘焙光照贴图（快速，但无法在运行时更新）。
   支持仅烘焙间接光照，或者同时烘焙直接和间接光照。可以根据每个灯光调整烘焙模式，以允许混合光照烘焙设置。
   支持使用自动和手动放置的探针照明动态物体。
   可选支持基于球谐函数的平行光和粗糙反射。
   光照贴图使用计算着色器在 GPU 上烘焙（与 CPU 光照贴图相比速度更快）。烘焙只能从编辑器执行，而不能在导出的项目中执行。
   支持使用 JNLM 进行基于 GPU 的降噪，或使用 OIDN 进行基于 CPU/GPU 的降噪。
   基于体素的 GI 探针。支持动态灯光和动态遮挡器，同时还支持反射。需要执行快速烘焙步骤，该步骤可在编辑器中或运行时（包括从导出的项目中）执行。
   为大型开放世界设计的有符号距离场 GI。支持动态光照，不支持动态遮挡器。支持反射。无需烘焙。
   以半分辨率或全分辨率进行的屏幕空间间接光照（SSIL）。完全实时并支持任何类型的自发光光源（包括贴花）。
   VoxelGI 和 SDFGI 使用延迟渲染通道，可以在半分辨率下渲染全局光照，以提高性能（同时还支持 MSAA 抗锯齿）。

5. 反射：
   基于体素的反射（使用 GI 探针时）和基于 SDF 的反射（使用符号距离场 GI 时）。基于体素的反射在透明表面上可见，而基于粗糙 SDF 的反射在透明表面上可见。
   使用 ReflectionProbe 实现较快的烘焙反射或较慢的实时反射。可以选择启用视差盒校正。
   支持材料粗糙度的屏幕空间反射。
   可以混用反射技术，以获得更高的准确性或可扩展性。
   使用 Forward+ 渲染器（桌面平台默认）时，反射探针通过集群前向优化渲染，以减少其单独的成本。集群渲染还消除了对网格上可使用的反射探针数量的任何限制。
   使用移动渲染器时，每个网格资源最多可以显示 8 个反射探针。使用兼容渲染器时，每个网格资源最多可以显示 2 个反射探针。

6. 贴花：
   支持反照率、自发光、ORM 和法线贴图。
   纹理通道平滑地叠加在底层材质之上，并支持普通/仅 ORM 贴花。
   支持法线淡化，以根据入射角度来淡化贴花。
   不依赖于实时网格生成。这意味着即使贴花每帧都在移动，也可以在复杂的蒙皮网格上使用贴花，而不会影响性能。
   支持最近邻、双线性、三线性、各向异性纹理过滤（全局设置）。
   可选的距离淡化系统（distance fade system）以淡化远处的贴花，提高性能。
   使用 Forward+ 渲染器（桌面平台默认）时，贴花通过集群前向优化渲染，以减少其单独的成本。集群渲染还消除了对网格上可使用的贴花数量的任何限制。
   使用移动渲染器时，每个网格资源最多可以显示 8 个贴花。

7. 天空:
   全景天空（使用 HDRI）。
   程序天空和基于物理的天空，用于响应场景中的定向光。
   支持可以动画化的自定义天空着色器。
   取决于所选的质量设置，用于环境光和镜面反射光的辐射图可以实时更新。

8. 雾：
   指数深度雾。
   指数高度雾。
   支持根据天空颜色自动调整雾的颜色（使用大气透视）。
   支持雾中的太阳散射。
   支持控制雾的渲染对天空的影响程度，对传统的雾和体积雾进行单独控制。
   支持使特定材质忽略雾。

9. 体积雾：
   对光影做出反应的全局体积雾。
   在使用 VoxelGI 或 SDFGI 时体积雾可以受间接光影响。
   可以放置雾体积节点以向特定区域添加雾（或从特定区域去除雾）。支持的形状包括盒状、椭圆形、圆锥体、圆柱体和基于 3D 纹理的密度图。
   每个雾体积都可以有自己的自定义着色器。
   可与传统雾一起使用。

10. 粒子：
    基于 GPU 的粒子，支持子发射器（2D + 3D）、尾迹（2D + 3D）、吸引器（仅 3D）和碰撞（2D + 3D）。
    支持 3D 粒子吸引器形状：盒状、球体和 3D 向量场。
    支持 3D 粒子碰撞形状：盒状、球体、烘焙带符号距离场和实时高度图（适用于开放世界天气效果）。
    2D 粒子碰撞是使用基于场景中的 LightOccluder2D 节点实时生成的带符号距离场来处理的。
    尾迹可以使用内置的带状尾迹和管状尾迹网格，也可以使用带有骨架的自定义网格。
    支持手动发射的自定义粒子着色器。
    基于 CPU 的粒子。

11. 后期处理：
    Tonemapping (Linear, Reinhard, Filmic, ACES, AgX).
    根据视口亮度自动调整曝光（或使用手动曝光覆盖）。
    可以通过景深的远近调节对焦外散斑的模拟（方框、六边形、圆形）。
    半分辨率或全分辨率的屏幕空间环境光遮蔽（SSAO）。
    辉光/泛光，可以使用可选的双三次放大和多种混合模式：滤色（Screen）、柔光（Soft Light）、添加（Add）、替换（Replace）、融合（Mix）。
    辉光可以使用彩色污渍贴图纹理，实现镜头脏污效果。
    辉光可用作屏幕空间模糊效果。
    使用一维渐变或 3D LUT 纹理进行颜色校正。
    可减少镜面反射锯齿的影响的粗糙度限幅器。
    亮度，对比度和饱和度调整。

12. 纹理过滤：
    最近邻、双线性、三线性、各向异性过滤。
    过滤选项是根据每个用途定义的，而不是根据每个纹理定义的。

13. 纹理压缩：
    Basis Universal（速度较慢，但文件较小）。
    用于高质量压缩的 BPTC（macOS 不支持）。
    ETC2（macOS 不支持）。
    S3TC（不支持网页和移动平台）。

14. 抗锯齿：
    时间抗锯齿（TAA）。
    AMD FidelityFX Super Resolution 2.2 抗锯齿（FSR2）可在原始分辨率下用作高质量的时间抗锯齿。
    多重采样抗锯齿（ MSAA ），同时适用于 2D 抗锯齿 和 3D 抗锯齿 。
    快速近似抗锯齿（FXAA）。
    使用双线性三维缩放和高于 1.0 的三维分辨率比例进行超采样抗锯齿 (SSAA)。
    在每种材质基础上的 Alpha 抗锯齿、基于多重采样（MSAA）的 Alpha 覆盖（Alpha-To-Coverage）和 Alpha 哈希。

15. 分辨率缩放：
    支持以较低分辨率渲染 3D，同时保持原始比例的 2D 渲染。 这可用于提高低端系统的性能或改善高端系统的视觉效果。
    分辨率缩放使用了双线性过滤、 AMD FidelityFX Super Resolution 1.0 （FSR1）和 AMD FidelityFX Super Resolution 2.2 （FSR2）。
    多级渐远纹理 LOD 偏置会自动调整，以提高较低分辨率比例下的质量。也可以通过手动偏移进行修改。
    上述效果中的大多数都可以进行调整，从而提升性能、提高质量。这在使用 Godot 进行脱机渲染时非常有用。

3D 工具

内置网格：立方体、圆柱体/圆锥体、（半）球体、棱柱体、平面、四边形、圆环面、条带、管状。
GridMaps 用于由 3D 图块构建的关卡设计。
构造实体几何（用于原型制作）。
程序式几何体生成工具。
Path3D 节点表示 3D 空间中的路径。
可以在编辑器中绘制或者程序化生成。
PathFollow3D 节点使节点沿 Path3D 运动。
3D 几何体辅助类。
支持在编辑器中、或在导出项目的运行时中，将当前场景导出为 glTF 2.0 文件。

3D 物理学

物理体：
静态物体。
可动画物体。
刚体。
角色体。
车身（用于街机物理，而非模拟）。
关节。
柔体。
布娃娃。
区域，用以检测实体进入或离开。

碰撞检测：
内置形状：立方体、球体、胶囊体、圆柱体、世界边界（无限平面）。
从编辑器中为任意网格生成三角形碰撞形状。
从编辑器中为任意网格生成一个或多个凸碰撞形状。

着色器

2D：自定义顶点、片段和灯光着色器。
3D：自定义顶点、片段、灯光和天空着色器。
基于文本的着色器，使用由 GLSL 启发的着色器语言。
可视化着色器编辑器。
支持可视化着色器插件。

编写脚本

常规：
具有脚本扩展节点的面向对象设计模式。
用于脚本之间通信的信号和组。
支持跨语言脚本编程。
多种 2D、3D 以及 4D 线性代数数据类型，比如向量和变换。

GDScript:
High-level interpreted language with optional static typing.
语法受 Python 启发。但是，GDScript 并不基于 Python。
GitHub 上提供了语法高亮显示。
使用线程执行异步操作或使用多个处理器内核。

C#:
打包成单个单独的二进制文件，以降低文件大小和依赖关系。
支持 .NET 8 及更高版本。
完全支持 C# 12.0 语法和特性。
支持 Windows、Linux 和 macOS。从 Godot 4.2 开始，也提供对 Android 和 iOS 的实验性支持。
在 iOS 平台上仅支持部分架构：arm64。
目前不支持 Web 平台。要在该平台上使用 C# ，请考虑改用 Godot 3。
建议使用外部编辑器以从 IDE 功能中获益。

GDExtension（C、C++、Rust、D……）：
按需链接到本机库以获得更高的性能和第三方集成。
对于编写游戏逻辑脚本，如果性能合适，建议使用 GDScript 或 C#。
用于 C 和 C++ 的官方 GDExtension 绑定。
使用你希望的任意构建系统和语言特性。
社区提供的积极开发中的 GDExtension 绑定包括 D、Swift 和 Rust。 （这些绑定中的一些可能是实验性的，尚不适用于生产环境）。

音频

特性：
单声道、立体声、5.1 和 7.1 输出。
2D 和 3D 的非定位和定位播放。
2D 或 3D 中可选的多普勒效应。
支持可重路由的音频总线和包含数十种效果的效果。
支持复调（使用单个 AudioStreamPlayer 节点播放多个声音）。
支持随机音量和音高。
支持实时音高缩放。
支持顺序 / 随机采样，包括在随机采样时的重复预防。
Listener2D 和 Listener3D 节点从不同于摄像机的位置进行侦听。
支持程序式音频生成。
录制麦克风的音频输入。
MIDI 输入。
尚不支持 MIDI 输出。

使用的 API：
Windows： WASAPI。
macOS： CoreAudio。
Linux： PulseAudio 或 ALSA。

导入

支持自定义导入插件。

格式：
图片：见导入图像。
音频：WAV，可选 IMA-ADPCM 压缩。
Ogg Vorbis。
MP3。

3D 场景：见导入 3D 场景。

glTF 2.0 （推荐）。
.blend（通过透明调用 Blender 的 glTF 导出功能）。
FBX （通过透明调用 FBX2glTF）。
Collada（.dae）。
Wavefront OBJ（仅静态场景，可直接被加载为网格或导入为 3D 场景）。
支持在运行时以及导出项目中加载 glTF 2.0 场景。
在导入时使用 Mikktspace 为 3D 网格生成切线，保证与 Blender 等其他 3D 应用的一致性。

输入

输入映射系统使用硬编码的输入事件或可重映射的输入动作。
轴值可以映射到具有可配置死区的两个不同的动作。
使用相同的代码来支持键盘和游戏手柄。
键盘输入。
按键可以以“物理”模式映射，以独立于键盘布局。
鼠标输入。
鼠标光标可以是可见的、隐藏的、被捕获的或被限制在窗口内的。
捕获输入时，在 Windows 和 Linux 平台会使用原始输入，回避操作系统的鼠标加速度设置。
手柄输入（最多同时支持 8 个控制器）。
支持带压感的绘图笔和平板输入。

导航

A* 算法在 2D 和 3D 里。
具有动态避障功能的导航网格在 2D 和 3D 里。
在编辑器内或运行时（包括导出项目）生成导航网格。

网络

使用 StreamPeer 和 TCPServer 进行低阶 TCP 网络通信。
使用 PacketPeer 和 UDPServer 进行低阶 UDP 网络通信。
使用 HTTPClient 进行低阶 HTTP 请求。
使用 HTTPRequest 进行高阶 HTTP 请求。
使用捆绑证书支持开箱即用的 HTTPS。
使用 UDP 和 ENet 的高级联机API。
使用远程过程调用（RPC）进行自动复制。
支持不可靠、可靠和有序传输。
WebSocket 客户端和服务器，全平台可用。
WebRTC 客户端和服务器，全平台可用。
当在 NAT 后托管服务器时，支持使用 UPnP 来避免转发端口的需求。

国际化

完全支持 Unicode，包括表情符号。
使用 CSV 或 gettext 存储本地化字符串。
支持从编辑器中生成 gettext POT 和 PO 文件。
在你的项目中自动在 GUI 元素中或通过使用 tr() 函数使用本地化的字符串。
使用 gettext 翻译时支持复数形式和翻译上下文。
支持双向排版、文本整形和 OpenType 本地化表单。
用于从右到左区域设置的自动 UI 镜像。
支持伪本地化，以测试你的项目对 i18n 的友好性。

窗口功能与操作系统整合

在单个进程中生成多个独立窗口。
移动、调整大小、最小化和最大化由项目产生的窗口。
更改窗口标题和图标。
吸引注意（在大多数平台上表现为标题栏闪烁）。
全屏模式。
在 Windows 上，默认情况下使用无边框全屏进行快速切换，但也可以选择使用独占全屏来减少输入滞后。
无边框窗口（全屏或非全屏）。
窗口置顶功能。
macOS 上的全局菜单整合。
以阻塞或非阻塞方式执行命令（包括运行同一项目的多个实例）。
使用默认或自定义（已在系统上注册）协议处理程序打开文件路径和 URL。
解析自定义命令行参数。
通过用 –headless 命令行参数启动它，任何 Godot 二进制文件（编辑器或导出的项目）都可以用作无头服务器。这允许在没有 GPU 或显示服务器的情况下运行引擎。

移动端

在 Android 或 iOS 上的应用内购。
支持使用第三方模块的广告。

XR 支持（AR 和 VR）

开箱即用的 OpenXR 支持。
包括对流行的桌面 VR 头显的支持，例如 Valve Index、WMR 头显和 Quest over Link。
通过插件，使用 OpenXR 支持基于 Android 的头显。
包括对流行的独立头显的支持，例如 Meta Quest 1/2/3 和 Pro、Pico 4、Magic Leap 2 和 Lynx R1。
通过 XR 插件结构支持的其他设备。
可以使用各种高级工具包来实现 XR 应用程序所需的常见功能。

GUI 系统

Godot 的 GUI 也是使用与用于在 Godot 中制作游戏相同的 Control 节点构建的。编辑器 UI 可以使用插件以多种方式轻松扩展。

节点：
按钮。
复选框、复选按钮、单选按钮。
使用 LineEdit（单行）和 TextEdit（多行）进行文本输入。TextEdit 还支持代码编辑功能，例如显示行号和语法高亮。
使用 PopupMenu 和 OptionButton 实现下拉菜单。
滚动条。
标签。
用于使用 BBCode 的格式化文本的 RichTextLabel，支持自定义动画效果。
树（也可用于显示表格）。
支持 RGB 及 HSV 模式的取色器。
控件可以被旋转和缩放。

调整大小：
锚点将 GUI 元素保持在特定的角落、边缘或中心。
容器按照特定规则自动放置 GUI 元素。
堆叠布局。
网格布局。
流式布局（类似于文本自动折行）。
边距、居中和纵横比布局。
可拖拽分割器布局。
使用 canvas_items 或 viewport 拉伸模式，缩放至多种分辨率。
使用锚点和 expand 拉伸比例，支持任意纵横比。

主题：
内置主题编辑器。
根据当前的编辑器主题设置生成主题。
使用 StyleBoxFlat 进行基于向量的程序式主题设计。
支持圆角/斜角、阴影、各边框宽度、抗锯齿。
使用 StyleBoxTexture 进行基于纹理的主题设计。
Godot 较小的发行包大小，使其适合成为 Electron 或 Qt 等框架的替代品。

动画

正向运动学与反向运动学。
支持使用可自定义插值动画化任意属性。
支持在动画轨道中调用方法。
支持在动画轨道中播放声音。
支持在动画中使用贝塞尔曲线。

文件格式

场景和资源可保存为文本或二进制格式。
基于文本的格式易于阅读，并且对版本控制更友好。
二进制格式保存/加载大型场景/资源的速度更快。
使用 FileAccess 读写文本或二进制文件。
可选择使用压缩或加密。
读写 JSON 文件。
使用 ConfigFile 读写 INI 样式的配置文件。
可以（反）序列化任何 Godot 数据类型，包括 Vector2/3、Color 等。
使用 XMLParser 读取 XML 文件。
无需通过 Godot 的导入系统， 即可在导出的项目中加载和保存图像、音频/视频、字体和 ZIP 存档。
将游戏数据打包到 PCK 文件（针对快速搜索优化的自定义格式）、ZIP 存档或直接打包到可执行文件中以进行单文件分发。
导出额外的 PCK 文件，引擎可以读取这些文件以支持 mod 和 DLC。

杂项

视频播放内置支持 Ogg Theora。
Movie Maker 模式可从正在运行的项目中录制视频，并具有同步音频和完美的帧同步。
对服务器的低级别访问，能够在必要时绕过场景树的开销。
使用命令行接口进行自动化。
使用持续集成平台导出和部署项目。
适用于 Bash、zsh 和 fish 的 Shell 补全脚本 。
在所有平台使用 print_rich 将彩色文本打印至标准输出。
支持将 C++ 模块静态链接到引擎二进制文件中。
引擎和编辑器以 C++17 编写。
可使用 GCC、Clang、MSVC 进行编译。同样支持 MinGW。
对打包者友好。通常情况下，可以使用系统库代替 Godot 提供的库。构建系统不会下载任何东西。构建完全可重现。
使用宽松的 MIT 许可。
开放的开发过程，欢迎贡献。

系统需求

导出的 Godot 项目

遵守许可证

Godot 是根据 MIT 许可证创建并分发的。
没有单一的所有者，因为每个向项目提交代码的贡献者都是在相同的许可证下进行，并保留其贡献的所有权。
许可证是使用和分发软件（以及衍生项目，包括用它制作的游戏）的法律要求。
你的游戏或项目可以具有不同的许可证，但仍需要遵守原始许可证。
对于 MIT 许可证，唯一的要求是将许可证文本包含在你的游戏或衍生项目的某处。

包含
必须向用户提供许可证文本。许可证并未指定如何包含文本，但以下是最常见的方法（只需实现其中一种，无需全部实现）。

制作人员画面
将上述许可证文本包含在制作人员画面的某个位置。它可以位于显示其余制作人员后的底部。大多数大型工作室都使用这种方法来获得开源许可证。

许可证画面
有些游戏有专门的菜单（通常在设置中）来显示许可证。该菜单通常通过名为第三方许可证或开源许可证的按钮访问。

输出日志
在全局输出日志可读的平台上，使用 print() 函数打印许可证文本可能就足够了。适用于桌面平台、Android 和 HTML5（但不适用于 iOS）。

随附文件
如果游戏是在桌面平台上发行的，则可以将包含许可证文本的文件添加到安装到用户电脑的软件中。

印刷手册
如果游戏包含印刷手册，则可以将许可证文本包含在其中。

许可证链接
Godot 引擎开发者认为，在你游戏的文档或者制作人员信息中加入指向 godotengine.org/license 的链接是满足许可条款的可接受方式。

Godot 提供了多种方法来获取 Engine 单例中的许可证信息。 这将允许你直接从引擎二进制文件中获取许可证信息，从而防止更新引擎版本时信息过时。

对于引擎自己：
Engine.get_license_text

对于引擎使用的第三方部件：
Engine.get_license_info
Engine.get_copyright_info

第三方许可证
Godot 本身包含由第三方编写的软件，这些软件与 Godot 的 MIT 许可证兼容，但不受其约束。
许多这些依赖项都是在宽松的开源许可证下分发的，这些许可证要求通过在最终产品的文档中明确引用其版权声明和许可证文本来署名。
考虑到 Godot 项目的规模，要彻底做到这一点相当困难。对于 Godot 编辑器，第三方版权和许可证的完整文档在 COPYRIGHT.txt 文件中提供。
对于最终用户来说，记录第三方许可证的一个好方法是将此文件包含在项目的分发中，例如，你可以将它重命名为 GODOT_COPYRIGHT.txt 以防止与你自己代码和资产混淆。

入门

前言

学习用 GDScript 编程

学习网站

Godot 关键概念概述

• 节点
• 场景
• 场景数
• 信号

手册

最佳实践

在 Godot 中应用面向对象原则

Godot 引擎主要提供了两种创建可复用对象的方式：脚本和场景。
严格来说，这两种方式都没有真的在底层定义类。
尽管如此，在许多使用 Godot 的最佳方法中，依然涉及将面向对象的编程原则应用到游戏的脚本和场景中。
这就是为什么我们需要了解如何将它们视为类。

1. 脚本：
   引擎提供了内置的类，如 Node 。你可以使用脚本扩展这些类来创建派生类型。
   这些脚本严格来说并不是类，而是一种资源，用来告知引擎在某一内置类的基础上执行一系列初始化。

Godot 的内部类可以将一个类的数据注册进一个名为ClassDB的数据库可以在运行时访问类的信息。
ClassDB 包含类的信息，例：属性 方法 常量 信号

当对象在执行访问属性或调用方法等操作时，它就会检查 ClassDB 中对象和对象基类的记录，以确定对象是否支持该操作。
将 Script 附加到你的对象上，可以扩展 ClassDB 中该对象的方法、属性和信号。

脚本即使没有使用 extends 关键字，也会隐式地继承引擎的基础 RefCounted 类。
因此，你可以从代码中实例化不使用 extends 关键字的脚本。
不过由于扩展的是 RefCounted，你是无法把它们附加到 Node 上的。

2. 场景：
   场景是可复用、可实例化、可继承的节点组。
   创建场景就类似于，有一个脚本去创建一些节点，并使用 add_child() 将它们添加为子节点。

我们经常为场景搭配一个带有脚本的根节点，并在脚本中使用这个场景下的节点。脚本是通过使用命令式代码为场景添加行为来扩展场景的。

场景的内容有助于定义：
脚本可使用哪些节点。
如何组织的。
如何初始化的。
彼此之间有什么信号连接。

为什么这些对组织场景很重要？
因为场景的实例都是对象。因此，许多适用于书面代码的面向对象原则也适用于场景：单一职责、封装等。

场景就是对附着在根节点上的脚本的扩展，所以你可以将其解释为类的一部分。
此系列最佳实践中所解释的大部分技术都建立在这一点上。

场景组织

如何有效地建立关系？
应尽可能设计没有依赖的场景。（创建的场景应该将其所需的一切保留在其内部）
如果场景必须与外部环境交互，经验丰富的开发人员会建议使用依赖注入。
该技术涉及使高级 API 提供低级 API 的依赖关系。为什么要这样呢？因为依赖于其外部环境的类可能会无意中触发 Bug 和意外行为。
要做到这一点，就必须暴露数据，然后依靠父级上下文对其进行初始化：

1. 连接信号。这样做极其安全，但只能用于“响应”行为，而不是启动行为。按照惯例，信号名称通常是过去式动词，如“entered”“skill_activated”“item_collected”（已进入、已激活技能、已收集道具）。

# Parent
$Child.signal_name.connect(method_on_the_object)

# Child
signal_name.emit() # Triggers parent-defined behavior.

2. 调用方法。用于启动行为。

# Parent
$Child.method_name = "do"

# Child, assuming it has String property 'method_name' and method 'do'.
call(method_name) # Call parent-defined method (which child must own).

3. 初始化 Callable 属性。比调用方法更安全，因为不需要拥有这个方法的所有权。用于启动行为。

# Parent
$Child.func_property = object_with_method.method_on_the_object

# Child
func_property.call() # Call parent-defined method (can come from anywhere).

4. 初始化 Node 或其他 Object 的引用。

# Parent
$Child.target = self

# Child
print(target) # Use parent-defined node.

5. 初始化 NodePath。

# Parent
$Child.target_path = ".."

# Child
get_node(target_path) # Use parent-defined NodePath.

这些选项隐藏了子节点的访问点。这反过来又使子节点与环境保持 松耦合 （loosely coupled）。
人们可以在另外一个上下文中重新使用它，而不需要对API做任何额外的改变。

选择节点树结构
构造节点树的方法有无数种。但对于没把握的人而言，这份有用的指南可以给他们一个不错的结构样本作为开始。
main.gd 脚本将作为你的游戏的主要控制器。
另外，你的游戏需要一个主要GUI，来管理项目所需的各种菜单和部件。
当变更关卡时，可以稍后换出“World”节点的子级。手动更换场景让用户完全控制他们的游戏世界如何过渡。
下一步是考虑项目需要什么样的游戏系统。如果有这么一个系统……
跟踪所有的内部数据
应该是全局可访问的
应该是独立存在的
…接下来他该创建一个自动加载“单例”节点了。

何时使用场景与脚本

自动加载与常规节点

何时以及如何避免为任何事情使用节点

Godot 接口

Godot 通知

数据偏好

逻辑偏好

项目组织

版本控制系统

故障排除

1. 编辑器运行缓慢，占用所有的 CPU 和 GPU 资源
   尤其是在 macOS 上，因为大多数 Mac 都有 Retina 显示屏。
   由于 Retina 显示器的像素密度更高，因此所有内容都必须以更高的分辨率渲染。会增加 GPU 上的负载并降低感知性能。

有几种衡量性能和电池续航的方法：

• 在 3D 模式下，单击左上角的透视按钮并启用半分辨率。现在 3D 视口就会以半分辨率渲染，速度最多可以提高到原来的 4 倍。
• 打开编辑器设置并将低处理器模式睡眠（微秒）的值增加到 33000（30 FPS）。该值决定了渲染每帧画面之间所间隔的时间（微秒单位）。 较高的值将会使编辑器操作起来没有那么跟手，但可显著降低 CPU 和 GPU 使用率。
• 如果有某个节点导致编辑器连续重新绘制（例如粒子），请将其隐藏并在脚本中使用 _ready() 方法显示它。这样，它将隐藏在编辑器中，但仍在正在运行的项目中可见。

2. 编辑器在我的可变刷新率显示器（G-Sync/FreeSync）上出现卡顿和闪烁的情
   可变刷新率显示器需要不断调整其伽玛曲线，以便随着时间的推移发出一致的光量。
   当刷新率变化很大时，这可能会导致图像的黑暗区域出现闪烁，这是因为 Godot 编辑器仅在必要时重绘。

这有几种解决办法：

• 在编辑器设置中启用界面 > 编辑器 > 持续更新。即使画面没有变化，编辑器也将不断渲染。请注意，这会增加功耗、加大热量和噪音排放。
  为了缓解这种情况，你可以在编辑器设置中将低处理器模式睡眠（微秒）增加到 33000（30 FPS）。
  该值决定了渲染每帧画面之间所间隔的时间（微秒单位）。
  较高的值将会使编辑器操作起来没有那么跟手，但可显著降低 CPU 和 GPU 使用率。
• 在显示器或图形驱动程序中禁用可变刷新率。
• VRR 闪烁这个问题在某些显示器上，可以通过你的显示器的 OSD 中的 VRR 控制或微调暗区选项来减少。这些选项可能会增加输入延迟或导致黑色失真。
• 如果使用 OLED 显示器，可以在编辑器设置中使用 Black (OLED) 编辑器主题预设。因为 OLED 显示器的出色的黑阶表现，这可以隐藏 VRR 闪烁。

3. 编辑器或项目花了很长时间才启动
   使用基于 Vulkan 的渲染器（Forward+ 或 Mobile）时，首次启动将会花费较长的时间。
   这是因为着色器需要先编译才能进行缓存。更新 Godot、更新显卡驱动或切换显卡后，着色器也需要重新缓存。

如果这个问题在首次启动后依然存在，那么这是 Windows 上的一个已知错误，当你连接了特定的 USB 外设时就会出现 。特别是，海盗船的 iCUE 软件似乎引起了该错误。尝试将 USB 外设的驱动程序更新为最新版本。如果错误仍然存在，则需要在打开编辑器之前断开故障外围设备的连接。然后，你可以再次连接外围设备。

Portmaster 等防火墙软件可能会屏蔽调试端口，导致项目启动时间变长，并且无法在编辑器中使用调试功能（例如查看 print() 的输出）。变通方法是在“编辑器设置”中修改项目所使用的调试端口（网络 > 调试 > 远程端口）。默认值是 6007；可以尝试设成大于 1024 的值，比如 7007。

在 Windows 上，当首次加载项目时，如果电脑刚开机，Windows Defender 会导致项目启动时文件系统缓存验证耗时显著增加。对于文件较多的项目尤为明显。考虑通过以下步骤将项目文件夹添加到排除列表中：病毒与威胁防护 > 病毒与威胁防护设置 > 添加或删除排除项。

4. 点击系统控制台后 Godot 编辑器没有响应
   在启用了系统控制台的 Windows 上运行 Godot 时，你可以通过在命令窗口中单击来意外启用选择模式。Windows 的这种特定行为会暂停应用程序，以便你在系统控制台内选择文本。Godot 无法覆盖此系统特定的行为。

要解决此问题，请选择系统控制台窗口，然后按 Enter 退出选择模式。

5. 手动移动 Godot 编辑器的 macOS Dock 图标之后出现多余的编辑器图标
   如果你打开 Godot 编辑器并手动改变 dock 图标的位置，然后重启编辑器，你会在 dock 的最右边看到一个重复的 dock 图标。

这是由于 macOS dock 的设计限制造成的。解决这个问题的唯一已知方法是将项目管理器和编辑器合并为一个进程，这意味着项目管理器在启动编辑器时不再产生一个单独的进程。虽然使用单一进程实例会带来一些好处，但由于任务的复杂性，完成这个功能没有列入我们近期的工作计划。

为了避免这个问题，保持 Godot 编辑器的 dock 图标在 macOS 创建的默认位置。

6. 在项目管理器和编辑器窗口的左上角出现“NO DC”之类的文本
   这是由于 NVIDIA 显卡驱动程序注入了覆盖显示信息造成的。

要在 Windows 上禁用此覆盖，请在 NVIDIA 控制面板中将图形驱动程序设置恢复为默认值。

要在 Linux 上禁用此覆盖，请打开 nvidia-settings，转到 X Screen 0 > OpenGL Settings，然后取消选中 Enable Graphics API Visual Indicator。

7. 在项目管理器和编辑器窗口右下角出现一个麦克风或刷新的图标
   这是由于 NVIDIA 图形驱动程序注入覆盖以显示 ShadowPlay 录制的即时重播信息造成的。此覆盖只能在 Windows 上看到，因为 Linux 不支持 ShadowPlay。

要禁用此覆盖，请按 Alt + Z（NVIDIA 覆盖的默认快捷方式）并在 NVIDIA 覆盖中禁用设置 > HUD 布局 > 状态指示器。

你也可以选择安装取代 GeForce Experience 的新的 NVIDIA 程序 https://www.nvidia.com/en-us/software/nvidia-app/，这样就不会遇到这个问题。与 GeForce Experience 不同的是，NVIDIA 程序会在屏幕的角落而不是每个窗口的角落绘制回放指示器。

8. 编辑器或项目显示得过于锐利或模糊
   可能是由于你的图形驱动程序强制对所有 Vulkan 或 OpenGL 应用程序进行图像锐化。

你可以在图形驱动程序的控制面板中禁用此行为：
NVIDIA（Windows）：打开开始菜单，选择 NVIDIA 控制面板。打开左侧的管理 3D 设置选项卡。在中间的列表中，滚动到图像锐化，并将其设置为关闭锐化。
AMD（Windows）：打开开始菜单，选择 AMD 软件。点击右上角的设置 “齿轮 “图标。转到图形选项卡，然后禁用 Radeon 图像锐化。
如果编辑器或者项目看起来过于模糊，这可能是由于 FXAA 被你的显卡驱动强制应用到所有的 Vulkan 或者 OpenGL 应用程序上。
NVIDIA（Windows）：打开开始菜单并选择 NVIDIA 控制面板。打开左侧的管理 3D 设置选项卡。在中间的列表中， 滚动到平滑设置 - FXAA 并将其设置为应用程序控制的。
NVIDIA（Linux）：打开应用程序菜单，选择 NVIDIA X 服务器设置。在左侧选择 Antialiasing Settings，取消对 Enable FXAA 的勾选。
AMD（Windows）：打开开始菜单并选择 AMD Software。点击设置右上角的“齿轮”图标。转到图形选项卡， 滚动到底部并点击高级以展开其设置。禁用形态抗锯齿。

像是 vkBasalt 这种第三方开发的供应的工具可能会强迫所有的 Vulkan 应用程序开启锐化或者 FXAA。你可能也需要检查他们的设置。

当你变更过了显卡驱动和第三方工具中的设置后，重启 Godot 去应用这些设置。
如果你仍然希望在其他应用程序上强制锐化或 FXAA，建议你使用显卡驱动控制面板提供的应用程序配置系统，针对每个应用程序的进行设置。

9. 此编辑器或项目看起来颜色很淡
   在 Windows 上，这通常是由不正确的操作系统或显示器设置引起的，因为 Godot 目前不支持 HDR 输出（即使它可能在内部以 HDR 渲染）。

由于大多数显示器并非被设计为在 HDR 模式下显示 SDR 内容 <https://tftcentral.co.uk/articles/heres-why-you-should-only-enable-hdr-mode-on-your-pc-when-you-are-viewing-hdr-content>__，建议在未运行使用 HDR 输出的应用程序时在 Windows 设置中禁用 HDR。在 Windows 11 上，可以通过按 Windows + Alt + B 来完成该操作（该快捷方式是 Xbox Game Bar 应用程序的一部分）。要根据当前正在运行的应用程序自动切换 HDR，你可以使用 AutoActions。

如果你坚持启用 HDR，可以通过确保显示器配置为使用 HGIG 色调映射（而不是 DTM），然后使用 Windows HDR 校准应用程序 <https://support.microsoft.com/en-us/windows/calibrate-your-hdr-display-using-the-windows-hdr-calibration-app-f30f4809-3369-43e4-9b02-9eabebd23f19>__ 来稍微改善结果。强烈建议在使用 HDR 时使用 Windows 11 而不是 Windows 10。不过，最终结果可能仍不如在显示器上禁用 HDR。

计划在未来版本中支持 HDR 导出。

10. 从挂起状态恢复 PC 后，编辑器/项目冻结或显示出现故障
    当在 Linux 上使用 NVIDIA 的专用图形驱动程序时便会出现这个已知的问题。
    目前还没有明确的解决方案，因为当涉及 OpenGL 或 Vulkan 时，Linux + NVIDIA 上的挂起通常会出现问题。
    与 Forward+ 和 Mobile 渲染方法（使用 Vulkan ）相比，兼容性渲染方法（采用 OpenGL ）通常不太容易出现挂起相关问题。

NVIDIA驱动程序提供了一个实验性选项可在挂起后保护视频内存用以解决这个问题。
据报道，该选项与较新的 NVIDIA 驱动程序版本配合使用效果更好。

为了避免丢失工作内容，请在使电脑进入睡眠状态之前将场景保存在编辑器中。

11. 项目在编辑器中正常运行，但在导出后无法加载部分文件
    这通常是由于忘记在导出对话框中指定非资源文件过滤器而导致的。
    默认情况下，Godot 只会将实际的资源包含到 PCK 文件中。一些常用的文件，例如 JSON 文件，不会被视为资源。
    例如，如果你在导出的项目中加载 test.json，则需要在非资源导出过滤器中指定 *.json。有关更多信息，请参阅 资源选项。

另外，请注意，导出的项目永远不会包含名字以点开头的文件和文件夹。这是为了防止将 .git 等版本控制文件夹包含在导出的 PCK 文件中。

在 Windows 上，也可能是大小写敏感性的问题。如果你在脚本里引用资源时所使用的大小写与文件系统中的不符，在导出项目后就会载入失败。这是因为虚拟 PCK 文件系统是大小写敏感的，而 Windows 的文件系统是大小写不敏感的。

12. 项目在从项目管理器打开后频繁崩溃或立即崩溃
    这可能是由多个因素引起的，比如编辑器插件、GDExtension 插件或其他原因。
    建议以恢复模式打开项目，并尝试找到并修复导致崩溃的原因。
    有关更多信息，请参见 Project Manager page。

编辑器简介

编辑器的界面

使用项目管理器不需要什么教程，自己实际体验就可以更好掌握

• 项目的使用
• 下载演示和模板
• 用标签管理项目
• 恢复模式

Inspector Dock
检查器扩展坞
如果不可见，可以通过导航到 编辑器 > 编辑器设置 > 编辑器停靠 > 检查器

在内部，Godot 将项目的设置存储在一个 project.godot 文件中，这是一个 INI 格式的纯文本文件。
虽然这种格式易于阅读且对版本控制友好，但直接编辑并不太方便。
可以通过 项目设置 窗口来编辑这些设置。要打开项目设置，请从主菜单中选择 项目 > 项目设置。

XR 编辑器

Android 编辑器

Web 编辑器

高级功能

管理编辑器功能

2D

3D

动画

资产管线

音频

音频总线

Godot的音频引擎允许创建任意数量的音频总线, 并且可以向每个总线添加任意数量的效果处理器.
运行游戏的设备的硬件会限制总线的数量, 以及在性能开始下降之前可以使用的效果.

分贝标度
分贝(dB)标度是一个相对标度. 它等于声功率比的常用对数的20倍(20 × log10(P/P/0)).
每增/减6分贝, 声幅就会加倍/减半.12dB代表系数4,18dB代表系数8,20dB代表系数10,40dB代表系数100, 以此类推.
由于比例是对数的, 因此无法表示真零(无音频).
0 dB 是数字音频系统中可能的最大振幅. 这个限制不是人为的限制, 而是声音硬件的限制. 因振幅太高而无法完全反映在0dB以下的音频, 会产生一种被称为 削波 的失真.
为了避免削波，你应该调整混音，使master 总线（后面会有更多的介绍）永远不超过 0 dB。
低于0dB限制的每6dB, 声能就会 减半 . 这意味着-6dB的音量是0dB的一半. -12dB是-6dB的一半, 依此类推.
使用分贝时, -60dB和-80dB范围内的声音被认为是听不见的. 也就是说你的工作范围一般在-60dB和0dB之间.

音频总线(audio bus)音频通道 (audio channel)
音频总线可以在Godot 编辑器的底部面板中找到:
音频从扬声器播放出来之前通过的地方.
它可以 修改 和 重路由 音频数据.
音频总线有一个 VU表(播放声音时亮起的条形), 表示通过的信号的幅度.

最左边的总线是 主总线 .
此总线将混音输出到你的扬声器, 因此, 正如之前 分贝标度 部分所述, 请确保主总线中的混音水平永远低于 0 dB.
其余的音频总线可以灵活地进行路由.
在修改声音后, 它们会将其发送到左边的另一条总线上. 非主总线的目标总线可以被单独设置.
而右侧总线的音频会被路由至左侧总线, 这避免了无限循环.

音频特效

音频流

将游戏玩法与音频和音乐同步

使用麦克风录音

文本转语音

导出

文件与数据 I/O

国际化

输入处理

数学

导航

网络

高级多人游戏

1. 高层API vs 底层 API
   Godot 始终支持通过 UDP、 TCP 和一些更高级别的协议（如 SSL 和 HTTP ）进行标准的低级网络连接。
   使用 Godot 的高级网络 API，牺牲了对低级网络的一些细度控制，有更强的易用性。

2. 中层抽象
   Godot 使用了一个中间层级的 MultiplayerPeer 对象。不应直接创建这种对象，它被设计为由多个 C++ 实现所提供。

这个对象扩展自 PacketPeer 类，继承了所有用于序列化、发送和接收数据的方法。
此外，该对象还添加了设置对等体、传输模式等方法。它还包括让你知道对等体何时连接或断开的信号。

这个类接口可以抽象出大多数类型的网络层、拓扑结构和库。
默认情况下，Godot 会提供一个基于 ENet 的实现（ENetMultiplayerPeer）、一个基于 WebRTC 的实现（WebRTCMultiplayerPeer）以及一个基于WebSocket的实现（WebSocketPeer），而该类接口可以用来实现移动 API（用于特设的 WiFi、蓝牙等）或自定义设备/控制台中特定的网络 API。

但大多数常见情况下，不鼓励直接使用这个对象，因为 Godot 提供了更高级别的网络使用方法。
只有当游戏对较低级别的API有特殊需求的情况下，才使用该对象。

3. 服务器托管的注意事项
   托管服务器时，LAN 上的客户端可以使用内网 IP 地址进行连接，该地址的格式通常是 192.168..。 非 LAN/Internet 客户端无法访问此内部 IP 地址。

在 Windows 中， 你可以在命令提示符中输入 ipconfig 命令， 在 macOS 中，你可以在终端中输入 ifconfig 命令，在 Linux 中，你可以在终端中输入 ip addr 命令，来找到你的内网 IP 地址。

如果你在自己的机器上托管了服务器，并且想让非内网客户端连接，那么你可能需要将服务器端口 转发 到你的路由器，由于大多数家用网络都使用 NAT 技术，因此转发服务器端口是让你的服务器能通过互联网访问的必经步骤。Godot 的高级多人 API 只使用 UDP 协议，所以你的端口转发也必须是 UDP 协议的端口，不能只转发 TCP 协议的端口。

在转发了 UDP 端口之后，你需要确保你的服务器使用这个端口。可以前往这个网站 https://icanhazip.com/去查询你的公网 IP 地址，然后把这个公网 IP 地址发送给想联机到你服务器的互联网客户端即可。

Godot 的高级多人联机 API 使用的是一个修改过的 ENet，包含全 IPv6 支持。

网络初始化

进行 HTTP 请求

HTTP 客户端类

TLS/SSL 证书

Using WebSockets

WebRTC

性能

物理

平台相关

插件

渲染

编写脚本

着色器

用户界面（UI）

XR

内置了一套模块化扩展现实（XR）系统，该系统通过抽象化不同 XR 平台的底层实现细节，以简化跨平台 XR 应用的开发流程。
该系统的核心是 XRServer 类，它作为整个 XR 架构的中枢接口，允许开发者通过该接口发现并连接各类 XR 运行时环境。