# WorldGit<\/p>\n
WorldGit is a Paper plugin for Minecraft 1.21.11 that introduces a Git-like
\nworkflow for collaborative world building.<\/p>\n
Players branch a selected region from the protected main world into an isolated
\nbranch world, edit safely, submit their work for review, and merge approved
\nchanges back into the main world. The main world stays read-only except through
\nexplicit merges.<\/p>\n
For the Chinese version, see [README.zh-CN.md](README.zh-CN.md).<\/p>\n
## Target Stack<\/p>\n
– Minecraft server: Paper `1.21.11`
\n– Java: `21`
\n– Build tool: Gradle Kotlin DSL + Shadow
\n– Main dependencies:
\n – Paper API `1.21.11-R0.1-SNAPSHOT`
\n – WorldEdit `7.4.1-SNAPSHOT`
\n – Multiverse-Core `5.5.3`
\n – SQLite JDBC `3.47.2.0`
\n– Optional integration:
\n – LuckPerms API<\/p>\n
## Core Features<\/p>\n
– Region-based branch creation from a WorldEdit selection
\n– Concurrent overlapping branches during the editing phase
\n– Isolated branch worlds for editing
\n– Book-driven player menu with branch-detail, conflict-center, review, and merge-history chest UIs
\n– Review flow: submit, approve, reject, confirm merge
\n– Region-scoped rebase onto the latest main-world revision with three-way conflict detection
\n– Conflict groups with `mine`, `theirs`, and manual resolution flows
\n– Approved branches are re-checked before merge; stale approvals are revoked and require re-review
\n– Approved branches become read-only until `\/wg forceedit`
\n– Sign-based coordinate input for `Pos1` \/ `Pos2` and merge messages
\n– Crash-safe merge journal and rebase journal with startup recovery
\n– Invite system for shared branch access
\n– Revision and commit tracking for the protected main world
\n– Short-lived integration lock during merge only
\n– Main-world protection to enforce read-only behavior
\n– Periodic and manual backups<\/p>\n
## Runtime Dependencies<\/p>\n
Install these plugins on the Paper 1.21.11 test server:<\/p>\n
– WorldEdit
\n– Multiverse-Core
\n– WorldGit<\/p>\n
LuckPerms is optional and only needed if you want to manage permissions through
\nit.<\/p>\n
## Build<\/p>\n
“`bash
\n.\/gradlew build
\n“`<\/p>\n
Output JAR:<\/p>\n
“`text
\nbuild\/libs\/worldgit-1.1.0.jar
\n“`<\/p>\n
## Installation<\/p>\n
1. Copy the built JAR to the server `plugins\/` directory.
\n2. Make sure `WorldEdit` and `Multiverse-Core` are also installed.
\n3. Start the server once to generate `plugins\/WorldGit\/config.yml`.
\n4. Edit the config if needed.
\n5. Restart the server.<\/p>\n
## Default Configuration<\/p>\n
“`yaml
\nmain-world: “world”
\nmax-region-size-x: 50
\nmax-region-size-z: 50
\nuse-full-height: false
\nmax-active-branches: 2<\/p>\n
backup:
\n enabled: true
\n interval-minutes: 30
\n max-backups: 10
\n directory: “backups”<\/p>\n
branch-world:
\n prefix: “wg_”<\/p>\n
database:
\n file: “worldgit.db”
\n“`<\/p>\n
## Commands<\/p>\n
### Player Commands<\/p>\n
– `\/wg create` ### Admin Commands<\/p>\n – `\/wg review list` ## Player Menu<\/p>\n – Players receive a menu book in hotbar slot `9`. ## Permissions<\/p>\n ### Player Permissions<\/p>\n – `worldgit.branch.create` ### Admin Permissions<\/p>\n – `worldgit.admin.review` ## Workflow<\/p>\n ## Terminology<\/p>\n – WorldGit 1.1.0 uses **Rebase** as a product term, and that is acceptable because the plugin is intentionally Git-flavored. ### Create a Branch<\/p>\n 1. Stand in the main world. ### Rebase and Resolve Conflicts<\/p>\n 1. Open the branch-detail UI from the player menu. ### Submit, Review, and Merge<\/p>\n 1. Run `\/wg submit [id]` or submit through the branch-detail UI. ## World Protection Coverage<\/p>\n The plugin blocks direct edits in the configured main world, including:<\/p>\n – Block place and multi-place Admins with `worldgit.admin.bypass` can bypass player-driven protection checks.<\/p>\n ## Paper 1.21.11 Test Checklist<\/p>\n ### Environment Setup<\/p>\n 1. Start a fresh Paper `1.21.11` server. ### Branch Creation<\/p>\n 1. Join as a player with `worldgit.branch.create`. ### Protection<\/p>\n 1. Try placing and breaking blocks in the main world. ### Rebase, Review, and Merge<\/p>\n 1. Let player A and player B create overlapping branches from the same region. ### Recovery<\/p>\n 1. Start a merge. ### Backup<\/p>\n 1. Run `\/wg admin backup`. ## Notes<\/p>\n – This repository currently passes `.\/gradlew build`. A Minecraft plugin for world building cooperation with git-like control.<\/p>\n","protected":false},"featured_media":171538,"template":"","meta":{"_minecraft_slug":"worldgit","_minecraft_project_id":"P12Htco8","_minecraft_author":"Alex_Tang","_minecraft_license":"MIT","_minecraft_downloads":12,"_minecraft_follows":3,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"worldgit.zip","_minecraft_size_bytes":43387209,"_minecraft_version_count":3,"_minecraft_updated_at":"2026-05-15T23:01:09.935964Z","_minecraft_date_created":"2026-03-24T22:41:07.320142Z","_minecraft_date_modified":"2026-03-23T11:57:20.520248Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/worldgit","_minecraft_icon_attachment_id":171538,"_minecraft_imported_at":"2026-06-09T21:30:10+00:00","_minecraft_import_hash":"09c887de0531c47dcdd358268ad376c2","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[126,127,128,92],"mod_loader":[132,133],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-171537","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-management","mod_category-paper","mod_category-purpur","mod_category-utility","mod_loader-paper","mod_loader-purpur","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n– `\/wg abandon
\n– `\/wg list`
\n– `\/wg info
\n– `\/wg submit [id]`
\n– `\/wg confirm [id]`
\n– `\/wg forceedit [id]`
\n– `\/wg invite
\n– `\/wg uninvite
\n– `\/wg tp
\n– `\/wg return`<\/p>\n
\n– `\/wg review approve
\n– `\/wg review reject
\n– `\/wg admin close
\n– `\/wg admin assign
\n– `\/wg admin list [player]`
\n– `\/wg admin backup`
\n– `\/wg admin locks`
\n– `\/wg reload`<\/p>\n
\n– Right-click the book to open the main player menu.
\n– Branch cards now open a dedicated branch-detail chest UI.
\n– `Pos1` \/ `Pos2` support:
\n – Left click to use the current player coordinates
\n – Right click to open a sign input
\n – Coordinate syntax supports absolute values, `~`, `~+n`, and `~-n`
\n– Branch detail exposes:
\n – Teleport
\n – Rebase
\n – Conflict Center
\n – Submit for review
\n – Confirm merge
\n – Force edit
\n – Abandon branch
\n– Conflict Center exposes:
\n – Conflict-group list
\n – Accept mine
\n – Accept theirs
\n – Teleport for manual resolution
\n – Mark resolved
\n– Approved branches are merged through the final confirmation UI plus a sign-based merge message input.
\n– The paper item in the lower-left area opens paged merge history with:
\n – Builders
\n – Approver
\n – Merger
\n – Merge message
\n – `Pos1` \/ `Pos2`
\n – Teleport entry back to the branch world<\/p>\n
\n– `worldgit.branch.abandon`
\n– `worldgit.branch.list`
\n– `worldgit.branch.info`
\n– `worldgit.branch.submit`
\n– `worldgit.branch.confirm`
\n– `worldgit.branch.forceedit`
\n– `worldgit.branch.invite`
\n– `worldgit.branch.tp`
\n– `worldgit.branch.return`<\/p>\n
\n– `worldgit.admin.close`
\n– `worldgit.admin.assign`
\n– `worldgit.admin.list`
\n– `worldgit.admin.backup`
\n– `worldgit.admin.locks`
\n– `worldgit.admin.reload`
\n– `worldgit.admin.bypass`<\/p>\n
\n– Technically, this is **not** full Git commit-history rewriting.
\n– It is a **region-scoped three-way replay** of the branch world onto the latest main-world revision:
\n – `base`: snapshot captured when the branch was created or last rebased
\n – `ours`: current branch-world blocks
\n – `theirs`: latest main-world blocks
\n– In user-facing docs and UI, the clearest wording is: **Rebase (sync to latest main world)**.<\/p>\n
\n2. Select a cuboid region with WorldEdit.
\n3. Run `\/wg create`.
\n4. Edit inside the generated branch world.<\/p>\n
\n2. If the main world has overlapping updates since your base revision, the branch is marked stale.
\n3. Click **Rebase** to replay your region onto the latest main-world revision.
\n4. If auto-merge is possible, the branch becomes clean immediately.
\n5. If conflicts remain, open **Conflict Center**.
\n6. Resolve each conflict group with:
\n – `mine`
\n – `theirs`
\n – manual fix in-world, then mark resolved
\n7. Once all conflict groups are resolved, the branch becomes clean again.<\/p>\n
\n2. If the branch is stale, submission is rejected until it is rebased.
\n3. An admin reviews the branch.
\n4. Once approved, the branch becomes read-only.
\n5. If you want to keep editing after approval, run `\/wg forceedit [id]` first.
\n6. After editing again, re-submit the branch for a fresh review.
\n7. If the main world changes after approval but before merge, the approval is revoked automatically.
\n8. Rebase the branch again, resolve conflicts if needed, and submit for re-review.
\n9. If the branch is still current, run `\/wg confirm [id]`, enter a merge message, and merge it back into the main world.<\/p>\n
\n– Block break
\n– Bucket empty\/fill
\n– Bone meal and fertilization updates
\n– Fluid and block-state changes such as spread, fade, form, and flow
\n– Pistons
\n– Explosions including TNT and fireball-style explosions
\n– Hanging entities such as paintings and item frames
\n– Armor stand manipulation and damage
\n– Spawn eggs, dispenser-fired spawn eggs, and egg hatching into chicks
\n– Natural creature and monster spawning, spawners, and trial spawners
\n– Patrol, raid, reinforcement, and similar hostile mob spawns
\n– Entering the Nether or the End from the main world<\/p>\n
\n2. Install `WorldEdit`, `Multiverse-Core`, and `WorldGit`.
\n3. Confirm all three plugins load without errors.
\n4. Confirm the main world name matches `config.yml`.<\/p>\n
\n2. Select a small cuboid region in the main world.
\n3. Run `\/wg create`.
\n4. Verify:
\n – A branch record exists in SQLite
\n – A branch world named like `wg_
\n – The selected blocks were copied correctly
\n – A base snapshot exists for the branch
\n – The branch stores a base revision<\/p>\n
\n2. Try buckets, bone meal, item frames, and armor stands in the main world.
\n3. Verify all changes are blocked unless the player has
\n `worldgit.admin.bypass`.<\/p>\n
\n2. Let player A edit and merge first.
\n3. On player B, run `\/wg submit`.
\n4. Verify submission is rejected and the branch is marked stale.
\n5. Use the branch-detail UI to run **Rebase**.
\n6. If conflicts appear, verify Conflict Center can:
\n – list groups
\n – accept mine
\n – accept theirs
\n – teleport for manual repair
\n – mark a group resolved
\n7. After the branch is clean, submit it again.
\n8. Approve with `\/wg review approve
\n9. Before merging, let another overlapping branch update the main world again.
\n10. Run `\/wg confirm
\n11. Verify the approval is revoked automatically and the branch must be rebased and re-reviewed.
\n12. Complete the second rebase and submit again.
\n13. Approve once more, then merge.
\n14. Verify:
\n – Players are moved out safely
\n – Blocks are merged into the main world
\n – A short-lived merge lock is created and released
\n – A world commit entry is recorded
\n – The branch world is unloaded after merge and can be reopened from merge history if needed
\n – The branch is marked `MERGED`
\n – Merge history shows builders, approver, merger, merge message, and region coordinates<\/p>\n
\n2. Stop the server during the merge or rebase process.
\n3. Restart the server.
\n4. Verify incomplete merge and rebase state is recovered cleanly.<\/p>\n
\n2. Verify a backup appears under the configured backup directory.
\n3. If scheduled backups are enabled, verify old backups are pruned.<\/p>\n
\n– No automated unit tests are included yet.
\n– Runtime validation should still be done on a real Paper 1.21.11 server with
\n WorldEdit and Multiverse-Core installed.<\/p>\n","protected":false},"excerpt":{"rendered":"