Cycle default home icons through item variants so homes are visually distinct

[milanmalhotra]

Idea

Every home created without an explicit icon gets the same white wool, so a player with eight homes has eight identical items in the menu and has to read the names to tell them apart.

Cycle through variants of the default item instead, so consecutive homes are visually distinct without anyone having to pick an icon:

• first home: white wool
• second: light grey wool
• third: grey wool
• and so on through the family

Proposed config key defaultHomeItemVariants, boolean, default true. When true, and when the configured defaultHomeItem belongs to a family that has variants, the icon becomes the next variant in that family. When false, or when the item has no variants, behaviour is exactly as today.

Families with variants: wool, beds, logs, planks, stairs, slabs, concrete, terracotta, glazed terracotta, candles, shulker boxes, and more. Items with none: compass, gold ingot, cauldron, crafting table.

Design questions to settle first

1. Where does the variant list come from? Minecraft has no runtime API for "other colours of this block", so it has to be derived. Two options, and this is the main decision in the issue:

   • Hardcode the families. Precise, readable, and needs a line adding whenever Mojang adds a colour or a wood type.
   • Derive from Material name suffixes, for example everything ending _WOOL. Self maintaining across versions, but fragile: SOUL_LANTERN is not a lantern variant of anything useful, and dyed families are not all named consistently.

   A hybrid is probably right: derive by suffix, with an explicit allow list of family suffixes so nothing unexpected is swept in.

2. What is "next"? Per player, presumably, counting that player's existing homes. But homes get deleted, so a naive count reuses colours. Counting is also not stable if a home is renamed or moved. Options: store the variant index on the home, or pick the first variant in the family not already used by that player, falling back to cycling once they are all taken.

   Picking the first unused variant is probably the best behaviour and needs no schema change, since the icon is already stored per home.

3. What happens to defaultHomeItem: chest? Chest has no variants, so nothing changes. Worth stating in the config comment so the setting does not look broken.

4. Interaction with the icon in the creation reply. The reply already names the icon it chose. With variants on, that becomes genuinely useful, since the player did not choose it.

5. Non-item variants. Any derived family has to be filtered by Material.isItem(). Storing a non-item material as an icon makes HomesGui throw when it builds the ItemStack, which is a bug this project has already hit once. CreateHome.defaultHomeItem() has the guard for the configured value; the variant picker needs the same one.

Acceptance criteria

• defaultHomeItemVariants documented in default-config.yml and the README, default true.
• With it true, consecutive homes created with no icon get different variants of the configured default.
• With it false, every such home gets the configured default, exactly as today.
• An item with no variants is unaffected either way.
• A variant that is not an item can never be selected.
• Deleting a home and creating another does not produce two homes with the same icon while unused variants remain.
• Unit tested, including the no-variant case and the all-variants-used case.

Notes

Raised from the manual in-game test pass for the v1 parity and permission config work.