Merge pull request #11101 from n-pigeon/spatial-doc

Documented Spatial node.

1 files changed, 45 insertions, 4 deletions

diff --git a/doc/base/classes.xml b/doc/base/classes.xml
index 4596c5f5b3..4b8ff98843 100644
--- a/doc/base/classes.xml
+++ b/doc/base/classes.xml
@@ -45514,16 +45514,17 @@
 </class>
 <class name="Spatial" inherits="Node" category="Core">
 	<brief_description>
-		Base class for all 3D nodes.
+		Most basic 3D game object, parent of all 3D related nodes.
 	</brief_description>
 	<description>
-		Spatial is the base for every type of 3D [Node]. It contains a 3D [Transform] which can be set or get as local or global. If a Spatial [Node] has Spatial children, their transforms will be relative to the parent.
+		Most basic 3D game object, with a 3D [Transform] and visibility settings. All 3D physics nodes and sprites inherit from Spatial. Use Spatial as a parent node to move, scale, rotate and show/hide children in a 3D project.
 	</description>
 	<methods>
 		<method name="get_gizmo" qualifiers="const">
 			<return type="SpatialGizmo">
 			</return>
 			<description>
+				Return the SpatialGizmo for this node. Used for example in [EditorSpatialGizmo] as custom visualization and editing handles in Editor.
 			</description>
 		</method>
 		<method name="get_global_transform" qualifiers="const">
@@ -45577,6 +45578,7 @@
 			<return type="World">
 			</return>
 			<description>
+				Return current [World] resource this Spatial node is registered to.
 			</description>
 		</method>
 		<method name="global_rotate">
@@ -45587,6 +45589,7 @@
 			<argument index="1" name="radians" type="float">
 			</argument>
 			<description>
+				Rotate current node along normal [Vector3] by angle in radians in Global space.
 			</description>
 		</method>
 		<method name="global_translate">
@@ -45595,42 +45598,49 @@
 			<argument index="0" name="offset" type="Vector3">
 			</argument>
 			<description>
+				Move current node by [Vector3] offset in Global space.
 			</description>
 		</method>
 		<method name="hide">
 			<return type="void">
 			</return>
 			<description>
+				Disable rendering of this node. Change Spatial Visible property to false.
 			</description>
 		</method>
 		<method name="is_local_transform_notification_enabled" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+				Returns whether node sends notification that its local transformation changed. Spatial will not propagate this by default.
 			</description>
 		</method>
 		<method name="is_set_as_toplevel" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+				Returns whether this node is set as Toplevel, ignoring its parent node transformations.
 			</description>
 		</method>
 		<method name="is_transform_notification_enabled" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+				Returns whether node sends notification that its transformation changed. Spatial will not propagate this by default.
 			</description>
 		</method>
 		<method name="is_visible" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+				Returns whether this node is set to be visible.
 			</description>
 		</method>
 		<method name="is_visible_in_tree" qualifiers="const">
 			<return type="bool">
 			</return>
 			<description>
+				Returns whether this node is visible, taking into consideration that its parents visibility.
 			</description>
 		</method>
 		<method name="look_at">
@@ -45641,6 +45651,7 @@
 			<argument index="1" name="up" type="Vector3">
 			</argument>
 			<description>
+				Rotates itself to point into direction of target position. Operations take place in global space.
 			</description>
 		</method>
 		<method name="look_at_from_pos">
@@ -45653,12 +45664,14 @@
 			<argument index="2" name="up" type="Vector3">
 			</argument>
 			<description>
+				Moves itself to specified position and then rotates itself to point into direction of target position. Operations take place in global space.
 			</description>
 		</method>
 		<method name="orthonormalize">
 			<return type="void">
 			</return>
 			<description>
+				Reset this node transformations (like scale, skew and taper) preserving its rotation and translation. Performs orthonormalization on this node [Transform3D].
 			</description>
 		</method>
 		<method name="rotate">
@@ -45669,6 +45682,7 @@
 			<argument index="1" name="radians" type="float">
 			</argument>
 			<description>
+				Rotates node in local space on given normal [Vector3] by angle in radians.
 			</description>
 		</method>
 		<method name="rotate_x">
@@ -45677,6 +45691,7 @@
 			<argument index="0" name="radians" type="float">
 			</argument>
 			<description>
+				Rotates node in local space on X axis by angle in radians.
 			</description>
 		</method>
 		<method name="rotate_y">
@@ -45685,6 +45700,7 @@
 			<argument index="0" name="radians" type="float">
 			</argument>
 			<description>
+				Rotates node in local space on Y axis by angle in radians.
 			</description>
 		</method>
 		<method name="rotate_z">
@@ -45693,6 +45709,7 @@
 			<argument index="0" name="radians" type="float">
 			</argument>
 			<description>
+				Rotates node in local space on Z axis by angle in radians.
 			</description>
 		</method>
 		<method name="set_as_toplevel">
@@ -45701,6 +45718,7 @@
 			<argument index="0" name="enable" type="bool">
 			</argument>
 			<description>
+				Makes this node ignore its parents tranformations. Node tranformations are only in global space.
 			</description>
 		</method>
 		<method name="set_gizmo">
