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)