Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

3D 简介

创造一个 3D 游戏很有挑战性。那个多出来的的 Z 轴使许多有助于使 2D 游戏变得简单的常用技术不再起作用。为了帮助习惯这种转变，值得一提的是，Godot在2D和3D上使用了类似的API。大多数节点是相同的，并且存在 2D 和 3D 版本。事实上，可以看看 3D 平台游戏教程或 3D 运动学角色教程，它们大部分与2D对应教程相同。

Godot 第三人称射击游戏 (TPS) 演示，可在 Github 仓库 或 资产库 中获取。

在3D中，数学比在2D中更复杂一些。想了解为游戏开发者（而非数学家或工程师）编写的相关数学介绍，请查看 向量数学 和 使用 3D 变换 。

3D 工作区

编辑 3D 场景在 3D 工作区中完成。该工作区可以手动选择，但在选择 Node3D 节点时将自动启用。

与 2D 类似，工作区选择器下方的选项卡用于在当前打开的场景之间切换，或使用加号（+）按钮创建新场景。左右两侧的面板应该从 编辑器简介 中熟悉了。

在场景选择器下方，能看到主工具栏，而主工具栏下面是 3D 视口。

主工具栏

主工具栏中的某些按钮与 2D 工作区中的按钮相同。如果鼠标光标悬停在按钮上一秒钟，会给出简要说明和快捷键。某些按钮在执行另一个按键操作时可能具有附加功能。下面从左到右概述了每个按钮的主要功能及其默认快捷键：

• 选择模式 (Q): 允许在视口中选择节点。左键单击节点即可选择。左键单击并拖动矩形框，松开后即可选择矩形边界内的所有节点。按住 Shift 键的同时选择可将更多节点添加到当前选择中。按住 Shift 键的同时单击已选中的节点可取消选择。在此模式下，你可以使用操纵器来执行移动或旋转操作。

• 移动模式 (W)：为已选节点启用移动（或平移）模式。查看 空间与操纵小工具 了解更多细节。

• **旋转模式**（E）：为已选节点启用旋转模式。查看 空间与操纵小工具 了解更多细节。

• 缩放模式 (R)：为已选节点启用缩放功能并显示各轴的缩放操作控件。查看 空间与操纵小工具 了解更多细节。

• Show the list of selectable nodes at the clicked position: As the description suggests, this provides a list of selectable nodes at the clicked position as a context menu, if there is more than one node in the clicked area.

• **锁定**（ Ctrl + L ）已选节点，防止它们在视口中被选中或移动。再次点击该按钮（或使用 Ctrl + Shift + L ）可解锁已选节点。已锁节点只能在场景树中被选中。在场景树中，它们可以用节点名称旁边的锁形图标轻易识别。点击该锁也可以解锁节点。

• 编组所选节点（Ctrl + G）。如果已经选择了任何子节点，该操作将允许选择根节点。使用 Ctrl + G 可以取消编组。此外，点击场景树中的取消编组按钮也会执行相同的操作。

• **标尺模式**（M）：启用后，可通过点击拖动操作以米为单位测量场景中的距离。

• **使用局部空间**（T）：如果启用，节点的操控器将使用当前节点的旋转角度绘制，而非 全局视口坐标系。

• 使用吸附 (Y)：如果启用，移动和旋转将吸附到网格。执行操作时按住 Ctrl 也可以临时激活吸附功能。下方会说明更改吸附选项的设置。

• Toggle preview sunlight: If no DirectionalLight3D exist in the scene, a preview of sunlight can be used as a light source. See 预览环境和灯光 for more details.

• Toggle preview environment: If no WorldEnvironment exists in the scene, a preview of the environment can be used as a placeholder. See 预览环境和灯光 for more details.

• Edit Sun and Environment Settings (three dots): Opens the menu to configure preview sunlight and environment settings. See 预览环境和灯光 for more details.

• 变换菜单：包含三个选项：

  • 吸附物体到地面：将物体吸附到实体地面。

  • 变换对话框：打开一个对话框来手动调整变换参数（平移、旋转、缩放和变换）。

  • Snap Settings: Allows you to change transform, rotate snap (in degrees), and scale snap (in percent) settings.

• 视图菜单：控制视图选项并启用额外的视口：

在此菜单中，你还可以显示/隐藏网格（默认设置为 1x1 米）和原点（蓝色、绿色和红色轴线的交点）。此外，在此菜单中还可以切换特定类型的小工具。

睁开的眼睛表示小工具可见，闭上的眼睛表示它被隐藏。半睁的眼睛表示它穿过不透明表面也可见。

点击视图菜单中的 设置 会打开一个窗口，用于更改 垂直视野 (VFOV) 参数（角度）、近平面Z 和 远平面Z 值。

在视图菜单旁边，可能会显示额外的按钮。在本章开头的工具栏图片中，由于选中了 MeshInstance3D，显示了一个额外的 Mesh 按钮。该菜单提供了一些快速操作或工具，用于处理特定节点或选中内容。

