ThreatSourceLibaray/docs/examples/Integration

第三方引擎集成示例

本目录包含了将ThreatSource仿真系统与第三方引擎集成的示例代码。这些示例展示了如何使用适配器模式将不同的游戏引擎与仿真系统进行集成。

系统要求

• .NET 8.0 或更高版本
• ThreatSource.dll 库文件
• 对应的第三方引擎开发环境

示例文件

UEExample.cs

虚幻引擎(Unreal Engine)集成示例，展示了：

• 虚幻引擎与ThreatSource仿真系统的双向通信
• Actor与仿真实体的映射和同步
• 事件的发布和订阅
• 坐标系转换和数据适配

核心功能

using ThreatSource.Simulation;
using ThreatSource.Data;
using ThreatSource.Missile;

public class UnrealThreatSourceAdapter
{
    private ISimulationManager _simulationManager;
    private ThreatSourceDataManager _dataManager;
    private Dictionary<string, object> _entityActors;

    public void UpdateSimulation()
    {
        // 更新仿真
        _simulationManager.UpdateSimulation();
        
        // 同步实体状态到虚幻引擎Actor
        SyncEntityStates();
    }

    public string CreateMissile(string missileType, Vector3 location, string targetId)
    {
        // 从配置创建导弹
        var missileData = _dataManager.GetMissile(missileType);
        var missile = new InfraredImagingTerminalGuidanceMissile(missileId, missileData);
        
        // 在虚幻引擎中创建Actor
        var missileActor = _unrealEngine.SpawnActor("BP_Missile", location, rotation);
        
        // 建立映射关系
        _entityActors[missileId] = missileActor;
        
        return missileId;
    }
}

UnityExample.cs

Unity引擎集成示例，展示了：

• Unity引擎与ThreatSource仿真系统的双向通信
• GameObject与仿真实体的映射和转换
• MonoBehaviour生命周期管理
• 事件系统的使用和视觉效果处理

核心功能

using ThreatSource.Simulation;
using ThreatSource.Data;
using ThreatSource.Missile;
using UnityEngine;

public class UnityThreatSourceAdapter : MonoBehaviour
{
    private ISimulationManager _simulationManager;
    private ThreatSourceDataManager _dataManager;
    private Dictionary<string, GameObject> _entityGameObjects;

    private void Update()
    {
        // 更新仿真
        _simulationManager.UpdateSimulation();
        
        // 同步实体状态到Unity GameObject
        SyncEntityStates();
    }

    public void CreateMissile(string missileType, Vector3 position, string targetId)
    {
        // 从配置创建导弹
        var missileData = _dataManager.GetMissile(missileType);
        var missile = new InfraredImagingTerminalGuidanceMissile(missileId, missileData);
        
        // 在Unity中创建GameObject
        var missileGameObject = Instantiate(missilePrefab, position, Quaternion.identity);
        
        // 建立映射关系
        _entityGameObjects[missileId] = missileGameObject;
    }
}

使用说明

基本集成流程

1. 初始化仿真系统

   _simulationManager = new SimulationManager();
   _dataManager = new ThreatSourceDataManager();
   _simulationManager.StartSimulation(timeStep);
   

2. 订阅仿真事件

   _simulationManager.Subscribe<MissileFireEvent>(OnMissileFireEvent);
   _simulationManager.Subscribe<MissileExplodeEvent>(OnMissileExplodeEvent);
   _simulationManager.Subscribe<FlightPhaseChangeEvent>(OnFlightPhaseChangeEvent);
   

3. 创建实体映射

   // 创建仿真实体
   var missile = new InfraredImagingTerminalGuidanceMissile(id, data);
   _simulationManager.RegisterEntity(missile);
   
   // 创建引擎对象（Unity GameObject 或 Unreal Actor）
   var visualObject = CreateVisualObject(missile);
   
   // 建立映射关系
   _entityMappings[id] = visualObject;
   

4. 同步状态

   private void SyncEntityStates()
   {
       foreach (var kvp in _entityMappings)
       {
           var entity = _simulationManager.GetEntity(kvp.Key);
           var visualObject = kvp.Value;
   
           // 同步位置和朝向
           SyncTransform(entity, visualObject);
       }
   }
   

坐标系转换

Unity集成

// ThreatSource -> Unity 坐标转换
gameObject.transform.position = new Vector3(
    entity.KState.Position.X,
    entity.KState.Position.Z, // Unity使用Y作为高度
    entity.KState.Position.Y
);

虚幻引擎集成

// ThreatSource -> Unreal 坐标转换（右手系 -> 左手系）
var location = new Vector3(
    entity.KState.Position.X,
    -entity.KState.Position.Y, // Y轴翻转
    entity.KState.Position.Z
);

事件处理

导弹发射事件

private void OnMissileFireEvent(MissileFireEvent evt)
{
    // 播放发射特效
    var visualObject = GetVisualObject(evt.SenderId);
    PlayLaunchEffect(visualObject);
}

