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

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

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

真实项目背景:作者的 Java Spring Boot 后端通过 TCP 连接 AFSIM 引擎的 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 里就能用你的类型名了。
cpp 复制代码
// 注册示例(示意,具体宏名以你的 WSF 版本头文件为准)
#include "WsfEvent.hpp"
// 在插件初始化函数中登记事件类型
void RegisterMyPlugin(WsfScenario& aScenario)
{
  // 将自定义事件类注册到场景的事件工厂
  aScenario.GetEventFactory().Register<FireWeaponEvent>("FIRE_WEAPON_EVENT");
}

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

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

头文件骨架(.h)

cpp 复制代码
// my_external_events.hpp
#ifndef MY_EXTERNAL_EVENTS_HPP
#define MY_EXTERNAL_EVENTS_HPP

#include "WsfEvent.hpp"
#include "WsfPlatform.hpp"
#include <string>

namespace wsf
{
namespace external
{
  // 平台通用指令事件:携带命令字符串与目标平台名
  class PlatformCommandEvent : public WsfEvent
  {
  public:
    PlatformCommandEvent(double aTime, WsfPlatform* aPlatform,
                         const std::string& aCommand);
    bool Execute() 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);
    bool Execute() override;
  private:
    double mLat; double mLon; double mAlt;
  };

  // 开火事件:携带武器名与目标平台指针
  class FireWeaponEvent : public WsfEvent
  {
  public:
    FireWeaponEvent(double aTime, WsfPlatform* aPlatform,
                    const std::string& aWeapon, WsfPlatform* aTarget);
    bool Execute() override;
  private:
    std::string  mWeapon;
    WsfPlatform* mTarget;
  };
}
}
#endif

实现骨架(.cpp)

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) {}

  bool PlatformCommandEvent::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) {}

  bool FlyToEvent::Execute()
  {
    // 将平台机动目标更新为 (mLat, mLon, mAlt)
    // 对应第 09 篇的航线/机动配置,由代码侧动态改写
    return true;
  }

  FireWeaponEvent::FireWeaponEvent(double aTime, WsfPlatform* aPlatform,
                                   const std::string& aWeapon, WsfPlatform* aTarget)
    : WsfEvent(aTime, aPlatform), mWeapon(aWeapon), mTarget(aTarget) {}

  bool FireWeaponEvent::Execute()
  {
    // 触发平台对 mTarget 发射 mWeapon(详见第 08 篇交战建模)
    return true;
  }
}
}

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

三、在插件中读取跟踪:WsfTrackList

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

WSF 通过 WsfTrackList(跟踪列表) 管理一个平台掌握的所有跟踪。关键 API:

  • GetMasterTrackList():拿到场景级(或平台级)的主跟踪列表。
  • GetTrackCount():返回当前跟踪数量。
  • GetTrackEntry(index):按索引取第 index 条跟踪条目。
  • WsfLocalTrack:单条跟踪的数据结构,含目标位置、速度、置信度等。
cpp 复制代码
#include "WsfTrackList.hpp"
#include "WsfLocalTrack.hpp"

void DumpTracks(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、把外部指令变成事件"这条路线,还有一种更轻量的插件范式------继承 WsfSimExtension,在 Initialize() 里向脚本引擎注册一个 Lua 可调用函数,让 SDL 脚本能直接调用你的 C++ 逻辑。安装目录自带的 wsf_udp_sender 插件就是活样板:

cpp 复制代码
// wsf_udp_sender/source/UdpSender.cpp(本机安装目录真实源码节选)
#include "WsfSimExtension.hpp"
#include <wsf/script/FunctionBindings.h>
#include <wsf/script/ScriptEngine.h>
#include <sys/socket.h>
#include <netinet/in.h>
#include <arpa/inet.h>

// 暴露给 SDL/Lua 脚本的 UDP 发送函数:udp_send(ip, port, data)
static int udp_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:
    virtual void Initialize() override {
        auto sim    = GetSimulation();
        auto engine = sim->GetScriptEngine();
        engine->RegisterFunction("udp_send", udp_send);  // 向脚本注册全局函数
    }
    virtual const char* GetName() const override {
        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 侧即可按名调用。
  • 实例化 :AFSIM 通过导出的 extern "C" CreateExtension() 工厂函数创建你的扩展实例,几乎不用关心加载细节。

🔍 安装实证:上面这段代码就是 E:\afsim-2.9.0-win64\wsf_udp_sender\source\UdpSender.cpp 的真实骨架(已精简注释)。该插件用 CMake 构建(CMakeLists.txt + wsf_cmake_extension.cmake),与 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 的 bin/ 目录。
  3. 启用:在场景 SDL(或启动配置)里声明启用该插件,使引擎在初始化时调用你的注册函数。
python 复制代码
# 部署目录示意(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 引擎三者的关系梳理清楚:

外部 TCP 客户端 (Java/Python 后端,127.0.0.1:31000) ↕ TCP 报文:指令下行 / Track 上行 wsf_external_control 插件 (wsf::external 命名空间,DLL 形式加载) ↕ 调用 WSF API WSF 仿真引擎(离散事件时钟,平台/传感器/武器)

  • 引擎 → 插件:生成 Track / 事件
  • 插件 → 引擎:封装为指令事件(FireWeaponEvent 等)

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

小结

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

下期预告

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

相关推荐
码事漫谈12 小时前
以后人人都可以成为导演
后端
Resean022312 小时前
Spring 源码分析(二)配置类的解析与扫描
java·后端·spring
一只爱撸猫的程序猿12 小时前
五周、两个开源仓库、九次拦截之后:AI 时代程序员缺的到底是什么
人工智能·后端·开源
ShineWinsu13 小时前
对于Qt:QFormLayout常见属性以及方法的解析
开发语言·c++·qt·面试·客户端·表单·qformlayout
kyle~13 小时前
嵌入式 SoC 系统
linux·c++·嵌入式·计算系统
北城笑笑13 小时前
Vue 110 ,若依SSE流式接口限次空500排查与解决
前端·javascript·vue.js·后端·vue
ServBay14 小时前
Local harness 将退役,VS Code 本地开发要不要搬到云端?
后端·ai编程·visual studio code
ashiho14 小时前
【LeetCode hot 100】3. 无重复字符的最长子串 (三种解法)
java·数据结构·后端·算法·leetcode·滑动窗口
张一凡9315 小时前
你的 AGENTS.md,真的管到模型写代码了吗?
前端·后端·agent
00后程序员15 小时前
iOS 实时活动怎么开发,Windows 上用 KXBuild 和 ActivityKit 写灵动岛
后端·ios