godotengine/godot-docs
1
0
Fork 0
mirror of https://github.com/godotengine/godot-docs.git synced 2026-01-04 14:11:02 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into 3.2

Browse Source
This commit is contained in:
Rémi Verschelde
2020-07-30 15:42:16 +02:00
parent 693d2586cd 29dccc8ecd
commit 76cf11c890
67 changed files with 1098 additions and 364 deletions
Download Patch File Download Diff File Expand all files Collapse all files

139
tutorials/misc/binary_serialization_api.rst
View File

@@ -10,13 +10,13 @@ Godot has a simple serialization API based on Variant. It's used for
converting data types to an array of bytes efficiently. This API is used
in the functions ``get_var`` and ``store_var`` of :ref:`class_File`
as well as the packet APIs for :ref:`class_PacketPeer`. This format
is not used for binary scenes and resources.
is *not* used for binary scenes and resources.
Packet specification
--------------------
The packet is designed to be always padded to 4 bytes. All values are
little endian encoded. All packets have a 4 byte header representing an
little-endian-encoded. All packets have a 4-byte header representing an
integer, specifying the type of data:
+--------+--------------------------+
@@ -79,11 +79,12 @@ integer, specifying the type of data:
| 27 | max |
+--------+--------------------------+
Following this is the actual packet contents, which varies for each type
of packet. Note that this assumes Godot is compiled with single precision
floats. If instead doubles are used, the length of "Float" fields within
data structures should be 8, and the offset should be (offset - 4) * 2 + 4.
The "float" type itself is always double precision.
Following this is the actual packet contents, which varies for each type of
packet. Note that this assumes Godot is compiled with single-precision floats,
which is the default. If Godot was compiled with double-precision floats, the
length of "Float" fields within data structures should be 8, and the offset
should be ``(offset - 4) * 2 + 4``. The "float" type itself always uses double
precision.
0: null
~~~~~~~
@@ -103,7 +104,7 @@ The "float" type itself is always double precision.
+----------+-------+-----------+--------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+==========================+
| 4 | 8 | Integer | Signed, 64-bit Integer |
| 4 | 8 | Integer | 64-bit signed integer |
+----------+-------+-----------+--------------------------+
3: :ref:`float<class_float>`
@@ -121,9 +122,9 @@ The "float" type itself is always double precision.
+----------+-------+-----------+----------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+============================+
| 4 | 4 | Integer | String Length (in Bytes) |
| 4 | 4 | Integer | String length (in bytes) |
+----------+-------+-----------+----------------------------+
| 8 | X | Bytes | UTF-8 Encoded String |
| 8 | X | Bytes | UTF-8 encoded string |
+----------+-------+-----------+----------------------------+
This field is padded to 4 bytes.
@@ -134,9 +135,9 @@ This field is padded to 4 bytes.
+----------+-------+---------+----------------+
| Offset | Len | Type | Description |
+==========+=======+=========+================+
| 4 | 4 | Float | X Coordinate |
| 4 | 4 | Float | X coordinate |
+----------+-------+---------+----------------+
| 8 | 4 | Float | Y Coordinate |
| 8 | 4 | Float | Y coordinate |
+----------+-------+---------+----------------+
6: :ref:`Rect2<class_rect2>`
@@ -145,13 +146,13 @@ This field is padded to 4 bytes.
+----------+-------+---------+----------------+
| Offset | Len | Type | Description |
+==========+=======+=========+================+
| 4 | 4 | Float | X Coordinate |
| 4 | 4 | Float | X coordinate |
+----------+-------+---------+----------------+
| 8 | 4 | Float | Y Coordinate |
| 8 | 4 | Float | Y coordinate |
+----------+-------+---------+----------------+
| 12 | 4 | Float | X Size |
| 12 | 4 | Float | X size |
+----------+-------+---------+----------------+
| 16 | 4 | Float | Y Size |
| 16 | 4 | Float | Y size |
+----------+-------+---------+----------------+
7: :ref:`Vector3<class_vector3>`
@@ -160,11 +161,11 @@ This field is padded to 4 bytes.
+----------+-------+---------+----------------+
| Offset | Len | Type | Description |
+==========+=======+=========+================+
| 4 | 4 | Float | X Coordinate |
| 4 | 4 | Float | X coordinate |
+----------+-------+---------+----------------+
| 8 | 4 | Float | Y Coordinate |
| 8 | 4 | Float | Y coordinate |
+----------+-------+---------+----------------+
| 12 | 4 | Float | Z Coordinate |
| 12 | 4 | Float | Z coordinate |
+----------+-------+---------+----------------+
8: :ref:`Transform2D<class_transform2d>`
@@ -222,17 +223,17 @@ This field is padded to 4 bytes.
+----------+-------+---------+----------------+
| Offset | Len | Type | Description |
+==========+=======+=========+================+
| 4 | 4 | Float | X Coordinate |
| 4 | 4 | Float | X coordinate |
+----------+-------+---------+----------------+
| 8 | 4 | Float | Y Coordinate |
| 8 | 4 | Float | Y coordinate |
+----------+-------+---------+----------------+
| 12 | 4 | Float | Z Coordinate |
| 12 | 4 | Float | Z coordinate |
+----------+-------+---------+----------------+
| 16 | 4 | Float | X Size |
| 16 | 4 | Float | X size |
+----------+-------+---------+----------------+
| 20 | 4 | Float | Y Size |
| 20 | 4 | Float | Y size |
+----------+-------+---------+----------------+
| 24 | 4 | Float | Z Size |
| 24 | 4 | Float | Z size |
+----------+-------+---------+----------------+
12: :ref:`Basis<class_basis>`
@@ -294,17 +295,17 @@ This field is padded to 4 bytes.
14: :ref:`Color<class_color>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------+-------+---------+----------------+
| Offset | Len | Type | Description |
+==========+=======+=========+================+
| 4 | 4 | Float | Red (0..1) |
+----------+-------+---------+----------------+
| 8 | 4 | Float | Green (0..1) |
+----------+-------+---------+----------------+
| 12 | 4 | Float | Blue (0..1) |
+----------+-------+---------+----------------+
| 16 | 4 | Float | Alpha (0..1) |
+----------+-------+---------+----------------+
+----------+-------+---------+--------------------------------------------------------------+
| Offset | Len | Type | Description |
+==========+=======+=========+==============================================================+
| 4 | 4 | Float | Red (typically 0..1, can be above 1 for overbright colors) |
+----------+-------+---------+--------------------------------------------------------------+
| 8 | 4 | Float | Green (typically 0..1, can be above 1 for overbright colors) |
+----------+-------+---------+--------------------------------------------------------------+
| 12 | 4 | Float | Blue (typically 0..1, can be above 1 for overbright colors) |
+----------+-------+---------+--------------------------------------------------------------+
| 16 | 4 | Float | Alpha (0..1) |
+----------+-------+---------+--------------------------------------------------------------+
15: :ref:`NodePath<class_nodepath>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -312,7 +313,7 @@ This field is padded to 4 bytes.
+----------+-------+-----------+-----------------------------------------------------------------------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+=========================================================================================+
| 4 | 4 | Integer | String Length, or New Format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF) |
| 4 | 4 | Integer | String length, or new format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF) |
+----------+-------+-----------+-----------------------------------------------------------------------------------------+
For old format:
@@ -321,7 +322,7 @@ For old format:
+----------+-------+---------+------------------------+
| Offset | Len | Type | Description |
+==========+=======+=========+========================+
| 8 | X | Bytes | UTF-8 Encoded String |
| 8 | X | Bytes | UTF-8 encoded string |
+----------+-------+---------+------------------------+
Padded to 4 bytes.
@@ -332,7 +333,7 @@ For new format:
+----------+-------+-----------+-------------------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+=====================================+
| 4 | 4 | Integer | Sub-Name Count |
| 4 | 4 | Integer | Sub-name count |
+----------+-------+-----------+-------------------------------------+
| 8 | 4 | Integer | Flags (absolute: val&1 != 0 ) |
+----------+-------+-----------+-------------------------------------+
@@ -342,9 +343,9 @@ For each Name and Sub-Name
+----------+-------+-----------+------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+========================+
| X+0 | 4 | Integer | String Length |
| X+0 | 4 | Integer | String length |
+----------+-------+-----------+------------------------+
| X+4 | X | Bytes | UTF-8 Encoded String |
| X+4 | X | Bytes | UTF-8 encoded string |
+----------+-------+-----------+------------------------+
Every name string is padded to 4 bytes.
@@ -385,7 +386,7 @@ other, using this same format.
+---------------+-------+-----------+------------------------+
| Offset | Len | Type | Description |
+===============+=======+===========+========================+
| 4 | 4 | Integer | Array Length (Bytes) |
| 4 | 4 | Integer | Array length (Bytes) |
+---------------+-------+-----------+------------------------+
| 8..8+length | 1 | Byte | Byte (0..255) |
+---------------+-------+-----------+------------------------+
@@ -398,9 +399,9 @@ The array data is padded to 4 bytes.
+------------------+-------+-----------+---------------------------+
| Offset | Len | Type | Description |
+==================+=======+===========+===========================+
| 4 | 4 | Integer | Array Length (Integers) |
| 4 | 4 | Integer | Array length (Integers) |
+------------------+-------+-----------+---------------------------+
| 8..8+length\*4 | 4 | Integer | 32 Bits Signed Integer |
| 8..8+length\*4 | 4 | Integer | 32-bit signed integer |
+------------------+-------+-----------+---------------------------+
22: :ref:`PoolRealArray<class_poolrealarray>`
@@ -409,9 +410,9 @@ The array data is padded to 4 bytes.
+------------------+-------+-----------+---------------------------+
| Offset | Len | Type | Description |
+==================+=======+===========+===========================+
| 4 | 4 |Integer | Array Length (Floats) |
| 4 | 4 | Integer | Array length (Floats) |
+------------------+-------+-----------+---------------------------+
| 8..8+length\*4 | 4 |Integer | 32 Bits IEEE 754 Float |
| 8..8+length\*4 | 4 | Integer | 32-bits IEEE 754 float |
+------------------+-------+-----------+---------------------------+
23: :ref:`PoolStringArray<class_poolstringarray>`
@@ -420,7 +421,7 @@ The array data is padded to 4 bytes.
+----------+-------+-----------+--------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+==========================+
| 4 | 4 | Integer | Array Length (Strings) |
| 4 | 4 | Integer | Array length (Strings) |
+----------+-------+-----------+--------------------------+
For each String:
@@ -428,9 +429,9 @@ For each String:
+----------+-------+-----------+------------------------+
| Offset | Len | Type | Description |
+==========+=======+===========+========================+
| X+0 | 4 | Integer | String Length |
| X+0 | 4 | Integer | String length |
+----------+-------+-----------+------------------------+
| X+4 | X | Bytes | UTF-8 Encoded String |
| X+4 | X | Bytes | UTF-8 encoded string |
+----------+-------+-----------+------------------------+
Every string is padded to 4 bytes.
@@ -441,11 +442,11 @@ Every string is padded to 4 bytes.
+-------------------+-------+-----------+----------------+
| Offset | Len | Type | Description |
+===================+=======+===========+================+
| 4 | 4 | Integer | Array Length |
| 4 | 4 | Integer | Array length |
+-------------------+-------+-----------+----------------+
| 8..8+length\*8 | 4 | Float | X Coordinate |
| 8..8+length\*8 | 4 | Float | X coordinate |
+-------------------+-------+-----------+----------------+
| 8..12+length\*8 | 4 | Float | Y Coordinate |
| 8..12+length\*8 | 4 | Float | Y coordinate |
+-------------------+-------+-----------+----------------+
25: :ref:`PoolVector3Array<class_poolvector3array>`
@@ -454,28 +455,28 @@ Every string is padded to 4 bytes.
+--------------------+-------+-----------+----------------+
| Offset | Len | Type | Description |
+====================+=======+===========+================+
| 4 | 4 | Integer | Array Length |
| 4 | 4 | Integer | Array length |
+--------------------+-------+-----------+----------------+
| 8..8+length\*12 | 4 | Float | X Coordinate |
| 8..8+length\*12 | 4 | Float | X coordinate |
+--------------------+-------+-----------+----------------+
| 8..12+length\*12 | 4 | Float | Y Coordinate |
| 8..12+length\*12 | 4 | Float | Y coordinate |
+--------------------+-------+-----------+----------------+
| 8..16+length\*12 | 4 | Float | Z Coordinate |
| 8..16+length\*12 | 4 | Float | Z coordinate |
+--------------------+-------+-----------+----------------+
26: :ref:`PoolColorArray<class_poolcolorarray>`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------+-------+-----------+----------------+
| Offset | Len | Type | Description |
+====================+=======+===========+================+
| 4 | 4 | Integer | Array Length |
+--------------------+-------+-----------+----------------+
| 8..8+length\*16 | 4 | Float | Red (0..1) |
+--------------------+-------+-----------+----------------+
| 8..12+length\*16 | 4 | Float | Green (0..1) |
+--------------------+-------+-----------+----------------+
| 8..16+length\*16 | 4 | Float | Blue (0..1) |
+--------------------+-------+-----------+----------------+
| 8..20+length\*16 | 4 | Float | Alpha (0..1) |
+--------------------+-------+-----------+----------------+
+--------------------+-------+-----------+--------------------------------------------------------------+
| Offset | Len | Type | Description |
+====================+=======+===========+==============================================================+
| 4 | 4 | Integer | Array length |
+--------------------+-------+-----------+--------------------------------------------------------------+
| 8..8+length\*16 | 4 | Float | Red (typically 0..1, can be above 1 for overbright colors) |
+--------------------+-------+-----------+--------------------------------------------------------------+
| 8..12+length\*16 | 4 | Float | Green (typically 0..1, can be above 1 for overbright colors) |
+--------------------+-------+-----------+--------------------------------------------------------------+
| 8..16+length\*16 | 4 | Float | Blue (typically 0..1, can be above 1 for overbright colors) |
+--------------------+-------+-----------+--------------------------------------------------------------+
| 8..20+length\*16 | 4 | Float | Alpha (0..1) |
+--------------------+-------+-----------+--------------------------------------------------------------+

