Mass-conservation audit and mechanical currency/XP assignment for 4.0 challenges

[minoneer]

Summary: Before the 4.0 catalog is authored, every challenge hand-in must pass a mass-conservation audit (no challenge may consume non-renewable items, and every bootstrap singleton needs a second designed source) and every challenge's currency/XP must be assigned mechanically and uniformly — while honoring two hard engine constraints: hand-in consumption is a single whole-challenge boolean (no per-item take flag), and a repeatable challenge with no inventory hand-in is silently un-repeatable.

Why this blocks 4.0

The 4.0 readiness survey flags resource conservation as a correctness blocker: on SkyBlock the only items that exist are the ones the catalog injects, so a challenge that consumes a non-renewable item (or an item with no renewable source) can strand a player permanently. The new engine consumes the entire hand-in by default — ChallengeCatalogYamlParser defaults consumeItemsOnCompletion to true — and the current draft catalog already ships repeatable challenges that take non-renewables on every completion (e.g. nethermining takes 64 netherrack + 32 quartz; see challenges.yml). Currency/XP are currently hand-tuned per challenge rather than assigned by a uniform, auditable rule, and the engine's repeat gate will silently turn any repeatable challenge without an item hand-in into a one-shot, so authoring must be done against these constraints rather than discovered after the fact.

Current state (on feature/immutable-challenge-catalog)

• Hand-in consumption is a single whole-challenge flag, not per-item. ChallengeProperties is record ChallengeProperties(boolean consumeItemsOnCompletion) — uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/catalog/ChallengeProperties.java:3.
• The flag defaults to true (items are consumed unless explicitly disabled): uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/catalog/yaml/ChallengeCatalogYamlParser.java:237 (section.getBoolean("consumeItemsOnCompletion", true)), and the legacy takeItems flag maps onto it in uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/catalog/bootstrap/LegacyChallengeCatalogImporter.java:248.
• The executor silently blocks a repeat when a challenge is not repeatable or has no inventory hand-in: uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/ChallengeExecutor.java:182 (!challenge.repeatPolicy().repeatable() || !hasInventoryHandIn(challenge)), with the helper at ChallengeExecutor.java:479.
• A validator WARN backs this up: uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/catalog/ChallengeCatalogValidator.java:51 checks the condition and emits "Repeatable challenge has no inventory hand-in requirement" at ChallengeCatalogValidator.java:52 (helper hasNoInventoryHandIn at ChallengeCatalogValidator.java:102).
• Currency and XP are first-class reward actions: EconomyReward(int amount) and ExperienceReward(int amount) in uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/catalog/ChallengeRewards.java:22 and :25.
• Currency is hidden/skipped when the economy is disabled, XP is always granted: in uSkyBlock-Core/src/main/java/us/talabrek/ultimateskyblock/challenge/RewardApplier.java, grantCurrency early-returns unless enableEconomyRewards() is set (RewardApplier.java:133) and the deposit is further guarded by getEconomyHook().ifPresent(...) (RewardApplier.java:139), whereas grantExperience grants whenever amount > 0 with no economy gate.
• The draft catalog still violates the conservation policy: nethermining is a repeatable hand-in of netherrack:64, quartz:32, etc. with no consumeItemsOnCompletion: false, so it consumes non-renewables on every completion (uSkyBlock-Core/src/main/resources/challenges.yml:614). The design draft's own "remaining work" list calls out non-renewable resource recalculation, a repeatable diamond source, a glow-lichen source, and a polish pass over currency/XP values.

Scope

• Audit every challenge hand-in (requiredItems) in challenges.yml and flag any that consume a non-renewable item (netherrack, nether quartz, and any item lacking a renewable/barterable source on SkyBlock).
• Redesign each offending hand-in to renewable/barterable items, or — where the take is intentional and the item is renewable — leave it; the nethermining netherrack/quartz hand-in specifically must be moved off non-renewables, as must any netherrack-consuming nether-cultivation challenges introduced from the design draft (e.g. nethergardener and warpedharvest).
• For each bootstrap singleton injected exactly once (lava bucket, crimson/warped fungus, spawn eggs, elytra, plus draft-noted gaps like glow lichen and raw diamonds), confirm a second, repeatable designed source exists or add one.
• Verify no challenge sets consumeItemsOnCompletion: false expecting per-item retention — the flag is whole-challenge only; split into separate challenges if some items must be kept and others taken.
• Verify every repeatable challenge carries at least one requiredItems (inventory hand-in) so the executor repeat gate and validator do not silently demote it to one-shot; resolve all ChallengeCatalogValidator WARNs.
• Assign currency and XP to all challenges per the draft policy: first completion = tier × 10, repeat = half, applied mechanically/uniformly so the values are auditable rather than hand-tuned.
• Confirm via the catalog validator/diagnostics that the authored catalog loads with zero conservation- or repeat-related warnings.

References

• Related: 4.0 gameplay changes: level progression, scoring, and challenges #128 (4.0 gameplay changes). Depends on the challenges.yml authoring issue.
• Design draft: docs/challenge-redesign/uskyblock-v2-challenge-redesign.md (currently untracked / do-not-commit) — see the "Currency and XP rewards" section and the "remaining design work" note (non-renewable resource recalculation, repeatable diamond source, glow-lichen source, currency/XP values).
• Engine constraints: ChallengeProperties.java:3, ChallengeCatalogYamlParser.java:237, ChallengeExecutor.java:182/:479, ChallengeCatalogValidator.java:51/:52/:102.
• Reward mechanics: ChallengeRewards.java:22/:25, RewardApplier.java (grantCurrency at :133/:139, grantExperience at :124).
• Offending content example: uSkyBlock-Core/src/main/resources/challenges.yml:614 (nethermining).

Category: content-data · Effort: medium · Source: 4.0 readiness survey.