Merge pull request #9621 from vgezer/intro2d

Add new Introduction to 2D page

tutorials/2d/index.rst

@@ -7,6 +7,7 @@
    :maxdepth: 1
    :name: toc-learn-features-2d
 
+   introduction_to_2d
    canvas_layers
    2d_transforms
 

tutorials/2d/introduction_to_2d.rst

@@ -0,0 +1,316 @@
+.. _doc_introduction_to_2d:
+
+Introduction to 2D
+==================
+
+Godot's 2D game development tools include a dedicated 2D rendering engine, physics system, 
+and features tailored specifically for creating 2D experiences. You can efficiently design 
+levels with the TileMap system, animate characters with 2D sprite or Cutout animation, 
+and leverage 2D lighting for dynamic scene illumination. The built-in 2D particle system 
+allows you to create complex visual effects, and Godot also supports custom shaders to 
+enhance your graphics. These features, combined with Godot's accessibility and 
+flexibility, provide a solid foundation for creating engaging 2D games.
+
+.. figure:: img/2d_platformer_demo.webp
+   
+   2D Platformer Demo available on the Asset Library.
+
+This page will show you the 2D workspace and how you can get to know it.
+
+.. tip:: If you would like to get an introduction to 3D, see :ref:`doc_introduction_to_3d`.
+
+2D workspace
+~~~~~~~~~~~~
+
+You will use the 2D workspace to work with 2D scenes, design levels, or create user 
+interfaces.
+To switch to the 2D workspace, you can either select a 2D node from the scene tree, 
+or use the workspace selector located at the top edge of the editor:
+
+.. image:: img/2d_editor_viewport.webp
+
+Similar to 3D, you can use the tabs below the workspace selector to change between currently 
+opened scenes or create a new one using the plus (+) button. The left and right docks should 
+be familiar from :ref:`editor introduction <toc-editor-interface>`.
+
+Below the scene selector is the main toolbar, and beneath the main toolbar
+is the 2D viewport.
+
+You can drag and drop compatible nodes from the FileSystem dock to add them to the 
+viewport as nodes.
+Dragging and dropping adds the dragged node as a sibling of the selected node 
+(if the root node is selected, adds as a child).
+Keeping :kbd:`Shift` pressed when dropping adds the node as a child of the selected node.
+Holding :kbd:`Alt` when dropping adds the node as a child of the root node.
+If :kbd:`Alt + Shift` is held when dropping, the node type can be selected if 
+applicable.
+
+
+Main toolbar
+------------
+
+Some buttons in the main toolbar are the same as those in the 3D workspace. A brief explanation
+is given with the shortcut if the mouse cursor is hovered over a button for one second. 
+Some buttons may have additional functionality if another keypress is performed. 
+A recap of main functionality of each button with its default shortcut is provided below 
+from left to right:
+
+.. image:: img/2d_toolbar.webp
+
+- **Select Mode** (:kbd:`Q`): Allows selection of nodes in the viewport. Left clicking on a node 
+  in the viewport selects it.
+  Left clicking and dragging a rectangle selects all nodes within the rectangle's boundaries,
+  once released.
+  Holding :kbd:`Shift` while selecting adds more nodes to the selection.
+  Clicking on a selected node while holding :kbd:`Shift` deselects the node.
+  In this mode, you can drag the selected node(s) to move, press :kbd:`Ctrl` to switch to the 
+  rotation mode temporarily, or use the red circles to scale it. If multiple nodes are 
+  selected, only movement and rotation are possible. In this mode, rotation and scaling 
+  will not use the snapping options if snapping is enabled.
+- **Move Mode** (:kbd:`W`): Enables move (or translate) mode for the selected nodes. See 
+  :ref:`doc_introduction_to_2d_the_viewport` for more details.
+- **Rotate Mode** (:kbd:`E`): Enables rotation mode for the selected nodes. See 
+  :ref:`doc_introduction_to_2d_the_viewport` for more details.
+- **Scale Mode** (:kbd:`R`): Enables scaling and displays scaling gizmos in both 
+  axes for the selected node(s). See :ref:`doc_introduction_to_2d_the_viewport` for more details.
+- **Show list of selectable nodes at position clicked**: 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.
+- **Rotation pivot**: Sets the rotation pivot to rotate node(s) around.
+  An added node has its rotation pivot at ``x: 0``, ``y: 0``, by default, with
+  exceptions. For example, the default pivot for a :ref:`Sprite2D <class_Sprite2D>` is its 
+  center if the ``centered`` property is set to ``true``. If you would like to change the 
+  rotation pivot of a node, click this button and choose a new location by left clicking. 
+  The node rotates considering this point. If you have multiple nodes selected, this icon 
+  will add a temporary pivot to be used commonly by all selected nodes. Pressing :kbd:`Shift` 
+  and clicking this button will create the pivot at the center of selected nodes. If any of 
+  the snap options are enabled, the pivot will also snap to them it when dragged.
+- **Pan Mode** (:kbd:`G`): Allows you to navigate in the viewport without accidentally selecting any nodes.
+  In other modes, you can also hold :kbd:`Space` and drag with the left mouse button to do the same.
+- **Ruler Mode**: After enabling, click on the viewport to display the current global 
+  x and y coordinates. Dragging from a position to another one measures the distance in pixels.
+  If you drag diagonally, it will draw a triangle and show the separate distances in terms 
+  of x, y, and total distance to the target, including the angles to the axes in degrees.
+  The :kbd:`R` key also activates the ruler. If snapping is enabled, it also displays the 
+  measurements in terms of grid count:
+
+.. figure:: img/2d_ruler_with_snap.webp
+   
+   Using ruler with snapping enabled.
+
+- **Use Smart Snap**: Toggles smart snapping for move, rotate, and scale modes; and 
+  the rotation pivot. Customize it using the three-dot menu next to the snap tools.
+- **Use Grid Snap**: Toggles snapping to grid for move and scale mode, rotation pivot, 
+  and the ruler. Customize it using the three-dot menu next to the snap tools.
+
+You can customize the grid settings so that move mode, rotate mode, scale mode, ruler, 
+and rotation pivot uses snapping.
+Use the three-dot menu for this:
+
+.. image:: img/2d_snapping_options_menu.webp
+
+- **Use Rotation Snap**: Toggles snapping using the configured rotation setting.
+- **Use Scale Snap**: Toggles snapping using the configured scaling step setting.
+- **Snap Relative**: Toggles the usage of snapping based on the selected node's current 
+  transform values. For example, if the grids are set to 32x32 pixels and if the selected node 
+  is located at ``x: 1, y: 1``, then, enabling this option will temporarily shift the grids by 
+  ``x: 1, y: 1``.
+- **Use Pixel Snap**: Toggles the use of subpixels for snapping. If enabled, the position values 
+  will be integers, disabling will enable subpixel movement as decimal values. For the runtime 
+  property, consider checking `Project Settings > Rendering > 2D > Snapping` property for 
+  Node2D nodes, and `Project Settings > GUI > General > Snap Controls to Pixels` for 
+  Control nodes.
+- **Smart Snapping**: Provides a set of options to snap to specific positions if they are enabled:
+
+  - Snap to Parent: Snaps to parent's edges. For example, scaling a child control node while 
+    this is enabled will snap to the boundaries of the parent.
+  - Snap to Node Anchor: Snaps to the node's anchor. For example, if anchors of a control 
+    node is positioned at different positions, enabling this will snap to the sides and 
+    corners of the anchor.
+  - Snap to Node Sides: Snaps to the node's sides, such as for the rotation pivot or anchor 
+    positioning.
+  - Snap to Node Center: Snaps to the node's center, such as for the rotation pivot or 
+    anchor positioning.
+  - Snap to Other Nodes: Snaps to other nodes while moving or scaling. Useful to align nodes 
+    in the editor.
+  - Snap to Guides: Snaps to custom guides drawn using the horizontal or vertical ruler. More 
+    on the ruler and guides below.
+
+.. image:: img/2d_snapping_options.webp
+
+- **Configure Snap**: Opens the window shown above, offering a set of snapping parameters.
+
+  - Grid Offset: Allows you to shift grids with respect to the origin. ``x`` and ``y`` can 
+    be adjusted separately.
+  - Grid Step: The distance between each grid in pixels. ``x`` and ``y`` can be adjusted separately.
+  - Primary Line Every: The number of grids in-between to draw infinite lines as indication of 
+    main lines.
+  - Rotation Offset: Sets the offset to shift rotational snapping.
+  - Rotation Step: Defines the snapping degree. E.g., 15 means the node will rotate and snap 
+    at multiples of 15 degrees if rotation snap is enabled and the rotate mode is used.
+  - Scale Step: Determines the scaling increment factor. For example, if it is 0.1, it will 
+    change the scaling at 0.1 steps if scaling snap is enabled and the scaling mode is used.
+
+- **Lock selected nodes** (:kbd:`Ctrl + L`). Locks the selected nodes, preventing selection and movement in the 
+  viewport. Clicking the button again (or using :kbd:`Ctrl + Shift + L`) unlocks the selected 
+  nodes. Locked nodes can only be selected in the scene tree.
+  They can easily be identified by a padlock next to their node names in the scene tree. 
+  Clicking on this padlock also unlocks the nodes.
+- **Group selected nodes** (:kbd:`Ctrl + G`). This allows selection of the root node if any 
+  of the children are selected. Using :kbd:`Ctrl + G` ungroups them. Additionally, clicking 
+  the ungroup button in the scene tree performs the same action.
+- **Skeleton Options**: Provides options to work with Skeleton2D and Bone2D.
+
+  - Show Bones: Toggles the visibility of bones for the selected node.
+  - Make Bone2D Node(s) from Node(s): Converts selected node(s) into Bone2D. 
+
+.. seealso:: To learn more about Skeletons, see :ref:`doc_cutout_animation`.
+
+- **Project Camera Override**: Temporarily replaces the active camera in the level 
+  (e.g., the camera following the player) with the camera in the editor's viewport, allowing
+  you to move freely and inspect the level's different parts, while the game is running.
+  
+- **View** menu: Provides options to control the viewport view. Since its options 
+  depend heavily on the viewport, it is covered in the :ref:`doc_introduction_to_2d_the_viewport` 
+  section.
+
+Next to the View menu, additional buttons may be visible. In the toolbar image
+at the beginning of this chapter, an additional *Sprite2D* button appears because a
+Sprite2D is selected. This menu provides some quick actions and tools to
+work on a specific node or selection. For example, while drawing a polygon, it
+provides buttons to add, modify, or remove points.
+
+
+Coordinate system
+-----------------
+
+In the 2D editor, unlike 3D, there are only two axes: ``x`` and ``y``. Also, the viewing 
+angle is fixed.
+
+In the viewport, you will see two lines in two colors going across the screen infinitely: 
+red for the x-axis, and green for the y-axis.
+In Godot, going right and down are positive directions.
+Where these two lines intersect is the origin: ``x: 0, y: 0``.
+
+A root node will have its origin at this position once added.
+Switching to the `move` or `scale` modes after selecting a node will display the gizmos at the 
+node's offset position.
+The gizmos will point to the positive directions of the x and y axes.
+In the move mode, you can drag the green line to move only in the ``y`` axis.
+Similarly, you can hold the red line to move only in the ``x`` axis.
+
+In the scale mode, the gizmos will have a square shape. You can hold and drag the green and 
+red squares to scale the nodes in the ``y`` or ``x`` axes.
+Dragging in a negative direction flips the node horizontally or vertically.
+
+.. _doc_introduction_to_2d_the_viewport:
+
+2D Viewport
+-----------
+
+The viewport will be the area you spend the most time if you plan to design levels or user 
+interfaces visually:
+
+.. image:: img/2d_editor_viewport_with_viewmenu.webp
+
+Middle-clicking and dragging the mouse will pan the view. 
+The scrollbars on the right or bottom of the viewport also move the view.
+Alternatively, the :kbd:`G` or :kbd:`Space` keys can be used.
+If you enable `Editor Settings > Editors > Panning > Simple Panning`, you can activate
+panning directly with :kbd:`Space` only, without requiring dragging.
+
+The viewport has buttons on the top-left.
+**Center View** centers the selected node(s) in the screen. Useful if you have a large scene 
+with many nodes, and want to see the node selected in the scene tree.
+Next to it are the zoom controls. **-** zooms out, **+** zooms in, and clicking on the number 
+with percentage defaults to 100%.
+Alternatively, you can use middle-mouse scrolling to zoom in (scroll up) and out (scroll down).
+
+The black bars at the viewport's left and top edges are the **rulers**. You can use them to 
+orient yourself in the viewport.
+By default, the rulers will display the pixel coordinates of the viewport, numbered at 
+100 pixel steps. Changing the zoom factor will change the shown values.
+Enabling `Grid Snap` or changing the snapping options will update the ruler's scaling and 
+the shown values.
+
+You can also create multiple custom guides to help you make measurements or align 
+nodes with them:
+
+.. image:: img/2d_editor_guidelines.webp
+
+If you have at least one node in the scene, you can create guides by dragging from the horizontal 
+or vertical ruler towards the viewport. A purple guide will appear, showing its position, and will 
+remain there when you release the mouse. You can create both horizontal and vertical guides 
+simultaneously by dragging from the gray square at the rulers' intersection. Guides can be 
+repositioned by dragging them back to their respective rulers, and they can be removed by 
+dragging them all the way back to the ruler.
+
+You can also enable snapping to the created guides using the `Smart Snap` menu.
+
+.. note:: If you cannot create a line, or do not see previously created guides, make sure that 
+          they are visible by checking the `View` menu of the viewport. :kbd:`Y` toggles their visibility, 
+          by default. Also, make sure you have at least one node in the scene.
+
+Depending on the tool chosen in the toolbar, left-clicking will have a primary action in the 
+viewport.
+For example, the `Select Mode` will select the left-clicked node in the viewport.
+Sometimes, left-clicking can be combined with a modifier (e.g., :kbd:`Ctrl`, or :kbd:`Shift`) to 
+perform secondary actions.
+For example, keeping :kbd:`Shift` pressed while dragging a node in the Select or Move modes will 
+try to snap the node in a single axis while moving.
+
+Right clicking in the viewport provides two options to create a node or instantiate a scene 
+at the chosen position.
+If at least one node is selected, right clicking also provides the option to move the selected 
+node(s) to this position.
+
+
+Viewport has a **View** menu which provides several options to change the look of the viewport:
+
+- **Grid**: Allows you to show grids all the time, only when using snapping, or not at all. You 
+  can also toggle them with the provided option.
+- **Show Helpers**: Toggles the temporary display of an outline of the node, with the previous 
+  transform properties (position, scaling, or rotation) if a transform operation has been 
+  initiated. For `Control` nodes, it also shows the sizing parameters. Useful to see the deltas.
+- **Show Rulers**: Toggles the visibility of horizontal and vertical rulers. See 
+  :ref:`doc_introduction_to_2d_the_viewport` more on rulers.
+- **Show Guides**: Toggles the visibility of created guides. See 
+  :ref:`doc_introduction_to_2d_the_viewport` for on how to create them.
+- **Show Origin**: Toggles the display of the green and red origin lines drawn at ``x: 0, y: 0``.
+- **Show Viewport**: Toggles the visibility of the game's default 
+  viewport, indicated by an indigo-colored rectangle. It is also the default window size on desktop 
+  platforms, which can be changed by going to `Project Settings > Display > Window > Size` and 
+  setting `Viewport Width` and `Viewport Height`.
+- **Gizmos**: Toggles the visibility of `Position` (shown with cross icon), `Lock` 
+  (shown with padlock), `Groups` (shown with two squares), and `Transformation` (shown with 
+  green and red lines) indicators.
+- **Center Selection**: The same as the **Center View** button inside the viewport. Centers the selected 
+  node(s) in the view. :kbd:`F` is the default shortcut.
+- **Frame to Selection**: Similar to `Center Selection`, but also changes the zoom factor to fit the 
+  contents in the screen. :kbd:`Shift + F` is the default shortcut.
+- **Clear Guides**: Deletes all guides from the screen. You will need to recreate them if 
+  you plan to use them later. 
+- **Preview Canvas Scale**: Toggles the preview for scaling of canvas in the editor when the zoom 
+  factor or view of the viewport changes. Useful to see how the controls will look like after scaling 
+  and moving, without running the game.
+- **Preview Theme**: Allows to choose from the available themes to change the look of control items 
+  in the editor, without requiring to run the game.
+
+
+Node2D and Control node
+~~~~~~~~~~~~~~~~~~~~~~~
+
+:ref:`CanvasItem <class_CanvasItem>` is the base node for 2D. :ref:`Node2D <class_Node2D>` is the base node
+for 2D game objects, and :ref:`Control <class_Control>` is the base node 
+for everything GUI. For 3D, Godot uses the :ref:`Node3D <class_Node3D>` node.
+
+3D in 2D
+--------
+
+It is possible to display 3D scenes in 2D screen. This is achieved by adding a 
+:ref:`SubViewport <class_SubViewport>` as a child.
+Then, you can drag a 3D scene as a child of the SubViewport:
+
+.. image:: img/3d_in_2d_demo_editor.webp
+
+.. seealso:: You can check the demo on: `3D in 2D Viewport demo <https://godotengine.org/asset-library/asset/2804>`__.