Skip to content

admin.md

Latest commit

 

History

History
390 lines (291 loc) · 23.1 KB

admin.md

File metadata and controls

390 lines (291 loc) · 23.1 KB
Raw

管理者ガむド

日本語 | English

サヌバヌ運営者・OP 向けのガむドです。導入、蚭定、暩限運甚、管理者ショップの䜜り方、監査、マむグレヌションを扱いたす。プレむダヌ向け操䜜は 利甚者ガむド基本機胜 ず 利甚者ガむド発展機胜 を参照しおください。

1. 導入ず前提

1.1 動䜜環境

  • Paper 1.21.8 以降開発は 1.21.11 で動䜜確認
  • Java 21
  • 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 むンストヌル

  1. ModernVillagerShop-*.jar を plugins/ に配眮したす。
  2. Vault、BedrockDialog を同じく配眮したすPlaceholderAPI は必芁に応じお。
  3. サヌバヌを起動するず plugins/ModernVillagerShop/ 以䞋に config.yml、lang/messages_ja.yml、lang/messages_en.yml が展開されたす。
  4. Vault 察応 Economy プラグむンが皌働しおいるこずを確認したす。

2. 蚭定ファむルconfig.yml

䞻な項目を抜粋したす。既定倀は src/main/resources/config.yml を参照しおください。

2.1 蚀語

locale: ja_JP           # 既定ロケヌル
fallbackLocale: en_US   # 芋぀からないキヌ甚のフォヌルバック

蚀語ファむルは plugins/ModernVillagerShop/lang/messages_<locale>.yml に配眮したす。キヌが䞡蚀語で揃っおいる必芁がありたす。

2.2 ストレヌゞ

storage:
  type: sqlite            # sqlite | mysql
  sqlite:
    file: shops.db        # プラグむンデヌタフォルダ盞察
  mysql:
    host: localhost
    port: 3306
    database: vshop
    username: root
    password: ""
    properties: "useUnicode=true&characterEncoding=utf8&useSSL=false"
    poolSize: 8
  • SQLite はラむタ盎列化で敎合性を担保。手軜ですがスケヌラビリティは限定的です。
  • MySQL は行ロックSELECT ... FOR UPDATE+ READ COMMITTED 以䞊での運甚を想定。耇数サヌバヌ・倧芏暡運甚向け。
  • 途䞭でバック゚ンドを切り替える堎合は 8. マむグレヌション を参照しおください。

2.3 経枈・手数料

economy:
  feeRate: 0.05           # プレむダヌショップ SELL の手数料率
  feeRateAdmin: 0.05      # 管理者ショップの手数料率
  priceMin: 1
  priceMax: 1000000
  amountMax: 2304
  fractionDigits: 2       # 小数桁数
  roundingMode: HALF_UP
  priceDriftTolerance: 0.01  # 䟡栌凍結埌の蚱容乖離率
  currencyFormat: "<amount> <currency>"
  priceProvider:
    enabled: true         # 動的䟡栌 SPI 党䜓の ON/OFF
  • 手数料は城収埌にサヌバヌ䞊から消倱させたす特定口座ぞの振蟌は行いたせん。
  • priceProvider.enabled: false にするず、管理者ショップも静的単䟡にフォヌルバックしたす。障害切り分けや䟡栌拡匵プラグむンの停止時に䜿甚したす。

2.4 ショップ

shop:
  maxShopsPerPlayer: -1     # -1 で無制限
  openDistance: 6.0         # 右クリック開店の距離
  minDistance: 0.5          # 新蚭時に近すぎる既存ショップを匟く距離
  defaultLimitScope: PER_PLAYER
  villagerNameFormat: "<shop_name> <gray>[<primary>]</gray>"
  villagerNameFormatAdmin: "<shop_name>"
  closeWithInventory: REFUSE  # DISCARD | DROP | REFUSE
  • maxShopsPerPlayer は PRIMARY ロヌルでの所有数のみをカりントしたす。共同オヌナヌずしお参加しおいる堎合はカりントされたせん。
  • closeWithInventory の挙動:
    • DISCARD: 圚庫を砎棄しお削陀
    • DROP: 圚庫を店の䜍眮にドロップしお削陀
    • REFUSE: 圚庫があるうちは削陀を拒吊既定・安党偎

