# Space Engineers Blueprint Editor

一款面向《Space Engineers（太空工程师）》的 Windows 蓝图查看与编辑工具。项目使用 WinUI 3 和 MVVM 构建，可读取游戏本地、Steam Cloud 与创意工坊缓存中的 `.sbc` 蓝图，并复用已安装游戏的定义与序列化程序集。

> [!IMPORTANT]
> 项目仍处于早期开发阶段（当前项目版本为 `0.1.0`）。编辑或删除蓝图前，请先备份整个蓝图目录；本项目不是 Keen Software House 的官方工具。

## 文档导航

- [用户指南](docs/USER_GUIDE.md)：打开、查看、编辑、保存蓝图及常见问题。
- [开发指南](docs/DEVELOPMENT.md)：环境准备、游戏定位、构建、运行与调试。
- [架构说明](docs/ARCHITECTURE.md)：项目分层、启动过程、数据流与扩展点。
- [贡献指南](CONTRIBUTING.md)：提交代码或文档前的约定与检查清单。

## 主要能力

- 自动发现 Steam 安装的《Space Engineers》，也可手动指定游戏目录。
- 浏览本地、Steam Cloud 和创意工坊缓存蓝图，并按名称搜索。
- 通过文件选择器或拖放打开任意 `.sbc` 蓝图。
- 查看作者、文件大小、网格与方块数量、DLC 以及建造所需组件统计。
- 按网格或方块组浏览方块，并通过属性树编辑基础字段。
- 在 WebGL 三维视图中选择、移动、旋转、复制或删除方块，并支持撤销/重做。
- 编辑网格 Skeleton 中的表面角点与面中心，实现装甲钣金形变。
- 批量切换可破坏性、可编辑性、网格尺寸和轻/重装甲定义。
- 浏览游戏中的方块、组件、物品和场景定义。
- 提供中英文界面资源、主题、导航布局和缓存管理设置。

下图概括了应用处理蓝图时涉及的主要数据源：

```mermaid
flowchart LR
    User["用户"] -->|"选择或拖放 .sbc"| UI["WinUI 3 桌面应用"]
    BP["%APPDATA%/SpaceEngineers/Blueprints"] --> UI
    UI --> Loader["GameAssemblyLoader"]
    Loader --> Bin["游戏 Bin64 程序集"]
    UI --> Core["SpaceEngineersCore"]
    Core --> Content["游戏 Content 与定义"]
    Core --> Model["ObjectBuilder 蓝图对象"]
    Model --> Details["详情与材料统计"]
    Model --> Editor["属性、三维与钣金编辑"]
    Editor --> Save["核心序列化与原子替换"]
    Save --> Saved["bp.sbc 与 bp.sbcB5"]
```

## 运行要求

- Windows 10 1809（Build 17763）或更高版本；建议使用 x64，并安装 Microsoft Edge WebView2 Runtime。
- 已通过 Steam 安装《Space Engineers》。
- 若从源码构建：Visual Studio 2022 与 .NET 8 SDK，并安装 Windows 应用开发相关组件。

游戏 DLL 不会提交到仓库，也不会复制到应用输出目录。构建和运行时都会直接从已安装游戏的 `Bin64` 加载它们，因此游戏更新后建议重新构建并做一次基本功能检查。

## 从源码开始

```powershell
git clone https://github.com/XFEstudio/SpaceEngineersBlueprintEditorInWinUI.git
cd SpaceEngineersBlueprintEditorInWinUI
dotnet build SpaceEngineersBlueprintEditor.sln -c Debug -p:Platform=x64
```

若自动检测不到游戏，可显式传入 `Bin64`：

```powershell
dotnet build SpaceEngineersBlueprintEditor.sln -c Debug -p:Platform=x64 `
  -p:SpaceEngineersBinPath="D:\Games\SpaceEngineers\Bin64"
