Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Overhaul Node2D documentation #89256

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+29 −25
Open

Overhaul Node2D documentation #89256

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 29 additions & 25 deletions doc/classes/Node2D.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,12 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="Node2D" inherits="CanvasItem" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A 2D game object, inherited by all 2D-related nodes. Has a position, rotation, scale, and skew.
Base object in 2D space, inherited by all 2D nodes.
</brief_description>
<description>
A 2D game object, with a transform (position, rotation, and scale). All 2D nodes, including physics objects and sprites, inherit from Node2D. Use Node2D as a parent node to move, scale and rotate children in a 2D project. Also gives control of the node's render order.
The [Node2D] node is the base representation of a node in 2D space. All other 2D nodes inherit from this class. These include [Sprite2D], [CollisionObject2D], [TileMap], and many more.
For UI elements, it is recommended to use [Control], instead.
[b]Note:[/b] Unless otherwise specified, all methods that need angle parameters must receive angles in [i]radians[/i]. To convert degrees to radians, use [method @GlobalScope.deg_to_rad].
[b]Note:[/b] Since both [Node2D] and [Control] inherit from [CanvasItem], they share several concepts from the class such as the [member CanvasItem.z_index] and [member CanvasItem.visible] properties.
</description>
<tutorials>
Expand All @@ -23,7 +25,7 @@
<return type="float" />
<param index="0" name="point" type="Vector2" />
<description>
Returns the angle between the node and the [param point] in radians.
Returns the angle between the node and the global [param point] in radians.
[url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/node2d_get_angle_to.png]Illustration of the returned angle.[/url]
</description>
</method>
Expand All @@ -38,15 +40,15 @@
<return type="void" />
<param index="0" name="offset" type="Vector2" />
<description>
Adds the [param offset] vector to the node's global position.
Adds the given translation [param offset] to the node's [member global_position] in global space (relative to the world).
</description>
</method>
<method name="look_at">
<return type="void" />
<param index="0" name="point" type="Vector2" />
<description>
Rotates the node so that its local +X axis points towards the [param point], which is expected to use global coordinates.
[param point] should not be the same as the node's position, otherwise the node always looks to the right.
Rotates the node so that its local right axis (+X, [constant Vector2.RIGHT]) points toward the [param point], in global space.
[b]Note:[/b] If [param point] is the same as the node's [member global_position], the node will always look to the right.
</description>
</method>
<method name="move_local_x">
Expand All @@ -69,21 +71,21 @@
<return type="void" />
<param index="0" name="radians" type="float" />
<description>
Applies a rotation to the node, in radians, starting from its current rotation.
Rotates this node by the given angle [param radians], in radians. This operation is calculated in parent space (relative to the parent) and preserves the [member position].
</description>
</method>
<method name="to_global" qualifiers="const">
<return type="Vector2" />
<param index="0" name="local_point" type="Vector2" />
<description>
Transforms the provided local position into a position in global coordinate space. The input is expected to be local relative to the [Node2D] it is called on. e.g. Applying this method to the positions of child nodes will correctly transform their positions into the global coordinate space, but applying it to a node's own position will give an incorrect result, as it will incorporate the node's own transformation into its global position.
Returns the [param local_point] converted from this node's local space to global space. This is the opposite of [method to_local].
</description>
</method>
<method name="to_local" qualifiers="const">
<return type="Vector2" />
<param index="0" name="global_point" type="Vector2" />
<description>
Transforms the provided global position into a position in local coordinate space. The output will be local relative to the [Node2D] it is called on. e.g. It is appropriate for determining the positions of child nodes, but it is not appropriate for determining its own position relative to its parent.
Returns the [param global_point] converted from global space to this node's local space. This is the opposite of [method to_global].
Comment on lines 80 to +88
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is for consistency with #87440
However, it's a pretty nasty loss of information here. The corresponding 3D methods are not as verbose as this. At the moment I don't know what to make of it.

