Merge pull request #54084 from reduz/node3d-rotation-options

3 files changed, 52 insertions, 11 deletions

diff --git a/doc/classes/Basis.xml b/doc/classes/Basis.xml
index 7f0d4cbbe3..6215c658c3 100644
--- a/doc/classes/Basis.xml
+++ b/doc/classes/Basis.xml
@@ -42,14 +42,6 @@
 		</method>
 		<method name="Basis" qualifiers="constructor">
 			<return type="Basis" />
-			<argument index="0" name="euler" type="Vector3" />
-			<description>
-				Constructs a pure rotation basis matrix from the given Euler angles (in the YXZ convention: when *composing*, first Y, then X, and Z last), given in the vector format as (X angle, Y angle, Z angle).
-				Consider using the [Quaternion] constructor instead, which uses a quaternion instead of Euler angles.
-			</description>
-		</method>
-		<method name="Basis" qualifiers="constructor">
-			<return type="Basis" />
 			<argument index="0" name="from" type="Quaternion" />
 			<description>
 				Constructs a pure rotation basis matrix from the given quaternion.
@@ -71,6 +63,13 @@
 				A negative determinant means the basis has a negative scale. A zero determinant means the basis isn't invertible, and is usually considered invalid.
 			</description>
 		</method>
+		<method name="from_euler" qualifiers="static">
+			<return type="Basis" />
+			<argument index="0" name="euler" type="Vector3" />
+			<argument index="1" name="order" type="int" default="2" />
+			<description>
+			</description>
+		</method>
 		<method name="from_scale" qualifiers="static">
 			<return type="Basis" />
 			<argument index="0" name="scale" type="Vector3" />
@@ -80,6 +79,7 @@
 		</method>
 		<method name="get_euler" qualifiers="const">
 			<return type="Vector3" />
+			<argument index="0" name="order" type="int" default="2" />
 			<description>
 				Returns the basis's rotation in the form of Euler angles (in the YXZ convention: when decomposing, first Z, then X, and Y last). The returned vector contains the rotation angles in the format (X angle, Y angle, Z angle).
 				Consider using the [method get_rotation_quaternion] method instead, which returns a [Quaternion] quaternion instead of Euler angles.
@@ -248,6 +248,18 @@
 		</member>
 	</members>
 	<constants>
+		<constant name="EULER_ORDER_XYZ" value="0">
+		</constant>
+		<constant name="EULER_ORDER_XZY" value="1">
+		</constant>
+		<constant name="EULER_ORDER_YXZ" value="2">
+		</constant>
+		<constant name="EULER_ORDER_YZX" value="3">
+		</constant>
+		<constant name="EULER_ORDER_ZXY" value="4">
+		</constant>
+		<constant name="EULER_ORDER_ZYX" value="5">
+		</constant>
 		<constant name="IDENTITY" value="Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)">
 			The identity basis, with no rotation or scaling applied.
 			This is identical to calling [code]Basis()[/code] without any parameters. This constant can be used to make your code clearer, and for consistency with C#.
diff --git a/doc/classes/Node3D.xml b/doc/classes/Node3D.xml
index 28acd77a39..2ca664e2b5 100644
--- a/doc/classes/Node3D.xml
+++ b/doc/classes/Node3D.xml
@@ -264,16 +264,28 @@
 		</method>
 	</methods>
 	<members>
+		<member name="basis" type="Basis" setter="set_basis" getter="get_basis">
+			Direct access to the 3x3 basis of the [Transform3D] property.
+		</member>
 		<member name="global_transform" type="Transform3D" setter="set_global_transform" getter="get_global_transform">
 			World3D space (global) [Transform3D] of this node.
 		</member>
 		<member name="position" type="Vector3" setter="set_position" getter="get_position" default="Vector3(0, 0, 0)">
 			Local position or translation of this node relative to the parent. This is equivalent to [code]transform.origin[/code].
 		</member>