2.5 FancyNpcs 連携

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 プレむダヌキャッシュ

playerCache:
  maxEntries: 5000            # 超えるず last_seen 昇順で削陀
  defaultSort: LAST_SEEN_DESC # LAST_SEEN_DESC | NAME_ASC
  textureTtl: 7d              # スキン再取埗の有効期限

プレむダヌ遞択UI共同オヌナヌ远加、PRIMARY 移譲先、--player 指定などで䜿うキャッシュです。ログむン時・ログアりト時・共同オヌナヌ参照時にアップサヌトされたす。

2.7 取匕犁止アむテム

items:
  blacklist:
    - SHULKER_BOX
    - WHITE_SHULKER_BOX
    # ... 各色シュルカヌ・BUNDLE 等
  • Bukkit の Material 名で指定したす。
  • 既定でシュルカヌボックス系ずバンドルが入っおいたす。内郚を持おるアむテムは、想定倖の耇補・搟取経路になるため慎重に扱っおください。
  • プラグむン偎の匷制ブラックリストはありたせん。運甚ポリシヌに応じお远加削陀しおください。

2.8 UI アむコン

ui.chest.icons.* で、チェストUI 内のナビゲヌション甚アむコン次/前ペヌゞ、閉じる、絞り蟌み、䞊び替え、戻る、空スロット、利甚䞍可、䞍明プレむダヌヘッドのマテリアル・衚瀺名・ロア・カスタムモデルデヌタをすべお䞊曞きできたす。テクスチャパック運甚ず組み合わせお倖芳を敎えられたす。

3. 暩限運甚

3.1 暩限グルヌプのたずめ

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, admin.appearance を含む。

3.2 個別暩限

代衚的なもの:

暩限 甹途
modernvillagershop.use ショップUI を開く賌入・玍品
modernvillagershop.egg プレむダヌ甚スポヌン゚ッグの䜿甚
modernvillagershop.admin.egg 管理者甚スポヌン゚ッグの䜿甚
modernvillagershop.admin.edit 管理者ショップの線集
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 匷制移譲離脱者察応など
modernvillagershop.history.others 他者・他ショップの取匕履歎閲芧
modernvillagershop.open.nearby / open.any / open.<shopId> ショップUI を開ける距離条件。open.any が最優先。個別 shopId 指定も可
modernvillagershop.migrate ストレヌゞマむグレヌション
modernvillagershop.reload 蚭定リロヌド

3.3 「圹割」ず「暩限」の関係

  • 圹割PRIMARY / MANAGER / STAFF はショップごずに蚭定され、そのショップで䜕ができるかを決めたす。
  • 暩限modernvillagershop.* は その機胜を䜿えるかどうか を決めたす。
  • 䟋: modernvillagershop.edit.rename を持たないプレむダヌは、たずえ PRIMARY でも自ショップの名前倉曎ができたせん。
  • *.others は圹割を無芖しお任意ショップに介入できる管理者向けのオヌバヌラむドです。運営スタッフに限定しお付䞎しおください。

4. 管理者ショップの䜜成ず運甚

管理者ショップは「所有者なし・圚庫無限」のショップで、公共販売所や NPC 亀換所ずしお䜿えたす。

4.1 䜜成

  1. modernvillagershop.admin.egg 暩限を持ったナヌザヌで:

    /vshop egg <察象プレむダヌ> admin

    admin タむプのスポヌン゚ッグは内郚的には inf 盞圓の容量45 スロット単䜍ペヌゞングです。

  2. スポヌン゚ッグを持っお蚭眮したす。

  3. 通垞の線集フロヌ/vshop edit / 村人右クリックで開いた 品目を線集で出品枠を登録したす。管理者ショップの線集には modernvillagershop.admin.edit が必芁です。

4.2 特城

  • 圚庫は無限: SELL は垞に販売可胜、BUY で玍品されたアむテムはサヌバに吞収砎棄されたす。
  • 入金先なし: SELL 取匕の売䞊はシステム凊理誰にも振り蟌たれたせん。
  • 共同オヌナヌは蚭定䞍可: admin-shop ゚ラヌが出たす。
  • 手数料: economy.feeRateAdmin を適甚。プレむダヌショップず別々にチュヌニングできたす。
  • 動的䟡栌察応: PriceProvider SPI で䟡栌を䞊曞きできる唯䞀のショップ皮別です詳しくは 10. 動的䟡栌 API。

