feat(command): add /vshop appearance

Command-only control over how a shop renders, as requested — no Dialog UI.
`/vshop appearance <id> npc [skin]` is the headline: one call switches a shop to
a PLAYER NPC, defaulting to the owner's own skin.

    show | npc [skin] | villager | type <entity> | skin <name|@none> [slim]
    glow <bool> [color] | scale <n> | equip <slot> [none]
    attribute <name> <value|@none> | reset

ShopAppearanceService is the write path: mutate, persist, re-render, keeping the
row, the registry and the thing standing in the world in step. It renders
through an async hop because skin resolution blocks its caller — the new
ShopEntityBackend#prepare hook does that warm-up off-thread, and the integration
now reuses it for boot instead of its own bespoke pass. Success messages fire
from the render callback, so "updated" means visibly updated.

An appearance mutated back to all-defaults deletes its row rather than storing a
no-op, which keeps "no row means plain Villager" true.

Guard rails: NPC-only knobs report that FancyNpcs is unavailable instead of
silently storing settings nothing will apply; entity types can be restricted by
fancynpcs.allowedTypes and scale by fancynpcs.maxScale, both bypassed by
modernvillagershop.admin.appearance; and URL skins pull an arbitrary remote
image through the server, so they sit behind their own permission. `show` is
read-only and therefore console-friendly.

Locale keys added to both messages_ja.yml and messages_en.yml, including
enum.shop-entity-kind.* and enum.skin-variant.*, with both enums registered in
EnumLabelsTest so a future constant cannot ship untranslated.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: f0reachARR

src/main/java/me/f0reach/vshop/ModernVillagerShopPlugin.java

@@ -14,6 +14,7 @@
 import me.f0reach.vshop.shop.ShopService;
 import me.f0reach.vshop.shop.VillagerTeleportGuard;
 import me.f0reach.vshop.shop.entity.ShopAppearanceRegistry;
+import me.f0reach.vshop.shop.entity.ShopAppearanceService;
 import me.f0reach.vshop.shop.entity.ShopDisplayName;
 import me.f0reach.vshop.shop.entity.ShopEntityBackend;
 import me.f0reach.vshop.shop.entity.ShopEntityIntegration;
