ThreatSourceLibaray/docs/examples/Integration/README.md

# 第三方引擎集成示例

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

## 示例文件

### [UEExample.cs](UEExample.cs)

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

- 虚幻引擎与仿真系统的双向通信
- 实体信息的同步和转换
- 事件的发布和订阅
- 数据的适配和转换

#### 源代码

```csharp
#if NEVER // 使用编译指令确保此文件永远不会被编译

// 第三方系统实现适配器示例代码
// 以虚幻引擎为例
// 需要实现的方法: GetEntity, PublishToExternalSimulation, ReceiveFromExternalSimulation

using ThreatSource.Simulation;

/// <summary>
/// 虚幻引擎适配器类，演示如何将第三方系统集成到仿真系统中
/// </summary>
public class UnrealEngineAdapter : ISimulationAdapter
{
    /// <summary>
    /// 虚幻引擎API接口，定义了与虚幻引擎交互的基本方法
    /// </summary>
    public interface IUnrealEngine
    {
        /// <summary>
        /// 根据ID获取虚幻引擎中的Actor对象
        /// </summary>
        object? GetActor(string id);

        /// <summary>
        /// 在虚幻引擎中生成导弹实体
        /// </summary>
        void SpawnMissile(string senderId, string targetId);
    }

    private readonly IUnrealEngine _unrealEngine;
    private readonly ISimulationManager _simulationManager;

    public UnrealEngineAdapter(IUnrealEngine unrealEngine, ISimulationManager simulationManager)
    {
        _unrealEngine = unrealEngine ?? throw new ArgumentNullException(nameof(unrealEngine));
        _simulationManager = simulationManager ?? throw new ArgumentNullException(nameof(simulationManager));
    }

    public object? GetEntity(string id)
    {
        return _unrealEngine.GetActor(id);
    }

    public void PublishToExternalSimulation<T>(T evt)
    {
        if (evt is MissileFireEvent missileEvt)
        {
            _unrealEngine.SpawnMissile(missileEvt.SenderId, missileEvt.TargetId);
        }
    }

    public void ReceiveFromExternalSimulation<T>(T evt)
    {
        // 处理来自虚幻引擎的事件
    }
}

#endif
```

### [UnityExample.cs](UnityExample.cs)

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

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

#### 源代码

```csharp
#if NEVER // 使用编译指令确保此文件永远不会被编译

// 第三方系统实现适配器示例代码
// 以Unity引擎为例
// 需要实现的方法: GetEntity, PublishToExternalSimulation, ReceiveFromExternalSimulation

using ThreatSource.Simulation;
using UnityEngine;  // 仅用于示例，实际项目中需要引用真实的Unity命名空间

/// <summary>
/// Unity引擎适配器类，演示如何将Unity引擎集成到仿真系统中
/// </summary>
public class UnityEngineAdapter : MonoBehaviour, ISimulationAdapter
{
    /// <summary>
    /// Unity引擎API接口，定义了与Unity引擎交互的基本方法
    /// </summary>
    public interface IUnityEngine
    {
        /// <summary>
        /// 根据ID获取Unity场景中的GameObject对象
        /// </summary>
        GameObject GetGameObject(string id);

        /// <summary>
        /// 在Unity场景中实例化导弹预制体
        /// </summary>
        GameObject InstantiateMissile(string prefabPath, Vector3 position, Quaternion rotation);
    }

    private readonly IUnityEngine _unityEngine;
    private readonly ISimulationManager _simulationManager;
    private const string MissilePrefabPath = "Prefabs/Missile";

    public UnityEngineAdapter(IUnityEngine unityEngine, ISimulationManager simulationManager)
    {
        _unityEngine = unityEngine ?? throw new ArgumentNullException(nameof(unityEngine));
        _simulationManager = simulationManager ?? throw new ArgumentNullException(nameof(simulationManager));
    }

    public object? GetEntity(string id)
    {
        return _unityEngine.GetGameObject(id);
    }

    public void PublishToExternalSimulation<T>(T evt)
    {
        if (evt is MissileFireEvent missileEvt)
        {
            var sender = _unityEngine.GetGameObject(missileEvt.SenderId);
            if (sender != null)
            {
                UnityMainThreadDispatcher.Instance.Enqueue(() =>
                {
                    var missile = _unityEngine.InstantiateMissile(
                        MissilePrefabPath,
                        sender.transform.position,
                        sender.transform.rotation
                    );
                    
                    var missileComponent = missile.GetComponent<MissileController>();
                    if (missileComponent != null)
                    {
                        missileComponent.SetTarget(missileEvt.TargetId);
                    }
                });
            }
        }
    }

    public void ReceiveFromExternalSimulation<T>(T evt)
    {
        if (evt is CollisionEvent collisionEvt)
        {
            _simulationManager.HandleCollision(collisionEvt);
        }
    }

    private void Update()
    {
        SyncSimulationState();
    }

    private void SyncSimulationState()
    {
        // 实现仿真状态同步逻辑
    }
}

#endif
```

## 使用说明

1. 这些文件仅作为参考示例，不参与实际编译（使用 `#if NEVER` 编译指令）
2. 实际项目中需要根据具体需求修改和扩展
3. 示例中的接口和类名仅供参考，应根据实际项目规范调整

## 关键概念

### 适配器模式

- 实现 `ISimulationAdapter` 接口
- 转换不同引擎的数据格式
- 处理事件的发布和订阅

### 实体映射

- 在仿真系统和游戏引擎之间建立实体对应关系
- 同步实体状态和属性
- 处理实体的创建和销毁

### 事件系统

- 定义统一的事件数据结构
- 处理事件的双向转换
- 确保事件的正确分发

## 注意事项

1. 需要处理线程安全问题
2. 注意性能优化，特别是在状态同步时
3. 合理处理资源的加载和释放
4. 确保异常处理的完整性