バイナリシリアル化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	オブジェクト
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)