```

也可以设置环境变量后重新打开终端：

```powershell
$env:SPACE_ENGINEERS_ROOT = "D:\Games\SpaceEngineers"
# 或：$env:SPACE_ENGINEERS_BIN = "D:\Games\SpaceEngineers\Bin64"
```

更完整的环境说明、检测顺序和故障排查见[开发指南](docs/DEVELOPMENT.md)。

## 快速使用

1. 启动应用，等待游戏定义加载完成。
2. 将 `.sbc` 拖入首页，或从导航栏打开本地、云端、工坊蓝图列表。
3. 在详情页检查蓝图信息、DLC、网格和组件统计。
4. 进入编辑器，通过网格、方块组、属性树、三维视图或钣金视图修改内容。
5. 使用“保存”写回当前 `.sbc`，或在三维页使用“另存为”创建新文件。

> [!CAUTION]
> 蓝图列表中的“删除”会直接删除对应蓝图文件夹；保存到已有文件也可能覆盖原内容。请在游戏未写入同一蓝图时操作，并事先保留副本。

## 蓝图目录

应用按《Space Engineers》的默认用户数据结构读取蓝图：

| 类型 | 默认目录 |
| --- | --- |
| 本地蓝图 | `%APPDATA%\SpaceEngineers\Blueprints\local` |
| Steam Cloud 蓝图 | `%APPDATA%\SpaceEngineers\Blueprints\cloud` |
| 创意工坊缓存 | `%APPDATA%\SpaceEngineers\Blueprints\workshop\temp\Steam` |

应用会读取每个蓝图目录中的 `bp.sbc` 和可选的 `thumb.png`。

## 项目组成

| 项目 | 作用 | 目标框架 |
| --- | --- | --- |
| `SpaceEngineersBlueprintEditor` | WinUI 3 主程序、页面、ViewModel 与应用服务 | `net8.0-windows10.0.22621.0` |
| `SpaceEngineersBlueprintEditor.GameAssemblyLoader` | 查找游戏目录并解析托管/原生依赖 | `net48;net8.0` |
| `SpaceEngineersBlueprintEditor.SpaceEngineersCore` | 初始化游戏定义、读取 ObjectBuilder、图像与网格转换支持 | `net48` |
| `SpaceEngineersBlueprintEditor.BlueprintConverter` | 独立的 JSON → `.sbc` 辅助转换器；主界面当前直接调用核心保存 API | `net48` |
| `SpaceEngineersBlueprintEditor.Installer` | WPF 安装与升级程序 | `net8.0-windows` |
| `SpaceEngineersBlueprintEditor.Test` | 开发期控制台试验项目，不是标准 `dotnet test` 测试套件 | `net8.0` |

## 当前限制

- 仅支持 Windows；核心逻辑依赖已安装游戏的程序集和内容文件。
- 主编辑流程面向船舶蓝图中的第一个 `ShipBlueprint` 定义。
- 三维视图使用方块定义包围盒而不是游戏模型；占位检测也不能覆盖所有多格方块重叠情形。
- 网格尺寸与轻/重甲转换只替换能从当前游戏定义中找到配对项的方块，未支持方块会保留并计数。
- 三维视图的撤销/重做只覆盖该视图中的移动、旋转、复制和删除，不覆盖属性、钣金或批量转换。
- SE Toolbox 格式导出入口尚未接通完整实现。
- 核心层为无窗口加载游戏定义而实现了最小平台/渲染桩，未覆盖的游戏接口可能抛出 `NotImplementedException`。
- 仓库暂未提供可由 `dotnet test` 发现的自动化测试项目。

## 技术栈

- C#、.NET 8 与 .NET Framework 4.8
- WinUI 3 / Windows App SDK
- WPF（安装器）
- CommunityToolkit.Mvvm
- Space Engineers / VRage ObjectBuilder 与定义系统

## 参与贡献

欢迎提交 Issue 和 Pull Request。开始前请先阅读[贡献指南](CONTRIBUTING.md)，并避免提交《Space Engineers》的 DLL、游戏资源或个人蓝图数据。

## 许可证与声明

本项目以 [MIT License](LICENSE.txt) 发布。《Space Engineers》及相关名称、资源和程序集的权利归其各自权利人所有；本仓库不分发游戏文件。