Finish biome rewards: author island unlocks, add nether-biome dimension restriction, and land permission-independence

[minoneer]

Summary: Biome painting works on feature/immutable-challenge-catalog, but the biome-reward feature is unfinished: nether biomes can be painted in the overworld (no dimension guard), the catalog still grants biomes through legacy usb.biome.* permission rewards instead of the new island-scoped BiomeReward, and the permission-independence work sits on an unmerged branch.

Why this blocks 4.0

The 4.0 readiness survey flags biome unlocking as a first-class challenge reward (#145), and the plumbing is mostly in place — IslandBiomeUnlocks, the BiomeReward reward action, and a YAML type: biome parser all exist. But the shipping catalog never actually uses any of it: every biome grant in challenges.yml is still a raw permission: usb.biome.<key> reward, so islands cannot earn biomes without an external permissions plugin, and the new island-derived unlock path is dead. On top of that, /is biome will happily paint a nether biome into the overworld skyblock world because there is no dimension restriction anywhere in the paint path. These are correctness/feature gaps that make biome rewards effectively non-functional for a stock 4.0 install.

Current state

• Painting itself works: SetBiomeTask.execute() calls world.setBiome(x, y, z, biome) (uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/island/task/SetBiomeTask.java:82), and BiomeCommand dispatches it against player.getWorld() (uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/command/island/BiomeCommand.java:136).
• The biome catalog defines 18 biomes, each resolved against the live registry via Registry.BIOME.match(biomeKey), warning on unknown keys (uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/biome/BiomeConfig.java:70, warning at line 72). The list includes nether/end biomes — nether_wastes and the_end (uSkyBlock-Core/src/main/resources/biomes.yml).
• No dimension restriction exists. A git grep -niE "Environment|NETHER|getEnvironment" across .../biome/ and SetBiomeTask.java returns nothing, and BiomeCommand paints into player.getWorld() with no World.Environment.NETHER guard — so a nether biome can be applied in the overworld.
• The island-unlock infrastructure is present but unused by the catalog: the BiomeReward(List<String> biomes) reward action (uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/catalog/ChallengeRewards.java:38), the type: biome YAML parser branch (uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/catalog/yaml/ChallengeCatalogYamlParser.java:271), and IslandBiomeUnlocks which derives unlocks from completed challenges and gates /is biome via canUseBiome (uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/IslandBiomeUnlocks.java:65, called at BiomeCommand.java:94).
• But the shipped catalog still grants biomes the legacy way: challenges.yml contains only permission: usb.biome.<key> rewards (lines 786, 831, 968, 1068, 1121), covering just three distinct biomes — deep_ocean, flower_forest, swamp. There are zero type: biome rewards authored anywhere in src/main/resources.
• canUseBiome deliberately keeps the personal usb.biome.<key> permission as an OR-fallback alongside the island-earned unlock (IslandBiomeUnlocks.java:65-67), so permission-based grants are meant to coexist, not be the primary path.
• The permission-independence work is unmerged. Branch independent-biome-unlocking is a single commit ahead of the catalog branch — 65c2dc3b ("make biome unlocking independent of an installed permissions plugin. Migrate legacy, permission-based unlocks.") — which adds general_defaultUnlockedBiomes to Settings.java (with a Registry.BIOME.match validation pass and a usb.biome. prefix strip) plus config/plugin.yml and PlayerInfo migration logic.

Scope

• Add a dimension restriction so nether/end biomes cannot be painted into the overworld skyblock world (and vice versa). Decide and enforce the rule in BiomeCommand and/or SetBiomeTask based on World.Environment / the target biome's dimension, rejecting mismatches with a localized error.
• Author the full set of biome rewards against real registered biome keys. Convert the legacy permission: usb.biome.<key> grants in challenges.yml to the island-scoped type: biome reward (or confirm the intended coexistence) and cover the intended biomes from biomes.yml, not just the current three.
• Validate every authored biome key resolves via Registry.BIOME.match at load (it already warns; ensure authored keys produce no warnings on a stock server).
• Integrate the single unmerged commit 65c2dc3b from independent-biome-unlocking (default-unlocked-biomes setting + legacy permission migration) into the 4.0 line, resolving any overlap with the existing default-unlocked-biomes path on the catalog branch (RuntimeConfig.Biomes#defaultUnlocked(), consumed in IslandBiomeUnlocks.unlockedBiomes() at IslandBiomeUnlocks.java:42).
• Verify the end-to-end flow on a stock install with no permissions plugin: completing a challenge that rewards a biome makes /is biome <key> succeed, and resetting the island removes the unlock.
• Confirm the usb.biome.<key> OR-fallback in canUseBiome still works for donor ranks/ops after migration.

References

• Related: Island-scoped biome unlocking as a first-class challenge reward (4.0) #145 (Island-scoped biome unlocking as a first-class challenge reward — do not duplicate).
• Design draft: docs/challenge-redesign/uskyblock-v2-challenge-redesign.md (currently untracked / do-not-commit).
• Unmerged work: branch independent-biome-unlocking, commit 65c2dc3b. Note also branch fix/biome-permission-nodes exists and may overlap.
• Key files: uSkyBlock-Core/src/main/resources/biomes.yml, uSkyBlock-Core/src/main/resources/challenges.yml, .../island/task/SetBiomeTask.java, .../command/island/BiomeCommand.java, .../biome/BiomeConfig.java, .../challenge/IslandBiomeUnlocks.java, .../challenge/catalog/ChallengeRewards.java, .../challenge/catalog/yaml/ChallengeCatalogYamlParser.java.

Category: gameplay-world-code · Effort: medium · Source: 4.0 readiness survey.