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 有一個基於 Variant 的簡單序列化 API。它用於有效地將資料型別轉換為位元組陣列。這個 API 用於 class_File 的 get_var
和 store_var
函式,以及 PacketPeer 的資料包 API。二進位場景和資源*不使用*該格式。
完整物件與物件實例 ID¶
如果使用「full_objects = true」序列化變量,則該變數中包含的任何物件都會被序列化並包含在結果中。這是遞歸的。
如果“full_objects = false”,則只有實例 ID 才會被序列化為變數中包含的任何物件。
封包規格¶
根據設計,封包總是會被填充到 4 個位元組。所有的值都是小端編碼的。所有封包都有一個 4 位元組的頭,代表一個整數,指定資料的型別。
兩個低位元組用於確定型別,而兩個高位元組則包含旗標:
base_type = val & 0xFFFF;
flags = val >> 16;
型別 |
值 |
---|---|
0 |
null |
1 |
bool |
2 |
整數 |
3 |
浮點數 |
4 |
字串 |
5 |
vector2 |
6 |
rect2 |
7 |
vector3 |
8 |
transform2d |
9 |
plane |
10 |
四元數 |
11 |
aabb |
12 |
basis |
13 |
變換 |
14 |
顏色 |
15 |
節點路徑 |
16 |
rid |
17 |
物件 |
18 |
字典 |
19 |
陣列 |
20 |
原始陣列 |
21 |
反轉陣列。 |
22 |
反轉陣列。 |
23 |
本地坐標 |
24 |
本地坐標 |
25 |
字串陣列 |
26 |
vector2 陣列 |
27 |
vector3 陣列 |
28 |
顏色陣列 |
29 |
最大值 |
在此之後是實際的封包內容,每種型別的封包內容都不同。請注意,這裡假設 Godot 是用單精確度浮點數編譯的,這也是預設的。如果 Godot 是用雙精度浮點數編譯的,那麼資料結構中“浮點數”欄位的長度應該是 8,偏移量應該是 (offset - 4) * 2 + 4
。浮點數“float”型別本身總是使用雙精度。
0: null¶
1: bool¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
0 代表 False, 1 代表 True |
2: int¶
如果沒有設定旗標(flags == 0),整數將作為32位元整數發送:
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
32位元有符號整數 |
如果旗標 ENCODE_FLAG_64
被設定(flags & 1 == 1
),則整數被發送為64位元整數:
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
8 |
整數 |
64位元有符號整數 |
3: float¶
如果沒有設定旗標(flags == 0),浮點數將作為 32 位單精確度發送:
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
浮點數 |
IEEE 754 單精確度浮點數 |
如果設定了 ENCODE_FLAG_64
旗標(flags & 1 == 1
),浮點數將作為 64 位元雙精度數字發送:
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
8 |
浮點數 |
IEEE 754 雙精度浮點數 |
4: String¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
字串長度(位元組數) |
8 |
X |
多位元組 |
UTF-8 編碼字串 |
該欄位會被填充到 4 個位元組。
5: Vector2¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
浮點數 |
下一個座標 |
8 |
4 |
浮點數 |
下一個座標 |
6: Rect2¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
浮點數 |
下一個座標 |
8 |
4 |
浮點數 |
下一個座標 |
12 |
4 |
浮點數 |
X 尺寸 |
16 |
4 |
浮點數 |
Y 尺寸 |
7: Vector3¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
浮點數 |
下一個座標 |
8 |
4 |
浮點數 |
下一個座標 |
12 |
4 |
浮點數 |
下一個座標 |
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 |
浮點數 |
距離 |
Quat¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
浮點數 |
虛數 X |
8 |
4 |
浮點數 |
虛數 Y |
12 |
4 |
浮點數 |
虛數 Z |
16 |
4 |
浮點數 |
實數 W |
11: AABB¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
浮點數 |
下一個座標 |
8 |
4 |
浮點數 |
下一個座標 |
12 |
4 |
浮點數 |
下一個座標 |
16 |
4 |
浮點數 |
X 尺寸 |
20 |
4 |
浮點數 |
Y 尺寸 |
24 |
4 |
浮點數 |
Z 尺寸 |
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]存取 |
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 |
浮點數 |
紅色(一般為 0...1,對於過亮的顏色可大於 1) |
8 |
4 |
浮點數 |
綠色(一般為 0...1,對於過亮的顏色可大於 1) |
12 |
4 |
浮點數 |
藍色(一般為 0...1,對於過亮的顏色可大於 1) |
16 |
4 |
浮點數 |
Alpha(0..1) |
15: NodePath¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
字串長度, 或新格式(val&0x80000000!=0 and NameCount=val&0x7FFFFFFF) |
對於舊格式:¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
8 |
X |
多位元組 |
UTF-8 編碼字串 |
填充到4個位元組.
對於新格式:¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
子名稱數 |
8 |
4 |
整數 |
旗標 (absolute: val&1 != 0 ) |
對於每個名稱和子名稱
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
X+0 |
4 |
整數 |
每行字數限制 |
X+4 |
X |
多位元組 |
UTF-8 編碼字串 |
每個名稱字串都會填充到4個位元組.
16: :ref:`RID<class_rid>`(不支援)¶
Object¶
物件可以透過三種不同的方式序列化:作為空值,使用“full_objects = false”,或使用“full_objects = true”。
空值¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
零(32 位元帶符號整數) |
禁用 full_objects
¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
8 |
整數 |
Object 實例 ID(64 位元帶符號整數) |
啟用 full_objects
¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
每行字數限制 |
8 |
X |
多位元組 |
類別名稱(UTF-8 編碼字串) |
X+8 |
4 |
整數 |
有六種搜尋模式: |
節點屬性
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
Y |
4 |
整數 |
每行字數限制 |
Y+4 |
Z |
多位元組 |
屬性名稱(UTF-8 編碼字串) |
Y+4+Z |
W |
變數 |
屬性值,格式相同 |
備註
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 = 元素,val&0x80000000 = 共用(bool) |
然後,後續就有“元素”數量個連續的鍵值對,使用的也是這種相同的格式。
19:Array¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
val&0x7FFFFFFF = 元素,val&0x80000000 = 共用(bool) |
然後,後續就有“元素”數量個連續的值,使用的也是這種相同的格式。
Array¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
陣列長度(位元組) |
8..8+長度 |
1 |
Byte |
位元組 (0..255) |
陣列資料填充為4個位元組.
Array¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
陣列長度(整數) |
8..8+length*4 |
4 |
整數 |
32位元有符號整數 |
Array¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
8 |
整數 |
陣列長度(整數) |
8..8+length*8 |
8 |
整數 |
64位元有符號整數 |
Array¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
陣列長度(浮點數) |
8..8+length*4 |
4 |
整數 |
32 位 IEEE 754 單精確度浮點數 |
Array¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
陣列長度(浮點數) |
8..8+length*8 |
8 |
整數 |
64 位 IEEE 754 雙精度浮點數 |
String¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
陣列長度(字串) |
對於每個字串:
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
X+0 |
4 |
整數 |
每行字數限制 |
X+4 |
X |
多位元組 |
UTF-8 編碼字串 |
每個字串填充為4個位元組.
Vector3¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
陣列 |
8..8+length*8 |
4 |
浮點數 |
下一個座標 |
8..12+length*8 |
4 |
浮點數 |
下一個座標 |
Vector3¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
陣列 |
8..8+length*12 |
4 |
浮點數 |
下一個座標 |
8..12+length*12 |
4 |
浮點數 |
下一個座標 |
8..16+length*12 |
4 |
浮點數 |
下一個座標 |
Array¶
偏移量 |
長度 |
型別 |
說明 |
---|---|---|---|
4 |
4 |
整數 |
陣列 |
8..8+length*16 |
4 |
浮點數 |
紅色(一般為 0...1,對於過亮的顏色可大於 1) |
8..12+length*16 |
4 |
浮點數 |
綠色(一般為 0...1,對於過亮的顏色可大於 1) |
8..16+length*16 |
4 |
浮點數 |
藍色(一般為 0...1,對於過亮的顏色可大於 1) |
8..20+length*16 |
4 |
浮點數 |
Alpha(0..1) |