Migration of claims data

[Thodor12]

Checklist

• I have read and accept the Contributing Guidelines
• I have tested and confirmed my changes are working on the most recent commit of this pull request

• I have used AI in the creation of this pull request
  • Primarily to audit my own changes and check the codebase if everything was correctly wired up/cleaned up
  • Define implementation criteria
  • Setup a testing plan
  • And no even though this PR text is going to be long AI did not write it, I hand wrote it 😄

Changes proposed in this pull request

• Chunk ownership moved from a separate capability to the existing manager capability.
• The manager capability contains a Map<Integer, Map<Long, ClaimInfo>> that will hold, per colony, per chunk, a ClaimInfo object that will define how this chunk was claimed.
• Chunk owning logic has been severely reduced (almost completely), because colonies can now easily query directly through the IColonyManager, whether a chunk is actually claimed or not, and by whom. Not having to rely on querying a LevelChunk capability anymore.
• Introduced a new debugging command that can show the claim status of a colony, list all the chunks the colony owns, which were force claimed, which are initial (center) claims, how many buildings claim this chunk. But also how many chunks are eligible for force loading, which ones are actually force loaded, and which chunks are actually loaded in the world.

Why this change

Most important reason, ease of querying data, previously it was impossible to know what a colony actually claims. Both Journeymap and my Bluemap addon have this issue. Journeymap solved it by a construction that required people to go through chunks and then go through a bunch of different network messages to synchronize the state of the chunk. Bluemap simply doesn't know at all and relied solely on building claims radii to calculate the claims.

Now that the colony manager stores this information in a map separated per colony, it's super easy to query this information with no effort at all. Meaning that both Journeymap and Bluemap can simply query this map for each colony, write the appropriate polygons, and be done with it.

This means that even the logic in either of these addons can be severely reduced, another bonus.

Testing

I validated all the logic of the claiming still works. If you want to see everything that I verified, you can see this file:
CLAIM_REFACTOR_TEST_PLAN.md

Migration

This is the only pain point in this process, there are 2 unfixable issues with this.