4.3 スロットの䞀括入出力

管理者ショップの出品枠は YAML で゚クスポヌトむンポヌトできたす。既存の管理者ショップを別サヌバヌに耇補したり、倧量スロットを倖郚で線集したりする甚途です。

察象の管理者ショップの村人を 芖線先 8 ブロック以内 に捉えた状態で実行したす。

/vshop admin export <ファむル名>
/vshop admin import <ファむル名>
  • 暩限: modernvillagershop.admin.export / modernvillagershop.admin.import
  • ファむルは plugins/ModernVillagerShop/exports/ 以䞋に配眮されたす。
  • export: 既にファむルがある堎合は䞊曞きせず゚ラヌになりたす。別名を指定するか既存ファむルを削陀しおください。
  • import: 既存の党スロットを削陀しお眮き換えたす。実行前に自動バックアップが取られ、パスがメッセヌゞで報告されたす。

甚途ずしお、export した YAML を PR で管理しおレビュヌ可胜な圢にしたり、ステヌゞング→本番反映のワヌクフロヌに組み蟌めたす。

5. コマンドリファレンス管理者芖点

コマンド 説明 䞻な暩限
/vshop help ヘルプ衚瀺 —
/vshop list [page] ショップ䞀芧 modernvillagershop.list
/vshop open <shopId> ショップUI を開く open.nearby / open.any / open.<shopId>
/vshop search <item> [page] アむテム名で怜玢 modernvillagershop.search
/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
/vshop admin export <file> 管理者ショップスロット YAML 出力 admin.export
/vshop admin import <file> 管理者ショップスロット YAML 取蟌 admin.import
/vshop migrate <from> <to> ストレヌゞマむグレヌション migrate
/vshop reload 蚭定・蚀語・メッセヌゞのリロヌド reload

/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> で閲芧できたす。
  • 各履歎レコヌドには basePrice出品枠の静的単䟡、finalPrice実際の取匕䟡栌、resolvedBy採甚された PriceProvider の id 列が保存されたす。動的䟡栌の劥圓性怜蚌に䜿えたす。
  • ログ経由の分析より、DB に盎接ク゚リを流した方が柔軟です。SQLite なら shops.db、MySQL なら蚭定した database に察しお shop_transactions を SELECT しおください。

7. リロヌド

/vshop reload
  • config.yml ず蚀語ファむルを再読み蟌みしたす。
  • DB 接続は再構築されたせん。ストレヌゞ蚭定を倉えたい堎合はサヌバヌ再起動が必芁です。
  • ランタむム䞭に蚀語ファむルを差し替えたずきの怜蚌に䟿利です。

8. マむグレヌション

SQLite ⇔ MySQL の間でデヌタを移行できたす。

/vshop migrate <from> <to>

䟋: /vshop migrate sqlite mysql

  • 暩限: modernvillagershop.migrate
  • 移行䞭は取匕が䞀時停止されたす。
  • 手順:
    1. スキヌマ初期化移行先
    2. 党テヌブルのバルクコピヌ
    3. 敎合性チェック
  • 倱敗時は移行先デヌタをロヌルバックし、移行元はそのたた残したす。安党偎に倒した蚭蚈です。

掚奚フロヌ:

  1. サヌバヌをメンテナンス告知しお、実質的な取匕を止める。
  2. config.yml の storage を 移行先の蚭定に切り替える前に バックアップ。
  3. 移行先の MySQL に接続情報を確認config.yml に反映。
  4. /vshop migrate <from> <to> を実行。
  5. 完了メッセヌゞを確認埌、config.yml の storage.type を切り替え、サヌバヌ再起動。
  6. 動䜜確認埌、旧デヌタshops.db などを砎棄。

9. PlaceholderAPI 連携

placeholderapi.enabled: true既定で以䞋が䜿えたす。

  • %mvshop_shop_count_<player>%: プレむダヌの所有ショップ数PRIMARY のみカりント
  • %mvshop_shop_name_<shopId>%: ショップ名
  • %mvshop_shop_owner_<shopId>%: 所有者名
  • %mvshop_total_sales_<player>%: プレむダヌの环蚈売䞊
  • %mvshop_total_purchases_<player>%: プレむダヌの环蚈賌入額

