Work in progress
The content of this page was not yet updated for Godot
4.2
and may be outdated. If you know how to improve this page or you can confirm
that it's up to date, feel free to open a pull request.
バイナリシリアル化API¶
はじめに¶
Godot has a serialization API based on Variant. It's used for
converting data types to an array of bytes efficiently. This API is exposed
via the global bytes_to_var()
and var_to_bytes() functions,
but it is also used in the get_var
and store_var
methods of
FileAccess as well as the packet APIs for PacketPeer.
This format is not used for binary scenes and resources.
Full Objects vs Object instance IDs¶
If a variable is serialized with full_objects = true
, then any Objects
contained in the variable will be serialized and included in the result. This
is recursive.
If full_objects = false
, then only the instance IDs will be serialized for
any Objects contained in the variable.
パケットの仕様¶
パケットは、常に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 |
quaternion |
11 |
aabb |
12 |
basis |
13 |
transform3d |
14 |
色 |
15 |
node path |
16 |
rid |
17 |
オブジェクト |
18 |
dictionary |
19 |
array |
20 |
raw array |
21 |
int32 array |
22 |
int64 array |
23 |
float32 array |
24 |
float64 array |
25 |
string array |
26 |
vector2 array |
27 |
vector3 array |
28 |
color array |
29 |
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: Quaternion¶
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
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: Transform3D¶
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
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¶
An Object could be serialized in three different ways: as a null value, with
full_objects = false
, or with full_objects = true
.
A null value¶
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
4 |
4 |
整数 |
Zero (32-bit signed integer) |
full_objects
disabled¶
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
4 |
8 |
整数 |
The Object instance ID (64-bit signed integer) |
full_objects
enabled¶
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
4 |
4 |
整数 |
Class name (String length) |
8 |
X |
バイト列 |
Class name (UTF-8 encoded string) |
X+8 |
4 |
整数 |
The number of properties that are serialized |
For each property:
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
Y |
4 |
整数 |
Property name (String length) |
Y+4 |
Z |
バイト列 |
Property name (UTF-8 encoded string) |
Y+4+Z |
W |
<variable> |
Property value, using this same format |
注釈
Not all properties are included. Only properties that are configured with the
PROPERTY_USAGE_STORAGE
flag set will be serialized. You can add a new usage flag to a property by overriding the
_get_property_list
method in your class. You can also check how property usage is configured by
calling Object._get_property_list
See
PropertyUsageFlags for the
possible usage flags.
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: PackedByteArray¶
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
4 |
4 |
整数 |
Array length (Bytes) |
8..8+長さ |
1 |
Byte |
Byte (符号なし: 0..255) |
配列データは4バイトにパディングされます。
21: PackedInt32Array¶
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
4 |
4 |
整数 |
Array length (Integers) |
8..8+長さ*4 |
4 |
整数 |
32-bit signed integer |
22: PackedInt64Array¶
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
4 |
8 |
整数 |
Array length (Integers) |
8..8+長さ*8 |
8 |
整数 |
64-bit signed integer |
23: PackedFloat32Array¶
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
4 |
4 |
整数 |
Array length (Floats) |
8..8+長さ*4 |
4 |
整数 |
32-bit IEEE 754 single-precision float |
24: PackedFloat64Array¶
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
4 |
4 |
整数 |
Array length (Floats) |
8..8+長さ*8 |
8 |
整数 |
64-bit IEEE 754 double-precision float |
25: PackedStringArray¶
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
4 |
4 |
整数 |
Array length (Strings) |
各文字列に対して:
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
X+0 |
4 |
整数 |
String length |
X+4 |
X |
バイト列 |
UTF-8 encoded string |
すべての文字列は4バイトにパディングされます。
26: PackedVector2Array¶
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
4 |
4 |
整数 |
Array length |
8..8+長さ*8 |
4 |
フロート |
X coordinate |
8..12+長さ*8 |
4 |
フロート |
Y coordinate |
27: PackedVector3Array¶
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
4 |
4 |
整数 |
Array length |
8..8+長さ*12 |
4 |
フロート |
X coordinate |
8..12+長さ*12 |
4 |
フロート |
Y coordinate |
8..16+長さ*12 |
4 |
フロート |
Z coordinate |
28: PackedColorArray¶
オフセット |
バイト長 |
タイプ(型) |
説明 |
---|---|---|---|
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) |