バイナリシリアル化API

はじめに

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 File as well as the packet APIs for PacketPeer. This format is not used for binary scenes and resources.

パケットの仕様

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 integer, specifying the type of data.

The lowest value two bytes are used to determine the type, while the highest value two bytes contain flags:

base_type = val & 0xFFFF;
flags = val >> 16;

タイプ(型)	値
0	null
1	bool
2	integer
3	float
4	string
5	vector2
6	rect2
7	vector3
8	transform2d
9	plane
10	quat
11	aabb
12	basis
13	transform
14	color
15	node path
16	rid
17	object
18	dictionary
19	array
20	raw array
21	int array
22	real array
23	string array
24	vector2 array
25	vector3 array
26	color array
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, 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

1: bool

Offset	バイト長	タイプ(型)	説明
4	4	整数	0 が False、1 が True

2: int

If no flags are set (flags == 0), the integer is sent as a 32 bit integer:

Offset	バイト長	タイプ(型)	説明
4	4	整数	32-bit signed integer

If flag ENCODE_FLAG_64 is set (flags & 1 == 1), the integer is sent as a 64-bit integer:

Offset	バイト長	タイプ(型)	説明
4	8	整数	64-bit signed integer

3: float

If no flags are set (flags == 0), the float is sent as a 32 bit single precision:

Offset	バイト長	タイプ(型)	説明
4	4	浮動小数点数	IEEE 754 single-precision float

If flag ENCODE_FLAG_64 is set (flags & 1 == 1), the float is sent as a 64-bit double precision number:

Offset	バイト長	タイプ(型)	説明
4	8	浮動小数点数	IEEE 754 double-precision float

4: String

Offset	バイト長	タイプ(型)	説明
4	4	整数	String length (in bytes)
8	X	バイト列	UTF-8 encoded string

このフィールドは4バイトにパディングされます。

5: Vector2

Offset	バイト長	タイプ(型)	説明
4	4	浮動小数点数	X coordinate
8	4	浮動小数点数	Y coordinate

6: Rect2

Offset	バイト長	タイプ(型)	説明
4	4	浮動小数点数	X coordinate
8	4	浮動小数点数	Y coordinate
12	4	浮動小数点数	X size
16	4	浮動小数点数	Y size

7: Vector3

Offset	バイト長	タイプ(型)	説明
4	4	浮動小数点数	X coordinate
8	4	浮動小数点数	Y coordinate
12	4	浮動小数点数	Z coordinate

8: Transform2D

Offset	バイト長	タイプ(型)	説明
4	4	浮動小数点数	X列ベクトルのX成分、[0][0] でアクセス
8	4	浮動小数点数	X列ベクトルのY成分、[0][1] でアクセス
12	4	浮動小数点数	Y列ベクトルのX成分、[1][0] でアクセス
16	4	浮動小数点数	Y列ベクトルのY成分、[1][1] でアクセス
20	4	浮動小数点数	原点ベクトルのX成分、[2][0] でアクセス
24	4	浮動小数点数	原点ベクトルのY成分、[2][1] でアクセス

9: Plane

Offset	バイト長	タイプ(型)	説明
4	4	浮動小数点数	法線X
8	4	浮動小数点数	法線Y
12	4	浮動小数点数	法線Z
16	4	浮動小数点数	距離

10: Quat

Offset	バイト長	タイプ(型)	説明
4	4	浮動小数点数	虚数X
8	4	浮動小数点数	虚数Y
12	4	浮動小数点数	虚数Z
16	4	浮動小数点数	実数W

11: AABB

Offset	バイト長	タイプ(型)	説明
4	4	浮動小数点数	X coordinate
8	4	浮動小数点数	Y coordinate
12	4	浮動小数点数	Z coordinate
16	4	浮動小数点数	X size
20	4	浮動小数点数	Y size
24	4	浮動小数点数	Z size

12: Basis

Offset	バイト長	タイプ(型)	説明
4	4	浮動小数点数	X列ベクトルのX成分、[0][0] でアクセス
8	4	浮動小数点数	X列ベクトルのY成分、[0][1] でアクセス
12	4	浮動小数点数	X列ベクトルのZ成分、[0][2] でアクセス
16	4	浮動小数点数	Y列ベクトルのX成分、[1][0] でアクセス
20	4	浮動小数点数	Y列ベクトルのY成分、[1][1] でアクセス
24	4	浮動小数点数	Y列ベクトルのZ成分、[1][2] でアクセス
28	4	浮動小数点数	Z列ベクトルのX成分、[2][0] でアクセス
32	4	浮動小数点数	Z列ベクトルのY成分、[2][1] でアクセス
36	4	浮動小数点数	Z列ベクトルのZ成分、[2][2] でアクセス

13: Transform

