ThreatSourceLibaray/ThreatSource/src/Simulation/SimulationElement.cs

using ThreatSource.Utils;

namespace ThreatSource.Simulation
{
    /// <summary>
    /// 仿真元素的抽象基类，所有仿真中的实体都继承自此类
    /// </summary>
    /// <remarks>
    /// 该类提供了仿真实体的基本功能的默认实现：
    /// - 位置和运动状态管理
    /// - 生命周期管理（激活/停用）
    /// - 事件发布机制
    /// - 状态更新机制
    /// - 频谱特性管理
    /// 所有具体的仿真实体（如导弹、目标等）都应继承此类并实现其抽象方法。
    /// </remarks>
    public abstract class SimulationElement : ISimulationElement
    {
        /// <inheritdoc/>
        public virtual string Id { get; set; }

        /// <inheritdoc/>
        public virtual Vector3D Position { get; set; }

        /// <inheritdoc/>
        public virtual double Speed { get; set; }

        /// <inheritdoc/>
        public virtual Vector3D Velocity { get; set; }

        /// <inheritdoc/>
        public virtual Orientation Orientation { get; set; }

        /// <inheritdoc/>
        public virtual bool IsActive { get; protected set; }

        /// <summary>
        /// 获取或设置仿真管理器的引用
        /// </summary>
        /// <remarks>
        /// 用于访问仿真系统的核心功能，如事件发布、实体查询等
        /// 在构造函数中初始化，整个生命周期内保持不变
        /// </remarks>
        protected ISimulationManager SimulationManager { get; set; }

        /// <summary>
        /// 初始化仿真元素的新实例
        /// </summary>
        /// <param name="id">仿真元素的唯一标识符</param>
        /// <param name="motionParameters">初始运动参数</param>
        /// <param name="simulationManager">仿真管理器实例</param>
        /// <remarks>
        /// 构造函数设置实体的初始状态：
        /// - 根据ID、位置、朝向和速度初始化实体
        /// - 计算初始速度向量
        /// - 设置初始状态为未激活
        /// </remarks>
        protected SimulationElement(string id, MotionParameters motionParameters, ISimulationManager simulationManager)
        {
            Id = id;
            Position = motionParameters.Position;
            Orientation = motionParameters.Orientation;
            Speed = motionParameters.InitialSpeed;
            Velocity = motionParameters.Orientation.ToVector() * motionParameters.InitialSpeed;
            this.SimulationManager = simulationManager;
            IsActive = false;
        }

        /// <summary>
        /// 更新仿真元素的状态
        /// </summary>
        /// <param name="deltaTime">时间步长，单位：秒</param>
        /// <remarks>
        /// 抽象方法，需要在派生类中实现具体的更新逻辑：
        /// - 更新位置和朝向
        /// - 计算新的速度和加速度
        /// - 处理碰撞和其他物理效果
        /// - 触发相关事件
        /// </remarks>
        public abstract void Update(double deltaTime);

        /// <summary>
        /// 获取仿真元素的状态信息
        /// </summary>
        /// <returns>包含实体当前状态的字符串描述</returns>
        /// <remarks>
        /// 返回的字符串包含：
        /// - 实体类型
        /// - 实体ID
        /// - 当前位置
        /// - 当前朝向
        /// - 活动状态
        /// </remarks>
        public virtual string GetStatus()
        {
            return $"仿真元素状态：{GetType().Name} {Id} at {Position}, Orientation: {Orientation}, Active: {IsActive}\n";
        }

        /// <summary>
        /// 发布仿真事件到事件系统
        /// </summary>
        /// <param name="evt">要发布的事件实例</param>
        /// <remarks>
        /// 在发布事件前会：
        /// - 设置事件的发送者ID
        /// - 添加时间戳
        /// - 通过仿真管理器发布到事件系统
        /// </remarks>
        protected void PublishEvent<T>(T evt) where T : SimulationEvent
        {
            evt.SenderId = Id;
            evt.Timestamp = DateTime.UtcNow.Ticks;
            SimulationManager.PublishEvent(evt);
            Console.WriteLine($"[仿真元素] 发布事件: 事件类型={evt.GetType().Name}, 发送者ID={evt.SenderId}, 时间戳={evt.Timestamp}");
        }

        /// <summary>
        /// 激活仿真元素，使其参与仿真
        /// </summary>
        /// <remarks>
        /// 激活操作会：
        /// - 将IsActive设置为true
        /// - 发布实体激活事件
        /// - 允许实体参与仿真计算
        /// </remarks>
        public virtual void Activate()
        {
            if (!IsActive)
            {
                IsActive = true;
            }
        }
    
        /// <summary>
        /// 停用仿真元素，将其从仿真中移除
        /// </summary>
        /// <remarks>
        /// 停用操作会：
        /// - 将IsActive设置为false
        /// - 发布实体停用事件
        /// - 停止实体参与仿真计算
        /// </remarks>
        public virtual void Deactivate()
        {
            if (IsActive)
            {
                IsActive = false;
            }
        }
    }
}