introduction_to_3d.rst 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445
  1. .. _doc_introduction_to_3d:
  2. Introduction to 3D
  3. ==================
  4. Creating a 3D game can be challenging. That extra Z coordinate makes
  5. many of the common techniques that helped to make 2D games simpler no
  6. longer work. To aid in this transition, it is worth mentioning that
  7. Godot uses similar APIs for 2D and 3D. Most nodes are the same and
  8. are present in both 2D and 3D versions. In fact, it is worth checking
  9. the 3D platformer tutorial, or the 3D kinematic character tutorials,
  10. which are almost identical to their 2D counterparts.
  11. .. figure:: img/godot-tps-demo.webp
  12. :align: center
  13. :alt: An example 3D game demo created using Godot
  14. Godot Third Person Shooter (TPS) Demo, available on the
  15. `Github repository <https://github.com/godotengine/tps-demo>`__ or the
  16. :ref:`Asset Library <doc_project_manager_downloading_demos>`.
  17. In 3D, math is a little more complex than in 2D. For an introduction to the
  18. relevant math written for game developers, not mathemeticians or engineers,
  19. check out :ref:`doc_vector_math` and :ref:`doc_using_transforms`.
  20. 3D workspace
  21. ------------
  22. Editing 3D scenes is done in the 3D workspace. This workspace can be selected
  23. manually, but it will be automatically selected when a Node3D node is
  24. selected.
  25. .. image:: img/tuto_3d3.webp
  26. Similar to 2D, the tabs below the workspace selector are used to change between
  27. currently opened scenes or create a new one using the plus (+) button. The left and
  28. right docks should be familiar from :ref:`editor introduction <doc_editor_introduction>`.
  29. Below the scene selector, the main toolbar is visible, and beneath the main toolbar
  30. is the 3D viewport.
  31. Main toolbar
  32. ~~~~~~~~~~~~
  33. Some buttons in the main toolbar are the same as those in the 2D workspace. A brief explanation
  34. is given with the shortcut if the mouse cursor is hovered over a button for one second.
  35. Some buttons may have additional functionality if another keypress is performed. A recap
  36. of main functionality of each button with its default shortcut is provided below from
  37. left to right:
  38. .. image:: img/3d_toolbar.webp
  39. - **Select Mode** (:kbd:`Q`): Allows selection of nodes in the viewport. Left clicking
  40. on a node to select one. Left clicking and dragging a rectangle selects all
  41. nodes within the rectangle's boundaries, once released.
  42. Holding :kbd:`Shift` while selecting adds more nodes to the selection.
  43. Clicking on a selected node while holding :kbd:`Shift` deselects the node.
  44. In this mode, you can use the gizmos to perform movement or rotation.
  45. - **Move Mode** (:kbd:`W`): Enables move (or translate) mode for the selected nodes.
  46. See :ref:`doc_introduction_to_3d_space_and_manipulation` for more details.
  47. - **Rotate Mode** (:kbd:`E`): Enables rotation mode for the selected nodes. See
  48. :ref:`doc_introduction_to_3d_space_and_manipulation` for more details.
  49. - **Scale Mode** (:kbd:`R`): Enables scaling and displays scaling gizmos in different
  50. axes for the selected nodes. See :ref:`doc_introduction_to_3d_space_and_manipulation`
  51. for more details.
  52. - **Show the list of selectable nodes at the clicked position**: As the description suggests,
  53. this provides a list of selectable nodes at the clicked position as a context menu,
  54. if there is more than one node in the clicked area.
  55. - **Lock** (:kbd:`Ctrl + L`) the selected nodes, preventing selection and movement in the viewport.
  56. Clicking the button again (or using :kbd:`Ctrl + Shift + L`) unlocks the selected nodes.
  57. Locked nodes can only be selected in the scene tree.
  58. They can easily be identified with a padlock next to their node names in the scene tree.
  59. Clicking on this padlock also unlocks the nodes.
  60. - **Group selected nodes** (:kbd:`Ctrl + G`). This allows selection of the root node if
  61. any of the children are selected.
  62. Using :kbd:`Ctrl + G` ungroups them. Additionally, clicking the ungroup button in
  63. the scene tree performs the same action.
  64. - **Ruler Mode** (:kbd:`M`): When enabled you can click and drag to measure distance in the scene
  65. in meters.
  66. - **Use Local Space** (:kbd:`T`): If enabled, gizmos of a node are drawn using the current node's
  67. rotation angle instead of the :ref:`global viewport axes <doc_introduction_to_3d_coordinate_system>`.
  68. - **Use Snap** (:kbd:`Y`): If enabled, movement, and rotation snap to grid. Snapping can also
  69. temporarily be activated using :kbd:`Ctrl` while performing the action.
  70. The settings for changing snap options are explained below.
  71. - **Toggle preview sunlight**: If no DirectionalLight3D exist in the scene, a preview
  72. of sunlight can be used as a light source. See
  73. :ref:`doc_introduction_to_3d_preview_environment_light` for more details.
  74. - **Toggle preview environment**: If no WorldEnvironment exists in the scene, a preview of the
  75. environment can be used as a placeholder. See
  76. :ref:`doc_introduction_to_3d_preview_environment_light` for more details.
  77. - **Edit Sun and Environment Settings (three dots)**: Opens the menu to configure preview
  78. sunlight and environment settings. See :ref:`doc_introduction_to_3d_preview_environment_light`
  79. for more details.
  80. - **Transform menu**: It has three options:
  81. - *Snap Object to Floor*: Snaps an object to a solid floor.
  82. - *Transform Dialog*: Opens a dialog to adjust transform parameters (translate, rotate, scale,
  83. and transform) manually.
  84. - *Snap Settings*: Allows you to change transform, rotate snap (in degrees), and scale snap
  85. (in percent) settings.
  86. - **View menu**: Controls the view options and enables additional viewports:
  87. .. image:: img/tuto_3d6.webp
  88. In this menu, you can also show/hide grids, which are set to 1x1 meter by default,
  89. and the origin, where the blue, green, and red axis lines intersect.
  90. Moreover, specific types of gizmos can be toggled in this menu.
  91. .. image:: img/tuto_3d6_2.webp
  92. An open eye means that the gizmo is visible, a closed eye means it is hidden.
  93. A half-open eye means that it is also visible through opaque surfaces.
  94. Clicking on *Settings* in this view menu opens a window to change the
  95. *Vertical Field of View (VFOV)* parameter
  96. (in degrees), *Z-Near*, and *Z-Far* values.
  97. Next to the View menu, additional buttons may be visible. In the toolbar image
  98. at the beginning of this chapter, an additional *Mesh* button appears because a
  99. MeshInstance3D is selected. This menu provides some quick actions or tools to
  100. work on a specific node or selection.
  101. View menu of viewport
  102. ~~~~~~~~~~~~~~~~~~~~~
  103. Below the *Select* tool, in the 3D viewport, clicking on the three dots opens the
  104. **View menu** for the viewport.
  105. Hiding all shown gizmos in the editor's 3D view can also be performed through
  106. this menu:
  107. .. image:: img/tuto_3d6_1.webp
  108. This menu also displays the current view type and enables quick adjustment of the
  109. viewport's viewing angle. Additionally, it offers options to modify the appearance of
  110. nodes within the viewport.
  111. .. _doc_introduction_to_3d_coordinate_system:
  112. Coordinate system
  113. ~~~~~~~~~~~~~~~~~
  114. Godot uses the `metric <https://en.wikipedia.org/wiki/Metric_system>`__
  115. system for everything in 3D, with 1 unit being equal to 1 meter.
  116. Physics and other areas are tuned for this scale. Therefore, attempting to use a
  117. different scale is usually a bad idea (unless you know what you are doing).
  118. When working with 3D assets, it's always best to work in the correct scale (set
  119. the unit to metric in your 3D modeling software). Godot allows scaling
  120. post-import and, while this works in most cases, in rare situations it may
  121. introduce floating-point precision issues (and thus, glitches or artifacts) in
  122. delicate areas such as rendering or physics. Make sure your artists always work
  123. in the right scale!
  124. The Y coordinate is used for "up". As for the horizontal X/Z axes, Godot uses a
  125. **right-handed** coordinate system. This means that for most objects that need
  126. alignment (such as lights or cameras), the Z axis is used as a "pointing
  127. towards" direction. This convention roughly means that:
  128. - **X** is sides
  129. - **Y** is up/down
  130. - **Z** is front/back
  131. See this chart for comparison with other 3D software:
  132. .. figure:: img/introduction_to_3d_coordinate_systems.webp
  133. :align: center
  134. :alt: 3D coordinate systems comparison chart
  135. Image by `Freya Holmér <https://twitter.com/FreyaHolmer>`__
  136. .. _doc_introduction_to_3d_space_and_manipulation:
  137. Space and manipulation gizmos
  138. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  139. Moving, rotating, and scaling objects in the 3D view is done through the
  140. manipulator gizmos.
  141. Each axis is represented by a color: Red, Green, Blue represent X, Y, Z
  142. respectively. This convention applies to the grid and other gizmos too
  143. (and also to the shader language, ordering of components for
  144. Vector3, Color, etc.).
  145. .. image:: img/tuto_3d5.webp
  146. Some useful keybindings:
  147. - To snap placement or rotation, press :kbd:`Ctrl` while moving, scaling,
  148. or rotating.
  149. - To center the view on the selected object, press :kbd:`F`.
  150. In the viewport, the arrows can be clicked and held to move the object on an axis.
  151. The arcs can be clicked and held to rotate the object.
  152. To lock one axis and move the object freely in the other two axes, the colored rectangles
  153. can be clicked, held, and dragged.
  154. If the transform mode is changed from *Select Mode* to *Scale Mode*, the arrows will be
  155. replaced by cubes, which can be dragged to scale an object as if the object is being moved.
  156. Navigating the 3D environment
  157. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  158. In 3D environments, it is often important to adjust the viewpoint or angle
  159. from which you are viewing the scene.
  160. In Godot, navigating the 3D environment in the viewport (or spatial editor)
  161. can be done in multiple ways.
  162. The default 3D scene navigation controls are similar to Blender (aiming to
  163. have some sort of consistency in the free software pipeline), but
  164. options are included to customize mouse buttons and behavior to be
  165. similar to other tools in the Editor Settings. To change the controls
  166. to Maya or Modo controls, you can navigate to **Editor Settings > Editors > 3D**.
  167. Then, under *Navigation*, search for *Navigation Scheme*.
  168. .. image:: img/tuto_3d4.webp
  169. Using the default settings, the following shortcuts control how one can
  170. navigate in the viewport:
  171. Pressing the middle mouse button and dragging the mouse allows you to orbit around
  172. the center of what is on the screen.
  173. It is also possible to left-click and hold the manipulator gizmo located
  174. on the top right of the viewport to orbit around the center:
  175. .. image:: img/tuto_3d_gizmo.webp
  176. Left-clicking on one of the colored circles will set the view to the chosen
  177. orthogonal and the viewport's view menu will be updated accordingly.
  178. .. image:: img/tuto_3d_updated_view_menu.webp
  179. If the *Perspective* view is enabled on the viewport (can be seen on the viewport's View menu,
  180. not the View menu on the main toolbar), holding down the right mouse button on the viewport
  181. or pressing :kbd:`Shift + F` switches to "free-look" mode.
  182. In this mode you can move the mouse to look around, use the :kbd:`W` :kbd:`A`
  183. :kbd:`S` :kbd:`D` keys to fly around the view, :kbd:`E` to go up, and :kbd:`Q` to
  184. go down. To disable this mode, release the right mouse button or press
  185. :kbd:`Shift + F` again.
  186. In the free-look mode, you can temporarily increase the flying
  187. speed using :kbd:`Shift` or decrease it using :kbd:`Alt`. To change and keep the
  188. speed modifier use :kbd:`mouse wheel up` or :kbd:`mouse wheel down`, to increase or
  189. decrease it, respectively.
  190. In orthogonal mode, holding the right mouse button will pan the view instead.
  191. Use :kbd:`Keypad 5` to toggle between perspective and orthogonal view.
  192. Using Blender-style transform shortcuts
  193. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  194. Since Godot 4.2, you can enable Blender-style shortcuts for translating,
  195. rotating and scaling nodes. In Blender, these shortcuts are:
  196. - :kbd:`G` for translating
  197. - :kbd:`R` for rotating
  198. - :kbd:`S` for scaling
  199. After pressing a shortcut key while focusing on the 3D editor viewport,
  200. move the mouse or enter a number to move the selected node(s) by the
  201. specified amount in 3D units. You can constrain movement to a specific
  202. axis by specifying the axis as a letter, then the distance (if entering a
  203. value with the keyboard).
  204. For instance, to move the selection upwards by 2.5 units, enter the
  205. following sequence in order (Y+ is upwards in Godot):
  206. :kbd:`G`-:kbd:`Y`-:kbd:`2`-:kbd:`.`-:kbd:`5`-:kbd:`Enter`
  207. To use Blender-style transform shortcuts in Godot, go to the Editor Settings'
  208. **Shortcuts** tab, then in the Spatial Editor section:
  209. - Bind **Begin Translate Transformation** to :kbd:`G`.
  210. - Bind **Begin Rotate Transformation** to :kbd:`R`.
  211. - Bind **Begin Scale Transformation** to :kbd:`S`.
  212. - Finally, unbind **Scale Mode** so that its shortcut won't conflict with
  213. **Begin Rotate Transformation**.
  214. .. tip:: More shortcuts can be found on the
  215. :ref:`doc_default_key_mapping_shortcuts_spatial_editor` page.
  216. Node3D node
  217. -----------
  218. :ref:`Node2D <class_Node2D>` is the base node for 2D.
  219. :ref:`Control <class_Control>` is the base node for everything GUI.
  220. Following this reasoning, the 3D engine uses the :ref:`Node3D <class_Node3D>`
  221. node for everything 3D.
  222. .. image:: img/tuto_3d1.webp
  223. Node3Ds have a local transform, which is relative to the parent
  224. node (as long as the parent node is also of **or inherits from** the type
  225. Node3D). This transform can be accessed as a 3×4
  226. :ref:`Transform3D <class_Transform3D>`, or as 3 :ref:`Vector3 <class_Vector3>`
  227. members representing location, Euler rotation (X, Y and Z angles) and
  228. scale.
  229. .. image:: img/tuto_3d2.webp
  230. 3D content
  231. ----------
  232. Unlike 2D, where loading image content and drawing is straightforward, 3D is a
  233. little more difficult. The content needs to be created with special 3D tools
  234. (also called Digital Content Creation tools, or DCCs) and exported to an
  235. exchange file format to be imported in Godot. This is required since 3D formats
  236. are not as standardized as images.
  237. Manually authored models (using 3D modeling software)
  238. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  239. .. FIXME: Needs update to properly description Godot 3.x workflow
  240. (used to reference a non existing doc_importing_3d_meshes importer).
  241. It is possible to import 3D models in Godot created in external tools.
  242. Depending on the format, you can import entire scenes (exactly as they look in
  243. the 3D modeling software), including animation, skeletal rigs, blend shapes, or
  244. as simple resources.
  245. .. seealso:: See :ref:`doc_importing_3d_scenes` for more on importing.
  246. Generated geometry
  247. ~~~~~~~~~~~~~~~~~~
  248. It is possible to create custom geometry by using the
  249. :ref:`ArrayMesh <class_ArrayMesh>` resource directly. Simply create your arrays
  250. and use the :ref:`ArrayMesh.add_surface_from_arrays() <class_ArrayMesh_method_add_surface_from_arrays>`
  251. function. A helper class is also available, :ref:`SurfaceTool <class_SurfaceTool>`,
  252. which provides a more straightforward API and helpers for indexing,
  253. generating normals, tangents, etc.
  254. In any case, this method is meant for generating static geometry (models
  255. that will not be updated often), as creating vertex arrays and
  256. submitting them to the 3D API has a significant performance cost.
  257. .. note:: To learn about prototyping inside Godot or using external tools, see
  258. :ref:`doc_csg_tools`.
  259. Immediate geometry
  260. ~~~~~~~~~~~~~~~~~~
  261. If, instead, you need to generate simple geometry that will be updated often,
  262. Godot provides a special :ref:`ImmediateMesh <class_ImmediateMesh>` resource
  263. that can be used in a :ref:`MeshInstance3D <class_MeshInstance3D>` node.
  264. This provides an OpenGL 1.x-style immediate-mode API to create points, lines,
  265. triangles, etc.
  266. 2D in 3D
  267. ~~~~~~~~
  268. While Godot packs a powerful 2D engine, many types of games use 2D in a
  269. 3D environment. By using a fixed camera (either orthogonal or
  270. perspective) that does not rotate, nodes such as
  271. :ref:`Sprite3D <class_Sprite3D>` and
  272. :ref:`AnimatedSprite3D <class_AnimatedSprite3D>`
  273. can be used to create 2D games that take advantage of mixing with 3D
  274. backgrounds, more realistic parallax, lighting/shadow effects, etc.
  275. The disadvantage is, of course, that added complexity and reduced
  276. performance in comparison to plain 2D, as well as the lack of reference
  277. of working in pixels.
  278. Environment
  279. -----------
  280. Besides editing a scene, it is often common to edit the environment.
  281. Godot provides a :ref:`WorldEnvironment <class_WorldEnvironment>`
  282. node that allows changing the background color, mode (as in, put a
  283. skybox), and applying several types of built-in post-processing effects.
  284. Environments can also be overridden in the Camera.
  285. .. _doc_introduction_to_3d_preview_environment_light:
  286. Preview environment and light
  287. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  288. By default, any 3D scene that doesn't have a :ref:`WorldEnvironment <class_WorldEnvironment>`
  289. node, or a :ref:`DirectionalLight3D <class_DirectionalLight3D>`, will have
  290. a preview turned on for what it's missing to light the scene.
  291. The preview light and environment will only be visible in the scene while
  292. in the editor. If you run the scene or export the project they will not
  293. affect the scene.
  294. The preview light and environment can be turned on or off from the top menu
  295. by clicking on their respective icon.
  296. .. image:: img/tuto_3d8.webp
  297. The three dots dropdown menu next to those icons can be used to adjust the properties
  298. of the preview environment and light if they are enabled.
  299. .. image:: img/tuto_3d9.webp
  300. The same preview sun and environment is used for every scene in the same project,
  301. So only make adjustments that would apply to all of the scenes you will need a preview
  302. light and environment for.
  303. Cameras
  304. ~~~~~~~
  305. No matter how many objects are placed in the 3D space, nothing will be
  306. displayed unless a :ref:`Camera3D <class_Camera3D>` is
  307. also added to the scene. Cameras can work in either orthogonal or
  308. perspective projections:
  309. .. image:: img/tuto_3d10.webp
  310. Cameras are associated with (and only display to) a parent or grandparent
  311. viewport. Since the root of the scene tree is a viewport, cameras will
  312. display on it by default, but if sub-viewports (either as render target
  313. or picture-in-picture) are desired, they need their own children cameras
  314. to display.
  315. .. image:: img/tuto_3d11.png
  316. When dealing with multiple cameras, the following rules are enforced for
  317. each viewport:
  318. - If no cameras are present in the scene tree, the first one that
  319. enters it will become the active camera. Further cameras entering the
  320. scene will be ignored (unless they are set as *current*).
  321. - If a camera has the "*current*" property set, it will be used
  322. regardless of any other camera in the scene. If the property is set,
  323. it will become active, replacing the previous camera.
  324. - If an active camera leaves the scene tree, the first camera in
  325. tree-order will take its place.
  326. Lights
  327. ~~~~~~
  328. The background environment emits some ambient light which appears on surfaces.
  329. Still, without any light sources placed in the scene, the scene will appear
  330. quite dark unless the background environment is very bright.
  331. Most outdoor scenes have a directional light (the sun or moon), while indoor
  332. scenes typically have several positional lights (lamps, torches, …).
  333. See :ref:`doc_lights_and_shadows` for more information on setting up lights in Godot.