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

典型套路分三步：

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

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