贡献指南
感谢你为 Space Engineers Blueprint Editor 提交改进。项目同时跨越 WinUI 3、WPF、.NET 8、.NET Framework 4.8 和《Space Engineers》游戏 API；较小、目标明确且可复现的变更最容易审查。
开始之前
- 阅读 README、开发指南和架构说明。
- 搜索已有 Issue，确认问题没有被重复报告。
- 对大范围架构调整，先用 Issue 说明目标、兼容性影响和迁移方式。
- 准备一个无 Mod、体积小且可公开的测试蓝图，保留原始副本。
报告问题
一个可操作的问题报告应包含：
- 应用版本或提交哈希。
- Windows 与《Space Engineers》版本。
- 游戏安装来源和非默认路径信息；不要粘贴隐私敏感的完整用户名路径。
- 复现步骤、期望行为和实际行为。
- 错误文本、相关日志或截图。
- 蓝图是否使用 DLC、Mod、旧版方块或 Steam Cloud。
- 若能安全共享，提供最小复现蓝图；提交前清理个人信息。
请勿上传游戏 DLL、Content 资源、Steam 凭据或无权分发的工坊内容。
开发流程
- 从最新目标分支创建功能分支。
- 只修改解决问题所需的文件，保留工作区中不相关的用户改动。
- 遵循现有命名、可空性和 MVVM 模式。
- 同时更新受影响的中英文资源和文档。
- 在
Debug|x64下构建并完成相应手工验证。 - 提交简洁、可独立理解的 commit。
推荐的基本验证命令：
dotnet build SpaceEngineersBlueprintEditor.sln -c Debug -p:Platform=x64 --nologo
游戏路径配置见开发指南的游戏目录检测章节。
代码约定
通用原则
- 启用并尊重可空引用类型，不用无意义的
!隐藏真实问题。 - 优先使用清晰的类型和方法名；注释解释原因、约束和游戏 API 怪异点。
- 不在 UI 线程执行蓝图反序列化、定义扫描或图像转换等重任务。
- 对文件覆盖、递归删除、升级和缓存清理等操作提供明确确认与错误反馈。
- 新异步流程应考虑异常传播、重复触发和页面离开后的生命周期。
- 不把本机绝对路径、服务器凭据或个人配置写入源码。
WinUI 与 MVVM
- 页面状态和命令放在 ViewModel；只有控件事件桥接或窗口句柄等 UI 专属逻辑留在 code-behind。
- 使用现有
ServiceManager、导航参数服务和消息/加载服务，避免新建平行的全局状态系统。 - 用户可见文本必须本地化。XAML 优先使用
x:Uid，C# 使用现有GetLocalized()方式。 - 大集合使用延迟加载或增量处理，避免在主线程一次性反射完整蓝图树。
游戏 API 与核心层
- 必须在首次使用游戏类型前初始化
GameAssemblyLoader。 - 游戏程序集引用保持
Private=false，不要复制或提交Bin64DLL。 SpaceEngineersCore面向net48；使用新 C# 特性前确认目标框架所需的编译器辅助类型。- 对未知、Mod 或版本不匹配的定义采用可诊断的降级行为，不要静默生成无效方块。
- 修改
InnerModel平台/渲染桩时，只实现调用路径需要的最小语义，并记录触发原因。
文件与保存
- 所有保存操作都应尽量使用同目录临时文件和原子替换。
- 保留或明确处理游戏的
sbcB5备份语义。 - 只反序列化本应用生成的带类型 JSON；不要把
TypeNameHandling用于不受信任输入。 - 测试删除、覆盖或迁移逻辑时使用临时目录，不使用真实玩家蓝图目录。
三维与钣金编辑
- 修改三维消息协议时同步更新 C# 场景模型、ViewModel、WebView2 桥接和本地 HTML。
- 本地 WebView 资源不得引入远程脚本；保持虚拟主机映射和消息输入边界清晰。
- 变换方块时同步维护方块组等坐标引用，并验证多格方块占位。
- Skeleton 偏移必须限制在游戏可编码范围，中性 Bone 应移除而不是重复写入。
- 明确撤销/重做覆盖范围，不要让界面暗示未记录的操作可以撤销。
文档约定
- Markdown 使用相对链接，确保 GitHub 仓库和本地查看都能工作。
- Mermaid 使用 GitHub 支持的语法；节点中包含空格、括号或标点时使用引号。
- 功能说明以已经接入 UI 且可验证的行为为准，实验代码要标注状态。
- 构建命令使用 PowerShell 示例，并说明 x64 与游戏路径要求。
- 改动功能、路径、项目结构或限制时，同步更新 README 和对应专题文档。
验证清单
根据改动范围完成以下项目：
- 解决方案
Debug|x64构建无错误。 - 没有新增或提交游戏 DLL、个人蓝图、缓存、
bin、obj或本机配置。 - 应用能自动或通过显式路径加载游戏。
- 受影响的蓝图可读取、另存并在游戏测试世界中验证。
- 若修改编辑器，三维选择/变换/撤销和钣金 Bone 写入均已用测试副本验证。
- 对未知定义、缺文件和无效路径有可理解的错误信息。
- 英文与简体中文资源键同步。
- Markdown 链接、代码块、表格和 Mermaid 图可渲染。
- 当前仓库没有标准自动化测试覆盖的部分已说明手工验证方法。
Pull Request 说明
PR 描述请包含：
- 解决了什么问题，为什么这样实现。
- 影响的项目和用户流程。
- 验证环境与验证结果。
- UI 变更前后截图或短视频。
- 蓝图格式、保存兼容性、游戏版本或发布布局风险。
- 尚未解决的问题和后续工作。
尽量避免把重构、依赖升级、格式化和功能修改混在同一个 PR 中。
许可证
提交代码或文档即表示你有权贡献这些内容，并同意其按仓库的 MIT License 分发。