バイナリシリアル化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.

パケットの仕様

パケットは、常に4バイトに埋め込まれるように設計されています。すべての値はリトルエンディアンでエンコードされています。すべてのパケットには、データのタイプを指定する整数を表す4バイトのヘッダーがあります。

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	色
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

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

2: int

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

オフセット	バイト長	タイプ(型)	説明
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:

オフセット	バイト長	タイプ(型)	説明
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:

オフセット	バイト長	タイプ(型)	説明
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:

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

4: String

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

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

5: Vector2

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

6: Rect2

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

7: Vector3

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

8: Transform2D

オフセット	バイト長	タイプ(型)	説明
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

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

10: Quat

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

11: AABB

オフセット	バイト長	タイプ(型)	説明
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

オフセット	バイト長	タイプ(型)	説明
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

オフセット	バイト長	タイプ(型)	説明
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

オフセット	バイト長	タイプ(型)	説明
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

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

古い形式の場合:

オフセット	バイト長	タイプ(型)	説明
8	X	バイト列	UTF-8 encoded string

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

新しい形式の場合:

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

名前とサブネームごと

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

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

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

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

18: Dictionary

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

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

19: Array

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

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

20: PoolByteArray

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

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

21: PoolIntArray

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

22: PoolRealArray

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

23: PoolStringArray

オフセット	バイト長	タイプ(型)	説明
4	4	整数	Array length (Strings)

各文字列に対して:

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

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

24: PoolVector2Array

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

25: PoolVector3Array

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

26: PoolColorArray

オフセット	バイト長	タイプ(型)	説明
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)