视口的视图菜单

Below the Select tool, in the 3D viewport, clicking on the three dots opens the View menu for the viewport. Hiding all shown gizmos in the editor's 3D view can also be performed through this menu:

此菜单还显示当前视图类型，并支持快速调整视口的视角。此外，它还提供了一些选项来修改视口中节点的外观。

坐标系

Godot 在 3D 中使用的都是公制，1 个单位等于 1 米。物理和其他区域都为此而调整过。因此，试图使用不同的比例通常是一个坏主意（除非你知道你在做什么）。

使用 3D 资产时，最好始终使用正确的比例（在 3D 建模软件中将单位设置为公制）。Godot 允许在导入后缩放，尽管在大多数时都没问题，但在极少数情况下，会在渲染或物理等敏感区域带来浮点精度问题（从而导致故障或伪影）。所以，确保你的艺术家始终在正确的比例下进行创作！

Y 坐标用于“向上”。至于水平 X/Z 轴，Godot 使用 右手 坐标系。这意味着对于大多数需要对齐的对象（例如灯光或相机），Z 轴被用作“指向”方向。这个约定的大致意思是：

• X 是两边

• Y 是上/下

• Z 是前/后

有关与其他 3D 软件的比较，请参阅此图表：

图像来自 Freya Holmér

空间与操纵小工具

在 3D 视图中移动、旋转和缩放物体是通过操纵器小工具完成的。每个轴用一种颜色表示：红、绿、蓝分别代表 X、Y、Z。这种惯例也适用于网格和其他小工具（也适用于着色器语言，Vector3、Color 等组件的排序）。

一些有用的键盘绑定:

• 要吸附放置或旋转，在移动、缩放或旋转时按 Ctrl 键。

• 要将视图居中到所选对象上，请按 F。

在视口中，点击并按住箭头可以沿轴移动物体。点击并按住弧线可以旋转物体。要锁定一个轴并在另外两个轴上自由移动物体，可点击、按住并拖动彩色矩形。

如果变换模式从*选择模式*更改为*缩放模式*，箭头将被立方体取代，拖动可以缩放物体，类似移动物体。

在 3D 环境中导航

在 3D 环境中，调整视角或观察场景的角度通常很重要。在 Godot 里，在视口（或空间编辑器）中，可以通过多种方式实现 3D 环境导航。

默认的3D场景导航控制类似于 Blender（旨在使免费软件开发流程中具有某种一致性），但在编辑器设置中也包含了自定义鼠标按钮和行为的选项，就仿佛使用其他工具那样。比如想修改成 Maya 或者 Modo 的控制逻辑，你可以打开 编辑器设置>各编辑器>3D 。然后在 导航 下，找到 导航方案 。

使用默认设置时，以下快捷键控制如何在视口中导航：

按下鼠标中键并拖动鼠标，可以让你围绕屏幕中心进行环绕观察。

你也可以左键点击并按住位于视口右上角的操纵器小工具来围绕中心进行环绕：

左键单击其中一个彩色圆圈会将视图设置为选定的正交视图，并且视口的视图菜单将相应更新。

如果视口中启用了*透视*视图（可在视口的视图菜单中看到，而非主工具栏的视图菜单），在视口中按住鼠标右键或按下 Shift + F 可切换到"自由视角"模式。在此模式下，你可以通过移动鼠标来环视四周，使用 W A S D 键在视图中飞行，按 E 上升，按 Q 下降。要退出此模式，松开鼠标右键或再次按下 Shift + F。

在自由视角模式下，你可以使用 Shift 临时提高飞行速度，或使用 Alt 降低速度。要更改并保持速度调节器，可以使用 鼠标滚轮向上 或 鼠标滚轮向下 来分别增加或减少速度。

在正交模式下，按住鼠标右键会平移视图。使用 小键盘 5 在透视视图和正交视图之间切换。

使用 Blender 风格的变换快捷键

从 Godot 4.2 开始，可以启用 Blender 风格的快捷键来平移、旋转和缩放节点。在 Blender 中，这些快捷键分别是：

• G 用于平移

• R 用于旋转

• S 用于缩放

在聚焦于 3D 编辑器视口的同时，按下快捷键，可以移动鼠标或输入数字以将选定节点移动指定的 3D 单位量。你可以通过用字母指定特定的轴，然后指定距离（如果使用键盘来输入值），以此来将选中节点的平移限制到特定的轴上。

例如，要将选中物体向上移动 2.5 个单位，请按顺序输入以下序列（Y+ 在 Godot 中是向上，也就是延 Y 轴正方向）：

G-Y-2-.-5-Enter

如果要在 Godot 中使用 Blender 风格的变换快捷键，请转到编辑器设置的 快捷键 选项卡，然后在 Spatial Editor 部分中进行以下调整：

• 将开始平移变换绑定到 G。

• 将开始旋转变换绑定到 R。

• 将开始缩放变换绑定到 S。

• 最后，取消 缩放模式 快捷键的绑定，使其快捷键不会与 开始旋转变换 冲突。

