Kiến trúc

Code game không bao giờ gọi thẳng vào phần native. Mọi lời gọi đi qua một autoload GDScript — autoload chọn phần native đúng nền tảng, hoặc trả giá trị mặc định khi chạy trong editor.

Luồng gọi

Code gameNativeUtils.get_app_info()

→

Autoload GDScriptAPI chung · fallback · chuyển tiếp API có sẵn của Godot

→

AndroidSingleton Leono… · Kotlin AAR

iOSSingleton Leono… · GDExtension

Autoload (NativeUtils…): API duy nhất game dùng. Có fallback cho editor/PC, biến callback thành hàm await được.
Singleton native (LeonoNativeUtils…): cùng tên, cùng tên hàm (snake_case), cùng signal trên Android và iOS.
Chuyển tiếp API của Godot: thứ Godot đã có (clipboard, locale, rung…) autoload gọi thẳng built-in, không viết lại bằng native.

Cấu trúc một plugin

plugins/<tên>/
├── android/                     Kotlin — Godot Android plugin v2 → .aar
├── ios/                         ObjC++ — GDExtension (godot-cpp 10, api 4.7) → .xcframework
├── addon/leono_<tên>/          thư mục game copy vào res://addons/
│   ├── plugin.cfg, plugin.gd    EditorPlugin: thêm autoload, cấu hình export
│   ├── <autoload>.gd            API duy nhất game gọi
│   ├── deps.json                thư viện Maven Android — một nguồn duy nhất
│   ├── leono_<tên>.gdextension  thư viện iOS (export Android tự bỏ qua)
│   └── bin/                     output build
└── README.md

Android: plugin v2

Mỗi plugin build thành một file .aar. Khi export, plugin.gd khai báo AAR và các thư viện Maven trong deps.json cho Gradle build của game, nên game không phải sửa file Gradle hay manifest nào.

Thư viện Godot chỉ dùng lúc biên dịch (compileOnly) — lúc chạy plugin dùng đúng engine của game, nên AAR build cho 4.7 chạy được trên các bản sau.

iOS: GDExtension

Phần iOS là GDExtension, build thành static .xcframework. Khi export iOS, Godot tự sinh code đăng ký thư viện và link vào app; plugin.gd thêm framework hệ thống và key Info.plist.

Vì sao không dùng .gdip

Plugin .gdip biên dịch theo header C++ của đúng một bản engine — nâng Godot là phải build lại. GDExtension tương thích tiến: build cho 4.7 chạy trên 4.8+.

File .gdextension có cờ android_aar_plugin = true để export Android bỏ qua nó — nhờ vậy một addon chứa được cả AAR lẫn GDExtension.

Nguyên tắc

Nguyên tắc	Lý do
Mỗi plugin độc lập, không có module dùng chung	Cài/cập nhật plugin này không kéo theo plugin khác
Cùng tên hàm/signal trên 2 nền tảng	Code game không cần `if OS.get_name() == "iOS"`
Luôn có fallback khi không có native	Game chạy và test được ngay trong editor
Tính năng nhạy cảm chính sách là opt-in	Tracking ID, permission quảng cáo… dễ bị store từ chối, nhất là game trẻ em
Không bắt game sửa tay manifest/Xcode	`plugin.gd` chèn mọi thứ lúc export