バイナリシリアル化API

はじめに

Godotには、Variantに基づくシンプルなシリアル化APIがあります。データ型をバイト配列に効率的に変換するために使用されます。このAPIは、File の get_var および store_var 関数で使用されるほか、PacketPeer のパケットAPIでも使用されます。この形式は、バイナリシーンおよびリソースには使用されません。

パケットの仕様

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

タイプ(型)	値
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. If instead doubles are used, the length of "Float" fields within data structures should be 8, and the offset should be (offset - 4) * 2 + 4. The "float" type itself is always double precision.

0: null

1: bool

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

2: int

Offset	バイト長	タイプ(型)	説明
4	8	整数	Signed, 64-bit Integer

3: float

Offset	バイト長	タイプ(型)	説明
4	4	浮動小数点数	IEE 754 32ビット浮動小数点

4: String

Offset	バイト長	タイプ(型)	説明
4	4	整数	文字列の長さ(バイト)
8	X	バイト列	UTF-8エンコードされた文字列

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

5: Vector2

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

6: Rect2

Offset	バイト長	タイプ(型)	説明
4	4	浮動小数点数	X座標
8	4	浮動小数点数	Y座標
12	4	浮動小数点数	Xサイズ
16	4	浮動小数点数	Yサイズ

7: Vector3

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

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座標
8	4	浮動小数点数	Y座標
12	4	浮動小数点数	Z座標
16	4	浮動小数点数	Xサイズ
20	4	浮動小数点数	Yサイズ
24	4	浮動小数点数	Zサイズ

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	浮動小数点数	赤 (0..1)
8	4	浮動小数点数	緑 (0..1)
12	4	浮動小数点数	青 (0..1)
16	4	浮動小数点数	アルファ (0..1)

15: NodePath

Offset	バイト長	タイプ(型)	説明
4	4	整数	文字列の長さ、または新しい形式(val&0x80000000!=0 及び NameCount=val&0x7FFFFFFF)

古い形式の場合:

Offset	バイト長	タイプ(型)	説明
8	X	バイト列	UTF-8エンコードされた文字列

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

新しい形式の場合:

Offset	バイト長	タイプ(型)	説明
4	4	整数	サブネームのカウント
8	4	整数	フラグ (絶対値: val&1 != 0)

名前とサブネームごと

Offset	バイト長	タイプ(型)	説明
X+0	4	整数	文字列の長さ
X+4	X	バイト列	UTF-8エンコードされた文字列

すべての名前文字列は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	整数	配列の長さ (バイト)
8..8+長さ	1	Byte	Byte (符号なし: 0..255)

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

21: PoolIntArray

Offset	バイト長	タイプ(型)	説明
4	4	整数	配列の長さ (整数)
8..8+長さ*4	4	整数	32ビット符号付き整数

22: PoolRealArray

Offset	バイト長	タイプ(型)	説明
4	4	整数	配列の長さ (浮動小数点数)
8..8+長さ*4	4	整数	32 Bits IEEE 754 Float

23: PoolStringArray

Offset	バイト長	タイプ(型)	説明
4	4	整数	配列の長さ (文字列)

各文字列に対して:

Offset	バイト長	タイプ(型)	説明
X+0	4	整数	文字列の長さ
X+4	X	バイト列	UTF-8エンコードされた文字列

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

24: PoolVector2Array

Offset	バイト長	タイプ(型)	説明
4	4	整数	配列の長さ
8..8+長さ*8	4	浮動小数点数	X座標
8..12+長さ*8	4	浮動小数点数	Y座標

25: PoolVector3Array

Offset	バイト長	タイプ(型)	説明
4	4	整数	配列の長さ
8..8+長さ*12	4	浮動小数点数	X座標
8..12+長さ*12	4	浮動小数点数	Y座標
8..16+長さ*12	4	浮動小数点数	Z座標

26: PoolColorArray

Offset	バイト長	タイプ(型)	説明
4	4	整数	配列の長さ
8..8+長さ*16	4	浮動小数点数	赤 (0..1)
8..12+長さ*16	4	浮動小数点数	緑 (0..1)
8..16+長さ*16	4	浮動小数点数	青 (0..1)
8..20+長さ*16	4	浮動小数点数	アルファ (0..1)