WaveEngine 是面向 Windows x64 的 C++20 实时渲染引擎与 ImGui 场景编辑器。当前唯一渲染后端是 DirectX 12，项目重点是现代 GPU 管线、静态场景编辑、自动化和性能分析，并以 AI-native 作为未来整个引擎的设计约束。
Important
当前版本可用于渲染研究、静态场景搭建和编辑器工具开发，但还不能独立制作与发布完整游戏。当前 AI-Native 基础改造只迁移已有能力及其架构边界，不新增 Player、Gameplay、物理、音频或打包功能；长期产品方向见产品化路线图。
- 渲染：Shader Model 6.6、bindless、Mesh Shader、RenderGraph、G-Buffer 延迟光照、Shadow、IBL、自动曝光和 Tonemap。
- Path Tracing：可选 DXR Tier 1.1 路径；不可用时回落到光栅。
- 资产：导入
.obj、.gltf、.glb、.fbx，后台构建 Meshlet/CLOD 和 WEMesh v3 缓存。 - 编辑器：Viewport、Scene、Content、Details、Settings、Trace Capture、Console，支持 Gizmo、Undo/Redo 和保存。
- 自动化：行分隔 JSON-RPC 2.0 MCP 服务，工具通过
rpc.discover查询。 - 分析：CPU/GPU Profiler、
.wetrace、live listener 和独立WaveTraceViewer。
世界坐标采用左手系：+X 前、+Y 右、+Z 上；欧拉角顺序为 [Pitch, Yaw, Roll]。
AI-native 不是增加一个 AI 模块。目标是让 Asset、World、Renderer、Gameplay、Build、Trace 等每个领域都具备稳定身份、可演进机器 schema、revisioned query/change feed、明确 effect、自动验证、provenance、安全预算和 headless 行为。
Human Editor / Agent / Script / CI
→ Domain Contracts
→ Deterministic Runtime
Shipping Player → Runtime-only closure
UI、MCP 和未来 headless host 只是同一领域能力的客户端。Query、Document Command、异步 Job 和 VCS/发布类 External Action 具有不同失败边界；修改必须用 change set、validator、artifact provenance、测试、截图或 trace 证明。未来运行时模型只产生受 Gameplay 校验的高层 Intent，不直接控制逐帧状态。
整体设计见 AI-Native Engine Architecture；通用设计输入已作为仓库内参考快照保存；公共契约基础见 A0-01 Verified Spec。
- Windows x64
- Visual Studio 2022、MSVC v143、Windows SDK
- CMake 4.0.1 或更高版本
- 支持 DirectX 12 Mesh Shader 的 GPU
- DXR Tier 1.1 GPU（仅 Path Tracing 需要）
- Python 3（运行 Spec、MCP 和资产契约测试时需要）
Vulkan 当前只有预留宏，没有可用后端。项目不使用 vcpkg 或 Conan，主要第三方依赖随仓库提供。
git clone https://github.com/kyriewxcode/WaveEngine.git
cd WaveEngine
cmake -S . -B Build -G "Visual Studio 17 2022" -A x64
cmake --build Build --config Debug
& .\Build\Debug\WaveEditor.exeRelease：
cmake --build Build --config Release
& .\Build\Release\WaveEditor.exeRebuild.bat 会复用已有 Build/ 重新生成并构建 Debug，不是 clean rebuild。构建后 CMake 会复制 Agility SDK、DXC 等运行时 DLL。
运行生成内容位于 Engine/Save/，日志写入当前工作目录的 WaveEngine.log。Build/、Engine/Save/、*.wemesh 和日志不应提交。
# 启动
& .\Build\Debug\WaveTraceViewer.exe
# 打开文件
& .\Build\Debug\WaveTraceViewer.exe .\path\to\capture.wetrace
# 连接 live listener
& .\Build\Debug\WaveTraceViewer.exe --connect 127.0.0.1:18086live 端口以编辑器 Trace Capture 面板中的配置为准。
无窗口 CPU 契约使用仓库 preset，Debug 与 Release 都只构建 WaveCoreContracts，不会构建或启动 Editor：
cmake --preset vs2022-x64
cmake --build --preset cpu-debug
ctest --preset test-cpu-debug
cmake --build --preset cpu-release
ctest --preset test-cpu-release测试 preset 只运行带 cpu label 的测试、显示失败输出，并在没有匹配测试时返回失败。CMakeSettings.json 保留给 Visual Studio 兼容使用，自动化以 CMakePresets.json 为准。
.github/workflows/cpu-contracts.yml 在 Windows x64 runner 上复用完全相同的 preset 链路；该 workflow 不构建或启动 Editor。
完整 Debug 验证：
cmake --build Build --config Debug
ctest --test-dir Build -C Debug --output-on-failure当前 CTest 覆盖：
- CMake preset 与 CPU target/source/include 边界。
- Spec 元数据、状态和链接。
- Core Runtime 坐标、旋转、RenderGraph allocator 和 trace codec。
- MCP framing、数值边界和恶意资产输入。
- WEMesh provenance、缓存、坐标转换、winding 和法线。
只验证 SDD 文档：
py -3 Tests/spec_contracts.py .RenderGraph 或 Pass 修改还需在 Debug 下设置 WAVE_RG_STRICT=1 并运行真实光栅路径。完整验证矩阵见 AGENTS.md。
完整职责、事实层级和冲突处理见 文档地图。
| 文档 | 职责 |
|---|---|
| AGENTS.md | 编码代理工作规则和高风险工程契约 |
| AI-Native Engine Architecture | 跨所有领域的长期设计不变量与验收维度 |
| 产品化路线图 | 阶段、依赖、Issue 和产品门禁 |
| SDD 流程 / Spec 注册表 | Spec 状态、session 协议、验证规则和活跃入口 |
| 设计参考快照 | 外部设计输入与校验值；不作为实现真值 |
源码与 CMakeLists.txt 是已实现能力的事实来源；路线和 Draft Spec 只描述未来工作。
核心源码位于：
Engine/Source/RHI/、RenderGraph/、Renderer/：GPU 与渲染。Engine/Source/Scene/：场景、资源导入和序列化。Engine/Source/UI/、Mcp/：编辑器与自动化。Engine/Source/Trace/、Tools/TraceViewer/：性能采集与分析。Tools/Mcp/：会启动并操作编辑器的 MCP smoke、demo 和性能脚本。Tests/：无第三方测试框架依赖的契约测试。
开发采用 Spec-Driven Development：
Draft → Accepted → Implementing → Verified
新功能和架构修改先从 Spec 注册表 查找或创建 Draft；只有用户明确接受后才能开始生产实现。
- 已拆分
WaveRuntime、WaveEditorSupport与WaveEditor.exe；没有新增 Player、Game 或发布功能。 - 没有完整 World/Entity/Component、Gameplay、PIE、Action Input、物理、音频和 Runtime UI。
- 没有稳定 Asset ID、Cook、Stage 或 Package。
- glTF alpha、双面、UV1、每纹理 sampler 和正确 sRGB 过滤尚未完整实现。
- RenderGraph 当前为单 Direct Queue、整资源状态跟踪。
- 平台范围仅为 Windows x64。