Offset	バイト長	タイプ(型)	説明
4	4	浮動小数点数	X列ベクトルのX成分、[0][0] でアクセス
8	4	浮動小数点数	X列ベクトルのY成分、[0][1] でアクセス
12	4	浮動小数点数	X列ベクトルのZ成分、[0][2] でアクセス
16	4	浮動小数点数	Y列ベクトルのX成分、[1][0] でアクセス
20	4	浮動小数点数	Y列ベクトルのY成分、[1][1] でアクセス
24	4	浮動小数点数	Y列ベクトルのZ成分、[1][2] でアクセス
28	4	浮動小数点数	Z列ベクトルのX成分、[2][0] でアクセス
32	4	浮動小数点数	Z列ベクトルのY成分、[2][1] でアクセス
36	4	浮動小数点数	Z列ベクトルのZ成分、[2][2] でアクセス
40	4	浮動小数点数	原点ベクトルのX成分、[3][0] でアクセス
44	4	浮動小数点数	原点ベクトルのY成分、[3][1] でアクセス
48	4	浮動小数点数	原点ベクトルのZ成分、[3][2] でアクセス

14: Color

Offset	バイト長	タイプ(型)	説明
4	4	浮動小数点数	Red (typically 0..1, can be above 1 for overbright colors)
8	4	浮動小数点数	Green (typically 0..1, can be above 1 for overbright colors)
12	4	浮動小数点数	Blue (typically 0..1, can be above 1 for overbright colors)
16	4	浮動小数点数	アルファ (0..1)

15: NodePath

Offset	バイト長	タイプ(型)	説明
4	4	整数	String length, or new format (val&0x80000000!=0 and NameCount=val&0x7FFFFFFF)

古い形式の場合:

Offset	バイト長	タイプ(型)	説明
8	X	バイト列	UTF-8 encoded string

4バイトにパディングされます。

新しい形式の場合:

Offset	バイト長	タイプ(型)	説明
4	4	整数	Sub-name count
8	4	整数	フラグ (絶対値: val&1 != 0)

名前とサブネームごと

Offset	バイト長	タイプ(型)	説明
X+0	4	整数	String length
X+4	X	バイト列	UTF-8 encoded string

すべての名前文字列は4バイトにパディングされます。

16: RID (サポートされていません)

17: Object (サポートされていません)

18: Dictionary

Offset	バイト長	タイプ(型)	説明
4	4	整数	val&0x7FFFFFFF = elements、 val&0x80000000 = shared (bool)

これに続き、この同じ形式を使用して、”elements” の個数分、キーと値のペアを次々に作成します。

19: Array

Offset	バイト長	タイプ(型)	説明
4	4	整数	val&0x7FFFFFFF = elements、 val&0x80000000 = shared (bool)

これに続き、"elements" の個数分、この同じ形式を使用して次々に値を設定します。

20: PoolByteArray

Offset	バイト長	タイプ(型)	説明
4	4	整数	Array length (Bytes)
8..8+長さ	1	Byte	Byte (符号なし: 0..255)

配列データは4バイトにパディングされます。

21: PoolIntArray

Offset	バイト長	タイプ(型)	説明
4	4	整数	Array length (Integers)
8..8+長さ*4	4	整数	32-bit signed integer

22: PoolRealArray

Offset	バイト長	タイプ(型)	説明
4	4	整数	Array length (Floats)
8..8+長さ*4	4	整数	32-bits IEEE 754 float

23: PoolStringArray

Offset	バイト長	タイプ(型)	説明
4	4	整数	Array length (Strings)

各文字列に対して:

Offset	バイト長	タイプ(型)	説明
X+0	4	整数	String length
X+4	X	バイト列	UTF-8 encoded string

すべての文字列は4バイトにパディングされます。

24: PoolVector2Array

Offset	バイト長	タイプ(型)	説明
4	4	整数	Array length
8..8+長さ*8	4	浮動小数点数	X coordinate
8..12+長さ*8	4	浮動小数点数	Y coordinate

25: PoolVector3Array

Offset	バイト長	タイプ(型)	説明
4	4	整数	Array length
8..8+長さ*12	4	浮動小数点数	X coordinate
8..12+長さ*12	4	浮動小数点数	Y coordinate
8..16+長さ*12	4	浮動小数点数	Z coordinate

26: PoolColorArray

Offset	バイト長	タイプ(型)	説明
4	4	整数	Array length
8..8+長さ*16	4	浮動小数点数	Red (typically 0..1, can be above 1 for overbright colors)
8..12+長さ*16	4	浮動小数点数	Green (typically 0..1, can be above 1 for overbright colors)
8..16+長さ*16	4	浮動小数点数	Blue (typically 0..1, can be above 1 for overbright colors)
8..20+長さ*16	4	浮動小数点数	アルファ (0..1)