docs: document the FancyNpcs appearance feature

spec.md gains the appearance backend under §3.1, the /vshop appearance surface
under §4, the two new tables under §8.1, and a §12.2 covering the FancyNpcs
integration — including why the build pins 2.9.2 and the three measured facts
the design rests on (synchronous interact event, blocking setSkin, NPCs absent
from the Bukkit entity API).

README, both admin guides and both player-advanced guides updated in step, with
the wording for each language taken from its own locale file rather than
translated across.

The admin guides call out the operational consequences rather than restating the
command list: URL skins sit behind their own permission because they pull a
remote image through the server, the profession button disappears while a shop
renders as an NPC, NPCs are invisible to other plugins' entity handling, and
/vshop reload re-sends them so config changes land without a restart.

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

Author: f0reachARR

README.md

@@ -11,6 +11,7 @@ ModernVillagerShop replaces the vanilla trade window with a **chest UI + Dialog*
 - **Co-owners with revenue sharing.** `PRIMARY` / `MANAGER` / `STAFF` roles per shop, percentage shares that always add up to 100%, instant payout split on every sale, and an ownership-transfer flow.
 - **Trade limits.** Per-slot caps, counted per player or server-wide, with an optional rolling reset window. Remaining amount and time-to-reset are shown in the slot lore.
 - **Villagers that stay put.** Shop villagers are AI-locked, invulnerable, protected from portals, and respawned from the database on chunk load if something removes them.
