Git for Minecraft Builds 面向 Minecraft 建筑协作的分布式版本控制系统。
BlockGit 希望让 Minecraft 建筑像软件源码一样被 stage、commit、branch、diff、merge、push 和 review。
项目首选使用 Gitea 承担仓库托管、组织权限、Pull Request、Review、Issue 和受保护分支，不再从零开发一套通用 Git 协作平台。BlockGit 只补充 Minecraft 特有的语义检查、文本报告、游戏身份桥接和游戏内 3D 交互；BlockHub 保留为可选的预配置发行方案，由 Gitea、BlockGit Gitea Bridge 与 BlockGit Identity 组合而成。
Important
BlockGit 目前处于设计与技术验证阶段，尚无可供日常使用的正式版本。当前工作的重点是验证世界数据往返、Git/JGit 对象格式、多人变更归属、暂存模型和安全检出。
完整产品与技术设计请阅读 开发文档。
我正在寻找愿意共同设计和实现 BlockGit 的开发者、设计者、测试者与 Minecraft 创作者。
项目的核心方向已经形成，但大量细节仍需要原型、实验和讨论来验证。欢迎你提出不同方案、指出设计问题，或者从自己的建筑团队、服务器和 Mod 开发经验出发，重新审视当前设想。参与项目不要求完全赞同现有文档，也不要求一开始就提交代码。
特别欢迎具备以下任一经验的参与者：
- Minecraft Java Edition、Fabric、NeoForge、Forge 或 Paper 开发；
- Java/Kotlin、JGit、Git Object、Pack 与远程协议；
- Anvil/NBT、Registry、Chunk、Block Entity 和世界存档格式；
- WorldEdit、建筑工具、服务端事件追踪或 Mod/插件兼容；
- Git 合并算法、三方 diff、内容寻址存储或大规模数据性能优化；
- Gitea API、Webhook、Actions、Commit Status、OIDC 与 Git 托管集成；
- 身份认证、应用安全、服务端运维或自托管平台；
- 游戏内 UI、原生渲染、3D overlay 和冲突交互；
- 大型建筑、校园还原、地图制作或多人创作项目管理；
- 测试、文档、交互设计、翻译或社区维护。
如果你只有一个使用场景、一份测试世界、一个反例或一条意见，也非常有价值。
大型 Minecraft 建筑项目通常依赖世界备份、.litematic、WorldEdit schematic、操作日志和人工分工。这些工具可以保存或恢复内容，但很难完整解决长期多人开发中的问题：
- 一个建筑需要同时维护多个方案和版本；
- 不清楚某次提交具体修改了哪些坐标、方块和 NBT；
- 多名玩家共享同一个世界，修改容易被错误归入他人的提交；
- 只能提交整个选区，难以只选择某位玩家或某组事务的变化；
- 两个分支修改同一位置时，文件级 Git 无法理解 Minecraft 冲突；
- 缺少受保护分支、Pull Request、审查、权限和贡献统计；
- 世界文件体积大、变化频繁，普通二进制备份难以增量存储和合并。
BlockGit 的目标不是简单地把整个世界压缩后提交到 Git，而是在 Minecraft 世界与 Git 之间建立稳定、可逆、可比较的语义数据层。
Minecraft World / Workspace
│
▼
status · diff · stage
│
▼
Git commit · branch · merge
│
▼
Gitea / compatible Git Remote
│
▼
Gitea PR · BlockGit Check · Review
三维空间相关操作保留在游戏内：
Minecraft Client
├─ 3D status overlay
├─ 3D diff
├─ staged / unstaged / other actor
└─ conflict resolver
| 项目 | 当前决定 |
|---|---|
| 项目名称 | BlockGit |
| 首选 Web 协作底座 | Gitea |
| BlockHub 定位 | Gitea + BlockGit Gitea Bridge + BlockGit Identity 的可选预配置发行方案 |
| 首发游戏版本 | Minecraft Java Edition 1.21.8 |
| 首发加载器 | Fabric |
| 后续适配顺序 | NeoForge → Forge → Paper |
| 首版追踪范围 | Build Profile |
| 版本库基础 | Git/JGit，兼容标准 Git 远程 |
| Gitea 集成方式 | API、Webhook、Actions、Commit Status 与 OIDC；MVP 不 Fork Gitea |
| Web 差异展示 | 类似 GitHub 的结构化文本 diff |
| 3D 差异展示 | 只在 Minecraft 客户端内提供 |
| 默认用户身份 | 游戏认证身份与 Java UUID 绑定 |
| 开源许可证 | GPL-3.0-or-later |
这些决定用于收敛首个原型，不代表后续设计不能通过数据和实践调整。
BlockGit 使用 JGit 管理标准 Git Commit、Tree、Blob、Ref 和远程传输。Minecraft 世界会先被规范化为稳定的语义结构，再写入 Git Tree，而不是直接提交不断变化的原始世界文件。
Git Commit
└─ Semantic Tree
├─ blockgit.toml
└─ world/
└─ dimensions/
└─ regions/
└─ chunks/
└─ sections/
├─ Block States
├─ Block Entities / NBT
└─ Build Profile Entities
仓库可以推送到 Gitea、GitHub 或其他标准 Git 服务。Gitea 是首个重点支持的协作宿主，负责 Git 对象、分支、PR、Review 和权限；BlockGit Checker 或 Gitea Bridge 负责生成 Minecraft 语义 diff、兼容性检查与合并检查。Core 通过 GitHostAdapter 保持平台无关，不能把仓库格式绑定到 Gitea。
普通 Git 中，每位开发者拥有独立 Working Tree；Minecraft 多人服务器中的玩家却经常同时修改同一个世界。
BlockGit 将 Workspace 作为一级概念：
Workspace
├─ repository / branch
├─ world / dimension / origin
├─ tracked area
├─ owner / writers / readers
├─ lock mode
└─ dirty state
同一坐标默认只能属于一个可写 Workspace，从源头减少权限、归属和暂存歧义。需要并行方案时，可以把相同仓库检出到不同位置、世界或维度。
系统记录的是“谁引发了哪一次变化”，而不是“某个方块永久属于谁”。
ChangeTransaction
├─ direct actor
├─ initiator
├─ source / cause
├─ attribution confidence
└─ semantic changes[]
BlockGit 会尽量识别玩家、命令、WorldEdit 和其他扩展引发的变化。无法可靠解释的变化必须标记为 SYSTEM、UNKNOWN 或低置信度来源，不能静默归给最近操作的玩家。
BlockGit 计划实现真正的 HEAD → Index → Working Tree 三态模型，并支持：
- 按玩家暂存；
- 按空间范围暂存；
- 按完整事务暂存；
- 逐项暂存与取消暂存；
- 提交后保留其他玩家尚未暂存的变化。
合并以 Base、Ours、Theirs 为输入：
- 只有一侧修改时自动采用修改侧；
- 两侧修改不同坐标时尝试自动合并；
- 同一坐标产生不同结果时形成 Minecraft 语义冲突；
- Block Entity 尝试进行 NBT 字段级合并；
- 无法证明安全的情况默认产生冲突，而不是覆盖数据。
Gitea 使用原生文本 diff 和 BlockGit 生成的 PR 报告展示坐标、BlockState、NBT 路径和 Before/After；Minecraft 客户端负责把相同结构化 diff 渲染成 3D overlay，并提供空间化冲突解决。
用户默认通过游戏已经认证的 Java UUID 建立 BlockGit 身份。在可信游戏会话中，玩家可以发起一次性账户绑定，在 HTTPS 页面设置 BlockGit Identity 登录凭据。
绑定完成后，在已接入 BlockGit Identity 的自托管 Gitea/BlockHub 实例中，用户无需启动 Minecraft，即可通过 OIDC 登录 Gitea。无实例管理权的第三方 Gitea 继续使用原有登录方式，再通过 OAuth2 与 BlockGit User 建立一次性账户关联。BlockGit 密码不会同步给 Gitea，也不会通过 Minecraft 聊天、命令参数或服务端日志明文传输。
游戏认证只负责确认身份，不自动授予仓库权限；组织、仓库、分支和 Workspace 仍分别执行授权检查。
| 能力 | Minecraft / BlockGit | Gitea Web |
|---|---|---|
| 世界读取与写入 | 是 | 否 |
| status / stage / commit | 是 | 查看状态与提交记录 |
| 3D diff 与投影 | 是 | 否 |
| 三维冲突解决 | 是 | 否 |
| 文本 diff | 生成结构化 diff | 原生 diff + BlockGit 文本报告 |
| 语义完整性与合并检查 | BlockGit Core | 通过 Actions/Bridge 回写状态 |
| Pull Request、Issue 与审批 | 可发起/同步 | Gitea 原生提供 |
| 组织、团队与分支权限 | 执行 Workspace 权限 | Gitea 为仓库授权事实来源 |
Web 端不计划实现 WebGL 世界查看器。需要理解空间关系时，用户可以从 Commit 或 PR 获取标识，并在 Minecraft 中打开对应的 3D diff。BlockHub 不是一套重新开发的 GitHub/Gitea，而是由 Gitea 和 BlockGit 扩展组件组成的官方一体化部署方案。
- 冻结第一版 Git Semantic Tree 和
blockgit.toml草案； - 完成 Fabric 1.21.8 Build 数据的读入、规范化和安全写回；
- 使用 JGit 创建可被标准 Git CLI 和远程识别的 Commit；
- 建立原版、Mod 方块、Block Entity 和自定义维度测试语料；
- 验证玩家、命令、WorldEdit 和系统变化的基础归属；
- 证明 Snapshot、Change Log、Index 与当前世界可以可靠对账。
init、status、stage、diff、commit、log和branch；- 游戏内 3D diff 与状态投影；
- 在线
checkout/restore的锁、写前日志和崩溃恢复； - 标准 Git remote 的 clone/fetch/push。
- Server Companion、Workspace、ACL、Lock/Freeze；
- 多人 ChangeTransaction 与按操作者暂存；
- 游戏 UUID 绑定、BlockGit Identity 凭据、受管 Gitea OIDC 登录和第三方 Gitea OAuth2 AccountLink；
- 独立副本间的远程同步和非冲突合并。
- 可复用的 Gitea Actions 语义检查工作流；
- 必要时提供 Gitea Bridge，用于统一 Webhook、幂等任务和 Commit Status 回写；
- PR 的结构化文本摘要、完整报告链接和“在 Minecraft 中打开”标识；
- Gitea 受保护分支强制 BlockGit Check；
- BlockGit Identity 与 Gitea OIDC 账户关联。
详细退出条件和后续阶段见 开发文档。
当前文档中的方案都欢迎被检验。尤其希望听到大家对以下问题的看法：
- Semantic Tree 应该使用 Chunk、Section，还是更细的空间粒度？
- 如何在 Git 对象数量、Pack 大小、diff 性能和局部复用之间取舍？
- WorldEdit、命令和异步 Mod 应怎样传播可靠的 actor/transaction context？
- Build Profile 默认应该追踪哪些装饰实体和 Block Entity 字段？
- 在线 checkout/merge 应怎样控制玩家安全、区块更新和崩溃恢复？
- 游戏内 3D diff 在大型建筑上应如何降级并保持流畅？
- Gitea 原生 diff、PR Markdown 摘要和独立完整报告应如何分工？
- Gitea PR 与 BlockGit 语义合并应该如何衔接并强制检查？
- 自托管 Minecraft 服务器、BlockGit Identity 和 Gitea 实例之间应如何建立信任？
- 如何在不 Fork Gitea 的前提下提供足够清晰的大型建筑文本审查？
- 哪些设计会妨碍真实建筑团队使用？
不必给出完整解决方案。真实使用场景、失败案例和对当前方向的质疑同样欢迎。
- 阅读本 README 和 开发文档。
- 选择你关心的使用场景或技术问题。
- 创建 Issue，描述问题、方案、替代方案或实验结果。
- 对影响仓库格式、协议、合并语义或身份安全的改动，先讨论简短 RFC。
- 小型修正、测试语料、文档和可独立验证的原型可以直接提交 Pull Request。
提出设计意见时，如果方便，可以包含：
- 真实场景：谁在什么环境中遇到了什么问题；
- 期望行为：用户最终希望完成什么；
- 建议方案：数据结构、流程或交互可以怎样设计；
- 代价与风险：性能、兼容性、安全性或复杂度影响；
- 验证方法：怎样通过测试世界、基准或原型判断方案是否有效。
- 世界数据安全优先，不允许静默丢失、替换或错误归属。
- 重要结论尽量由测试世界、基准数据或可复现原型支持。
- 仓库格式、协议和兼容性变化需要显式版本化。
- 优先完成小而完整的纵向闭环，再逐步扩展加载器和平台。
- 欢迎建设性的不同意见，讨论针对设计与证据，不针对参与者。
BlockGit 的设计受到 Gitmatica、MCGit 和 Reden RVC 等项目的启发：
- Gitmatica 展示了 Semantic Storage、tracked mask 和方块级三方合并的价值；
- MCGit 提供了贴近 Git Working Tree、Stage、Commit 和 relative origin 的思路；
- Reden RVC 展示了红石结构、运行状态、Region 和模块化方向的可能性。
BlockGit 希望在这些探索之上，进一步解决多人共享 Working Tree、玩家变更归属、Workspace 权限、选择性暂存和 Web 协作问题。欢迎熟悉这些项目的开发者纠正理解或补充经验。
- 当前状态：早期设计 / P0 技术验证准备阶段；
- 首个目标：Minecraft Java Edition 1.21.8 + Fabric + Build Profile；
- 许可证：
GPL-3.0-or-later； - 开发文档：docs/DEVELOPMENT.md。
如果你对“Minecraft 的 Git”感兴趣，欢迎留下你的想法，也欢迎一起把它真正做出来。