</description>
</method>
<method name="translate">
Expand All @@ -96,44 +98,46 @@
</methods>
<members>
<member name="global_position" type="Vector2" setter="set_global_position" getter="get_global_position">
Global position. See also [member position].
Global position (translation) of this node in global space (relative to the world). This is equivalent to the [member global_transform]'s [member Transform2D.origin]. See also [member position].
</member>
<member name="global_rotation" type="float" setter="set_global_rotation" getter="get_global_rotation">
Global rotation in radians. See also [member rotation].
Global rotation of this node in radians, in global space (relative to the world). See also [member rotation].
</member>
<member name="global_rotation_degrees" type="float" setter="set_global_rotation_degrees" getter="get_global_rotation_degrees">
Helper property to access [member global_rotation] in degrees instead of radians. See also [member rotation_degrees].
The [member global_rotation] of this node, in degrees instead of radians. See also [member rotation_degrees].
</member>
<member name="global_scale" type="Vector2" setter="set_global_scale" getter="get_global_scale">
Global scale. See also [member scale].
Global scale of this node in global space (relative to the world). See also [member scale].
[b]Note:[/b] The behavior of some 2D node types is not affected by this property. These include [Camera2D], [AudioStreamPlayer2D], and more.
</member>
<member name="global_skew" type="float" setter="set_global_skew" getter="get_global_skew">
Global skew in radians. See also [member skew].
Global skew applied to this node in the X axis, in radians and in global space (relative to the world). Higher values distort the node more. See also [member skew].
</member>
<member name="global_transform" type="Transform2D" setter="set_global_transform" getter="get_global_transform">
Global [Transform2D]. See also [member transform].
Global transformation of this node in global space (relative to the world). Contains and represents this node's [member global_position], [member global_rotation], [member global_scale], and [member global_skew]. See also [member transform].
</member>
<member name="position" type="Vector2" setter="set_position" getter="get_position" default="Vector2(0, 0)">
Position, relative to the node's parent. See also [member global_position].
Local position (translation) of this node in local space (relative to the parent node). This is equivalent to the [member transform]'s [member Transform2D.origin]. See also [member global_position].
</member>
<member name="rotation" type="float" setter="set_rotation" getter="get_rotation" default="0.0">
Rotation in radians, relative to the node's parent. See also [member global_rotation].
[b]Note:[/b] This property is edited in the inspector in degrees. If you want to use degrees in a script, use [member rotation_degrees].
Local rotation of this node in radians, in local space (relative to the parent node). See also [member global_rotation].
[b]Note:[/b] This property is edited in degrees in the inspector. If you want to use degrees in a script, use [member rotation_degrees].
</member>
<member name="rotation_degrees" type="float" setter="set_rotation_degrees" getter="get_rotation_degrees">
Helper property to access [member rotation] in degrees instead of radians. See also [member global_rotation_degrees].
The [member rotation] of this node, in degrees instead of radians. See also [member global_rotation_degrees].
[b]Note:[/b] This is [b]not[/b] the property available in the Inspector dock.
</member>
<member name="scale" type="Vector2" setter="set_scale" getter="get_scale" default="Vector2(1, 1)">
The node's scale, relative to the node's parent. Unscaled value: [code](1, 1)[/code]. See also [member global_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.
Local scale of this node in local space (relative to the parent node). See also [member global_scale].
[b]Note:[/b] The behavior of some 2D node types is not affected by this property. These include [Camera2D], [AudioStreamPlayer2D], etc.
[b]Warning:[/b] The scale's components must either be all positive or all negative, and [b]not[/b] exactly [code]0.0[/code]. Otherwise, it won't be possible to obtain the scale from the [member transform]'s basis. This may cause the intended scale to be lost when reloaded from disk, and potentially other unstable behavior.
</member>
<member name="skew" type="float" setter="set_skew" getter="get_skew" default="0.0">
If set to a non-zero value, slants the node in one direction or another. This can be used for pseudo-3D effects. See also [member global_skew].
[b]Note:[/b] Skew is performed on the X axis only, and [i]between[/i] rotation and scaling.
[b]Note:[/b] This property is edited in the inspector in degrees. If you want to use degrees in a script, use [code]skew = deg_to_rad(value_in_degrees)[/code].
Local skew applied to this node in the X axis, in radians, in local space (relative to the parent node), and [i]between[/i] rotation and scaling. Higher values distort the node more. See also [member global_skew].
[b]Note:[/b] This property is edited in degrees in the inspector. If you want to use degrees in a script, convert this property's value with [method @GlobalScope.rad_to_deg].
</member>
<member name="transform" type="Transform2D" setter="set_transform" getter="get_transform">
The node's [Transform2D], relative to the node's parent. See also [member global_transform].
Local transformations of this node in local space (relative to the parent node). Contains and represents this node's [member position], [member rotation], [member scale], and [member skew]. See also [member global_transform].
</member>
</members>
</class>
Loading