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

タイプ(型)
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

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

3: float

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

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)