@@ -67,6 +68,7 @@ public final class ModernVillagerShopPlugin extends JavaPlugin {
     private VillagerBackend villagerBackend;
     private ShopEntityService shopEntities;
     private ShopTargeting shopTargeting;
+    private ShopAppearanceService shopAppearanceService;
     private ShopInteractionRouter interactionRouter;
     private ShopEntityIntegration npcIntegration;
     private DialogService dialogService;
@@ -134,6 +136,8 @@ public void onEnable() {
         this.shopEntities = new ShopEntityService(villagerBackend, shopAppearances, npcBackend);
         this.shopTargeting = new ShopTargeting(registry, shopEntities);
         this.shopService = new ShopService(storage, registry, shopEntities, config);
+        this.shopAppearanceService = new ShopAppearanceService(this, storage.appearance(),
+                shopAppearances, shopEntities, shopService);
         this.eggFactory = new SpawnEggFactory(this, messages);
         this.dialogService = new DialogService(this);
         this.iconConfig = new IconConfig(messages, config);
@@ -265,6 +269,9 @@ public void reloadConfigInternal() {
     public ShopEntityService shopEntities() { return shopEntities; }
     public ShopAppearanceRegistry shopAppearances() { return shopAppearances; }
     public ShopTargeting shopTargeting() { return shopTargeting; }
+    public ShopAppearanceService shopAppearanceService() { return shopAppearanceService; }
+    /** Whether NPC-backed shops can actually be rendered right now. */
+    public boolean hasNpcIntegration() { return npcIntegration != null; }
     public ShopDisplayName shopDisplayName() { return shopDisplayName; }
     public DialogService dialogService() { return dialogService; }
     public ShopBrowseUi browseUi() { return browseUi; }

src/main/java/me/f0reach/vshop/command/VShopCommand.java

@@ -6,6 +6,7 @@
 import me.f0reach.vshop.ModernVillagerShopPlugin;
 import me.f0reach.vshop.command.sub.AdminExportSlotsCommand;
 import me.f0reach.vshop.command.sub.AdminImportSlotsCommand;
+import me.f0reach.vshop.command.sub.AppearanceCommand;
 import me.f0reach.vshop.command.sub.CoOwnerCommand;
 import me.f0reach.vshop.command.sub.EditCommand;
 import me.f0reach.vshop.command.sub.EggCommand;
@@ -33,6 +34,7 @@ public final class VShopCommand {
     private final ListCommand list;
     private final OpenCommand open;
     private final EditCommand edit;
+    private final AppearanceCommand appearance;
     private final CoOwnerCommand coowner;
     private final TransferCommand transfer;
     private final StatsCommand stats;
@@ -50,6 +52,7 @@ public VShopCommand(ModernVillagerShopPlugin plugin) {
         this.list = new ListCommand(support);
         this.open = new OpenCommand(support);
         this.edit = new EditCommand(support);
+        this.appearance = new AppearanceCommand(support);
         this.coowner = new CoOwnerCommand(support);
         this.transfer = new TransferCommand(support);
         this.stats = new StatsCommand(support);
@@ -69,6 +72,7 @@ public LiteralCommandNode<CommandSourceStack> build() {
                 .then(list.node())
                 .then(open.node())
                 .then(edit.node())
+                .then(appearance.node())
                 .then(coowner.node())
                 .then(transfer.node())
                 .then(stats.node())

src/main/java/me/f0reach/vshop/command/sub/AppearanceCommand.java

@@ -15,7 +15,7 @@ public final class HelpCommand {
 
     /** Display order; the text of each line lives in {@code command.help.<key>}. */
     private static final List<String> ENTRIES = List.of(
-            "list", "open", "edit", "coowner", "transfer", "stats",
+            "list", "open", "edit", "appearance", "coowner", "transfer", "stats",
             "search", "history", "egg", "migrate", "reload");
 
     private final CommandSupport support;

src/main/java/me/f0reach/vshop/command/sub/HelpCommand.java

@@ -97,7 +97,9 @@ public void reload(FileConfiguration cfg) {
         this.fancyNpcs = new FancyNpcsConfig(
                 cfg.getBoolean("fancynpcs.enabled", true),
                 cfg.getBoolean("fancynpcs.turnToPlayer", true),
-                (float) cfg.getDouble("fancynpcs.interactionCooldown", 0.0)
+                (float) cfg.getDouble("fancynpcs.interactionCooldown", 0.0),
+                (float) cfg.getDouble("fancynpcs.maxScale", 2.0),
+                List.copyOf(cfg.getStringList("fancynpcs.allowedTypes"))
         );
 
         this.playerCache = new PlayerCacheConfig(
@@ -197,7 +199,18 @@ public record VillagerLookConfig(boolean enabled, double radius) {}
      * plugin still has to be installed for NPC-backed shops to render at all.
      * {@code turnToPlayer} is the default for shops that have not overridden it.
      */
-    public record FancyNpcsConfig(boolean enabled, boolean turnToPlayer, float interactionCooldown) {}
+    public record FancyNpcsConfig(boolean enabled, boolean turnToPlayer, float interactionCooldown,
+                                  float maxScale, List<String> allowedTypes) {
+
+        /** Empty list = every entity type is allowed. Matching is case-insensitive on the enum name. */
+        public boolean allowsType(org.bukkit.entity.EntityType type) {
+            if (allowedTypes.isEmpty()) return true;
+            for (String allowed : allowedTypes) {
+                if (allowed.equalsIgnoreCase(type.name())) return true;
+            }
+            return false;
+        }
+    }
 
     public record PlayerCacheConfig(int maxEntries, PlayerCacheSort defaultSort, Duration textureTtl) {}
 }

src/main/java/me/f0reach/vshop/config/PluginConfig.java

@@ -122,6 +122,29 @@ void removeById(UUID shopId) {
         npc.removeForAll();
     }
 
+    @Override
+    public void prepare(ShopAppearance a) {
+        if (a.skin() == null) return;
+        EntityType type = a.entityType() == null ? EntityType.PLAYER : a.entityType();
+        if (type != EntityType.PLAYER) return;
+        try {
+            // Populates FancyNpcs' skin cache so the later setSkin() on the main
+            // thread is a hit rather than a ~0.7s round trip to Mojang.
+            FancyNpcsPlugin.get().getSkinManager().getByIdentifier(a.skin(), variantOf(a));
+        } catch (SkinLoadException ex) {
+            // Reported again with the shop id attached when the NPC is built.
+            plugin.getLogger().warning("Could not pre-load skin '" + a.skin() + "': " + ex.getReason());
+        } catch (RuntimeException ex) {
+            plugin.getLogger().warning("Skin pre-load failed for '" + a.skin() + "': " + ex);
+        }
+    }
+
+    private static SkinData.SkinVariant variantOf(ShopAppearance a) {
+        return a.skinVariant() == me.f0reach.vshop.model.SkinVariant.SLIM
+                ? SkinData.SkinVariant.SLIM
+                : SkinData.SkinVariant.AUTO;
+    }
+
     Npc find(UUID shopId) {
         return FancyNpcsPlugin.get().getNpcManager().getNpc(npcName(shopId));
     }
@@ -158,11 +181,8 @@ private void applySkin(NpcData data, ShopAppearance a, Shop shop) {
             data.setSkinData(null);
             return;
         }
-        SkinData.SkinVariant variant = a.skinVariant() == me.f0reach.vshop.model.SkinVariant.SLIM
-                ? SkinData.SkinVariant.SLIM
-                : SkinData.SkinVariant.AUTO;
         try {
-            data.setSkin(a.skin(), variant);
+            data.setSkin(a.skin(), variantOf(a));
         } catch (SkinLoadException ex) {
             plugin.getLogger().warning("Shop " + shop.id() + ": could not load skin '"
                     + a.skin() + "' (" + ex.getReason() + "); rendering without one");

src/main/java/me/f0reach/vshop/integration/fancynpcs/FancyNpcBackend.java

@@ -2,11 +2,8 @@
 
 import de.oliver.fancynpcs.api.FancyNpcsPlugin;
 import de.oliver.fancynpcs.api.events.NpcsLoadedEvent;
-import de.oliver.fancynpcs.api.skins.SkinData;
-import de.oliver.fancynpcs.api.skins.SkinLoadException;
 import me.f0reach.vshop.config.PluginConfig;
 import me.f0reach.vshop.model.Shop;
-import me.f0reach.vshop.model.ShopAppearance;
 import me.f0reach.vshop.model.ShopEntityKind;
 import me.f0reach.vshop.shop.ShopInteractionRouter;
 import me.f0reach.vshop.shop.ShopRegistry;
@@ -16,15 +13,12 @@
 import me.f0reach.vshop.shop.entity.ShopEntityIntegration;
 import org.bukkit.Bukkit;
 import org.bukkit.Location;
-import org.bukkit.entity.EntityType;
 import org.bukkit.event.EventHandler;
 import org.bukkit.event.Listener;
 import org.bukkit.plugin.Plugin;
 
 import java.util.ArrayList;
-import java.util.LinkedHashSet;
 import java.util.List;
-import java.util.Set;
 
 /**
  * Owns the FancyNpcs side of the plugin: the backend, the interaction listener,
@@ -92,45 +86,16 @@ private synchronized void spawnAll() {
         List<Shop> targets = npcBackedShops();
         if (targets.isEmpty()) return;
 
-        // Resolving a skin blocks the calling thread on a cache miss (~0.7s per
-        // unseen name against Mojang), so warm the cache off-thread first and
-        // only then build the NPCs, where the same lookups are a cache hit.
-        Set<SkinRequest> skins = new LinkedHashSet<>();
-        for (Shop shop : targets) {
-            ShopAppearance a = appearances.getOrDefault(shop.id());
-            EntityType type = a.entityType() == null ? EntityType.PLAYER : a.entityType();
-            if (a.skin() != null && type == EntityType.PLAYER) {
-                skins.add(new SkinRequest(a.skin(),
-                        a.skinVariant() == me.f0reach.vshop.model.SkinVariant.SLIM
-                                ? SkinData.SkinVariant.SLIM : SkinData.SkinVariant.AUTO));
-            }
-        }
-
-        if (skins.isEmpty()) {
-            spawnOnMain(targets);
-            return;
-        }
+        // Skin resolution blocks its caller on a cache miss, so warm every
+        // appearance off-thread and only then build the NPCs on the main thread.
         Bukkit.getScheduler().runTaskAsynchronously(plugin, () -> {
-            warmSkinCache(skins);
+            for (Shop shop : targets) {
+                backend.prepare(appearances.getOrDefault(shop.id()));
+            }
             Bukkit.getScheduler().runTask(plugin, () -> spawnOnMain(targets));
         });
     }
 
-    private void warmSkinCache(Set<SkinRequest> skins) {
-        var manager = FancyNpcsPlugin.get().getSkinManager();
-        for (SkinRequest request : skins) {
-            try {
-                manager.getByIdentifier(request.identifier(), request.variant());
-            } catch (SkinLoadException ex) {
-                // Reported again per shop by the backend, with the shop id attached.
-                plugin.getLogger().warning("Could not pre-load skin '" + request.identifier()
-                        + "': " + ex.getReason());
-            } catch (RuntimeException ex) {
-                plugin.getLogger().warning("Skin pre-load failed for '" + request.identifier() + "': " + ex);
-            }
-        }
-    }
-
     private void spawnOnMain(List<Shop> targets) {
         int created = 0;
         for (Shop shop : targets) {
@@ -157,5 +122,4 @@ private List<Shop> npcBackedShops() {
         return out;
     }
 
-    private record SkinRequest(String identifier, SkinData.SkinVariant variant) {}
 }

src/main/java/me/f0reach/vshop/integration/fancynpcs/FancyNpcsIntegration.java

@@ -0,0 +1,114 @@
+package me.f0reach.vshop.shop.entity;
+
+import me.f0reach.vshop.model.Shop;
+import me.f0reach.vshop.model.ShopAppearance;
+import me.f0reach.vshop.model.ShopEntityKind;
+import me.f0reach.vshop.shop.ShopService;
+import me.f0reach.vshop.storage.repo.ShopAppearanceRepository;
+import org.bukkit.Bukkit;
+import org.bukkit.plugin.Plugin;
+
+import java.sql.SQLException;
+import java.time.Instant;
+import java.util.UUID;
+import java.util.function.Consumer;
+import java.util.logging.Level;
+
+/**
+ * Write path for a shop's appearance: mutate, persist, re-render.
+ *
+ * <p>Callers describe the change and this keeps the three copies in step — the
+ * {@code shop_appearance} row, the in-memory {@link ShopAppearanceRegistry}, and
+ * whatever is standing in the world.
+ */
+public final class ShopAppearanceService {
+
+    private final Plugin plugin;
+    private final ShopAppearanceRepository repository;
+    private final ShopAppearanceRegistry registry;
+    private final ShopEntityService entities;
+    private final ShopService shops;
+
+    public ShopAppearanceService(Plugin plugin, ShopAppearanceRepository repository,
+                                 ShopAppearanceRegistry registry, ShopEntityService entities,
+                                 ShopService shops) {
+        this.plugin = plugin;
+        this.repository = repository;
+        this.registry = registry;
+        this.entities = entities;
+        this.shops = shops;
+    }
+
+    /** The shop's stored appearance, or the implicit Villager default. */
+    public ShopAppearance current(Shop shop) {
+        return registry.getOrDefault(shop.id());
+    }
+
+    /**
+     * Applies {@code mutation}, writes it through, and rebuilds the shop's
+     * representation. {@code onRendered} runs on the main thread once the change
+     * is actually visible — later than this call returns, because the render may
+     * need an off-thread skin lookup first.
+     *
+     * <p>An appearance mutated back to all-defaults deletes its row instead of
+     * storing a no-op, keeping "no row means plain Villager" true.
+     */
+    public void apply(Shop shop, Consumer<ShopAppearance> mutation, Runnable onRendered) throws SQLException {
+        ShopAppearance appearance = registry.find(shop.id())
+                .orElseGet(() -> ShopAppearance.defaultFor(shop.id()));
+        ShopEntityKind before = appearance.backend();
+
+        mutation.accept(appearance);
+        appearance.setUpdatedAt(Instant.now());
+
+        if (appearance.isDefault()) {
+            repository.delete(shop.id());
+            registry.remove(shop.id());
+        } else {
+            repository.upsert(appearance);
+            registry.put(appearance);
+        }
+
+        boolean backendChanged = before != registry.backendOf(shop.id());
+        Bukkit.getScheduler().runTaskAsynchronously(plugin, () -> {
+            entities.prepare(shop);
+            Bukkit.getScheduler().runTask(plugin, () -> {
+                render(shop, backendChanged);
+                if (onRendered != null) onRendered.run();
+            });
+        });
+    }
+
+    /** Drops every override and returns the shop to a plain Villager. */
+    public void reset(Shop shop, Runnable onRendered) throws SQLException {
+        apply(shop, appearance -> {
+            appearance.setBackend(ShopEntityKind.VILLAGER);
+            appearance.setEntityType(null);
+            appearance.setSkin(null);
+            appearance.setSkinVariant(null);
+            appearance.setGlowing(false);
+            appearance.setGlowColor(null);
+            appearance.setScale(null);
+            appearance.setTurnToPlayer(null);
+            appearance.attributes().clear();
+            appearance.equipment().clear();
+        }, onRendered);
+    }
+
+    private void render(Shop shop, boolean backendChanged) {
+        if (!backendChanged) {
+            entities.refresh(shop);
+            return;
+        }
+        // The old representation belongs to the other backend, so respawn tears
+        // down both. The new entity id (null for NPCs) has to be persisted.
+        UUID entityId = entities.respawn(shop);
+        shop.setVillagerEntityId(entityId);
+        try {
+            shops.update(shop);
+        } catch (SQLException ex) {
+            plugin.getLogger().log(Level.SEVERE,
+                    "Failed to persist the new entity id for shop " + shop.id(), ex);
+        }
+    }
+}

src/main/java/me/f0reach/vshop/shop/entity/ShopAppearanceService.java

@@ -1,14 +1,15 @@
 package me.f0reach.vshop.shop.entity;
 
 import me.f0reach.vshop.model.Shop;
+import me.f0reach.vshop.model.ShopAppearance;
 import org.bukkit.Location;
 
 import java.util.UUID;
 
 /**
  * Strategy for the in-world representation of a shop — the thing a player walks
- * up to and clicks. Today the only implementation is {@link VillagerBackend};
- * a FancyNpcs-backed one is planned, which is why callers should depend on
+ * up to and clicks: a real Villager ({@link VillagerBackend}) or a packet NPC
+ * ({@code integration.fancynpcs.FancyNpcBackend}). Callers depend on
  * {@link ShopEntityService} rather than on a concrete backend.
  *
  * <p>All methods run on the main thread and are best-effort: if the shop's
@@ -32,4 +33,13 @@ public interface ShopEntityBackend {
 
     /** Despawns the representation. Does not touch persistence. */
     void remove(Shop shop);
+
+    /**
+     * Off-main-thread warm-up for an appearance that is about to be spawned or
+     * refreshed. Backends whose rendering needs a slow lookup — FancyNpcs
+     * resolves a skin name against Mojang, blocking the caller for the better
+     * part of a second on a cache miss — do it here so the main thread only
+     * hits the cache. Must be safe to call from any thread, and safe to skip.
+     */
+    default void prepare(ShopAppearance appearance) {}
 }