MCkeiba

Japanese / English

HorseRacingPlugin (Alpha)

A horse racing mini-game plugin for Minecraft (Paper 1.21).
It provides a full gameplay loop: course building, race running, betting, payouts, and scheduled races.

⚠️ This is an alpha release. Specifications, data compatibility, and balance may change frequently. Testing on a staging server is strongly recommended.

Features

• In-game course creation (checkpoint-based)
• Gate / goal line / spawn point setup
• Race operation (manual start and forced next-race start)
• Betting GUI (Win, Place, Quinella, Exacta, Trio, Trifecta)
• Vault economy integration for bet purchases and payouts
• AI profile switching and AI debug display
• Horse data management (acquire, rename, retire, records)
• Automatic race schedule generation and operation

Requirements

• Minecraft / Paper: 1.21.x (paper-api 1.21-R0.1-SNAPSHOT)
• Java: 21
• Recommended dependencies:
  • Vault
  • An economy plugin (e.g. EssentialsX Economy)

If Vault integration is unavailable, betting features are effectively disabled (no purchases).

Installation

1. Download horseracing-0.2-SNAPSHOT.jar
2. Put it into your server plugins folder
3. Start the server
4. Edit plugins/HorseRacingPlugin/config.yml if needed
5. Prefer a full server restart rather than /reload

Commands

For players

• /racebet : Open the betting GUI

For admins (mainly /race)

• /race create <course_name> : Enter course creation mode
• /race save : Save current editing data
• /race cancel : Cancel current setup/edit mode
• /race undo : Undo recent operation (course/spawn/etc.)
• /race list : List available courses
• /race setgoal <course_name> : Set goal line
• /race setgate <course_name> : Set gate area
• /race setspawn <course_name> : Set spawn points
• /race setwidth <course_name> <width> : Set course width
• /race setdirection <course_name> <clockwise|counterclockwise> : Set lap direction
• /race tpgate <course_name> : Teleport to gate
• /race cleargrass <course_name> [height_offset] : Clear grass
• /race clearglass <edit|apply|undo|cancel> : Edit grass-clear region
• /race standby <course_name> <horse_count> [track] : Prepare a race
• /race start <course_name> : Start race
• /race end <course_name> : End race
• /race next [start] : Show next race / force-start next race
• /race schedule <start|end|status> : Control schedule operation
• /race debug <gate|spawns|ai|off> ... : Debug display tools
• /race reloadai : Reload AI settings
• /race horse <list|info|name|retire|get> : Manage owned horses

Permissions

• horseracing.race : Access to /race (default: OP)
• horseracing.race.admin : Administrative /race operations (default: OP)
• horseracing.bet : Access to /racebet (default: true)

About Horse AI

CPU horses in races are controlled by the plugin's AI system.
You can tune behavior in config.yml based on your server style.

• race-mode: AI mode (physics / style / simple)
  • physics: richer movement with pathing, cornering, and slope influence
  • style: easier-to-read behavior based on running styles
  • simple: lightweight baseline behavior
• ai-profile: loads AI parameter sets from ai-profiles/<name>.yml
• strategy-common: shared coefficients (pace, positioning, final spurt, stamina drain)
• physics-strategy: physics-only coefficients (inner-lane preference, overtaking, slope/corner effects)

AI operation tips

• Run /race reloadai after tuning values
• Use /race debug ai <course_name> [horse_number] to inspect behavior
• AI balance is still being tuned during alpha; adjusting values per server policy is recommended

Main config keys (config.yml)

• language: display language (ja / en)
• debug: debug logging
• race-mode: AI mode (physics / style / simple)
• ai-profile: AI profile name
• horse-data.limits.*: horse-data limits
• economy.enabled: enable/disable Vault integration
• odds-system.*: odds and virtual bettor settings
• race-schedule.*: race interval and betting window

For schedule generation details, see generator_settings.yml.

Alpha notes

• Config keys and command behavior may change
• Internal data changes may break compatibility
• Test on smaller/staging servers first
• When reporting issues, include your config.yml and reproduction steps

Known assumptions

• Betting requires Vault + an economy plugin
• Races may fail if course setup (gate/goal/spawns) is incomplete

Planned improvements (examples)

• Better GUI and race presentation effects
• AI and odds balance tuning
• Expanded operator/admin tooling

Feedback is welcome. Since this is an alpha release, your reports and balancing notes are highly appreciated!

HorseRacingPlugin（アルファ版）

English version: README_en.md

Minecraft（Paper 1.21系）向けの競馬ミニゲームプラグインです。
コース作成、出走、ベット、払戻し、スケジュール開催まで一通り遊べます。

⚠️ 本バージョンはアルファ版です。仕様変更・データ互換性の変更・不具合修正が頻繁に入る可能性があります。検証サーバーでの利用を推奨します。