16
tutorials/misc/running_code_in_the_editor.rst
View File

@@ -10,7 +10,7 @@ What is ``tool``?
You can use it for doing many things, but it is mostly useful in level design for visually presenting things that are hard to predict ourselves. Here are some use cases:
- If you have a cannon that shoots cannonballs affected by physics (gravity), you can draw cannonball's trajectory in the editor, making level design a lot easier.
- If you have a cannon that shoots cannonballs affected by physics (gravity), you can draw the cannonball's trajectory in the editor, making level design a lot easier.
- If you have jumppads with varying jump heights, you can draw the maximum jump height a player would reach if it jumped on one, also making level design easier.
- If your player doesn't use a sprite, but draws itself using code, you can make that drawing code execute in the editor to see your player.
@@ -27,11 +27,11 @@ You can use it for doing many things, but it is mostly useful in level design fo
How to use it
-------------
To turn a script into a tool, add ``tool`` keyword at the top of your code.
To turn a script into a tool, add the keyword ``tool`` at the top of your code.
To check if you are currently in the editor, use: ``Engine.editor_hint``.
For example, if you want to execute some code only in editor, use:
For example, if you want to execute some code only in the editor, use:
.. tabs::
.. code-tab:: gdscript GDScript
@@ -39,7 +39,7 @@ For example, if you want to execute some code only in editor, use:
if Engine.editor_hint:
# Code to execute when in editor.
On the other hand, if you want to execute code only in game, simply negate previous expression:
On the other hand, if you want to execute code only in game, simply negate the same statement:
.. tabs::
.. code-tab:: gdscript GDScript
@@ -47,9 +47,9 @@ On the other hand, if you want to execute code only in game, simply negate previ
if not Engine.editor_hint:
# Code to execute when in game.
Pieces of code that are not having any of the 2 conditions above will run both in editor and in game.
Pieces of code do not have either of the 2 conditions above will run both in-editor and in-game.
Here is how a ``_process()`` function might look like for you:
Here is how a ``_process()`` function might look for you:
.. tabs::
.. code-tab:: gdscript GDScript
@@ -63,7 +63,7 @@ Here is how a ``_process()`` function might look like for you:
# Code to execute both in editor and in game.
.. note:: Modifications in editor are permanent. In our case, when we remove the script, the node will keep its rotation direction. Be careful so that you don't make unwanted modifications.
.. note:: Modifications in editor are permanent. For example, in the following case, when we remove the script, the node will keep its rotation. Be careful to avoid making unwanted modifications.
Try it out
-----------
@@ -150,4 +150,4 @@ If you are using :ref:`EditorScript<class_EditorScript>`:
parent.add_child(node)
node.set_owner(get_scene())
.. warning:: Using ``tool`` improperly can yield many errors. It is advised to first write the code how you want it, and only then add the ``tool`` keyword to the top. Also make sure you divide your code into part that runs in editor and part that runs in game. This way you can find your bug easier.
.. warning:: Using ``tool`` improperly can yield many errors. It is advised to first write the code how you want it, and only then add the ``tool`` keyword to the top. Also, make sure to separate code that runs in-editor from code that runs in-game. This way, you can find bugs more easily.