+- **Custom shop appearance.** With [FancyNpcs](https://modrinth.com/plugin/fancynpcs) installed, a shop can render as an NPC instead of a villager — a player skin, any entity type, glow colour, scale and equipment — all through `/vshop appearance`, no UI to click through.
 - **Spawn-egg based creation.** `/vshop egg` hands out an egg that encodes how many listing rows the shop gets — 1 to *n* rows, or unlimited.
 - **Full trade history and statistics.** Filterable history (`--side`, `--from`, `--to`, `--player`, `--shop`), per-shop stats, cumulative fees, and audit fields (`basePrice` / `finalPrice` / `resolvedBy`) on every record.
 - **Owner notifications.** Chat notification on each trade while online, a summary on next login while offline, toggleable per player.
@@ -28,6 +29,7 @@ ModernVillagerShop replaces the vanilla trade window with a **chest UI + Dialog*
 | [BedrockDialog](https://modrinth.com/plugin/bedrockdialog) | **required** |
 | Geyser + Floodgate | optional — needed only to serve Bedrock clients |
 | [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) | optional |
+| [FancyNpcs](https://modrinth.com/plugin/fancynpcs) | optional — lets shops render as NPCs instead of villagers |
 
 ## Installation
 
@@ -67,6 +69,7 @@ Root command is `/vshop` (bare `/vshop` prints help).
 | `/vshop stats <shopId>` | Shop statistics | `modernvillagershop.stats` |
 | `/vshop history [page] [--shop <id>] [--side sell\|buy] [--from <date>] [--to <date>] [--player <name>]` | Trade history | `history` / `history.others` |
 | `/vshop edit [shopId]` | Open the owner/editor menu | `edit` / `edit.others` |
+| `/vshop appearance <shopId> <sub>` | Change how the shop looks (needs FancyNpcs) | `edit.appearance` / `edit.others` |
 | `/vshop coowner <shopId>` | Co-owner management UI | `coowner.manage` / `.others` |
 | `/vshop transfer <shopId> <player>` | Transfer `PRIMARY` ownership | `coowner.transfer` / `.others` |
 | `/vshop egg <player> <lines\|inf\|admin>` | Give a shop spawn egg | `egg` / `admin.egg` |
@@ -77,12 +80,33 @@ Root command is `/vshop` (bare `/vshop` prints help).
 
 `--from` / `--to` accept `YYYY-MM-DD` or `YYYY-MM-DDTHH:mm[:ss]`, interpreted in the server's default time zone.
 
+### `/vshop appearance`
+
+Command-only, by design — this is an occasional operation with a lot of knobs, which reads better flat than as a menu tree.
+
+| Subcommand | Effect |
+| --- | --- |
+| `show` | Print the current settings (read-only, so the console can run it too) |
+| `npc [skin]` | Switch to a PLAYER NPC. Without `skin`, uses the owner's name |
+| `villager` | Switch back to a plain villager |
+| `type <entityType>` | Change the NPC's entity type |
+| `skin <name\|uuid\|url\|@none> [slim]` | Set or clear the skin (PLAYER type only) |
+| `glow <true\|false> [color]` | Glow and glow colour |
+| `scale <n>` | Size multiplier |
+| `equip <slot> [none]` | Equip the item in your hand, or clear the slot |
+| `attribute <name> <value\|@none>` | Set a FancyNpcs attribute (e.g. `pose sitting`) |
+| `reset` | Drop every override and go back to a villager |
+
+Equipment slots are FancyNpcs': `MAINHAND`, `OFFHAND`, `HEAD`, `CHEST`, `LEGS`, `FEET`, `BODY`, `SADDLE`.
+
+Appearance is stored in this plugin's own database, so it travels with `/vshop migrate` and NPCs are rebuilt from it on every boot. If FancyNpcs is missing or `fancynpcs.enabled` is false, NPC-backed shops fall back to villagers with a single warning — cosmetics never take a shop offline.
+
 ## Permissions
 
 All nodes are prefixed `modernvillagershop.`. Two convenience bundles exist:
 
 - **`modernvillagershop.player`** (default: everyone) — `use`, `egg`, `list`, `search`, `stats`, `history`, `open.nearby`, and the `edit.*` / `coowner.*` nodes needed to run your own shop.
-- **`modernvillagershop.admin`** (default: op) — `admin.egg`, `admin.edit`, `admin.export`, `admin.import`, `edit.others`, `coowner.manage.others`, `coowner.transfer.others`, `history.others`, `open.any`, `migrate`, `reload`.
+- **`modernvillagershop.admin`** (default: op) — `admin.egg`, `admin.edit`, `admin.export`, `admin.import`, `admin.appearance`, `edit.others`, `coowner.manage.others`, `coowner.transfer.others`, `history.others`, `open.any`, `migrate`, `reload`.
 
 Two independent layers decide what a player can do:
 
@@ -91,6 +115,8 @@ Two independent layers decide what a player can do:
 
 The `*.others` nodes are moderation overrides — they ignore role entirely and apply to any shop.
 
+Two appearance nodes sit outside the bundles' defaults: `edit.appearance.url` (op) gates loading a skin from an arbitrary URL, since that pulls a remote image through the server, and `admin.appearance` (op) bypasses the `fancynpcs.allowedTypes` and `fancynpcs.maxScale` limits.
+
 ## Configuration highlights
 
 Full annotated defaults live in [`src/main/resources/config.yml`](https://github.com/f0reachARR/ModernVillagerShop/blob/main/src/main/resources/config.yml).
@@ -158,6 +184,8 @@ which copies shops, listings, stock, transactions, notifications, limits, co-own
 | `%mvshop_total_sales_<player>%` | Cumulative sales |
 | `%mvshop_total_purchases_<player>%` | Cumulative purchases |
 
+**FancyNpcs** (`fancynpcs.enabled: true`) — renders shops as NPCs; see [`/vshop appearance`](#vshop-appearance). Built against the `de.oliver:FancyNpcs` 2.x API. FancyNpcs 2.10.0+ requires Java 25 on the server; if you are on Java 21, use the `-java21` builds FancyNpcs publishes.
+
 **Events** — `ShopCreateEvent`, `ShopDeleteEvent`, `ShopPreTransactionEvent` (cancellable), `ShopTransactionEvent`, `ShopSlotChangeEvent`.
 
 **Public API** — `ModernVillagerShopAPI` is registered with Bukkit's `ServicesManager` and exposes shop lookup, search, statistics and history for dashboards, logging and third-party integrations.

docs/guide/admin.md

@@ -13,6 +13,8 @@
 - **Vault**: 必須。Vault 対応の Economy プラグイン（EssentialsX Economy など）が別途必要です。
 - **BedrockDialog**: 必須。Modrinth 配布の Paper プラグイン。Bedrock 対応をしたい場合は Geyser + Floodgate も併せて導入します。
 - **PlaceholderAPI**: 任意。導入すればプレースホルダーが利用できます。
+- **FancyNpcs**: 任意。導入すると、ショップの見た目を村人以外（主にプレイヤー NPC）にできます。
+    - FancyNpcs 2.10.0 以降はサーバー側に **Java 25** を要求します。Java 21 で運用する場合は FancyNpcs が配布している `-java21` ビルドを使ってください。
 
 ### 1.2 インストール
 
@@ -94,7 +96,22 @@ shop:
     - `DROP`: 在庫を店の位置にドロップして削除
     - `REFUSE`: 在庫があるうちは削除を拒否（既定・安全側）
 
-### 2.5 プレイヤーキャッシュ
+### 2.5 FancyNpcs 連携
+
+```yaml
+fancynpcs:
+  enabled: true
+  turnToPlayer: true        # ショップ側で個別指定がないときの既定値
+  interactionCooldown: 0.0  # 同一プレイヤーの連続クリックを無視する秒数（0 = 無効）
+  maxScale: 2.0             # /vshop appearance scale で指定できる最大倍率
+  allowedTypes: []          # 空 = 全許可
+```
+
+- `enabled: false` にすると、FancyNpcs が入っていても連携を止められます。NPC 指定のショップは村人として表示され、起動時に警告が 1 行出るだけで、ショップ自体は通常どおり動きます。
+- `allowedTypes` / `maxScale` は `modernvillagershop.admin.appearance` を持つプレイヤーには適用されません。
+- 見た目の設定はこのプラグイン自身の DB（`shop_appearance` テーブル）に保存されます。FancyNpcs 側の `npcs.yml` には書き込まないため、`/vshop migrate` でストレージを移すときも一緒に移動します。NPC は起動のたびに DB から作り直されます。
+
+### 2.6 プレイヤーキャッシュ
 
 ```yaml
 playerCache:
@@ -105,7 +122,7 @@ playerCache:
 
 プレイヤー選択UI（共同オーナー追加、PRIMARY 移譲先、`--player` 指定など）で使うキャッシュです。ログイン時・ログアウト時・共同オーナー参照時にアップサートされます。
 
-### 2.6 取引禁止アイテム
+### 2.7 取引禁止アイテム
 
 ```yaml
 items:
@@ -119,7 +136,7 @@ items:
 - 既定でシュルカーボックス系とバンドルが入っています。内部を持てるアイテムは、想定外の複製・搾取経路になるため慎重に扱ってください。
 - プラグイン側の強制ブラックリストはありません。運用ポリシーに応じて追加削除してください。
 
-### 2.7 UI アイコン
+### 2.8 UI アイコン
 
 `ui.chest.icons.*` で、チェストUI 内のナビゲーション用アイコン（次/前ページ、閉じる、絞り込み、並び替え、戻る、空スロット、利用不可、不明プレイヤーヘッド）のマテリアル・表示名・ロア・カスタムモデルデータをすべて上書きできます。テクスチャパック運用と組み合わせて外観を整えられます。
 
@@ -130,7 +147,7 @@ items:
 `paper-plugin.yml` に、次のロール的グルーピングが定義されています。LuckPerms などの権限プラグインで付与すると便利です。
 
 - **`modernvillagershop.player`** (default: `true`): 一般プレイヤーが必要とする権限のパック。`use`, `egg`, `list`, `search`, `stats`, `history`, `open.nearby`, `edit.*`, `coowner.manage`, `coowner.transfer` を含む。
-- **`modernvillagershop.admin`** (default: `op`): 管理者権限パック。`admin.egg`, `admin.edit`, `admin.export`, `admin.import`, `edit.others`, `coowner.manage.others`, `coowner.transfer.others`, `history.others`, `open.any`, `migrate`, `reload` を含む。
+- **`modernvillagershop.admin`** (default: `op`): 管理者権限パック。`admin.egg`, `admin.edit`, `admin.export`, `admin.import`, `edit.others`, `coowner.manage.others`, `coowner.transfer.others`, `history.others`, `open.any`, `migrate`, `reload`, `admin.appearance` を含む。
 
 ### 3.2 個別権限
 
@@ -142,7 +159,9 @@ items:
 | `modernvillagershop.egg` | プレイヤー用スポーンエッグの使用 |
 | `modernvillagershop.admin.egg` | 管理者用スポーンエッグの使用 |
 | `modernvillagershop.admin.edit` | 管理者ショップの編集 |
-| `modernvillagershop.edit.*` | 自ショップの各種編集操作（move / rename / profession / suspend / delete / delete.refund） |
+| `modernvillagershop.edit.*` | 自ショップの各種編集操作（move / rename / profession / appearance / suspend / delete / delete.refund） |
+| `modernvillagershop.edit.appearance.url` | 任意の URL からスキンを読み込む（既定 op） |
+| `modernvillagershop.admin.appearance` | `fancynpcs.allowedTypes` / `maxScale` の制限を無視する |
 | `modernvillagershop.edit.others` | 他者ショップの編集（ロール無視） |
 | `modernvillagershop.coowner.manage.others` | 任意ショップの共同オーナー管理 |
 | `modernvillagershop.coowner.transfer.others` | 任意ショップの PRIMARY 強制移譲（離脱者対応など） |
@@ -211,6 +230,7 @@ items:
 | `/vshop stats <shopId>` | 統計表示 | `modernvillagershop.stats` |
 | `/vshop history [shopId] [page] [--flags]` | 取引履歴 | `history` / `history.others` |
 | `/vshop edit [shopId]` | 編集メニュー | `edit` / `edit.others` |
+| `/vshop appearance <shopId> <sub>` | 見た目の変更（FancyNpcs 必須） | `edit.appearance` / `edit.others` |
 | `/vshop coowner <shopId>` | 共同オーナー管理UI | `coowner.manage` / `.others` |
 | `/vshop transfer <shopId> <player>` | PRIMARY 移譲 | `coowner.transfer` / `.others` |
 | `/vshop egg <player> <lines\|inf\|admin>` | スポーンエッグ配布 | `egg` / `admin.egg` |
@@ -221,6 +241,32 @@ items:
 
 `/vshop history` の `--from` / `--to` は `YYYY-MM-DD` または `YYYY-MM-DDTHH:mm[:ss]` を受け付け、サーバーのデフォルトタイムゾーンで解釈します。
 
+### 5.1 `/vshop appearance` の詳細
+
+見た目の変更は Dialog UI を用意せず、コマンドだけで操作します。設定項目が多く、たまにしか触らない操作なので、メニューを潜るより一覧で見えるほうが扱いやすいためです。
+
+| サブコマンド | 内容 |
+| --- | --- |
+| `show` | 現在の設定を表示（読み取り専用なのでコンソールからも実行可） |
+| `npc [skin]` | プレイヤー NPC に切り替える。`skin` 省略時はオーナー名を使う |
+| `villager` | 通常の村人に戻す |
+| `type <entityType>` | NPC のエンティティタイプを変える |
+| `skin <name\|uuid\|url\|@none> [slim]` | スキンを設定・解除する（PLAYER タイプのみ） |
+| `glow <true\|false> [color]` | 発光と発光色 |
+| `scale <倍率>` | 大きさ |
+| `equip <slot> [none]` | 手に持っているアイテムを装備させる / 外す |
+| `attribute <name> <value\|@none>` | FancyNpcs の属性を設定・削除する（例: `pose sitting`） |
+| `reset` | 設定をすべて破棄して村人に戻す |
+
+装備スロットは FancyNpcs のもので、`MAINHAND` / `OFFHAND` / `HEAD` / `CHEST` / `LEGS` / `FEET` / `BODY` / `SADDLE` です。
+
+運用上の注意:
+
+- **URL スキンは別権限**です。`modernvillagershop.edit.appearance.url`（既定 op）を持つ人だけが `https://...` を指定できます。任意の外部画像をサーバー経由で取得することになるため、一般プレイヤーには開けないでおくのが無難です。
+- NPC 表示中のショップでは、編集メニューから**職業変更のボタンが消えます**。職業は村人固有の設定だからです。設定値自体は残るので、`villager` に戻せば元の職業で復元されます。
+- NPC はサーバー上のエンティティとして存在しません。他プラグインのエンティティ一覧やモブカウント、`/kill` などの対象にはなりません。
+- `/vshop reload` を実行すると、`fancynpcs` セクションの変更を反映するため NPC を再送信します。
+
 ## 6. 監査と取引ログ
 
 - 取引履歴は DB に永続化され、他者・他ショップは `modernvillagershop.history.others` を持つユーザーが `/vshop history <shopId>` や `--player <name>` で閲覧できます。