+		<member name="quaternion" type="Quaternion" setter="set_quaternion" getter="get_quaternion">
+			Access to the node rotation as a [Quaternion]. This property is ideal for tweening complex rotations.
+		</member>
 		<member name="rotation" type="Vector3" setter="set_rotation" getter="get_rotation" default="Vector3(0, 0, 0)">
-			Rotation part of the local transformation in radians, specified in terms of YXZ-Euler angles in the format (X angle, Y angle, Z angle).
+			Rotation part of the local transformation in radians, specified in terms of Euler angles. The angles construct a rotaton in the order specified by the [member rotation_order] property.
 			[b]Note:[/b] In the mathematical sense, rotation is a matrix and not a vector. The three Euler angles, which are the three independent parameters of the Euler-angle parametrization of the rotation matrix, are stored in a [Vector3] data structure not because the rotation is a vector, but only because [Vector3] exists as a convenient data-structure to store 3 floating-point numbers. Therefore, applying affine operations on the rotation "vector" is not meaningful.
 		</member>
+		<member name="rotation_edit_mode" type="int" setter="set_rotation_edit_mode" getter="get_rotation_edit_mode" enum="Node3D.RotationEditMode" default="0">
+			Specify how rotation (and scale) will be presented in the editor.
+		</member>
+		<member name="rotation_order" type="int" setter="set_rotation_order" getter="get_rotation_order" enum="Node3D.RotationOrder" default="2">
+			Specify the axis rotation order of the [member rotation] property. The final orientation is constructed by rotating the Euler angles in the order specified by this property.
+		</member>
 		<member name="scale" type="Vector3" setter="set_scale" getter="get_scale" default="Vector3(1, 1, 1)">
 			Scale part of the local transformation.
 		</member>
@@ -311,5 +323,23 @@
 		<constant name="NOTIFICATION_VISIBILITY_CHANGED" value="43">
 			Node3D nodes receives this notification when their visibility changes.
 		</constant>
+		<constant name="ROTATION_EDIT_MODE_EULER" value="0" enum="RotationEditMode">
+		</constant>
+		<constant name="ROTATION_EDIT_MODE_QUATERNION" value="1" enum="RotationEditMode">
+		</constant>
+		<constant name="ROTATION_EDIT_MODE_BASIS" value="2" enum="RotationEditMode">
+		</constant>
+		<constant name="ROTATION_ORDER_XYZ" value="0" enum="RotationOrder">
+		</constant>
+		<constant name="ROTATION_ORDER_XZY" value="1" enum="RotationOrder">
+		</constant>
+		<constant name="ROTATION_ORDER_YXZ" value="2" enum="RotationOrder">
+		</constant>
+		<constant name="ROTATION_ORDER_YZX" value="3" enum="RotationOrder">
+		</constant>
+		<constant name="ROTATION_ORDER_ZXY" value="4" enum="RotationOrder">
+		</constant>
+		<constant name="ROTATION_ORDER_ZYX" value="5" enum="RotationOrder">
+		</constant>
 	</constants>
 </class>
diff --git a/doc/classes/Quaternion.xml b/doc/classes/Quaternion.xml
index 1ef6320d61..9c948ca21a 100644
--- a/doc/classes/Quaternion.xml
+++ b/doc/classes/Quaternion.xml
@@ -43,9 +43,8 @@
 		</method>
 		<method name="Quaternion" qualifiers="constructor">
 			<return type="Quaternion" />
-			<argument index="0" name="euler" type="Vector3" />
+			<argument index="0" name="euler_yxz" type="Vector3" />
 			<description>
-				Constructs a quaternion that will perform a rotation specified by Euler angles (in the YXZ convention: when decomposing, first Z, then X, and Y last), given in the vector format as (X angle, Y angle, Z angle).
 			</description>
 		</method>
 		<method name="Quaternion" qualifiers="constructor">