导弹爆炸事件

private void OnMissileExplodeEvent(MissileExplodeEvent evt)
{
    // 播放爆炸特效
    PlayExplosionEffect(evt.Position);
    
    // 销毁视觉对象
    DestroyVisualObject(evt.SenderId);
}

飞行阶段变化事件

private void OnFlightPhaseChangeEvent(FlightPhaseChangeEvent evt)
{
    var visualObject = GetVisualObject(evt.SenderId);
    
    switch (evt.NewPhase)
    {
        case FlightPhase.Boost:
            ShowBoostEffect(visualObject);
            break;
        case FlightPhase.Terminal:
            ShowTerminalEffect(visualObject);
            break;
    }
}

关键概念

适配器模式

适配器模式用于连接ThreatSource仿真系统和第三方引擎：

• 仿真层：ThreatSource核心仿真逻辑
• 适配器层：数据转换和事件映射
• 引擎层：Unity/Unreal等第三方引擎

实体映射

在仿真系统和游戏引擎之间建立实体对应关系：

// 映射关系管理
private Dictionary<string, VisualObject> _entityMappings;

// 创建映射
public void CreateEntityMapping(string entityId, VisualObject visualObject)
{
    _entityMappings[entityId] = visualObject;
}

// 同步状态
public void SyncEntity(string entityId)
{
    var entity = _simulationManager.GetEntity(entityId);
    var visualObject = _entityMappings[entityId];
    
    // 同步位置、朝向、状态等
    SyncTransform(entity, visualObject);
    SyncVisualState(entity, visualObject);
}

事件系统

统一的事件处理机制：

// 事件订阅
_simulationManager.Subscribe<TEvent>(handler);

// 事件处理
private void HandleEvent(TEvent evt)
{
    // 转换为引擎特定的操作
    ConvertToEngineOperation(evt);
}

性能优化

批量更新

// 批量同步实体状态，减少单次调用开销
private void BatchSyncEntities()
{
    var entities = _simulationManager.GetAllEntities();
    foreach (var entity in entities)
    {
        if (_entityMappings.TryGetValue(entity.Id, out var visualObject))
        {
            SyncEntity(entity, visualObject);
        }
    }
}

距离剔除

// 只同步视野范围内的实体
private void SyncVisibleEntities(Vector3 viewerPosition, float maxDistance)
{
    foreach (var kvp in _entityMappings)
    {
        var entity = _simulationManager.GetEntity(kvp.Key);
        var distance = Vector3.Distance(entity.KState.Position, viewerPosition);
        
        if (distance <= maxDistance)
        {
            SyncEntity(entity, kvp.Value);
        }
    }
}

帧率控制

// 控制仿真更新频率
private float _lastUpdateTime;
private float _updateInterval = 0.02f; // 50Hz

private void Update()
{
    if (Time.time - _lastUpdateTime >= _updateInterval)
    {
        _simulationManager.UpdateSimulation();
        SyncEntityStates();
        _lastUpdateTime = Time.time;
    }
}

注意事项

通用注意事项

1. 线程安全：确保仿真更新和引擎渲染在正确的线程中执行
2. 性能优化：合理控制同步频率，避免过度更新
3. 资源管理：正确处理实体的创建和销毁
4. 异常处理：添加完整的异常处理机制

Unity特定注意事项

1. 主线程操作：Unity API必须在主线程中调用
2. 生命周期管理：正确处理MonoBehaviour的生命周期
3. 预制体管理：合理组织和加载预制体资源
4. 坐标系转换：注意Unity的左手坐标系

虚幻引擎特定注意事项

1. 蓝图集成：考虑与蓝图系统的集成
2. Actor生命周期：正确管理Actor的创建和销毁
3. 坐标系转换：处理右手系到左手系的转换
4. 性能分析：使用虚幻引擎的性能分析工具

扩展功能

多人同步

// 网络同步支持
public class NetworkedThreatSourceAdapter
{
    public void SyncEntityOverNetwork(string entityId, EntityState state)
    {
        // 通过网络同步实体状态
        NetworkManager.SendEntityUpdate(entityId, state);
    }
}

录制回放

// 仿真录制和回放
public class SimulationRecorder
{
    public void RecordFrame(float timestamp, List<EntityState> states)
    {
        // 记录当前帧的所有实体状态
        _recordedFrames.Add(new SimulationFrame(timestamp, states));
    }
    
    public void PlaybackFrame(int frameIndex)
    {
        // 回放指定帧的状态
        var frame = _recordedFrames[frameIndex];
        ApplyFrameStates(frame);
    }
}

自定义渲染

// 自定义渲染效果
public class CustomMissileRenderer
{
    public void RenderMissileTrail(Vector3 position, Vector3 velocity)
    {
        // 根据导弹状态渲染自定义拖尾效果
        var trailLength = velocity.magnitude * 0.1f;
        RenderTrail(position, velocity.normalized, trailLength);
    }
}