AFSIM 14篇自定义 C++ 插件开发:扩展你的仿真能力

走到这一篇，你已经能用外部控制（第 11 篇）和 TCP 客户端（第 12 篇）操控仿真了。但有没有想过：当标准功能不够用时，如何给 AFSIM 自己"加个零件"？答案就是C++ 插件（Plugin）。

AFSIM 的核心引擎 WSF（Weapon Simulation Framework）采用高度可扩展的设计——几乎每种核心能力（处理器、传感器、武器、事件、通信方式等）都留了"继承基类 + 注册类型"的扩展点。本篇我们就以作者正在维护的 wsf_external_control 插件为例，带你摸清插件开发的全流程。

真实项目背景：作者的 Java Spring Boot 后端通过 TCP 连接 AFSIM 引擎的 wsf_external_control 插件（DLL 源码路径示例：F:\AFSIMManage\afsim-2.9\swdev\src\wsf_plugins\wsf_external_control\），监听 127.0.0.1:31000，操控红方 UAV_01（类型 RECON_STRIKE_UAV）与蓝方 Enemy_Ship（类型 ENEMY_DDG）。下文代码即取自这一真实工程骨架。

AFSIM 插件机制：继承基类，注册类型

一句话类比：WSF 的插件系统就像乐高——引擎先定好"插槽"形状和"积木"基类，你写一个子类插进去，再跟引擎报个到（注册），它就被纳入仿真体系了。

典型套路分三步：

继承 WSF 基类：比如要自定义事件，就继承 WsfEvent（或对应具体事件基类）；要自定义处理器，就继承 WsfProcessor。
重写关键虚函数：如 Initialize()（初始化）、ProcessInput()（读取 SDL 配置）、Execute()/ProcessEvent()（运行时行为）。
注册新类型：通过 WSF_*_REGISTRATION 之类的宏或注册接口，把你的类登记到引擎的类型工厂里，这样 SDL 里就能用你的类型名了。

// 注册示例（示意，具体宏名以你的 WSF 版本头文件为准）#include ”WsfEvent.hpp”// 在插件初始化函数中登记事件类型voidRegisterMyPlugin(WsfScenario& aScenario){  // 将自定义事件类注册到场景的事件工厂  aScenario.GetEventFactory().Register(”FIRE_WEAPON_EVENT”);}

命名空间 wsf::external 与事件类骨架

作者的外部控制插件统一放在 wsf::external 命名空间下，把"外部系统下发的指令"封装成引擎能识别的事件。下面给出三个核心事件类的可对照骨架：FireWeaponEvent（开火指令）、PlatformCommandEvent（平台通用指令）、FlyToEvent（飞往某点）。

头文件骨架（.h）

// my_external_events.hpp#ifndef MY_EXTERNAL_EVENTS_HPP#define MY_EXTERNAL_EVENTS_HPP#include ”WsfEvent.hpp”#include ”WsfPlatform.hpp”#includenamespace wsf{namespace external{  // 平台通用指令事件：携带命令字符串与目标平台名  class PlatformCommandEvent : public WsfEvent  {  public:    PlatformCommandEvent(double aTime, WsfPlatform* aPlatform,                         const std::string& aCommand);    boolExecute()override;          // 引擎在时钟推进到此事件时调用    const std::string& GetCommand()const{ return mCommand; }  private:    std::string mCommand;  };  // 飞往某点事件：携带目标经纬度与高度  class FlyToEvent : public WsfEvent  {  public:    FlyToEvent(double aTime, WsfPlatform* aPlatform,               double aLat, double aLon, double aAlt);    boolExecute()override;  private:    double mLat; double mLon; double mAlt;  };  // 开火事件：携带武器名与目标平台指针  class FireWeaponEvent : public WsfEvent  {  public:    FireWeaponEvent(double aTime, WsfPlatform* aPlatform,                    const std::string& aWeapon, WsfPlatform* aTarget);    boolExecute()override;  private:    std::string  mWeapon;    WsfPlatform* mTarget;  };}}#endif

实现骨架（.cpp）

