From 3398fb77a915d3f6d7a3dc6bf2398840c696365b Mon Sep 17 00:00:00 2001
From: Aaron Franke <arnfranke@yahoo.com>
Date: Fri, 10 Jun 2022 00:56:35 -0500
Subject: [PATCH] Document limitations of negative scales in 2D and 3D

---
 doc/classes/Node2D.xml      | 1 +
 doc/classes/Node3D.xml      | 1 +
 doc/classes/Transform2D.xml | 1 +
 3 files changed, 3 insertions(+)

diff --git a/doc/classes/Node2D.xml b/doc/classes/Node2D.xml
index bb730196682..ed753c8da19 100644
--- a/doc/classes/Node2D.xml
+++ b/doc/classes/Node2D.xml
@@ -113,6 +113,7 @@
 		</member>
 		<member name="scale" type="Vector2" setter="set_scale" getter="get_scale" default="Vector2(1, 1)">
 			The node's scale. Unscaled value: [code](1, 1)[/code].
+			[b]Note:[/b] Negative X scales in 2D are not decomposable from the transformation matrix. Due to the way scale is represented with transformation matrices in Godot, negative scales on the X axis will be changed to negative scales on the Y axis and a rotation of 180 degrees when decomposed.
 		</member>
 		<member name="skew" type="float" setter="set_skew" getter="get_skew" default="0.0">
 		</member>
diff --git a/doc/classes/Node3D.xml b/doc/classes/Node3D.xml
index 4444416a06c..ac434af4fa2 100644
--- a/doc/classes/Node3D.xml
+++ b/doc/classes/Node3D.xml
@@ -302,6 +302,7 @@
 		</member>
 		<member name="scale" type="Vector3" setter="set_scale" getter="get_scale" default="Vector3(1, 1, 1)">
 			Scale part of the local transformation.
+			[b]Note:[/b] Mixed negative scales in 3D are not decomposable from the transformation matrix. Due to the way scale is represented with transformation matrices in Godot, the scale values will either be all positive or all negative.
 		</member>
 		<member name="top_level" type="bool" setter="set_as_top_level" getter="is_set_as_top_level" default="false">
 			If [code]true[/code], the node will not inherit its transformations from its parent. Node transformations are only in global space.
diff --git a/doc/classes/Transform2D.xml b/doc/classes/Transform2D.xml
index 8c2a5aa6d91..e1f7ff21d0e 100644
--- a/doc/classes/Transform2D.xml
+++ b/doc/classes/Transform2D.xml
@@ -163,6 +163,7 @@
 			<argument index="0" name="scale" type="Vector2" />
 			<description>
 				Sets the transform's scale.
+				[b]Note:[/b] Negative X scales in 2D are not decomposable from the transformation matrix. Due to the way scale is represented with transformation matrices in Godot, negative scales on the X axis will be changed to negative scales on the Y axis and a rotation of 180 degrees when decomposed.
 			</description>
 		</method>
 		<method name="set_skew">