Package com.enhancedechest.gui.dialog

Class IconCatalog

java.lang.Object
com.enhancedechest.gui.dialog.IconCatalog
public final class IconCatalog extends Object
Catalog of pickable chest icons, backed by the server's Material registry, plus helpers to render a chosen icon as an Adventure sprite object component — the icon shown inside Dialog action buttons (since 1.21.9 / Adventure 4.25.0, no resource pack required).

Atlases. A sprite object draws one stitched texture from a named atlas. Vanilla splits these: block textures live in minecraft:blocks under block/<id>, item textures in minecraft:items under item/<id>. The icon a material shows in the inventory is its item texture when one exists (e.g. doors, boats), otherwise its block texture (e.g. planks). Many derived blocks (slabs, stairs, fences, walls, signs, …) have no flat texture at all — they are drawn from a block model — so they cannot be a sprite and are simply not offered as icons.

No missing-texture boxes. The exact set of flat textures that exist in the client is bundled at icons/valid-icon-sprites.txt (generated from the client jar). A material is only catalogued, and a stored icon only rendered, when its resolved sprite is in that set — so the picker never shows a purple/black missing-texture sprite.

Performance. The valid-sprite set and the full, name-sorted catalog (~2k entries, each with a precomputed display name, lower-cased search name and a reusable sprite Component) are built once, lazily, and cached immutably. Building any picker page is then just a sub-list — no Material scan and no component allocation per render. Stored-icon sprites are memoized by key too.

Client-locale search. search(String, Locale) also matches a query against the item's localized name for the viewer's client locale, e.g. a Vietnamese client can type "kim cương" and still find Diamond. This only works for locales with a bundled name table at icons/lang/<locale>.json (lowercase Minecraft locale id, e.g. en_us.json, vi_vn.json) — currently just the two locales this plugin's own messages support. For any other client locale, search silently falls back to the English name only (the label itself still renders correctly via Component.translatable(), regardless of whether search covers it — see IconCatalog.Entry.name()). Each table is generated once from Mojang's official assets/minecraft/lang/<locale>.json, filtered down to just item.minecraft.* / block.minecraft.* keys. To add another locale: fetch that file (via the version manifest → asset index → resources.download.minecraft.net, or extract en_us.json straight out of the client jar, since it alone ships inside the jar rather than as a separate asset object), filter it the same way, and drop it in as icons/lang/<locale>.json — no code change needed. See docs/ for the full runbook.

Server-owner override, no rebuild needed. setExternalLangDir(java.nio.file.Path, org.slf4j.Logger) points the catalog at plugins/EnhancedEchest/icons/lang/ (wired once from EnhancedEchestPlugin#onEnable); a same-named file dropped there is preferred over the bundled classpath resource, so an admin can add a locale this plugin doesn't ship, or override/fix a bundled one, purely by dropping a JSON file in while the server is running — no plugin update required. Per-locale results are cached after first lookup (like the bundled path), so a file added or edited after the server started only takes effect once reloadLocaleNames() is called, which /ee reload does automatically.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final record 
    IconCatalog.Entry
    One pickable icon: a material with its precomputed display name, reusable sprite component, and a translatable name component.

  • Method Summary

    Modifier and Type
    Method
    Description
    static List<IconCatalog.Entry>
    all()
    Lazily builds and returns the immutable, name-sorted list of pickable icons.
    static @Nullable org.bukkit.inventory.ItemStack
    item(@Nullable String materialKey)
    A real item icon for the detail-dialog body, or null if the key is null/unknown/not an item.
    static @Nullable org.bukkit.Material
    material(@Nullable String materialKey)
    Resolves a material key string (e.g.
    static void
    reloadLocaleNames()
    Drops every cached locale-name table so the next search re-reads from disk/classpath, picking up any file added or edited since the server started.
    static List<IconCatalog.Entry>
    search(@Nullable String query, @Nullable Locale viewerLocale)
    Filters the catalog by a case-insensitive substring, matched against the server-derived English name and — when a bundled lang table exists for viewerLocale — the item's client-localized name too (blank query = full list).
    static void
    setExternalLangDir(Path dir, org.slf4j.Logger logger)
    Points locale-name lookups at an on-disk override directory (an admin/dev drop-in folder), checked before the bundled classpath resource for each locale.
    static @Nullable net.kyori.adventure.text.Component
    sprite(@Nullable String materialKey)
    Sprite object component for a stored icon key, or null if the key is null/unknown/unrenderable.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • setExternalLangDir

      public static void setExternalLangDir(Path dir, org.slf4j.Logger logger)
      Points locale-name lookups at an on-disk override directory (an admin/dev drop-in folder), checked before the bundled classpath resource for each locale. Called once from EnhancedEchestPlugin#onEnable with plugins/EnhancedEchest/icons/lang/; the directory itself need not exist yet, it's only touched lazily on the first search that needs a given locale.

    • reloadLocaleNames

      public static void reloadLocaleNames()
      Drops every cached locale-name table so the next search re-reads from disk/classpath, picking up any file added or edited since the server started. Cheap to call (no work happens until a search actually needs a locale again) — wired into /ee reload.

    • all

      public static List<IconCatalog.Entry> all()
      Lazily builds and returns the immutable, name-sorted list of pickable icons.

    • search

      public static List<IconCatalog.Entry> search(@Nullable @Nullable String query, @Nullable @Nullable Locale viewerLocale)
      Filters the catalog by a case-insensitive substring, matched against the server-derived English name and — when a bundled lang table exists for viewerLocale — the item's client-localized name too (blank query = full list). viewerLocale may be null (no localized matching, same as the old English-only behavior).

    • sprite

      @Nullable public static @Nullable net.kyori.adventure.text.Component sprite(@Nullable @Nullable String materialKey)
      Sprite object component for a stored icon key, or null if the key is null/unknown/unrenderable.

    • item

      @Nullable public static @Nullable org.bukkit.inventory.ItemStack item(@Nullable @Nullable String materialKey)
      A real item icon for the detail-dialog body, or null if the key is null/unknown/not an item.

    • material

      @Nullable public static @Nullable org.bukkit.Material material(@Nullable @Nullable String materialKey)
      Resolves a material key string (e.g. minecraft:diamond) to a Material, or null.