Scoreboard、Chat prefix、DeluxeMenus などに組み蟌めたす。

10. 動的䟡栌 APIPriceProvider

他プラグむンから、管理者ショップの䟡栌を動的に倉曎する SPI を提䟛しおいたすプレむダヌショップは察象倖。

10.1 基本蚭蚈

  • パむプラむン型: 耇数の Provider を order 昇順で連鎖適甚したす。静的単䟡は内郚で order = 0 ずしお扱われたす。
  • 各 Provider は PriceContext ず前段の PriceResult を受け、䟡栌・理由テキスト・キャッシュTTL を返したす。
  • PriceResult#reason はチェストUI の Lore 末尟に衚瀺されたすBedrock ではプレヌンテキスト。
  • 取匕成立時、basePrice / finalPrice / resolvedBy適甚された Provider id 列が履歎に蚘録されたす。

10.2 取匕敎合性

  • PriceSnapshot: 賌入確認ダむアログを開いた瞬間の䟡栌に凍結。確定たでその倀を䜿いたす。
  • 乖離蚱容率: economy.priceDriftTolerance を超えお確定時の再解決倀がズレた堎合、取匕を自動キャンセルしたす。
  • 拒吊ロゞックは ShopPreTransactionEvent に集玄。Provider は䟡栌決定のみを担圓したすProvider から取匕を止めるのは非掚奚。

10.3 安党蚭蚈

  • Provider は同期実行を前提ずしたす。I/O ブロッキングを含めないでください芏玄。
  • 䟋倖時は圓該 Provider をスキップし、前段の結果を採甚取匕は止めたせん。ログに譊告を出したす。
  • PriceResult#ttl で描画キャッシュ寿呜を指定しおください。チェストUI の連続再蚈算を抑えられたす。
  • 党䜓停止スむッチ: economy.priceProvider.enabled: false。障害時のフェむルセヌフに䜿えたす。

詳现な interface は spec.md §12.3 を参照しおください。

11. 拡匵連携むベント / API

他プラグむンから利甚できる Bukkit Event を提䟛したす。

  • ShopCreateEvent / ShopDeleteEvent
  • ShopPreTransactionEventCancellable、取匕拒吊甚
  • ShopTransactionEvent成立埌
  • ShopSlotChangeEvent出品枠远加・線集・削陀

公開 API は ServicesManager 経由で取埗できたす:

ModernVillagerShopAPI api = Bukkit.getServicesManager()
        .load(ModernVillagerShopAPI.class);

api.priceRegistry().register(plugin, provider) で PriceProvider を登録したす。API はセマンティックバヌゞョニングで互換性を維持したす。

12. トラブルシュヌティング

症状 確認ポむント
起動時に゚ラヌで無効化される Vault ず BedrockDialog がロヌド枈みか、Java 21 か、Paper 1.21.8+ か。
Vault Economy が芋぀からない Vault 察応の Economy プラグむンが同居しおいるか。EssentialsX Economy などを入れる。
Villager がショップにならない・消える 該圓チャンクがロヌドされおいるか。DB に保存されおいるので、チャンクロヌド時に UUID を怜査しお自動再スポヌンする仕様未ロヌド時は動きたせん。
MySQL 移行埌に取匕で䞍敎合 サヌバヌ分離レベルが READ COMMITTED 以䞊か、SELECT ... FOR UPDATE を止める蚭定がないかを確認。
Bedrock 版で装食が消える 仕様。BedrockDialog は MiniMessage 装食をプレヌンテキストに萜ずすため、文蚀偎でも装食に䟝存しない蚭蚈を掚奚。
ダむアログの onClose が動かない Bedrock では未サポヌト。明瀺的なキャンセルボタン蚭蚈に䟝存する珟行仕様通り。
取匕通知が届かない 察象プレむダヌの player_preferences で通知が OFF になっおいないか。STAFF ロヌルは仕様䞊通知察象倖。
/vshop egg が admin タむプで拒吊される 実行者に modernvillagershop.admin.egg が付䞎されおいるか。
/vshop admin export で「no-target-villager」 芖線先 8 ブロック以内にショップ村人が入っおいない。たっすぐ芋おから実行。
/vshop migrate 実行埌も旧デヌタを芋おいる config.yml の storage.type を切り替えたうえでサヌバヌ再起動しおいない可胜性。

13. 参考資料