There is no way to directly hoist over the claim data, this is because the old capability is lost (even if I kept it, there's no clean way to hoist the data over to the new capability).
Due to this, upon first load, we have to call the same thing that the BackupHelper does, reclaimChunks. This sets up the initial colony claim, and claims and chunks that each building is supposed to have.

Unfortunately, there are 2 problems with this approach:

• Prior forced claimed chunks through the command are lost. Since there's no building claiming them, they are not brought back.
  • Remedy: Manually re-claim any lost chunks if no building claimed them after the force claim.
• Claim order is lost, if colony 1 is created first. Then colony 2, both of them have the initial claim area. If I then build a guardtower in colony 2, that guard tower nicely wraps around colony 2 its border. However after the migration, I first rebuild all of colony 1 its borders, then colony 2, etc. This now means that colony 2 wraps around colony 1, instead of the other way around. This is because the whole claim system doesn't use dates, it uses map insertion order. Whoever comes first is served first. Note: This is only an issue for colonies that actually border eachother, regular colonies are not impacted by this
  • Remedy: Force claim any chunks in that were lost by the later loaded colony, trigger a repair on all buildings in the area so that building claims on the chunks are properly set back. Then force unclaim the chunks again. The chunks are then not force claimed, solely claimed by the building.

The latter also means there is 1 deviation with the original code. You can no longer command unclaim chunks. The claim info only retains whether the chunk was forcefully claimed, making is ineligible for chunk cleanup if buildings are removed.
So if you force claim a chunk, then build something on it, then try to unclaim it, won't work, because a building is there, the chunk is claimed no matter if you want it or not.

Review please

[Thodor12]

@uecasm I want you to look at this PR too since it also affects Journeymap

[someaddons]

erm if we do it you should port the existing system that literally does this in 1.21.1, not introduce a new one that differs from it creating conflcits

[Thodor12]

The system in 1.21 has some of the identical problems that this PR still solves, mainly where the data lives, in there it's still not possible to fetch all claims of a colony in an O(1) way.

I am considering actually updating 1.21 with the same structure as this, should be somewhat easier to port over so it uses the same classes there, and there I can probably do it without the 2 issues that this PR will have.

[someaddons]

why do we need to fetch all claims in O(1)?

[Thodor12]

For Journeymap and Bluemap, if we have 1 Map of only chunkpos it's hard to fetch all chunks because you have to iterate an enormous list of items. Just a basic colony is 121 map entries already. So imagine how long that iteration would take in a fleshed out world

[Raycoms]

I think a cache with colony ID to claimy reference in top of the 1.21 system is probably the easiest. But I agree that the pr should be first in top of the 1.21 system https://proton.me/mail/home

…

-------- Original Message --------

On Sunday, 08/16/26 at 17:24 Thom van den Akker ***@***.***> wrote: Thodor12 left a comment [(ldtteam/minecolonies#11788)](#11788 (comment)) For Journeymap and Bluemap, if we have 1 Map of only chunkpos it's hard to fetch all chunks because you have to iterate an enormous list of items. Just a basic colony is 121 map entries already. So imagine how long that iteration would take in a fleshed out world — Reply to this email directly, [view it on GitHub](#11788?email_source=notifications&email_token=ABRD3SZBA344KGQ6DDIOGU35KF4TRA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMZQGY3TGMZTHEYKM4TFMFZW63VQOJSXM2LFO5PXEZLROVSXG5DFMSSWK5TFNZ2KYZTPN52GK4S7MNWGSY3L#issuecomment-5306733390), or [unsubscribe](https://github.com/notifications/unsubscribe-auth/ABRD3S56GKFO7UNFR7OMYST5KF4TRAVCNFSNUABEKJSXA33TNF2G64TZHM3DKNRRGY3TMMB3JFZXG5LFHM2TCNRQGMZDGNZVG2QXMAQ). Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for [iOS](https://github.com/notifications/mobile/ios/ABRD3S6DDFQAPA5NGD5QROD5KF4TRA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMZQGY3TGMZTHEYKM4TFMFZW63VQOJSXM2LFO5PXEZLROVSXG5DFMSSWK5TFNZ2KUZTPN52GK4S7NFXXG) and [Android](https://github.com/notifications/mobile/android/ABRD3S6MKMH2DGMZJ5NVCKL5KF4TRA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMZQGY3TGMZTHEYKM4TFMFZW63VQOJSXM2LFO5PXEZLROVSXG5DFMSSWK5TFNZ2K4ZTPN52GK4S7MFXGI4TPNFSA). Download it today! You are receiving this because your review was requested.Message ID: ***@***.***>

[Thodor12]

But then what about the bugs that this still solves, plus the unnecessary old infrastructure. All of the network stuff was never removed from 1.21 either, despite being basically useless

[Raycoms]

Makes more sense to solve on 1.21 first then too. Would be weird the other way around given 1.21 has the newer better version

[someaddons]

what bugs?

[Thodor12]

Bugs maybe was the wrong word. There are problematic points of code because the claim data isn't centrally managed on 1.21, that opens the door to mismanaging data. Also there's no recovery for that.

Basically, each colony in 1.21 controls its own claim list, this means that it's way too easy for a colony (or faulty addon) to assume they can insert a claim directly in there and be done with it. That's exactly where the colony manager comes into play, because you have to route your claim request through the colony manager.
The colony manager is then responsible for checking if the request to claim is then valid.

I think this does still happen in 1.21, so it's not a direct issue, but by not centralizing the storage into 1 place individual data can be written in a wrongful way.
I remedied that by giving the colony manager capability the sole control over the claim list. That's the equivalent in 1.21 of putting it on the level data (basically where the actual colony list NBT lives).

That way each claim request MUST go through the manager, and there's no other way to go through it. The claims technically live per colony but because they are stored in 1 and the same place, it's impossible for individual colonies (or addon code) to faultily be able to claim something they shouldn't have access to.