バイナリシリアル化API

はじめに

Godotには、Variantに基づくシンプルなシリアル化APIがあります。データ型をバイト配列に効率的に変換するために使用されます。このAPIは、class_File の get_var および store_var 関数で使用されるほか、class_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

次は実際のパケットの内容であり、パケットのタイプごとに異なります:

0: null

1: bool

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

2: int

Offset バイト長 タイプ(型) 説明
4 4 整数 符号付き32ビット整数

3: float/real

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 浮動小数点数 [0][0]
8 4 浮動小数点数 [0][1]
12 4 浮動小数点数 [1][0]
16 4 浮動小数点数 [1][1]
20 4 浮動小数点数 [2][0]
24 4 浮動小数点数 [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 浮動小数点数 [0][0]
8 4 浮動小数点数 [0][1]
12 4 浮動小数点数 [0][2]
16 4 浮動小数点数 [1][0]
20 4 浮動小数点数 [1][1]
24 4 浮動小数点数 [1][2]
28 4 浮動小数点数 [2][0]
32 4 浮動小数点数 [2][1]
36 4 浮動小数点数 [2][2]

13: Transform

Offset バイト長 タイプ(型) 説明
4 4 浮動小数点数 [0][0]
8 4 浮動小数点数 [0][1]
12 4 浮動小数点数 [0][2]
16 4 浮動小数点数 [1][0]
20 4 浮動小数点数 [1][1]
24 4 浮動小数点数 [1][2]
28 4 浮動小数点数 [2][0]
32 4 浮動小数点数 [2][1]
36 4 浮動小数点数 [2][2]
40 4 浮動小数点数 [3][0]
44 4 浮動小数点数 [3][1]
48 4 浮動小数点数 [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ビットIEE 754浮動小数点

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)