乐于分享
好东西不私藏

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

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 的插件系统就像乐高——引擎先定好"插槽"形状和"积木"基类,你写一个子类插进去,再跟引擎报个到(注册),它就被纳入仿真体系了。

典型套路分三步:

  1. 继承 WSF 基类:比如要自定义事件,就继承 WsfEvent(或对应具体事件基类);要自定义处理器,就继承 WsfProcessor。
  2. 重写关键虚函数:如 Initialize()(初始化)、ProcessInput()(读取 SDL 配置)、Execute()/ProcessEvent()(运行时行为)。
  3. 注册新类型:通过 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 加载:

  1. 编译:通常有两种方式——用官方提供的 CMake 工程(推荐,跨平台且能自动链接 WSF 头文件与库),或在 Visual Studio 中新建 DLL 工程,把 swdev/include 加入包含路径、把 WSF 的 .lib 加入链接依赖,目标产出 .dll(Windows)。
  2. 放置:把生成的 DLL 放进 AFSIM 的 plugins/ 目录。
  3. 启用:在场景 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 篇 调试与最佳实践,我们把调试、性能优化、工程化这三件"决定项目能否落地"的事一次讲透。别忘了点赞、收藏、关注,完结篇见。

回首页,搜索你想要的文档

在首页搜索框输入关键词,快速定位资料

文库首页搜索指引 立即搜索

相关学习资料