Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

바이너리 직렬화 API

소개

Godot에는 Variant를 기반으로 한 직렬화 API가 있습니다. 데이터 유형을 바이트 배열로 효율적으로 변환하는 데 사용됩니다. 이 API는 전역 bytes_to_var() 및 var_to_bytes() 함수를 통해 노출되지만 다음의 get_var 및 store_var 메서드에서도 사용됩니다. FileAccess 및 :ref:`class_PacketPeer`용 패킷 API. 이 형식은 바이너리 장면 및 리소스에 사용되지 않습니다.

전체 객체와 객체 인스턴스 ID

변수가 ``full_objects = true``로 직렬화되면 변수에 포함된 모든 개체가 직렬화되어 결과에 포함됩니다. 이는 재귀적입니다.

``full_objects = false``인 경우 변수에 포함된 모든 개체에 대해 인스턴스 ID만 직렬화됩니다.

패킷 사양

패킷은 항상 4바이트로 채워지도록 설계되었습니다. 모든 값은 리틀 엔디안으로 인코딩됩니다. 모든 패킷에는 데이터 유형을 지정하는 정수를 나타내는 4바이트 헤더가 있습니다.

가장 낮은 값 2바이트는 유형을 결정하는 데 사용되며 가장 높은 값 2바이트에는 플래그가 포함됩니다.

base_type = val & 0xFFFF;
flags = val >> 16;

유형	값
0	null
1	bool
2	정수
3	float
4	문자열
5	벡터2
6	직사각형2
7	벡터3
8	변환 2D
9	비행기
10	쿼터니언
11	아브
12	기초
13	변형
14	색
15	노드 경로
16	없애다
17	오브젝트
18	사전
19	배열
20	원시 배열
21	int32 배열
22	int64 배열
23	지역 변수(Local Variables)
24	float64 배열
25	문자열 배열
26	벡터2 배열
27	벡터3 배열
28	색상 배열
2	최대

아래는 실제 패킷 내용으로, 각 패킷의 타입에 따라 다릅니다. 이는 Godot가 디폴트로 단정밀도(single-precision) 실수형으로 컴파일되었음을 가정합니다. 만약 Godot가 배정밀도(double-precision) 실수형으로 컴파일되었다면, 자료 구조 내 "Float" 필드의 길이는 8이 되어야 하며, 오프셋은 (offset - 4) * 2 + 4가 되어야 합니다. "float" 타입 자체는 항상 배정밀도를 사용합니다.

0: 널

1: bool

오프셋	렌	유형	설명
4	4	정수	거짓이면 0, 참이면 1

2: int

플래그가 설정되지 않은 경우(플래그 == 0) 정수는 32비트 정수로 전송됩니다.

오프셋	렌	유형	설명
4	4	정수	32비트 부호 있는 정수

플래그 ENCODE_FLAG_64``가 설정된 경우(``flags & 1 == 1) 정수는 64비트 정수로 전송됩니다.

오프셋	렌	유형	설명
4	8	정수	64비트 부호 있는 정수

float

플래그가 설정되지 않은 경우(플래그 == 0) 부동 소수점은 32비트 단정밀도로 전송됩니다.

오프셋	렌	유형	설명
4	4	Float	IEEE 754 단정밀도 부동 소수점

플래그 ENCODE_FLAG_64``가 설정된 경우(``flags & 1 == 1) 부동 소수점은 64비트 배정밀도 숫자로 전송됩니다.

오프셋	렌	유형	설명
4	8	Float	IEEE 754 배정밀도 부동 소수점

4: String

오프셋	렌	유형	설명
4	4	정수	문자열 길이 (바이트 단위)
8	X	바이트	UTF-8 인코딩된 문자열

이 필드는 4바이트로 채워져 있습니다.

5: Vector2

오프셋	렌	유형	설명
4	4	Float	X 좌표
8	4	Float	Y 좌표

6: Rect2

오프셋	렌	유형	설명
4	4	Float	X 좌표
8	4	Float	Y 좌표
12	4	Float	X 크기
16	4	Float	Y 크기

7: Vector3

오프셋	렌	유형	설명
4	4	Float	X 좌표
8	4	Float	Y 좌표
12	4	Float	Z 좌표

8: Transform2D

오프셋	렌	유형	설명
4	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
8	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
12	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
16	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
20	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
24	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.

9: Plane

오프셋	렌	유형	설명
4	4	Float	노멀X
8	4	Float	노멀 Y
12	4	Float	노멀Z
16	4	Float	거리

Quat

오프셋	렌	유형	설명
4	4	Float	상상의 X
8	4	Float	상상의 Y
12	4	Float	상상의 Z
16	4	Float	레알 여

11: AABB

오프셋	렌	유형	설명
4	4	Float	X 좌표
8	4	Float	Y 좌표
12	4	Float	Z 좌표
16	4	Float	X 크기
20	4	Float	Y 크기
24	4	Float	Z 사이즈

12: Basis

오프셋	렌	유형	설명
4	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
8	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
12	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
16	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
20	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
24	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
28	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
32	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
36	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.

Transform

오프셋	렌	유형	설명
4	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
8	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
12	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
16	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
20	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
24	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
28	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
32	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
36	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
40	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
44	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.
48	4	Float	벡터의 각각의 컴포넌트는 이름으로 직접 접근할 수 있습니다.

14: Color