できること

• コースをゲーム内で作成（チェックポイント方式）
• ゲート／ゴール／スポーン地点の設定
• レース開催（手動開始・次レース強制開始）
• ベットGUI（単勝・複勝・馬連・馬単・3連複・3連単）
• Vault経済連携による購入＆払戻し
• AIプロファイル切替・AIデバッグ表示
• 馬データの管理（獲得・命名・引退・戦績表示）
• レース番組の自動生成・スケジュール運用

対応環境

• Minecraft / Paper: 1.21.x（paper-api 1.21-R0.1-SNAPSHOT）
• Java: 21
• 依存プラグイン（推奨）:
  • Vault
  • 経済プラグイン（EssentialsX Economy など）

Vault連携が使えない場合、ベット関連機能は実質無効になります（購入不可）。

導入方法

1. horseracing-0.2-SNAPSHOT.jar をダウンロード
2. サーバーの plugins フォルダへ配置
3. サーバー起動
4. 必要に応じて plugins/HorseRacingPlugin/config.yml を編集
5. /reload ではなくサーバー再起動を推奨

コマンド

プレイヤー向け

• /racebet : ベットGUIを開く

管理者向け（主に /race）

• /race create <コース名> : コース作成モード開始
• /race save : 作成中データを保存
• /race cancel : 各種設定モードをキャンセル
• /race undo : 直前操作の取り消し（コース・スポーン等）
• /race list : コース一覧
• /race setgoal <コース名> : ゴール設定
• /race setgate <コース名> : ゲート設定
• /race setspawn <コース名> : スポーン地点設定
• /race setwidth <コース名> <幅> : コース幅設定
• /race setdirection <コース名> <clockwise|counterclockwise> : 周回方向設定
• /race tpgate <コース名> : ゲートへテレポート
• /race cleargrass <コース名> [高さオフセット] : 草除去
• /race clearglass <edit|apply|undo|cancel> : 草除去範囲編集
• /race standby <コース名> <頭数> [馬場] : レース待機作成
• /race start <コース名> : レース開始
• /race end <コース名> : レース終了
• /race next [start] : 次レース情報表示 / 強制開始
• /race schedule <start|end|status> : スケジュール運用
• /race debug <gate|spawns|ai|off> ... : デバッグ表示
• /race reloadai : AI設定再読み込み
• /race horse <list|info|name|retire|get> : 所有馬管理

権限

• horseracing.race : /race 利用権限（デフォルト: OP）
• horseracing.race.admin : 管理系 /race 操作（デフォルト: OP）
• horseracing.bet : /racebet 利用権限（デフォルト: true）

馬AIについて

本プラグインでは、レース中のCPU馬の挙動をAIで制御しています。
運営スタイルに合わせて、config.yml でモードやチューニングを変更できます。

• race-mode: AIモード切替（physics / style / simple）
  • physics: 進路取り・コーナー・坂などを考慮する、よりリッチな挙動
  • style: 脚質ベースで分かりやすい挙動
  • simple: 軽量で扱いやすい基本挙動
• ai-profile: AIパラメータセットを読み込み（ai-profiles/<name>.yml）
• strategy-common: 全モード共通の係数（巡航・位置取り・終盤スパート・スタミナ消費など）
• physics-strategy: physicsモード専用係数（内ラチ志向、追い抜き、坂/コーナー補正など）

AI運用のヒント

• 調整を反映したいときは /race reloadai を実行
• 走り方の確認には /race debug ai <course_name> [horse_number] を利用
• アルファ版ではAIバランスを継続調整中のため、サーバー方針に合わせて数値調整を推奨

主要設定（config.yml）

• language: 表示言語（ja / en）
• debug: デバッグログ
• race-mode: AIモード（physics / style / simple）
• ai-profile: AIプロファイル名
• horse-data.limits.*: 馬データ上限
• economy.enabled: Vault連携有効/無効
• odds-system.*: オッズ計算・仮想ベッター設定
• race-schedule.*: 開催間隔・受付秒数

自動番組生成の詳細は generator_settings.yml で調整できます。

アルファ版としての注意事項

• 設定キーやコマンド仕様が更新で変わる可能性があります
• 内部データ構造の変更により、既存データ互換が崩れる可能性があります
• まずは小規模サーバーやテスト環境での運用を推奨します
• 不具合報告時は、config.yml と発生手順を添えてください

既知の前提

• ベット機能を使う場合は Vault + 経済プラグインが必要です
• コース設定（ゲート・ゴール・スポーン）が未完了のままでは正常に開催できません

更新予定（例）

• GUI/演出の強化
• バランス調整（AI・オッズ）
• 運営向け管理コマンドの拡張

フィードバック歓迎です。アルファ版のため、ぜひ使用感を教えてください！