// my_external_events.cpp#include ”my_external_events.hpp”#include ”WsfSimulation.hpp”namespace wsf{namespace external{  PlatformCommandEvent::PlatformCommandEvent(double aTime, WsfPlatform* aPlatform,                                             const std::string& aCommand)    : WsfEvent(aTime, aPlatform), mCommand(aCommand) {}  boolPlatformCommandEvent::Execute()  {    // 解析 mCommand，例如 ”HOLD” / ”RTB” / 自定义机动指令    // 典型做法：调用平台的 Mover 接口或下发新的 Route    return true; // 返回 true 表示事件已成功处理  }  FlyToEvent::FlyToEvent(double aTime, WsfPlatform* aPlatform,                         double aLat, double aLon, double aAlt)    : WsfEvent(aTime, aPlatform), mLat(aLat), mLon(aLon), mAlt(aAlt) {}  boolFlyToEvent::Execute()  {    // 将平台机动目标更新为 (mLat, mLon, mAlt)    // 对应 [第 09 篇](09.md) 的航线/机动配置，由代码侧动态改写    return true;  }  FireWeaponEvent::FireWeaponEvent(double aTime, WsfPlatform* aPlatform,                                   const std::string& aWeapon, WsfPlatform* aTarget)    : WsfEvent(aTime, aPlatform), mWeapon(aWeapon), mTarget(aTarget) {}  boolFireWeaponEvent::Execute()  {    // 触发平台对 mTarget 发射 mWeapon（详见 [第 08 篇](08.md) 交战建模）    return true;  }}}

注意：以上为骨架代码，展示了类定义与关键方法 Execute() 的位置。真实工程中 Execute() 内部需要调用 WSF 提供的平台/武器/机动 API，具体函数名请以你 swdev/ 下的 WSF 头文件为准，不要照抄未经验证的符号。

在插件中读取跟踪：WsfTrackList

外部控制插件最常做的一件事，是"替外部系统读取平台的感知世界"。在第 07 篇我们讲过 Track（跟踪）的概念，这里用代码把它取出来。

WSF 通过 WsfTrackList（跟踪列表）管理一个平台掌握的所有跟踪。关键 API：

GetMasterTrackList()
：拿到场景级（或平台级）的主跟踪列表。
GetTrackCount()
：返回当前跟踪数量。
GetTrackEntry(index)
：按索引取第 index 条跟踪条目。
WsfLocalTrack
：单条跟踪的数据结构，含目标位置、速度、置信度等。

#include ”WsfTrackList.hpp”#include ”WsfLocalTrack.hpp”voidDumpTracks(WsfPlatform* aPlatform){  // 取得该平台掌握的主跟踪列表（具体获取方式依版本而定）  WsfTrackList* trackList = aPlatform->GetMasterTrackList();  if (trackList == nullptr) return;  const size_t count = trackList->GetTrackCount();  for (size_t i = 0; i < count; ++i)  {    const WsfLocalTrack* track = trackList->GetTrackEntry(i);    if (track == nullptr) continue;    // track->GetLocation() / GetVelocity() / GetTrackId() 等读取字段  }}

这正是第 12 篇Java 客户端通过 TCP 收到的 Track 数据的"源头"——wsf_external_control 插件在这里把 WsfLocalTrack 序列化成报文发往 127.0.0.1:31000，外部系统再反序列化使用。

另一种插件范式：SimExtension 注册脚本函数

除了"继承 WsfEvent、把外部指令变成事件"这条路线，wsf_external_control 之外还有一种更轻量的插件范式——继承WsfSimExtension，在Initialize()里向脚本引擎注册一个 Lua 可调用函数，让 SDL 脚本能直接调用你的 C++ 逻辑。安装目录自带的 wsf_udp_sender 插件就是活样板（源码 wsf_udp_sender/source/UdpSender.cpp）：

// wsf_udp_sender/source/UdpSender.cpp（本机安装目录真实源码节选）#include ”WsfSimExtension.hpp”#include#include#include#include#include// 暴露给 SDL/Lua 脚本的 UDP 发送函数：udp_send(ip, port, data)staticintudp_send(lua_State* L){    const char* ip   = luaL_checkstring(L, 1);    int         port = luaL_checkinteger(L, 2);    const char* data = luaL_checkstring(L, 3);    int sock = socket(AF_INET, SOCK_DGRAM, 0);    if (sock < 0) { lua_pushboolean(L, 0); return 1; }    struct sockaddr_in addr;    memset(&addr, 0, sizeof(addr));    addr.sin_family = AF_INET;    addr.sin_port   = htons(port);    inet_pton(AF_INET, ip, &addr.sin_addr);    ssize_t sent = sendto(sock, data, strlen(data), 0,                          (struct sockaddr*)&addr, sizeof(addr));    close(sock);    lua_pushboolean(L, sent > 0);    return 1;}class UdpSenderExtension : public WsfSimExtension {public:    virtualvoidInitialize()override{        auto sim    = GetSimulation();        auto engine = sim->GetScriptEngine();        engine->RegisterFunction(”udp_send”, udp_send);  // 向脚本注册全局函数    }    virtualconstchar* GetName()constoverride{        return ”UdpSenderExtension”;    }};// AFSIM 通过这个函数实例化你的扩展extern ”C” WsfSimExtension* CreateExtension(){    return new UdpSenderExtension();}