오프셋	렌	유형	설명
4	4	Float	빨간색(일반적으로 0..1, 지나치게 밝은 색상의 경우 1보다 높을 수 있음)
8	4	Float	녹색(일반적으로 0..1, 지나치게 밝은 색상의 경우 1보다 높을 수 있음)
12	4	Float	파란색(일반적으로 0..1, 지나치게 밝은 색상의 경우 1보다 높을 수 있음)
16	4	Float	알파(0..1)

15: NodePath

오프셋	렌	유형	설명
4	4	정수	문자열 길이 또는 새로운 형식(val&0x80000000!=0 및 NameCount=val&0x7FFFFFFF)

이전 형식의 경우:

오프셋	렌	유형	설명
8	X	바이트	UTF-8 인코딩된 문자열

4바이트로 채워졌습니다.

새로운 형식의 경우:

오프셋	렌	유형	설명
4	4	정수	하위 이름 수
8	4	정수	플래그(절대: val&1 != 0 )

각 이름 및 하위 이름에 대해

오프셋	렌	유형	설명
X+0	4	정수	줄 길이
X+4	X	바이트	UTF-8 인코딩된 문자열

모든 이름 문자열은 4바이트로 채워집니다.

16: :ref:`RID<class_rid>`(지원되지 않음)

Object

개체는 null 값, full_objects = false 또는 ``full_objects = true``의 세 가지 방법으로 직렬화될 수 있습니다.

null 값

오프셋	렌	유형	설명
4	4	정수	0(32비트 부호 있는 정수)

full_objects 비활성화됨

오프셋	렌	유형	설명
4	8	정수	객체 인스턴스 ID(64비트 부호 있는 정수)

full_objects 활성화됨

오프셋	렌	유형	설명
4	4	정수	줄 길이
8	X	바이트	클래스 이름(UTF-8로 인코딩된 문자열)
X+8	4	정수	6 가지 패턴 유형이 있습니다:

각각의 속성:

오프셋	렌	유형	설명
Y	4	정수	줄 길이
Y+4	지	바이트	속성 이름(UTF-8로 인코딩된 문자열)
Y+4+Z	여	변수	동일한 형식을 사용하는 속성 값

참고

모든 속성이 포함되는 것은 아닙니다. PROPERTY_USAGE_STORAGE 플래그 세트로 구성된 속성만 직렬화됩니다. 클래스에서 _get_property_list 메서드를 재정의하여 속성에 새 사용 플래그를 추가할 수 있습니다. ``Object._get_property_list``를 호출하여 속성 사용이 어떻게 구성되었는지 확인할 수도 있습니다. 가능한 사용 플래그는 :ref:`PropertyUsageFlags<enum_@GlobalScope_PropertyUsageFlags>`를 참조하세요.

18: Dictionary

오프셋	렌	유형	설명
4	4	정수	val&0x7FFFFFFF = 요소, val&0x80000000 = 공유(부울)

그런 다음 "요소"의 양에 대해 동일한 형식을 사용하여 키와 값의 쌍을 차례로 사용합니다.

19: Array

오프셋	렌	유형	설명
4	4	정수	val&0x7FFFFFFF = 요소, val&0x80000000 = 공유(부울)

그런 다음 "요소"의 양에 대해 동일한 형식을 사용하여 값을 차례로 지정합니다.

Array

오프셋	렌	유형	설명
4	4	정수	배열 길이(바이트)
8..8+length	1	바이트	바이트(0..255)

배열 데이터는 4바이트로 채워집니다.

Array

오프셋	렌	유형	설명
4	4	정수	배열 길이(정수)
8..8+길이*4	4	정수	32비트 부호 있는 정수

Array

오프셋	렌	유형	설명
4	8	정수	배열 길이(정수)
8..8+길이*8	8	정수	64비트 부호 있는 정수

Array

오프셋	렌	유형	설명
4	4	정수	배열 길이(부동 소수점)
8..8+길이*4	4	정수	32비트 IEEE 754 단정밀도 부동 소수점

Array

오프셋	렌	유형	설명
4	4	정수	배열 길이(부동 소수점)
8..8+길이*8	8	정수	64비트 IEEE 754 배정밀도 부동 소수점

String

오프셋	렌	유형	설명
4	4	정수	배열 길이(문자열)

각 문자열에 대해:

오프셋	렌	유형	설명
X+0	4	정수	줄 길이
X+4	X	바이트	UTF-8 인코딩된 문자열

모든 문자열은 4바이트로 채워집니다.

Vector3

오프셋	렌	유형	설명
4	4	정수	ArrayMesh
8..8+길이*8	4	Float	X 좌표
8..12+길이*8	4	Float	Y 좌표

Vector3

오프셋	렌	유형	설명
4	4	정수	ArrayMesh
8..8+길이*12	4	Float	X 좌표
8..12+길이*12	4	Float	Y 좌표
8..16+길이*12	4	Float	Z 좌표

Array

오프셋	렌	유형	설명
4	4	정수	ArrayMesh
8..8+길이*16	4	Float	빨간색(일반적으로 0..1, 지나치게 밝은 색상의 경우 1보다 높을 수 있음)
8..12+길이*16	4	Float	녹색(일반적으로 0..1, 지나치게 밝은 색상의 경우 1보다 높을 수 있음)
8..16+길이*16	4	Float	파란색(일반적으로 0..1, 지나치게 밝은 색상의 경우 1보다 높을 수 있음)
8..20+길이*16	4	Float	알파(0..1)