小技巧

更多快捷键可以在 3D / 空间编辑器 页面找到。

Node3D 节点

Node2D 是 2D 的基础节点。Control 是所有 GUI 的基础节点。同理，3D 引擎中的所有 3D 物体都使用 Node3D 节点。

Node3D 有一个局部变换，它是相对于父节点而言的（只要父节点也是或继承自 Node3D 类型）。这个变换可以以 3×4 的 Transform3D 形式访问，也可以以 3 个 Vector3 成员的形式访问，分别代表位置、欧拉旋转（X、Y、Z 角度）和缩放。

3D 内容

与 2D 中加载图像内容和绘图都非常直观相比，3D 就有所不同，会稍微难一些。3D 内容需要使用特殊的 3D 工具（通常称为数字内容创建工具，Digital Content Creation 工具，简称 DCC）来创建，然后导出到某种交换文件格式，才能被 Godot 导入。这是因为 3D 格式的标准化不及图像。

手动制作的模型（使用 3D 建模软件）

在Godot中可以导入外部工具创建的3D模型。具体取决于格式，你可以导入整个场景（与在3D建模软件中呈现的完全一致），包括其中的动画、骨骼绑定、混合形状，也可以简单地作为资源使用。

参见

关于导入的更多信息见 导入 3D 场景。

生成的几何体

可以直接使用 ArrayMesh 资源创建自定义几何体。只需创建数组并使用 ArrayMesh.add_surface_from_arrays() 函数即可。也可以使用辅助类 SurfaceTool，它提供了更直接的 API 和辅助工具，用于索引、生成法线、切线等。

在任何情况下，这种方法都是为了用于生成静态几何体(不会经常更新的模型)，因为创建顶点数组并将它们提交给3D API具有显著的性能开销。

备注

要了解在 Godot 中进行原型设计或使用外部工具，请参阅 使用 CSG 设计关卡原型。

即时几何体

相反，如果你需要生成经常更新的简单几何体，Godot 提供了一种特殊的 ImmediateMesh 资源，它可以在 MeshInstance3D 节点中使用。这提供了 OpenGL 1.x 风格的即时模式 API 来创建点、线、三角形等。

3D 中的 2D

虽然Godot包装了强大的2D引擎，但许多类型的游戏会使用在3D环境中的2D效果。 通过使用不旋转的固定相机(正交或透视)，可以使用诸如 Sprite3D 和 AnimatedSprite3D 等节点来创建混合了具有3D背景，更逼真的视差，灯光/阴影效果等的2D游戏。

当然，缺点在于与普通2D相比增加了复杂性并降低了与普通2D 相比的性能，以及缺乏进行像素工作时的参考。

环境

除了编辑场景之外，编辑环境通常也很常见。 Godot提供了一个 WorldEnvironment 节点，该节点允许更改背景颜色，模式(就像放一个天空盒时那样)以及应用多种内置处理后效果。 环境可以在Camera中被覆写。

预览环境和灯光

默认情况下，如果 3D 场景中没有 WorldEnvironment 或者 DirectionalLight3D 节点，就会打开对应的预览项，为该场景布光。

预览灯光和预览环境只会在编辑器的场景中显示。运行场景或导出后的项目时不会对场景产生影响。

预览灯光和预览环境可以通过点击顶部菜单中的对应图标来开关。图标右侧画着三个点的下拉菜单中可以调整预览灯光和预览环境的属性。

预览灯光和预览环境可以通过点击顶部菜单中的对应图标来开关。图标右侧画着三个点的下拉菜单中可以调整预览灯光和预览环境的属性。

同一个项目中，不同的场景使用的是相同的预览太阳和预览环境。因此，在这里作出的调整应该适合所有需要预览灯光和预览环境的场景。

相机

无论在 3D 空间中放置多少物体，除非在场景中添加了 Camera3D，否则不会显示任何内容。相机可以在正交或透视投影中工作：

摄像机与父视口或其祖先视口相关联，且仅显示到他们上面。 由于场景树的根是一个视口，默认情况下会在其上显示摄像机，但如果需要子视口(作为渲染目标或画中画)，则需要自己的子摄像头才能显示。

处理多台摄像机时，每个视口都遵循以下规则:

• 如果场景树中没有摄像机，则第一个进入的摄像机将成为活跃摄像机。进入场景的其他摄像机将被忽略（除非它们被设置为 current）。

• 如果相机设置了“current”属性，则无论场景中是否有其他相机，都会使用它。如果该属性已设置，它将变为活动状态，取代之前的摄像机。

• 如果活动摄像机离开了场景树，则按树形顺序排列的第一台摄像机将取代它。

灯光

背景环境发出一些出现在表面上的环境光。然而，如果场景中没有任何光源，除非背景环境非常明亮，否则场景会显得很暗。

大多数室外场景都有平行光（太阳或月亮），而室内场景通常有多个位置光（灯、火把等）。有关在 Godot 中设置灯光的更多信息，请参阅 3D 灯光和阴影。