架构概览
AnvilKit 引擎的整体架构设计
三大支柱
引擎围绕三大支柱构建：
- 渲染 — Canvas2D (2D)、Canvas3D (3D)、帧捕获，以及完整的 PBR 管线
- AI 接口 — MCP 服务器提供 17 个工具（视觉/控制/状态/场景），让代理能看到并操作游戏
- 运行时 —
GameCallbacks生命周期 +bevy_app调度系统
Crate 结构
引擎（总括）: anvilkit
运行时: anvilkit-app (GameCallbacks, 调度, 状态, 插件)
渲染: anvilkit-render (Canvas2D, Canvas3D, PBR 管线, 帧捕获, transform)
核心: anvilkit-core (数学, 时间, 错误, 持久化)
资产: anvilkit-assets
输入: anvilkit-input
音频: anvilkit-audio
AI Describe: anvilkit-describe + anvilkit-describe-derive
AI MCP: anvilkit-mcp (17 个工具: spawn_object, press_key, capture, save_scene 等)
游戏级（不在总括中）:
anvilkit-camera, anvilkit-gameplay, anvilkit-data注意：
anvilkit-ecs已不存在。其调度、插件系统和状态机已迁移至anvilkit-app。
分层架构
AnvilKit 采用分层模块化设计，每层只依赖下层：
Crate 依赖图
每帧生命周期
ECS Schedule 阶段
| 阶段 | 时机 | 典型系统 |
|---|---|---|
Startup | 初始化时运行一次 | 资源设置，初始生成 |
Main | 每帧最先执行 | (预留，用于全局逻辑) |
PreUpdate | 每帧 Update 之前 | DeltaTime 同步、父子层级同步 |
FixedUpdate | 每帧 0-N 次（累加器） | 确定性物理、固定速率游戏逻辑 |
Update | 每帧主逻辑 | 输入、物理、游戏逻辑、相机 |
PostUpdate | 每帧 Update 之后 | Transform 传播、渲染提取 |
Cleanup | 每帧最后 | (预留) |
Feature Flags
| Crate | Feature | 启用功能 |
|---|---|---|
anvilkit-core | serde | Transform, GlobalTransform 的序列化 |
anvilkit-core | persistence | SaveManager, Settings, WorldStorage |
anvilkit-core | bevy_ecs | 数学类型的 Component derive |
anvilkit-app | serde | ECS 组件序列化 |
anvilkit-assets | hot-reload | notify 文件监视热重载 |
anvilkit-assets | bevy_ecs | Skeleton, AnimationPlayer 的 Component derive |
anvilkit-gameplay | stats | Stats、Health、DamageEvent、health_system |
anvilkit-gameplay | inventory | SlotInventory、StackInventory、ItemStack |
anvilkit-gameplay | cooldown | Cooldown、cooldown_tick_system |
anvilkit-gameplay | status-effect | StatusEffect、StatusEffectList、StackPolicy |
anvilkit-gameplay | entity-pool | EntityPool 实体回收 |
模块概览
anvilkit-core
基础类型库：数学工具 (Vec3, Mat4, Transform, GlobalTransform, 插值)、时间系统 (Time, Timer)、错误类型 (AnvilKitError，with_context 保留原始错误类别)、持久化系统 (SaveManager, Settings, WorldStorage — 均返回 Result<_, AnvilKitError>)。Aabb 轴对齐包围盒、Frustum 和射线投射工具 (screen_to_ray, ray_plane_intersection, ray_sphere_intersection) — 在 v0.3 中从 render crate 迁移而来。持久化错误类别 (AnvilKitError::Persistence)，支持 category-preserving 的 with_context。
anvilkit-render
统一 2D/3D 渲染，提供代理友好的入口：
- Canvas2D：即时模式 2D 绘图（矩形、文本、精灵）
- Canvas3D：场景图 3D API，支持 PBR 材质和相机控制
- 帧捕获：
capture_frame()返回渲染像素 — 让 AI 代理能看到游戏 - PBR 材质系统 (Cook-Torrance BRDF, 5 种纹理贴图)
- HDR 渲染 (Rgba16Float) + ACES Filmic 色调映射
- Bloom (13-tap 降采样 + 9-tap tent 上采样, 5 级 mip)
- SSAO (半球采样, 半分辨率, 深度重建法线)
- 级联阴影贴图 (3 级级联, D2Array, PCF)
- IBL (BRDF LUT + 环境辐照度)
- MSAA 4x 抗锯齿
- GPU 骨骼动画 (线性混合蒙皮, 128 关节)
- 视锥剔除 + GPU 实例化 + 批次排序
- Sprite、Line、Particle、Text、UI 渲染器
- StandardMaterial 组件 (PBR builder 模式)
- PostProcessSettings (SSAO/DOF/运动模糊/Bloom/色彩分级)
- 正交/透视投影枚举, 多相机优先级
- PipelineCache/BindGroupCache
- 点光/聚光阴影系统 (ShadowAtlas)
- events.rs 拆分为 6 个文件 (events/ 目录), draw.rs 拆分为 5 个文件 (draw/ 目录)
- CachedBuffer 共享工具替代 5 处重复的 cached_vb 模式
- ProjectionUniform 共享类型替代 5 处重复的 ortho 结构体
- DebugRenderer 合并至 LineRenderer
anvilkit-assets
资产管线：glTF 模型加载（网格、材质、骨骼、动画）、AssetServer（同步+异步加载，去重）、AssetHandle (Arc 引用计数)、程序化网格生成、文件监视热重载。DependencyGraph 用于资产依赖追踪（基于 AssetId）。AssetCache 集成（内容哈希去重）。通过依赖图实现级联卸载。insert_parsed/get_parsed 用于类型化资产存储。
anvilkit-audio
基于 rodio 的音频系统：AudioSource ECS 组件、AudioBus（master/music/sfx/voice 音量混合）、空间音频（通过 AudioListener 距离衰减）、循环播放和变调控制。NonSend 资源模式确保 macOS CoreAudio 的线程安全。通过 listener right 向量实现立体声平移。通过 AudioSource.asset_id 集成资产系统。
anvilkit-input
输入抽象：InputState（键盘/鼠标 pressed/just_pressed/released、mouse_delta、scroll_delta）、GamepadState（16 个按钮、6 个轴）、ActionMap（逻辑动作 -> 物理绑定）、ActionId（零分配查询）、AxisBinding（键盘/手柄模拟轴）。InputPlugin 用于自动资源初始化。ActionMap 支持 apply_overrides 按键重绑定。手柄事件转发。
anvilkit-camera
生产级相机系统，5 种模式 (FirstPerson/ThirdPerson/Orbit/Free/Rail)。OrbitState 组件、CameraRig 实体跟随、SpringArm 碰撞避免、Trauma+Perlin 噪声抖动、CameraTransition 过渡混合 (5 种缓动)、LookAtTarget 软约束、CameraRail 推轨 (Catmull-Rom)、InputCurve 死区+响应曲线。8 系统管线，帧率无关平滑。
anvilkit-app
游戏应用运行器，消除样板代码。AnvilKitApp::run() 管理 winit 事件循环、输入转发、DeltaTime 和帧生命周期。游戏实现 GameCallbacks（init、post_update、render、on_resize、on_window_event）并传入 GameConfig（标题、窗口尺寸、垂直同步）。通过 GameContext 提供对 ECS App 和 RenderApp 的访问。重构后，anvilkit-app 还包含调度、ECS 插件系统和状态机（之前在已删除的 anvilkit-ecs 中）。
anvilkit-describe
AI 优先的内省机制：Describe trait 及其 derive 宏，允许引擎类型输出可被 AI 代理消费的结构化描述。配套的 anvilkit-describe-derive crate 提供 proc macro。
anvilkit-mcp
MCP（Model Context Protocol）服务器，提供 17 个工具，向 AI 代理暴露引擎状态和控制接口。工具类别：视觉（capture_frame、describe_scene）、控制（press_key、move_mouse、spawn_object）、状态（get_component、set_component）、场景（save_scene、load_scene）。让代理能看到并交互运行中的游戏。
anvilkit-gameplay
可选的、按 feature 门控的游戏性构建模块：stats（通用属性系统，支持加法/乘法/覆盖修饰器）、health（Health 组件，含自动回血、DamageEvent、HealEvent、DeathEvent、health_system）、inventory（基于槽位的可堆叠物品栏）、cooldown（技能/动作冷却计时器）、status-effect（基于持续时间的状态效果，支持堆叠策略）、entity-pool（实体回收对象池）。
anvilkit-data
数据驱动配置与本地化：DataTable（从 RON/JSON 加载的类型化键值表）、Locale（带回退链的翻译查找）、DataTablePlugin ECS 集成。
坐标系
AnvilKit 使用左手坐标系：
- +X 向右
- +Y 向上
- +Z 向屏幕内（前方）
投影使用 perspective_lh 和 look_at_lh。