这套写法的关键点有三处，和 wsf_external_control 互为对照：

路线不同：wsf_external_control 走的是"TCP 监听 + WsfEvent 子类"的事件驱动路线；wsf_udp_sender 走的是"WsfSimExtension 子类 + RegisterFunction"的脚本扩展路线——后者不需要自己开端口，直接在 SDL 脚本里 udp_send("127.0.0.1", 5000, "hello") 就能用。
注册入口：engine->RegisterFunction("udp_send", udp_send) 把 C++ 函数挂到脚本全局命名空间，Lua/SDL 侧即可按名调用；函数签名遵循 lua_CFunction（lua_State* 进出栈）。
实例化：AFSIM 通过导出的 extern "C" CreateExtension() 工厂函数创建你的扩展实例，你几乎不用关心加载细节。

🔍 安装实证：上面这段代码就是 E:\afsim-2.9.0-win64\wsf_udp_sender\source\UdpSender.cpp 的真实骨架（已精简注释）。该插件用 CMake 构建（CMakeLists.txt + wsf_cmake_extension.cmake + wsf_module），与 wsf_external_control 的构建方式一致。两种范式你按需求选：要"仿真主动推/拉外部系统"用 wsf_external_control；要"在场景脚本里顺手调一段 C++ 能力"用 WsfSimExtension。

编译部署：从源码到 DLL

写好的插件需要编译成动态库，再让 AFSIM 加载：

编译：通常有两种方式——用官方提供的 CMake 工程（推荐，跨平台且能自动链接 WSF 头文件与库），或在 Visual Studio 中新建 DLL 工程，把 swdev/include 加入包含路径、把 WSF 的 .lib 加入链接依赖，目标产出 .dll（Windows）。
放置：把生成的 DLL 放进 AFSIM 的 plugins/ 目录。
启用：在场景 SDL（或启动配置）里声明启用该插件，例如通过 plugin 相关语句加载，使引擎在初始化时调用你的注册函数。

# 部署目录示意（AFSIM 2.9.0，Windows）AFSIM/├─ bin/│  ├─ wizard.exe / warlock.exe / mystic.exe# 引擎与各类工具│  ├─ wsf_plugins.dll / wsf_cyber.dll / ...# 官方标准插件（已在此目录）│  └─ wsf_external_control.dll# 你编译出的自定义插件└─ scenarios/   └─ my_scenario.txt# 启用了该插件的场景

注意：AFSIM 2.9.0 把标准插件 DLL（如 wsf_plugins.dll、wsf_cyber.dll、wsf_l16.dll）直接放在 bin/ 下，本机实测并没有独立的顶层 plugins/ 目录——自定义插件也放在 bin/（或与标准插件同级、引擎能搜索到的目录）即可被加载。插件启用语法请以你安装目录 documentation/ 下的插件开发文档为准，避免套用不存在的语句。

插件架构图

把外部系统、wsf_external_control 插件与 WSF 引擎三者的关系画清楚：

graph LR  A[外部 TCP 客户端Java/Python 后端127.0.0.1:31000]    <-->|TCP 报文：指令下行 / Track 上行| B[wsf_external_control 插件wsf::external 命名空间DLL 形式加载]  B <-->|调用 WSF API| C[WSF 仿真引擎离散事件时钟平台/传感器/武器]  C -->|生成 Track / 事件| B  B -->|封装为指令事件FireWeaponEvent 等| C

这张图串起了第 11 篇外部控制、第 12 篇TCP 客户端，以及本篇的插件实现——外部系统发的每一条指令，最终都落地为引擎里的一个 WsfEvent 子类实例。

小结

AFSIM 插件遵循"继承 WSF 基类 → 重写关键虚函数 → 注册新类型"的标准套路，扩展点覆盖事件、处理器、传感器、武器等。
自定义事件统一放在 wsf::external 命名空间，FireWeaponEvent/PlatformCommandEvent/FlyToEvent 等通过重写 Execute() 把外部指令变成引擎行为。
读取平台感知靠 WsfTrackList：GetMasterTrackList()、GetTrackCount()、GetTrackEntry() 配合 WsfLocalTrack 即可遍历所有跟踪。
插件编译为 DLL（CMake 或 VS），放入 plugins/ 并在场景中启用即可生效。
插件是外部控制（第 11/12 篇）与引擎之间的"翻译层"，也是 AFSIM 真正可定制性的核心。

下期预告

系列最后一期——第 15 篇调试与最佳实践，我们把调试、性能优化、工程化这三件"决定项目能否落地"的事一次讲透。别忘了点赞、收藏、关注，完结篇见。