@@ -45709,6 +45727,7 @@
 			<argument index="0" name="gizmo" type="SpatialGizmo">
 			</argument>
 			<description>
+				Set [SpatialGizmo] for this node. Used for example in [EditorSpatialGizmo] as custom visualization and editing handles in Editor.
 			</description>
 		</method>
 		<method name="set_global_transform">
@@ -45717,13 +45736,14 @@
 			<argument index="0" name="global" type="Transform">
 			</argument>
 			<description>
-				Set the transform globally, relative to worldspace.
+				Set the transform globally, relative to world space.
 			</description>
 		</method>
 		<method name="set_identity">
 			<return type="void">
 			</return>
 			<description>
+				Reset all tranformations for this node. Set its [Transform3D] to identity matrix.
 			</description>
 		</method>
 		<method name="set_ignore_transform_notification">
@@ -45732,6 +45752,7 @@
 			<argument index="0" name="enabled" type="bool">
 			</argument>
 			<description>
+				Set whether this node ignores notification that its transformation changed.
 			</description>
 		</method>
 		<method name="set_notify_local_transform">
@@ -45740,6 +45761,7 @@
 			<argument index="0" name="enable" type="bool">
 			</argument>
 			<description>
+				Set whether this node sends notification that its local transformation changed. Spatial will not propagate this by default.
 			</description>
 		</method>
 		<method name="set_notify_transform">
@@ -45748,6 +45770,7 @@
 			<argument index="0" name="enable" type="bool">
 			</argument>
 			<description>
+				Set whether this node sends notification that its transformation changed. Spatial will not propagate this by default.
 			</description>
 		</method>
 		<method name="set_rotation">
@@ -45774,6 +45797,7 @@
 			<argument index="0" name="scale" type="Vector3">
 			</argument>
 			<description>
+				Set the scale.
 			</description>
 		</method>
 		<method name="set_transform">
@@ -45805,6 +45829,7 @@
 			<return type="void">
 			</return>
 			<description>
+				Enable rendering of this node. Change Spatial Visible property to false.
 			</description>
 		</method>
 		<method name="to_global" qualifiers="const">
@@ -45813,6 +45838,7 @@
 			<argument index="0" name="local_point" type="Vector3">
 			</argument>
 			<description>
+				Tranform [Vector3] from this node local space to world space.
 			</description>
 		</method>
 		<method name="to_local" qualifiers="const">
@@ -45821,6 +45847,7 @@
 			<argument index="0" name="global_point" type="Vector3">
 			</argument>
 			<description>
+				Tranform [Vector3] from world space to this node local space.
 			</description>
 		</method>
 		<method name="translate">
@@ -45829,46 +45856,60 @@
 			<argument index="0" name="offset" type="Vector3">
 			</argument>
 			<description>
+				Change node position by given offset [Vector3].
 			</description>
 		</method>
 		<method name="update_gizmo">
 			<return type="void">
 			</return>
 			<description>
+				Update [SpatialGizmo] of this node.
 			</description>
 		</method>
 	</methods>
 	<members>
 		<member name="global_transform" type="Transform" setter="set_global_transform" getter="get_global_transform" brief="">
+			World space (global) [Transform] of this node.
 		</member>
 		<member name="rotation" type="Vector3" setter="set_rotation" getter="get_rotation" brief="">
+			Local euler rotation in radians of this node.
 		</member>
 		<member name="rotation_deg" type="Vector3" setter="set_rotation_deg" getter="get_rotation_deg" brief="">
+			Local euler rotation in degrees of this node.
 		</member>
 		<member name="scale" type="Vector3" setter="set_scale" getter="get_scale" brief="">
+			Local scale of this node.
 		</member>
 		<member name="transform" type="Transform" setter="set_transform" getter="get_transform" brief="">
+			Local space [Transform] of this node.
 		</member>
 		<member name="translation" type="Vector3" setter="set_translation" getter="get_translation" brief="">
+			Local translation of this node.
 		</member>
 		<member name="visible" type="bool" setter="set_visible" getter="is_visible" brief="">
+			Visibility of this node. Toggles if this node is rendered.
 		</member>
 	</members>
 	<signals>
 		<signal name="visibility_changed">
 			<description>
+				Emitted when node visibility changed.
 			</description>
 		</signal>
 	</signals>
 	<constants>
 		<constant name="NOTIFICATION_TRANSFORM_CHANGED" value="29" enum="">
-			Spatial nodes receive this notification with their global transform changes. This means that either the current or a parent node changed its transform.
+			Spatial nodes receive this notification when their global transform changes. This means that either the current or a parent node changed its transform.
+			In order for NOTIFICATION_TRANSFORM_CHANGED to work user first needs to ask for it, with set_notify_transform(true).
 		</constant>
 		<constant name="NOTIFICATION_ENTER_WORLD" value="41" enum="">
+			Spatial nodes receive this notification when they are registered to new [World] resource.
 		</constant>
 		<constant name="NOTIFICATION_EXIT_WORLD" value="42" enum="">
+			Spatial nodes receive this notification when they are unregistered from current [World] resource.
 		</constant>
 		<constant name="NOTIFICATION_VISIBILITY_CHANGED" value="43" enum="">
+			Spatial nodes receive this notification when their visibility changes.
 		</constant>
 	</constants>
 </class>