Work in progress
The content of this page was not yet updated for Godot
4.2
and may be outdated. If you know how to improve this page or you can confirm
that it's up to date, feel free to open a pull request.
API de serialización Binaria¶
Introducción¶
Godot has a serialization API based on Variant. It's used for
converting data types to an array of bytes efficiently. This API is exposed
via the global bytes_to_var()
and var_to_bytes() functions,
but it is also used in the get_var
and store_var
methods of
FileAccess as well as the packet APIs for PacketPeer.
This format is not used for binary scenes and resources.
Full Objects vs Object instance IDs¶
If a variable is serialized with full_objects = true
, then any Objects
contained in the variable will be serialized and included in the result. This
is recursive.
If full_objects = false
, then only the instance IDs will be serialized for
any Objects contained in the variable.
Especificación de paquete¶
El paquete está diseñado para que siempre tenga un relleno de 4 bytes. Todos los valores están codificados en formato little-endian. Todos los paquetes tienen una cabecera de 4 bytes que representa un entero, especificando el tipo de datos.
Los dos bytes de menor valor se utilizan para determinar el tipo, mientras que los dos bytes de mayor valor contienen flags:
base_type = val & 0xFFFF;
flags = val >> 16;
Tipo |
Valor |
---|---|
0 |
null |
1 |
bool |
2 |
entero |
3 |
real |
4 |
string |
5 |
vector2 |
6 |
rect2 |
7 |
vector3 |
8 |
transformación 2d |
9 |
plano |
10 |
quaternion |
11 |
aabb* |
12 |
bases |
13 |
transform3d |
14 |
color |
15 |
ruta de nodo |
16 |
rid (Resource ID) |
17 |
objeto |
18 |
diccionario |
19 |
arreglo |
20 |
array crudo |
21 |
int32 array |
22 |
int64 array |
23 |
float32 array |
24 |
float64 array |
25 |
array de cadenas |
26 |
array de vector2 |
27 |
array de vector3 |
28 |
array de color |
29 |
maximo |
A continuación se encuentran los contenidos reales del paquete, los cuales varían para cada tipo de paquete. Ten en cuenta que esto asume que Godot está compilado con floats de precisión simple, que es el valor predeterminado. Si Godot se compiló con floats de precisión doble, la longitud de los campos Float
dentro de las estructuras de datos debería ser de 8 y el desplazamiento debería ser (offset - 4) * 2 + 4
. El tipo float
en sí siempre utiliza precisión doble.
0: nulo¶
1: bool¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
0 para False, 1 para True |
2: int¶
Si no se establecen banderas (flags == 0), el entero se envía como un entero de 32 bits:
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
Entero con signo de 32 bits |
Si la bandera ENCODE_FLAG_64
está establecida (flags & 1 == 1
), el entero se envía como un entero de 64 bits:
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
8 |
Entero |
Entero de 64 bits con signo |
3: float¶
Si no se establecen banderas (flags == 0), el flotante se envía como una precisión simple de 32 bits:
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Flotante |
IEEE 754 flotante de precisión simple |
Si la bandera ENCODE_FLAG_64
está establecida (flags & 1 == 1
), el flotante se envía como un número de precisión doble de 64 bits:
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
8 |
Flotante |
IEEE 754 flotante de precisión doble |
4: String¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
Longitud de cadenas (en bytes) |
8 |
X |
Bytes |
Cadena codificada en UTF-8 |
Este campo se rellena hasta alcanzar 4 bytes.
5: Vector2¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Flotante |
Coordenada X |
8 |
4 |
Flotante |
Coordenada Y |
6: Rect2¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Flotante |
Coordenada X |
8 |
4 |
Flotante |
Coordenada Y |
12 |
4 |
Flotante |
Tamaño en X |
16 |
4 |
Flotante |
Tamaño en Y |
7: Vector3¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Flotante |
Coordenada X |
8 |
4 |
Flotante |
Coordenada Y |
12 |
4 |
Flotante |
Coordenada Z |
8: Transform2D¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Flotante |
La componente X del vector columna X, accedido mediante [0][0] |
8 |
4 |
Flotante |
La componente Y del vector columna X, accedido mediante [0][1] |
12 |
4 |
Flotante |
La componente X del vector columna Y, accedido mediante [1][0] |
16 |
4 |
Flotante |
La componente Y del vector columna Y, accedido mediante [1][1] |
20 |
4 |
Flotante |
La componente X del vector origin, accedido mediante [2][0] |
24 |
4 |
Flotante |
La componente Y del vector origin, accedido mediante [2][1] |
9: Plane¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Flotante |
Normal en X |
8 |
4 |
Flotante |
Normal en Y |
12 |
4 |
Flotante |
Normal en Z |
16 |
4 |
Flotante |
Distancia |
10: Quaternion¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Flotante |
X imaginario |
8 |
4 |
Flotante |
Y imaginario |
12 |
4 |
Flotante |
Z imaginario |
16 |
4 |
Flotante |
W real |
11: AABB¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Flotante |
Coordenada X |
8 |
4 |
Flotante |
Coordenada Y |
12 |
4 |
Flotante |
Coordenada Z |
16 |
4 |
Flotante |
Tamaño en X |
20 |
4 |
Flotante |
Tamaño en Y |
24 |
4 |
Flotante |
Tamaño en Z |
12: Basis¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Flotante |
La componente X del vector columna X, accedido mediante [0][0] |
8 |
4 |
Flotante |
La componente Y del vector columna X, accedido mediante [0][1] |
12 |
4 |
Flotante |
La componente Z del vector columna X, accedido mediante [0][2] |
16 |
4 |
Flotante |
La componente X del vector columna Y, accedido mediante [1][0] |
20 |
4 |
Flotante |
La componente Y del vector columna Y, accedido mediante [1][1] |
24 |
4 |
Flotante |
La componente Z del vector columna Y, accedido mediante [1][2] |
28 |
4 |
Flotante |
La componente X del vector columna Z, accedido mediante [2][0] |
32 |
4 |
Flotante |
La componente Y del vector columna Z, accedido mediante [2][1] |
36 |
4 |
Flotante |
La componente Z del vector columna Z, accedido mediante [2][2] |
13: Transform3D¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Flotante |
La componente X del vector columna X, accedido mediante [0][0] |
8 |
4 |
Flotante |
La componente Y del vector columna X, accedido mediante [0][1] |
12 |
4 |
Flotante |
La componente Z del vector columna X, accedido mediante [0][2] |
16 |
4 |
Flotante |
La componente X del vector columna Y, accedido mediante [1][0] |
20 |
4 |
Flotante |
La componente Y del vector columna Y, accedido mediante [1][1] |
24 |
4 |
Flotante |
La componente Z del vector columna Y, accedido mediante [1][2] |
28 |
4 |
Flotante |
La componente X del vector columna Z, accedido mediante [2][0] |
32 |
4 |
Flotante |
La componente Y del vector columna Z, accedido mediante [2][1] |
36 |
4 |
Flotante |
La componente Z del vector columna Z, accedido mediante [2][2] |
40 |
4 |
Flotante |
La componente X del vector origin, accedido mediante [3][0] |
44 |
4 |
Flotante |
La componente Y del vector origin, accedido mediante [3][1] |
48 |
4 |
Flotante |
La componente Z del vector origin, accedido mediante [3][2] |
14: Color¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Flotante |
Rojo (generalmente en el rango de 0 a 1, pero puede ser superior a 1 para colores muy brillantes) |
8 |
4 |
Flotante |
Verde (generalmente en el rango de 0 a 1, pero puede ser superior a 1 para colores muy brillantes) |
12 |
4 |
Flotante |
Azul (generalmente en el rango de 0 a 1, pero puede ser superior a 1 para colores muy brillantes) |
16 |
4 |
Flotante |
Alpha (0..1) |
15: NodePath¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
Longitud de la cadena o nuevo formato (val&0x80000000!=0 y NameCount=val&0x7FFFFFFF) |
Para el viejo formato:¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
8 |
X |
Bytes |
Cadena codificada en UTF-8 |
Rellenado a 4 bytes.
Para el nuevo formato:¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
conteo de sub-nombre |
8 |
4 |
Entero |
Banderas (absolute: val&1 != 0 ) |
Por cada Nombre y Sub-nombre
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
X+0 |
4 |
Entero |
Longitud de la cuerda |
X+4 |
X |
Bytes |
Cadena codificada en UTF-8 |
Cada cadena de nombres es rellenado a 4 bytes.
16: RID (sin soporte)¶
17: Object¶
An Object could be serialized in three different ways: as a null value, with
full_objects = false
, or with full_objects = true
.
A null value¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
Zero (32-bit signed integer) |
full_objects
disabled¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
8 |
Entero |
The Object instance ID (64-bit signed integer) |
full_objects
enabled¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
Class name (String length) |
8 |
X |
Bytes |
Class name (UTF-8 encoded string) |
X+8 |
4 |
Entero |
La cantidad de propiedades que serán serializadas |
Para cada propiedad:
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
Y |
4 |
Entero |
Property name (String length) |
Y+4 |
Z |
Bytes |
Property name (UTF-8 encoded string) |
Y+4+Z |
W |
<variable> |
Property value, using this same format |
Nota
Not all properties are included. Only properties that are configured with the
PROPERTY_USAGE_STORAGE
flag set will be serialized. You can add a new usage flag to a property by overriding the
_get_property_list
method in your class. You can also check how property usage is configured by
calling Object._get_property_list
See
PropertyUsageFlags for the
possible usage flags.
18: Dictionary¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
val&0x7FFFFFFF = elementos, val&0x80000000 = compartidos (bool) |
A continuación, para la cantidad de "elementos", se encuentran pares de clave y valor, uno tras otro, utilizando el mismo formato.
19: Array¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
val&0x7FFFFFFF = elementos, val&0x80000000 = compartidos (bool) |
A continuación, para la cantidad de "elementos", se encuentran los valores uno tras otro, utilizando el mismo formato.
20: PackedByteArray¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
Longitud de array (Bytes) |
8..8+longitud |
1 |
Byte |
Byte (0..255) |
Los datos del array son rellenados a 4 bytes.
21: PackedInt32Array¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
longitud de array(Enteros) |
8..8+longitud*4 |
4 |
Entero |
Entero con signo de 32 bits |
22: PackedInt64Array¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
8 |
Entero |
longitud de array(Enteros) |
8..8+longitud*8 |
8 |
Entero |
Entero de 64 bits con signo |
23: PackedFloat32Array¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
Longitud de array (Flotantes) |
8..8+longitud*4 |
4 |
Entero |
32-bit IEEE 754 single-precision float |
24: PackedFloat64Array¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
Longitud de array (Flotantes) |
8..8+longitud*8 |
8 |
Entero |
64-bit IEEE 754 double-precision float |
25: PackedStringArray¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
Longitud de array (Cadenas) |
Por cada Cadena:
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
X+0 |
4 |
Entero |
Longitud de la cuerda |
X+4 |
X |
Bytes |
Cadena codificada en UTF-8 |
Cada cadena es rellenada a 4 bytes.
26: PackedVector2Array¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
Longitud de la matriz |
8..8+longitud*8 |
4 |
Flotante |
Coordenada X |
8..12+longitud*8 |
4 |
Flotante |
Coordenada Y |
27: PackedVector3Array¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
Longitud de la matriz |
8..8+longitud*12 |
4 |
Flotante |
Coordenada X |
8..12+longitud*12 |
4 |
Flotante |
Coordenada Y |
8..16+longitud*12 |
4 |
Flotante |
Coordenada Z |
28: PackedColorArray¶
Ajuste |
Len (longitud) |
Tipo |
Descripción |
---|---|---|---|
4 |
4 |
Entero |
Longitud de la matriz |
8..8+longitud*16 |
4 |
Flotante |
Rojo (generalmente en el rango de 0 a 1, pero puede ser superior a 1 para colores muy brillantes) |
8..12+longitud*16 |
4 |
Flotante |
Verde (generalmente en el rango de 0 a 1, pero puede ser superior a 1 para colores muy brillantes) |
8..16+longitud*16 |
4 |
Flotante |
Azul (generalmente en el rango de 0 a 1, pero puede ser superior a 1 para colores muy brillantes) |
8..20+longitud*16 |
4 |
Flotante |
Alpha (0..1) |