简介：面向X-Plane飞行模拟器二次开发的SDK便携资料包，适用于计划使用C、C++、Python或Delphi等语言编写插件、扩展功能的开发者。压缩包内共52个文件，类型上包括24个C/C++头文件、17个Delphi单元文件、7个C++源文件，以及2个库文件和2个说明文本；其中头文件负责声明接口，单元文件对应Delphi封装，源文件则是可编译的示例工程，整体大小约159KB，轻量易用。目前已有189人学习浏览，是初学者时常借鉴的入门参考。内容提供API头文件的声明、Delphi封装接口和C++示例代码，可以帮助使用者理解插件加载机制、数据读写流程和渲染交互方式，同时附带README与许可证文件，便于快速明确使用规范与授权范围。对于需要快速搭建X-Plane开发环境或寻找现成代码骨架的开发者，这套文件能显著提高前期调研效率，无论是入门学习还是实际项目，都能提供清晰的参考路径。
1. 拿到 SDK.rar 之后：X-Plane SDK 到底是什么，Python 能碰哪一层
很多人的第一次 X-Plane 开发都是从某个论坛的“SDK.rar”解压包开始的：一堆 .h、一堆 .lib/.so、一份 Documentation，翻遍整个包找不到任何 .py 文件。这里先立一个结论：X-Plane 官方 SDK（含 X-Plane 11/12）只提供 C API，官方从未发布 Python 绑定。任何“用 Python 开发 X-Plane 插件”的方案，本质上只有两条路——把 Python 解释器嵌进 C 插件进程里，或在 X-Plane 进程外用 UDP/DataRef 协议做外部通信。下面针对这两条路给出可直接复现的工程做法，覆盖插件生命周期、构建命令、崩溃排查和热重载。适合想用 Python 写航电面板、数据记录器和外置仪表的人阅读，也适合从 C 插件迁移脚本逻辑的团队。
2. 拆开 SDK.rar：目录结构、插件生命周期与 DataRef 机制
2.1 SDK 包里每层目录是干什么的
官方 SDK 压缩包解压后，顶层目录基本固定。即使你手上的压缩包文件名里带着 tillagz 之类的杂字符，解压开大概率还是这四类东西：
| 路径 | 内容 | 开发时的用途 |
|---|---|---|
| SDK/CHeaders/XPLM | XPLM 主头文件，包括 XPLMPlugin.h、XPLMDataRef.h、XPLMUtilities.h 等 | 插件主逻辑、DataRef 读写、工具函数 |
| SDK/CHeaders/XPWidgets | 2D 界面组件头文件 | 用原生窗口做简单 UI 时用到 |
| SDK/Libraries | Windows(.lib/.dll)、Linux(.so)、Mac(.framework) | 编译链接时的导入库 |
| SDK/Documentation | 官方 API 说明和 SDK 版本变更记录 | 查函数签名，别背 API |
CHeaders 里有个容易忽略的 Deprecated 子目录，旧代码里常见的 XPLMGetDirectory 一类函数已经被移到这里。如果编译时遇到“函数未声明”的提示，优先去 Deprecated 里找。SDK 版本信息不在文件名里，而在 Documentation 下的 HTML 页面中，打开看版本号，再决定你写的插件能运行在哪个 X-Plane 主版本上。
这里的头文件全部是 C 声明，不是 C++。这决定了后续无论是写纯 C 插件还是 C++ 包 Python，都必须用 extern "C" 处理好导出符号，否则编译器会对函数名做 name mangling，X-Plane 在加载时找不到 XPluginStart 入口。
2.2 五个入口函数：理解 XPLM 插件的生命周期
X-Plane 加载插件和浏览器加载扩展类似，按固定顺序调用一组导出函数。官方 SDK 要求插件必须导出这五个符号，缺一个插件就加载失败，错误会写进主目录的 Log.txt。
// plugin.c —— 最小可编译的 X-Plane 插件骨架 #include "XPLMPlugin.h" #include "XPLMUtilities.h" #include <string.h> XPLMPluginID XPluginStart( char *outName, char *outSig, char *outDesc) { strcpy(outName, "PyBridge"); strcpy(outSig, "com.example.xplane.pybridge"); strcpy(outDesc, "Embedded Python bridge for X-Plane"); return NULL; } void XPluginStop(void) { // 在这里释放注册的资源和 Python 解释器 } int XPluginEnable(void) { return 1; } void XPluginDisable(void) { // 通知脚本执行环境进入挂起状态 } void XPluginReceiveMessage( XPLMPluginID inFrom, int inMsg, void *inParam) { // 收到 XPLM_MSG_PLANE_LOADED 时可重新加载飞机配置 }逻辑说明：XPluginStart 负责填写插件名称、签名和描述，返回值是插件 ID，一般情况下返回空指针即可；XPluginEnable 在飞行器加载后调用，返回 1 表示启用成功；XPluginDisable 和 XPluginStop 是对称的清理函数。XPluginReceiveMessage 处理系统广播，比如飞机重载时收到 XPLM_MSG_PLANE_LOADED 就重新读取配置文件。outName 的缓冲区由 X-Plane 分配，长度固定，写入的字符串建议控制在 256 字节以内，用 strncpy 会更稳。
编译 Windows 版时的最小命令，MinGW 和 MSVC 二选一：
# MinGW gcc -shared -o pybridge.dll plugin.c \ -I SDK/CHeaders -L SDK/Libraries/Win -lXPLM # MSVC cl /LD plugin.c /I SDK/CHeaders \ /link /LIBPATH:SDK/Libraries/Win XPLM.lib链接到 Windows 的 XPLM.lib 时不要混用 MinGW 自己生成的静态导入库，X-Plane 官方包里的导入库只配合官方 DLL 使用。如果链接阶段提示找不到 XPLMRegisterDataAccessor，多半是头文件里的函数声明用了默认调用约定而导入库期望 __stdcall，在包含头文件前定义 XPLM_STDCALL 宏可以对齐。
2.3 DataRef：SDK 和外部工具都能读写的“共享状态”
DataRef 是 X-Plane 暴露给插件和外部程序的全局变量系统。每个参数（空速、燃油量、起落架位置等）对应一个带类型的字符串名。插件先用 XPLMFindDataRef 拿引用，再按类型用 XPLMGetDatai / XPLMSetDatai 一类的函数读写。
这里的关键认知是：X-Plane 自带 UDP 数据接口，X-Plane 在 49000 端口接收外部指令，在 49001 端口向外部发送数据帧，暴露的正是 DataRef 的子集。外部 Python 脚本最常见的做法就是直接走 UDP，不碰 C 代码。下一章把这条边界划清楚，再决定你的脚本到底该走哪条路。
3. Python 连 X-Plane SDK 的三条路线：外部 UDP、ctypes 与嵌入式解释器
3.1 纯 Python 的外部 UDP 方案：不写插件，最适合数据采集
如果需求只是“把空速、高度读进 Python，或者向 X-Plane 发指令”，不需要动 SDK 的 C 文件。X-Plane 设置界面勾选“允许外部数据”后，Python 端用 socket 和 struct 就能完成订阅与解析。
# xplane_udp.py —— 通过 UDP 订阅 DataRef 的外部脚本 import socket import struct def subscribe_rref(sock, path, freq=1.0, index=1): # RREF 帧: 4字节类型 + 4字节频率 + 4字节索引 # + 4字节值占位 + 500字节路径 frame = b"RREF" frame += struct.pack("<f", freq) frame += struct.pack("<I", index) frame += struct.pack("<f", 0.0) frame += path.encode("ascii").ljust(500, b"\x00") sock.sendto(frame, ("127.0.0.1", 49000)) sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM) sock.bind(("", 49001)) sock.settimeout(2.0) subscribe_rref( sock, "sim/cockpit2/gauges/indicators/airspeed_kts_pilot", freq=1.0 ) while True: try: data, _ = sock.recvfrom(1024) except socket.timeout: continue if data[:4] == b"RREF": value = struct.unpack("<f", data[12:16])[0] path = data[16:516].split(b"\x00")[0].decode() print(path, round(value, 2))值得注意的字段：RREF 帧的 value 在偏移 12 到 16，路径在偏移 16 之后，前面 12 字节是类型、频率和索引。Python 端用小端字节序解析，因为 X-Plane 在 x86 平台上以 little-endian 发送所有数值。设定“允许外部数据”后，X-Plane 就会按订阅频率持续向 49001 推数，不需要每帧都发请求。
这条路的边界有两个。第一，外部 UDP 只能访问 X-Plane 内置 DataRef，插件自己注册的私有 DataRef 默认不会被转发；第二，UDP 是推模式，没有回调能力，做不到“飞机进入某个状态立刻触发 Python 逻辑”，只能靠轮询去判断。下面是三条路线的对比，方便你直接选型。
| 方案 | 运行位置 | 能否注册回调 | 对版本的侵入性 | 适合场景 |
|---|---|---|---|---|
| 纯 Python UDP | X-Plane 进程外 | 否，只能轮询 | 极低，只需开外部数据开关 | 数据采集、外置仪表 |
| ctypes 加载 XPLM | 仅插件进程内 | 困难，GIL 和回调线程难管理 | 依赖头文件与运行时对齐 | 给 C 插件生成绑定层，不推荐独立使用 |
| C++ 壳 + pybind11 | X-Plane 插件进程内 | 是 | 需匹配 Python 开发库版本 | 完整插件逻辑、事件驱动开发 |
3.2 ctypes 加载 XPLM 库：为什么外部进程里调不通
看到 SDK 里有 XPLM.dll 或 libXPLM.so，第一反应是 Python 的 ctypes 直接加载调用，这个思路在外部进程里必翻车。原因很直接：XPLM 库的大部分函数依赖 X-Plane 主程序在加载插件时注入的回调指针，主进程还没运行，XPLM 内部的全局状态是空的。这时哪怕硬加载成功，一调用 XPLMFindDataRef 就会段错误。
在插件进程内部，ctypes 理论上可用，但官方 C 头的声明转换工作量和直接写一个 C 桥接层差不了多少，又绕不开编译器导出符号和线程模型，所以实践中没人这样包。ctypes 真正有意义的用法是在开发期读取 SDK 自带的头文件，生成一份 Python 侧的 C 声明清单，给 pybind11 那层做函数签名对照，而不是让 Python 直接当宿主。
3.3 真正“用 Python 写 X-Plane 插件”：C++ 壳 + pybind11 嵌入
最接近标题意图的做法，是把 Python 解释器嵌进一个 C++ 编写的 XPLM 插件里。插件用 C++ 实现五个入口函数，启动时调用 Py_Initialize 初始化解释器，然后把一组自定义函数注册进 Python 模块，让脚本通过纯 Python 的 facade 读写 DataRef、订阅飞行循环回调。
// bridge.cpp —— 把 DataRef 读写暴露给 Python 的片段 #include <pybind11/pybind11.h> #include "XPLMDataRef.h" namespace py = pybind11; void register_data_api(py::module_ &m) { m.def("get_datai", [](const char *path) -> int { XPLMDataRef ref = XPLMFindDataRef(path); if (!ref) return -1; return XPLMGetDatai(ref); }, "读取整型 DataRef，取不到返回 -1"); m.def("set_datai", [](const char *path, int value) -> bool { XPLMDataRef ref = XPLMFindDataRef(path); if (!ref || !XPLMIsDataRefWritable(ref)) return false; XPLMSetDatai(ref, value); return true; }, "写入整型 DataRef，失败返回 false"); }逻辑说明：这里用 pybind11 的 m.def 把 C++ lambda 直接暴露为 Python 函数，参数和返回值都自动转换。XPLMFindDataRef 每次调用都会在 X-Plane 的 DataRef 表里做一次字符串查找，频繁读值的路径应该在 Python 侧缓存引用，而不是每帧都传字符串。XPLMIsDataRefWritable 必须在写入前调用，X-Plane 对只读 DataRef 的写入会直接忽略，不会报错。
pybind11 相比裸 Python C API 的好处是自动处理对象持有和参数转换。代价也明显：插件体积从几十 KB 涨到几十 MB，启动耗时增加 200ms 以上，而且 X-Plane 插件列表里一旦有同名旧插件残留，新老两个实例会抢同一个解释器命名空间。下一章给出完整工程布局和编译命令，把最容易出错的线程问题先讲掉。
4. 嵌入解释器的完整工程：目录布局、编译命令与常见崩溃点
4.1 推荐的项目布局与构建脚本
在实践中，我一般把整个工程分成三层：C++ 桥接层、Python 业务层、SDK 资源层。目录如下：
xplane-python-bridge/ ├── src/ │ ├── plugin.cpp # XPLM 五个入口 │ ├── bridge.cpp # pybind11 模块注册 │ └── bridge.h ├── python/ │ └── my_logic.py # 真正业务逻辑 ├── SDK/ # 官方 SDK 头文件与库 └── CMakeLists.txt因为 X-Plane 插件本质是动态库，CMake 里把目标类型设为 MODULE：
cmake_minimum_required(VERSION 3.16) project(pybridge LANGUAGES CXX) find_package(Python3 REQUIRED COMPONENTS Interpreter Development) add_library(pybridge MODULE src/plugin.cpp src/bridge.cpp ) target_include_directories(pybridge PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/SDK/CHeaders ) target_link_libraries(pybridge PRIVATE Python3::Python) if(WIN32) target_link_libraries(pybridge PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/SDK/Libraries/Win/XPLM.lib ) endif()CMake 里的 MODULE 输出的是不带 lib 前缀的动态库，Windows 上会生成 pybridge.dll，Linux 上是 pybridge.so，macOS 上是 pybridge.bundle。Windows 上链接官方 XPLM.lib 是为了生成导入表，运行时符号仍由 X-Plane 主程序提供；Linux 下不需要显式 -lXPLM，宿主进程在 dlopen 插件时会自动解析 XPLM 符号，强行链接系统里的 libXPLM.so 反而可能引入版本冲突。
4.2 从 C++ 初始化 Python：线程与 GIL 的处理
XPLM 的飞行循环回调和菜单回调都运行在 X-Plane 主线程上，但插件可能在自己创建的线程里做异步任务，所以 Python 解释器的进入必须遵守 GIL 规则。最稳妥的方式是：解释器只由主线程初始化，任何其他线程想调用 Python 前都用 PyGILState_Ensure / PyGILState_Release 包裹。
// bridge.h —— 用 unique_ptr 管理解释器生命周期 #include <pybind11/embed.h> #include <memory> std::unique_ptr<py::scoped_interpreter> g_interp;然后在 XPluginStart 里初始化：
#include "bridge.h" extern "C" XPLMPluginID XPluginStart( char *outName, char *outSig, char *outDesc) { strcpy(outName, "PyBridge"); g_interp = std::make_unique<py::scoped_interpreter>(); return NULL; }逻辑说明：py::scoped_interpreter 构造时调用 Py_Initialize 并接管解释器生命周期，析构时自动 Py_Finalize。把它放进 unique_ptr 是为了控制析构时机在 XPluginStop 之后，避免 X-Plane 卸载插件时 Python 解释器还持有已失效的插件指针。
飞行循环回调里拿 GIL 的写法：
float flight_loop_cb( float elapsed, float elapsed_sim, int counter, void *ref) { // 回调可能来自其他线程，必须显式获取 GIL py::gil_scoped_acquire acquire; try { py::module_::import("my_logic") .attr("on_flight_loop")(elapsed, elapsed_sim); } catch (py::error_already_set &e) { // 写进 X-Plane 的 Log.txt，而不是 stdout XPLMDebugString(e.what()); } return -1; }gil_scoped_acquire 在构造时调用 PyGILState_Ensure，析构时自动 Release，避免回调里忘掉释放造成的死锁。catch 住 py::error_already_set 是关键：Python 脚本里任何未捕获异常都会通过它冒泡到 C++，如果不拦截，轻则打印一堆无用的堆栈，重则带着锁状态触发 abort。
有一个常见的坑：在 XPluginStart 里直接执行 Python 脚本加载，如果脚本里用了 numpy 这类需要成熟环境变量的库，可能因为 PYTHONPATH 还没注入而失败。常见做法是把脚本加载延后到 XPluginEnable 之后，用 XPLMGetSystemPath 拼出插件目录再 sys.path.insert(0, path)。
4.3 编译、安装与验证的最小流程
构建完成后，把生成的动态库放到 X-Plane 的 plugins 目录下，Windows 上必须是Resources/plugins/my_plugin/64/win.xpl，Linux 是 lin.xpl，macOS 是 mac.xpl。Windows 放错到 32 或根目录时，X-Plane 会直接跳过加载。
验证顺序：
- 启动 X-Plane，打开
Settings → Plugins，看插件是否列出且没有红字警告。 - 查看
Log.txt里的Loaded: .../win.xpl行，以及 Python 侧 print 的输出是否出现在标准输出里。 - 在 X-Plane 菜单栏点你注册的菜单项，确认回调能被触发。
如果插件加载失败，Log.txt 里一般能搜到 “Plugin failed” 或 “Symbol not found”。前者通常是没有导出 XPluginStart 函数，后者是动态库链接期有未解析符号。Windows 上还常见一种：MSVC 运行时和 MinGW 运行时混用导致崩溃，建议整个项目统一用同一套工具链。
5. 进阶技巧：飞行循环频率、DataRef 批量注册与脚本热重载
最后三个技巧，都是调试和性能优化时绕不开的。
5.1 控制飞行循环回调频率
flight_loop_cb 的返回值是“多少秒后再调用一次”。返回 -1 表示下一帧调用，返回 0.5 就是每秒约两次。数据采集日志没必要每帧都跑，用 0.2 到 1.0 秒的间隔能明显降低 CPU 占用。别在回调里直接写文件，把数据攒到 Python 列表，用另一个线程定期 flush 到磁盘，避免文件 IO 拖垮飞行循环。
5.2 批量注册私有 DataRef
如果 Python 业务层需要把参数暴露给 X-Plane 的操纵界面，可以在 C++ 里批量注册自定义 DataRef，再用一个函数暴露给 Python：
m.def("register_int_drefs", [](py::dict mapping) { for (auto item : mapping) { std::string path = item.first.cast<std::string>(); XPLMRegisterDataAccessor( path.c_str(), xplmType_Int, 1, int_getter, int_setter, nullptr, nullptr, nullptr, nullptr, nullptr, nullptr, nullptr, nullptr, nullptr, nullptr); } });注册自定义 DataRef 时，路径前缀最好写sim/custom/bridge/这类命名空间，避免和官方冲突。注册总量控制在 200 个以内，因为 X-Plane 每帧遍历 DataRef 表的开销和数量成正比，注册太多会拖慢整个飞行模拟的循环。
5.3 脚本热重载
插件启动时用 importlib 加载 Python 逻辑，调试时改完脚本要重载。正确姿势是先退役旧模块再重新 import，而不是直接重复 import：
# reload_hook.py —— 供 C++ 桥接层调用的热重载函数 import importlib import sys def reload(name: str = "my_logic") -> object: old = sys.modules.pop(name, None) if old is not None: for sub in list(sys.modules): if sub == name or sub.startswith(name + "."): sys.modules.pop(sub, None) return importlib.import_module(name)热重载对 X-Plane 的主循环是安全的，前提是数据源全部走 C 桥接层，Python 侧只持有引用，不保存待释放的 C 指针。DataRef 的注册回调地址在重载后不能变，所以注册逻辑永远留在 C++ 层，Python 只负责业务逻辑。
本文还有配套的精品资源，点击获取
