CFramework/REFACTOR_NOTES.md

2026-08 External Data-Layer Refactor

本次修改以当前 CFramework 外部框架为基础，没有重新迁移 Overlay / ImGui / Camera / Transform。目标是修复共享状态竞争、固定数组越界和新版本 IPlayer 布局差异，并让渲染/目标选择与目标进程读取解耦。

已完成

1. CGame 状态同步

   • GameWorld / LocalGameWorld / FPS Camera / ViewMatrix 统一由 CGame::Refresh() 刷新。
   • 内部状态使用 mutex，消费者通过 GameStateSnapshot 读取一致副本。
   • 移除渲染线程每帧调用 InitAddress() 的行为。

2. 不可变世界快照

   • 新增 DynamicWorldSnapshot：本地玩家、远端玩家、Camera/ViewMatrix、Grenade。
   • 新增 StaticWorldSnapshot：Exfil、Item。
   • 使用 shared_ptr<const ...> + atomic_load/atomic_store 发布，消费者不会看到构建到一半的容器。

3. ESP / Aim 数据读取解耦

   • RenderESP() 不再直接 RPM，也不再调用 Player Update/Health/Bone。
   • Aim 目标筛选和骨骼选择只读取动态快照。
   • Memory Aim 与 Misc override 继续保留为明确的写入路径。

4. 玩家类型适配

   • 新增 CPlayerKind::{EftPlayer, ObservedPlayer}。
   • 完整玩家使用当前 dump 中的 Player + 0x618 Profile、+0x660 HealthController、+0x6E8 PlayerBones 等链。
   • ObservedPlayer 使用当前 dump 可确认的 +0x60 PlayerBones、+0x68 PlayerBody、+0xB8 Transform、+0x100 Side。
   • 对 dump 未确认的 Observed Profile/Health/Role 不做猜测。

5. 列表越界修复

   • 移除固定 CGameObjectList::address[64] 和 Item address[2048] 读取方式。
   • Managed List/Array 使用实际 count/length + hard limit + TryReadVector。
   • 当前 hard limit：Player 512、Item 8192、Grenade 256、Exfil 32。

6. Memory API 加固

   • 增加 IsUserAddress、TryRead、TryWrite、TryReadBuffer、TryReadVector。
   • ReadChain 增加地址校验。
   • 修复旧 ReadWString 返回临时缓冲地址的问题。
   • DetachProcess() 会关闭并清空句柄/PID/Base。

7. Worker 配置同步

   • g_* 仍保留为 ImGui 绑定配置。
   • 渲染线程通过 UpdateWorkerConfigFromUi() 发布 WorkerConfigSnapshot。
   • 后台列表线程仅读取该受锁保护的配置副本，不与 UI 裸共享普通 bool/float。

8. 退出生命周期

   • 动态/静态数据线程不再 detach。
   • Overlay 退出后设置原子 process_active=false，join 两个线程，再 Reset overrides / Destroy overlay / Detach process。

9. 其他边界修复

   • Exfil 名称读取增加地址、长度和缓冲区限制，并修复 status 未正确缓存的问题。
   • Unity Transform、Camera、Managed Array/List 等常用裸偏移集中到 Offset.h。
   • min 调用改为显式 std::min，降低 Windows 宏依赖。
   • README 移除源码中不存在的“子弹追踪（只读）已完成”声明。

Runtime 防回归护栏

为避免后续 pointer validation、GOM 布局或线程优化再次让 ESP 静默失效，新增以下强制契约：

• 动态 Snapshot 无论刷新成功与否都持续发布，generation 单调增加；
• Snapshot 带 capturedAt、刷新总次数和连续失败数；超过 250ms 的数据不会用于 ESP、Aim 或功能写入；
• CGame 通过 IGameMemoryReader 支持 synthetic memory 注入，生产默认适配器仍使用全局 Memory m；
• GetObjectFromList 保留可选 last sentinel，并对 self-loop 和多节点环进行检测；
• 新增独立 CFramework.SelfTest Console 项目，覆盖对象链、四种 GOM 布局、首次失败恢复、Camera 降级和 W2S；
• 根目录 verify_runtime.ps1 会先重建并运行 SelfTest，测试失败则阻止 Overlay 构建。

验证

当前 Windows 环境已执行：

powershell -ExecutionPolicy Bypass -File .\verify_runtime.ps1

验证结果：

• Offline Runtime SelfTest：16 PASS，0 FAIL；
• 主程序：MSVC v143 Release | x64 全量重建成功；
• 新产物写入隔离目录 x64\RuntimeGuard\，不会覆盖正在运行的 known-good x64\Release\CFramework.exe；
• 仅保留项目既存的 C4828、C4244、LNK4098 和 FreeType LNK4099 warning，无新增编译或链接错误。

离线门禁不能替代最终实机烟雾测试。涉及 offset、Camera、玩家结构或线程生命周期的修改，仍必须验证启动顺序、连续进出局、Gen/Fresh/Age/Fail/Try 和 ESP/Aim 实际效果。