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...
번역 형식
gdextension_interface.json 파일은 Godot가 GDExtensions와 통신하는 데 사용하는 C API의 "진실 소스"입니다.
다음 명령을 사용하여 Godot 실행 파일을 사용하여 파일을 덤프할 수 있습니다:
godot --headless --dump-gdextension-interface-json
이 파일은 GDExtension 언어 바인딩에서 해당 언어에 가장 적합한 형식으로 이 API를 사용하기 위한 코드를 생성하는 데 사용됩니다.
참고
이는 GDExtension 언어 바인딩에서도 사용되며 Godot에 의해 노출되는 클래스 및 메소드에 대한 정보를 포함하는 ``extension_api.json``와 혼동하지 마십시오. ``gdextension_interface.json``는 더 낮은 수준이며 더 높은 수준의 클래스 및 메서드와 상호 작용하는 데 사용됩니다.
C를 통해 확장할 수 있거나 C 코드와 상호 작용하기 위한 도구를 제공할 수 있는 언어의 경우 Godot 실행 파일을 사용하여 생성된 C 헤더 파일을 덤프하는 것도 가능합니다:
godot --headless --dump-gdextension-interface
참고
헤더 파일은 Godot 4.5 및 이전 버전에 포함된 이전 버전의 헤더 파일과 호환됩니다. 이는 호환성을 보장하기 위해 이름의 일부 오타를 보존한다는 의미입니다.
이 페이지의 목표는 JSON에서 자체 코드 생성을 수행하려는 GDExtension 언어 바인딩의 JSON 형식을 설명하는 것입니다.
노드 구조
JSON 파일은 3개의 섹션으로 구성됩니다.
JSON 파일의 최상위 수준에 있는 몇 가지 기타 정보를 포함하는 헤더입니다.
GDExtension 인터페이스에 사용되는 모든 유형을 정의하는
types키.interface키는 로드될 때 모든 GDExtension에 전달되는GDExtensionInterfaceGetProcAddress함수 포인터를 통해 로드할 수 있는 모든 함수 포인터를 정의합니다.
https://github.com/godotengine/godot-demo-projects
Godot의 각 마이너 릴리스마다 새로운 유형과 인터페이스 기능을 추가할 수 있지만, 이전 버전과 호환되지 않는 방식으로 절대로 변경하거나 제거하지 않으려고 노력합니다. 모든 인터페이스 기능에는 그것이 도입된 Godot 버전(since 키)이 표시되어 있으므로 항상 최신 버전의 파일을 사용할 수 있으며, 목표로 하는 버전보다 최신 버전의 Godot에서는 어떤 것도 사용하지 마십시오.
셰이더
"헤더"는 파일의 최상위 수준에 있는 3개의 기타 키로 구성됩니다.
_copyright: Godot가 모든 소스 코드 파일에 포함하는 표준 저작권 및 라이센스 텍스트입니다.$schema: 이 파일과 관련된 JSON 스키마를 가리킵니다. JSON 스키마를 이해하는 코드 편집기로 스키마를 보는 경우 동일한 디렉터리에 스키마를 배치하는 것이 유용할 수 있습니다.format_version: 파일 형식 버전(스키마를 의미)에 대한 정수입니다. 현재는 하나의 형식 버전(1)만 있습니다. 호환되지 않는 방식으로 파일 형식을 변경하면 이 숫자가 증가합니다. 이는 파일의 데이터 버전을 반영하지 *않으며*(따라서 Godot 버전 간에 변경되지 않음) 형식만 반영합니다. 바라건대, 우리는 이것을 사용할 필요가 없지만, 여기서 예상치 못한 값을 발견하면 코드 생성기가 조기에 오류를 발생시킬 수 있습니다.
타입(Types)
types 섹션은 다른 타입에서 사용할 타입의 배열과 마지막 섹션에 들어갈 인터페이스 기능이다.
유형은 순서대로 평가되어야 합니다. 이후 유형은 이전 유형을 참조할 수 있지만 이전 유형은 이후 유형을 참조하지 않습니다.
JSON에 명시적으로 나열되지 않은 작은 내장 유형 세트가 있습니다.
-> voidinColor8inuint16_tinuint32_tinuint64_tsize_t``(32비트 아키텍처에서는 ``uint32_t, 64비트 아키텍처에서는uint64_t)charchar16_tchar32_twchar_tfloat[]byte[]
이는 동등한 C 유형에 해당합니다.
또한 유형에는 다음과 같은 수정자가 포함될 수 있습니다.
유형에 대한 포인터를 나타내는
*``(예: ``int8_t*)const 유형을 나타내는
const``(예: ``const int8_t*)
JSON 파일에 정의된 각 유형은 5가지 "종류" 중 하나에 속합니다.
endScale정면 뷰
: String함수
"종류"에 관계없이 모든 유형은 다음과 같은 키를 가질 수 있습니다.
kind(필수): 유형의 "종류"입니다.``name``(필수): 유효한 C 식별자로 사용될 수 있는 유형의 이름입니다.
description: 유형을 문서화하는 문자열 배열입니다. 여기서 각 문자열은 문서 라인입니다(``description``에 대한 이 형식은 JSON 파일 전체에서 사용됩니다).deprecated: 해당 유형이 더 이상 사용되지 않는 Godot 버전(since)에 대한 자체 키가 있는 객체, 더 이상 사용되지 않음을 설명하는 메시지(message), 선택적으로 대신 사용할 대체 항목(replacement).
열거형
열거형은 고정된 가능한 값 집합이 있는 32비트 정수입니다. C에서는 ``enum``로 표현될 수 있습니다.
다음 예제에서:
is_bitfield: true인 경우 이 열거형은 비트필드이며, 여기서 열거형 값은 함께 비트 OR로 연결될 수 있습니다. 기본적으로는 거짓입니다.values: 각각name,value및 ``description``를 포함하는 이 열거형의 고정 값 배열입니다.
열거형은 ``is_bitfield``가 true가 아닌 한 ``int32_t``로 표시되어야 하며, 이 경우 ``uint32_t``를 사용해야 합니다.
예제
{
"name": "GDExtensionInitializationLevel",
"kind": "enum",
"values": [
{
"name": "GDEXTENSION_INITIALIZATION_CORE",
"value": 0
},
{
"name": "GDEXTENSION_INITIALIZATION_SERVERS",
"value": 1
},
{
"name": "GDEXTENSION_INITIALIZATION_SCENE",
"value": 2
},
{
"name": "GDEXTENSION_INITIALIZATION_EDITOR",
"value": 3
},
{
"name": "GDEXTENSION_MAX_INITIALIZATION_LEVEL",
"value": 4
}
]
}
핸들
핸들은 불투명 구조체에 대한 포인터입니다. C에서는 void * 또는 ``struct{} *``로 표시될 수 있습니다.
다음 예제에서:
is_const: true인 경우 이 핸들 유형은 "const 포인터"로 처리됩니다. 즉, 내부 데이터가 변경되지 않음을 의미합니다. 기본적으로는 거짓입니다.is_uninitialized: true인 경우 이 핸들 유형은 초기화되지 않은 메모리(인터페이스 함수를 사용하여 초기화될 수 있음)를 가리키는 것으로 처리됩니다. 기본적으로는 거짓입니다.parent: 이 핸들 유형이 상위 유형의 const 또는 초기화되지 않은 버전인 경우 다른 핸들 유형의 선택적 이름입니다. 이는is_const또는 ``is_uninitialized``가 true인 경우에만 의미가 있습니다.
핸들은 지정된 아키텍처에서 포인터의 크기입니다(예를 들어 x86_64에서는 64비트, x86_32에서는 32비트).
예제
{
"name": "GDExtensionStringNamePtr",
"kind": "handle"
}
정면 뷰
별칭은 유형에 대한 대체 이름입니다. C에서는 ``typedef``로 표시될 수 있습니다.
추가 키는 하나만 있습니다.
type: 별칭이 대체 이름인 유형입니다. 이는 위에서 설명한 수정자를 포함할 수 있습니다.
이는 참조하는 유형과 동일한 C 유형을 사용하여 표현되어야 합니다.
예제
{
"name": "GDExtensionInt",
"kind": "alias",
"type": "int64_t"
}
생성자
구조체는 C structs(주어진 멤버를 순서대로 구성한 메모리 블록이라고도 함)를 나타내며 C 구조체와 동일한 레이아웃 및 정렬 규칙을 모두 따라야 합니다.
추가 키는 하나만 있습니다.
예제
{
"name": "GDExtensionCallError",
"kind": "struct",
"members": [
{
"name": "error",
"type": "GDExtensionCallErrorType"
},
{
"name": "argument",
"type": "int32_t"
},
{
"name": "expected",
"type": "int32_t"
}
]
}
함수
함수는 인수 목록과 반환 유형을 사용하여 C 함수 포인터 유형을 나타내며 C 함수 포인터와 동일한 크기 및 정렬 요구 사항을 따라야 합니다.
다음 예제에서:
return_value: ``type``(수정자를 포함할 수 있음) 및 ``description``가 있는 개체입니다. 함수에 반환 값이 없으면 생략됩니다.arguments``(필수): 각각 ``type``(수정자를 포함할 수 있음), ``name및 ``description``가 있는 함수 인수 배열입니다.
예제
{
"name": "GDExtensionPtrConstructor",
"kind": "function",
"arguments": [
{
"name": "p_base",
"type": "GDExtensionUninitializedTypePtr"
},
{
"name": "p_args",
"type": "const GDExtensionConstTypePtr*"
}
]
}
Godot 인터페이스
JSON 파일의 interface 섹션은 로드될 때 모든 GDExtension에 전달되는 GDExtensionInterfaceGetProcAddress 함수 포인터를 사용하여 ``name``에서 로드할 수 있는 인터페이스 함수 목록입니다.
인터페이스 기능에는 name``(필수), ``deprecated 및 ``description``를 포함하여 유형과 동일한 키 중 일부가 있습니다.
또한 기능 유형의 해당 키와 동일한 형식을 갖는 return_value 및 ``arguments``(필수)도 있습니다(이전 섹션에서 설명).
소수의 고유 키만 있습니다.
since(필수): 이 인터페이스 기능을 도입한 Godot 버전입니다.see: 예를 들어 Godot 소스 코드의 클래스나 함수 이름, 문서를 가리키는 URL과 같은 추가 정보가 포함된 외부 참조를 설명하는 문자열 배열입니다.legacy_type_name: 레거시 이름이 이러한 유형 이름에 사용된 패턴과 일치하지 않을 때 Godot가 생성한 헤더의 함수 포인터 유형에 사용되는 레거시 이름입니다. 이 필드는 Godot 4.5 또는 이전 버전의 헤더와 역호환되는 방식으로 헤더를 생성할 수 있도록 하기 위해서만 존재하며, 이전 헤더와의 호환성도 유지해야 하는 경우가 아니면 사용해서는 안 됩니다.
예제
{
"name": "get_godot_version",
"arguments": [
{
"name": "r_godot_version",
"type": "GDExtensionGodotVersion*",
"description": [
"A pointer to the structure to write the version information into."
]
}
],
"description": [
"Gets the Godot version that the GDExtension was loaded into."
],
"since": "4.1",
"deprecated": {
"since": "4.5",
"replace_with": "get_godot_version2"
}
}