消息与日志

单帧消息实体（MessageEntity）在 ECS 里的设计 / 生命周期 / 用法，以及框架日志门面 Log。

命名空间 HYC.Framework.Dots。

单帧消息

// 发一条引导弹窗消息（UI 窗口基类 AbsUISystem.OpenGuide 内部就这么干）
var e = ecb.CreateEntity();
ecb.AddComponent<MessageEntity>(e);
ecb.AddComponent(e, new EventMessage { EventID = 10023, IsRepeated = false });

// 消费系统
public partial struct GuideSystem : ISystem
{
    public void OnUpdate(ref SystemState state)
    {
        foreach (var msg in SystemAPI.Query<EventMessage>())
            ShowGuide(msg.EventID, msg.IsRepeated);
    }
}

消息相关类型

类型	作用
Message	标记「这是一条消息」
MessageEntity	标记「单帧消息实体」——MessageClearSystem 帧末清掉整个实体
DestroyEndOfFrame	标记「帧末可删」，由 MessageExpirySystem 清掉
EventMessage	消息载荷：int EventID + bool IsRepeated
MessageAttribute / StatusAttribute	给消息 / 状态组件加 Desc/Group/Order 元数据
MessageClearSystem	[UpdateInGroup(SimulationSystemGroup), OrderLast = true]
MessageExpirySystem	UpdateGroup_B9（OrderLast），专清 DestroyEndOfFrame

日志门面 Log

Log.Open(dir = null);                       // 在 PersistentDataPath/logs 下开 framework_时间.log
Log.Trace(msg); Log.Info(msg); Log.Warn(msg); Log.Error(msg);
Log.Error(ex, "context");                   // 异常 → 字符串
Log.Format(LogLevel.Info, "玩家 {0} 升到 {1} 级", id, lv);
Log.Close();                                // flush + dispose

LogLevel : Trace(0) / Info(1) / Warning(2) / Error(3) / Fatal(4)
Log.OnLog += (level, row, a, b) => { /* 转服务器 */ };

坑

• 消息实体必须同帧消费完——下一帧就没了（MessageClearSystem 帧末清）。延迟处理（如等动画）请改用 DestroyEndOfFrame 或自己维护状态组件。
• 发消息只加 Message 不行，必须 MessageEntity 才会被自动清，否则实体泄漏。
• 别往消息实体上堆 class 组件。
• MessageClearSystem 要求 RequireForUpdate<MessageEntity>()——没有消息实体时整个系统跳过（零开销）。
• 两个清理系统别动排序：改 [UpdateInGroup/OrderLast] 会让 Entities sorter 抛 NRE（已踩过）。