AziCave

AziCave は、ローグライク向けにダンジョンピースをランダム接続して生成する Paper プラグインです。 外部 schematic / schem を WorldEdit 経由で配置し、入口の正対・隣接判定に成功した接続だけを開口します。

前提

• Paper 1.21 系
• WorldEdit
• Java 21

WorldEdit が無い場合、プラグインは起動しますが schematic 配置は実行できません。

できること

• 設定で複数テンプレートパターンを指定
• コマンドでテンプレートパターン、初期ピース、ワールド、座標、seed を上書き
• 外部 schematic の配置
• 入口 2 点指定による開口定義
• 入口サイズごとの個別開口
• piece ごとの隣接ピース denylist
• 1x1x2 接続部へのランダムドア配置
• seed 再現
• AI 解析しやすい key=value 形式のデバッグログ

コマンド

生成

/azicave generate
/azicave generate --patterns=templates/*.yml,templates/boss/*.yml
/azicave generate --start=start_room --world=dungeon_world --x=100 --y=64 --z=100
/azicave generate --seed=123456789
/azicave generate --depth=10

指定可能なオプション:

• --patterns= テンプレートファイルの glob をカンマ区切りで指定
• --start= 初期ピース ID
• --world= 生成先ワールド名
• --x= --y= --z= 初期座標
• --seed= seed
• --depth= その実行だけ最大 depth を上書き

リロード

/azicave reload

デバッグ切替

/azicave debug on
/azicave debug off

現在のセッションのmob状況

/azicave debug mobs

現在いるセッションワールドの補正後の最大パワー、現在パワー、総モブ数、種類別モブ数（0体の種類も含む）をチャットに表示します。 自然スポーンと同じ基準で探索人数・最大深度を計算し、補正の根拠も表示します。探索者がいない場合は人数・深度を0として計算します。 ホームや管理観戦中でも実行でき、debugログがOFFでも利用できます。権限は azicave.command.debug（デフォルト: OP）です。

mobの手動スポーン

/azicave debug spawn <mob名>
/azicave debug spawn creaking

探索中のセッションワールド内で、現在位置に1体スポーンします。観戦中の管理者も実行できます。 権限は azicave.command.debug（デフォルト: OP）です。デバッグログの有効化は不要です。 mob名は zombie_brute、skeleton_archer、powered_creeper、mini_enderman、copper_golem、creaking で、TAB補完に対応しています。 自然スポーンの光量・距離・出現数制限を無視し、設定済みの能力値・専用AI・ドロップを適用します。通常のデスポーン処理は適用されます。

ゲーム内 authoring

piece と entrance は WorldEdit 選択とコマンドだけで更新できます。
piece の schematic origin は常に WorldEdit 選択範囲の最小 corner へ固定されます。

/azicave author piece upsert templates/custom.yml room_a schematics/custom/room_a.schem 1.5
/azicave author entrance upsert templates/custom.yml room_a north_gate NORTH
/azicave author entrance remove templates/custom.yml room_a north_gate

推奨手順:

1. WorldEdit でピース全体を選択する
2. /azicave author piece upsert ... を実行する
3. この時点で piece の origin は選択範囲の最小 corner に固定される
4. 次に入口面を WorldEdit で 2 点選択する
5. /azicave author entrance upsert ... を実行する

author piece upsert は bounds、schematic、weight を更新します。
author piece upsert 実行時に piece の最小 corner は補助メタデータとして保存されます。
author entrance upsert はその保存済み corner を自動再利用して選択面を point1 / point2 に変換し、bounds 外や開口深さ超過は拒否します。

config.yml

generation:
  template-patterns:
    - templates/*.yml
  start-piece: start_room
  world: world
  origin:
    x: 0
    y: 64
    z: 0
  seed: 123456789
  algorithm:
    max-depth: 8
    branch-chance: 0.45
    entrance-branch-bonus: 0.15
    depth-prediction-multiplier: 1.0
    min-piece-count: 12
    max-piece-count: 24
door:
  enabled: true
  chance: 0.35
  material: SPRUCE_DOOR
debug:
  enabled: false

主要パラメータ

• max-depth: 木構造の最大深さ
• branch-chance: 分岐の基本強度
• entrance-branch-bonus: 利用可能 entrance 数が多いピースほど枝を増やしやすくする補正
• depth-prediction-multiplier: depth から求める目標ピース数の倍率
• min-piece-count / max-piece-count: depth 予測から求めた目標ピース数の下限 / 上限
• door.enabled: デフォルト true
• door.chance: 1x1x2 入口のドア出現確率
• door.material: Bukkit Material

目標ピース数は max-depth、開始ピースの入口数、テンプレート全体の入口数と重みから予測されます。
同じ seed なら、同じ depth と同じテンプレート集合で同じ目標数と同じ生成順になります。

テンプレート YAML

入口は point1 と point2 の 2 点指定です。
向きは NORTH / EAST / SOUTH / WEST のいずれかです。
YAML にタブは使わず、半角スペースでインデントしてください。

pieces:
  start_room:
    schematic: schematics/example/start_room.schem
    weight: 1.0
    denied-adjacent-pieces:
      - trap_*
      - boss_hall
    bounds:
      min: [0, 0, 0]
      max: [8, 5, 8]
    entrances:
      - id: north_gate
        facing: NORTH
        point1: [3, 1, 0]
        point2: [5, 3, 0]
      - id: east_door
        facing: EAST
        point1: [8, 1, 3]
        point2: [8, 2, 3]

denied-adjacent-pieces は任意です。
未指定なら隣接制限なし、指定した場合はその piece は列挙した piece ID に隣接できません。
* ワイルドカードも使えます。どちらか片側でも相手を deny していれば、その隣接は成立しません。 旧キー allowed-adjacent-pieces は非対応です。残っている場合はテンプレート読み込み時にエラーになります。

入口サイズと開口ルール

• NORTH/SOUTH は X 幅と Y 高さから入口サイズを求めます
• EAST/WEST は Z 幅と Y 高さから入口サイズを求めます
• 開口奥行きは width を使用します
• 3x3 の入口は 3x3x3 を開口します
• 1x2 の入口は 1x1x2 を開口します
• 接続判定は「正対しており、1 ブロック隣接し、入口底面の Y が一致していて、横方向が中央一致しており、スパンが 1 ブロック以上重なっていること」です
• 3x3x3 と 1x1x2 が接続しても、開口はそれぞれのサイズで個別適用され、1x4x2 のような統合開口にはなりません
• 入口接続は入口底面の Y を一致させ、横方向だけ中央寄せで配置します
• 生成後も全ピースを再走査し、親子接続でなくても隣接していて entrance 条件が合う組は自動で開口します
• denied-adjacent-pieces を指定した piece は、deny された piece と面で接する配置自体が拒否されます

schematic 配置の考え方

• schematic はテンプレート YAML からの相対パス、またはプラグインデータフォルダからの相対パス、または絶対パスで指定できます
• 貼り付け時は clipboard origin を最小 corner に正規化したうえで、回転ごとに paste 座標へ補正を入れて min-corner 整合を維持します
• bounds と入口座標は最小 corner 基準で合わせてください

デバッグログ

/azicave debug on または debug.enabled: true で有効化できます。

出力例:

debug|scope=schematic|event=paste_begin|piece=start_room|rotation=90|schematic=C:\...\start_room.schem|target=100,64,100
debug|scope=generation|event=candidate_rejected|candidate=corner_room|reason=collision|rotation=180|origin=110,64,95
debug|scope=carve|event=applied|parentBox=100,65,100->102,67,102|childBox=100,65,99->100,66,99

Mob の湧き状況は scope=mob_spawn で出力します（debug OFF 時は出力しません）。

• wave_status: スポーン間隔ごとのセッション・ワールド・探索人数・深度、設定上の基本最大パワー (baseMaxAlivePower)、深度と人数補正後の最大パワー (maxAlivePower)、現在パワー (alivePower)、生存数と種類別内訳。
• nearby_status: プレイヤー位置ごとの周辺パワーと上限・判定半径（周辺制限が有効な場合）。
• wave_skipped: 探索者なし (no_exploring_players)、最大パワー無効 (max_power_disabled)、全体パワー上限 (global_power_limit) によるスポーン停止。探索者なしの場合、wave_status の人数・深度は 0 です。
• wave_complete: 今回のスポーン数と判定対象の部屋数、場所が見つからなかった回数 (noLocation: 距離・周辺パワー制限、床・空間・天空光、光量・松明の条件)、残りパワー・種類別上限・重みで選べるモブがなかった回数 (noProfile)、失敗数 (failed)、スポーン後のパワーと生存数。
• spawned / spawn_failed: 自然・手動スポーン時のモブ名、座標、成功時のパワー・深度・UUID、失敗時の理由。
• despawned: プレイヤーから離れたモブの削除数と削除後の生存数。

nametag の調査ログは scope=nametag で、debug ON 中に約5秒間隔で出力します。 有効化後の初回には environment としてサーバーバージョンと導入プラグイン一覧も記録します。 セッション参加者とセッションワールド内の観戦者について、scoreboard 更新前 (before_update)、 更新直後 (after_update)、1 tick 後 (next_tick) の状態を記録します。

• viewer / world / mode: 名前を見る側のプレイヤー、ワールド、ゲームモード。
• board / expectedBoard / ownBoard: 実際の scoreboard と AziCave が保持する scoreboard の識別値・一致状態。 before_update や next_tick で ownBoard=false なら、別の処理による差し替えの可能性があります。 初回適用前や通常の参加者でない観戦者は expectedBoard=none です。
• mainBoard / sidebar: main scoreboard かどうかとサイドバー Objective 名。
• targets: 同じワールド内の各プレイヤーについて、見る側の scoreboard 上の所属 Team と nametag 設定。 Alice:azicave_hidden/NEVER なら API 上は非表示、Alice:none や ALWAYS なら Team 未適用・上書きが疑われます。

再現時は /azicave debug on を実行し、10秒程度待ってから /azicave debug off に戻してください。 ownBoard=true と全対象の NEVER が維持されていても見える場合、API 上の状態だけでは原因を特定できないため、 名前表示を変更するプラグインによるパケット操作やクライアント側の表示を追加で調べます。

敵配置について

Mob は azicave.mobs の重みとスポーン間隔でダンジョン内に出現します。テンプレート YAML の enemy-sockets は読みません。

開発メモ

• このリポジトリには Gradle wrapper 実体が入っていないため、ビルドにはローカルの gradle か wrapper の追加が必要です
• src/main/resources/templates/example-basic.yml にサンプル定義があります

Session / Round / Economy / Shop

このブランチでは、従来の単一 GameSession 前提から、複数人・複数 session を同時に扱う基盤へ拡張しています。

Session

• /azicave session create [maxPlayers] で session を作成します。
• /azicave session join <sessionId> で参加します。
• azicave.session.spectate 権限（デフォルト: OP）があれば /azicave session spectate <sessionId> で管理者として自由に観戦できます。参加中の場合は先に退出してください。
• 管理観戦者は人数・統計・ラウンド進行に含まれず、スペクテイターモードのまま通常の /tp でセッション間や外部ワールドへ移動できます。観戦権限はバニラのテレポート権限も付与します。他プラグインが /tp を置き換えている場合は /minecraft:tp を使用してください。
• 管理観戦は /azicave session leave で退出できます。観戦コマンド使用前のゲームモードへ戻り、セッション終了時は全観戦者も退避してからワールドをアンロードします。
• /azicave session leave で退出します。
• /azicave session list で state、round、人数、共有資金などを確認します。
• /azicave session forceend <sessionId> で強制終了します。
• session owner は表示・作成者記録用のみで、特別権限はありません。
• sessions.home-template-world-path のテンプレート world を session 作成時にコピーし、sessions.world-name-prefix + sessionId の world としてロードします。
• session 終了時は world unload 後に session world folder を削除します。
• 起動時の残存 session world folder 削除は sessions.cleanup-leftover-worlds-on-startup で制御します。

Home / Round

• home.spawn が session 参加時の initial spawn、home.return-spawn が dungeon から帰還した時の spawn です。
• home.area は帰還済み判定と、就寝可能なベッドの範囲として使います。
• /azicave round start [maxDepth] で round を開始します。プレイヤーには「危険度」として表示され、ダイアログでは gui.depth.levels（desc と depth の対応表）から選択します。テンプレートは generation の設定を常に使用します。round 開始時に player は dungeon へ即時 teleport されず、家側 portal から入ります。
• round は朝に始まり、Minecraft 時刻 18000（既定値、深夜）で強制終了します。時刻は round-timing で設定できます。
• 生存者の round-timing.sleep.minimum-percentage% 以上が深い睡眠に達して wait-seconds 秒経つか、生存者全員が深く眠ると夜をスキップし、同じ危険度で次ラウンドを自動開始します。昼は確認ダイアログで夜へ進めてから、ホーム内のベッドで眠れます。
• 深夜時点で眠っていない player と、ラウンド終了時にホームへ帰還していない player はそのラウンドの死亡扱いになります。
• DungeonGenerator は変更せず、session world 内の家から離れた未使用領域に dungeon を生成します。
• 生成位置は dungeon.base-distance-from-home と dungeon.round-spacing を使って round ごとに割り当てます。
• default の maxDepth は dungeon.default-max-depth で設定します。
• round 中の途中参加・再接続は spectator/pending 扱いになり、次 round 開始時に SURVIVAL、health/food 初期化、home spawn teleport で復帰します。

Portal

• round 中のみ、家エリアと dungeon エリアを往復する portal が有効です。
• dead、spectator、session 外 player は portal を使用できません。
• portals.home-to-dungeon.area は家側 portal の範囲です。
• portals.home-to-dungeon.destination-offset は dungeon origin からの teleport 先 offset です。帰還 portal とのループを避けるため、portal 範囲から少しずらした座標にします。yaw は teleport 前の player yaw に加算する yaw offset です。
• portals.dungeon-to-home.area は root piece 内のローカル座標で指定する帰還 portal 範囲です。
• portals.dungeon-to-home.destination-yaw-offset は帰還時に teleport 前の player yaw へ加算する yaw offset です。
• portals.cooldown-seconds で連続 teleport を抑制します。

Economy

• 各 session は共有資金 sharedBalance を持ちます。
• session 作成時に economy.initial-balance が付与されます。
• /azicave money で自分の session の共有資金と対象 round のノルマを確認できます。
• /azicave money set <sessionId> <amount> で共有資金を設定します。
• /azicave money add <sessionId> <amount> で共有資金を加算します。
• economy.quota.delivery-chest に session ごとの納品箱を設置します。ラウンド終了時はこのチェスト内だけを換金し、player inventory 内のアイテムは納品に含めません。
• ノルマは ceil((economy.quota.base + economy.quota.per-round * currentRound) * economy.quota.multiplier) です。納品価格がノルマ以上なら達成となり、村人の怒りが1段階下がります。
• 未達が economy.quota.max-consecutive-misses 回連続すると GAME_OVER です。進行度はスコアボードの村人の怒りゲージに表示され、warning-remaining 以下では警告します。
• 納品した宝の価格は共有資金へ加算されます。共有資金からノルマ額を差し引くことはありません。
• 換金価格は economy.sell-prices.<MATERIAL> の Material name ベースです。

Villager Shop GUI

• session world 内の村人を右クリックすると共有資金で購入する shop GUI が開きます。
• shop は IN_ROUND と LOBBY で利用できます。
• IN_ROUND では alive かつ非 spectator の session member のみ購入できます。
• LOBBY では session member が利用できます。
• 取引内容は shop.trades に設定し、探索中とロビーで同じ商品を販売します。旧形式の2つのリストも読み込めます（同じ id は探索中の設定を優先）。

shop:
  title: AziCave Shop
  trades:
    - id: bread
      material: BREAD
      amount: 4
      price: 12
    - id: healing_potion
      material: POTION
      potion-type: HEALING
      potion-level: 2
      amount: 1
      price: 100
    - id: enchanted_book
      material: ENCHANTED_BOOK
      stored-enchantments:
        sharpness: 3
      price: 150

potion-type は Bukkit の PotionType 名です。potion-level は省略時 1、強化可能な種類のみ 2 を指定できます。ポーションには SPLASH_POTION、LINGERING_POTION、TIPPED_ARROW も使えます。商品には必要に応じて display-name、lore（文字列リスト）、enchantments（名前とレベルのマップ）、stored-enchantments（エンチャント本）、durability（残り耐久値）、unbreakable、can-destroy（ブロック名のリスト）を追加できます。名前と説明文は & カラーコードに対応します。

MariaDB player statistics / leaderboard

プレイヤー統計とランキングはMariaDBへ保存します。DB停止中もゲームセッションは継続しますが、統計の保存とランキング更新は一時停止します。

CREATE DATABASE azicave CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'azicave'@'%' IDENTIFIED BY 'replace-with-a-strong-password';
GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, INDEX ON azicave.* TO 'azicave'@'%';
FLUSH PRIVILEGES;

接続情報とTextDisplayの配置は config.yml で設定します。テーブルとインデックスはプラグイン起動時に自動作成されます。

database:
  enabled: true
  host: 127.0.0.1
  port: 3306
  name: azicave
  username: azicave
  password: "replace-with-a-strong-password"
  use-ssl: false
  maximum-pool-size: 4
  connection-timeout-millis: 5000
leaderboard:
  enabled: true
  timezone: Asia/Tokyo
  top-size: 10
  update-interval-seconds: 60
  displays:
    daily:
      world: world
      x: 0.5
      y: 76.0
      z: 0.5
      yaw: 0.0
      pitch: 0.0
      title: Daily Ranking

daily、weekly、monthly、total の各配置を個別に指定できます。日次は当日0時、週次は月曜日0時、月次は当月1日を、leaderboard.timezone のカレンダー境界として集計します。同点の場合は対象ラウンドへの到達時刻が早いプレイヤーを上位にします。

/azicave stats で自分の統計を、azicave.stats.others 権限があれば /azicave stats <player> でオフラインを含む他プレイヤーの統計を確認できます。記録対象は最大・総到達ラウンド数、セッション参加数、死亡・ゲームオーバー数、実際に到達した最大ダンジョン深度、累積・最長プレイ時間、Mob撃破数、宝箱・宝物取得数、累積売却金額、途中離脱・切断数です。