225 lines
5.8 KiB
Markdown
225 lines
5.8 KiB
Markdown
# Diplomacy Calculation Engine API
|
||
|
||
ディプロマシー（Diplomacy）ボードゲームの計算エンジンとして機能する、ステートレスなFastAPIアプリケーションです。
|
||
`diplomacy`ライブラリの計算ロジックをウェブAPIとして提供します。フロントエンドアプリケーション等から利用されることを想定しています。
|
||
|
||
## 主な機能
|
||
|
||
* **ステートレスな計算**: ゲームの状態（JSON）と命令を送り、次の状態を取得可能。
|
||
* **命令の解決 (Processing)**: フェイズを進行させ、命令を解決します。
|
||
* **命令の検証 (Validation)**: 指定された命令がルール上有効かどうかをチェック。
|
||
* **実行可能な命令の取得**: 現在の盤面で各ユニットができる全命令のリストを取得。
|
||
* **可視化 (Rendering)**: 現在の盤面や入力中の命令を反映したSVG画像を生成。
|
||
|
||
## 開発環境のセットアップ
|
||
|
||
```bash
|
||
# 仮想環境の作成と有効化
|
||
python -m venv .venv
|
||
source .venv/bin/activate # Linux/macOS
|
||
|
||
# 依存ライブラリのインストール
|
||
pip install -r requirements.txt
|
||
pip install requests # テスト用
|
||
```
|
||
|
||
## 起動方法
|
||
|
||
### 推奨: Pythonコマンド
|
||
|
||
```bash
|
||
python main.py
|
||
```
|
||
|
||
### Option: uvicornコマンド
|
||
|
||
```bash
|
||
# main.pyがルートにあるため main:app と指定します
|
||
uvicorn main:app --host 127.0.0.1 --port 8000
|
||
```
|
||
|
||
起動後、Swagger UIが [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) で利用可能です。
|
||
|
||
---
|
||
|
||
## API エンドポイント仕様
|
||
|
||
### 1. マップ情報の取得
|
||
|
||
#### マップ一覧の取得
|
||
|
||
* **URL**: `/maps`
|
||
* **Method**: `GET`
|
||
* **Description**: 利用可能なマップ名の一覧を返します。
|
||
|
||
#### マップ詳細の取得
|
||
|
||
* **URL**: `/maps/{map_name}`
|
||
* **Method**: `GET`
|
||
* **Description**: 指定したマップのトポロジー情報（地域、隣接関係など）を返します。
|
||
* **Example**: `/maps/standard`
|
||
|
||
### 2. 計算・フェイズ進行
|
||
|
||
#### ゲームの進行 (Process)
|
||
|
||
現在の状態と命令を受け取り、判定を行い、次のフェイズの状態を返します。
|
||
|
||
* **URL**: `/calculate/process`
|
||
* **Method**: `POST`
|
||
* **Request Body**:
|
||
|
||
```json
|
||
{
|
||
"game_state": { ... }, // diplomacyライブラリの Game.to_dict() 形式
|
||
"orders": {
|
||
"FRANCE": ["A MAR - SPA", "A PAR - BUR"],
|
||
"ENGLAND": ["F LON - ENG"]
|
||
}
|
||
}
|
||
```
|
||
|
||
* **Response**:
|
||
|
||
```json
|
||
{
|
||
"game_state": { ... } // 更新された新しいゲーム状態
|
||
}
|
||
```
|
||
|
||
#### 命令の検証 (Validate)
|
||
|
||
指定された命令が現在の局面で有効かどうかを検証します（フェイズは進みません）。
|
||
|
||
* **URL**: `/calculate/validate`
|
||
* **Method**: `POST`
|
||
* **Request Body**: `process` と同様（`game_state` と `orders`）
|
||
* **Response**:
|
||
|
||
```json
|
||
{
|
||
"validated_orders": {
|
||
"FRANCE": ["A MAR - SPA"] // 受け付けられた命令
|
||
},
|
||
"errors": [] // エラーがあればここにリストされます
|
||
}
|
||
```
|
||
|
||
#### 実行可能な命令の取得 (Possible Orders)
|
||
|
||
現在の局面で実行可能なすべての命令のリストを取得します。
|
||
|
||
* **URL**: `/calculate/possible-orders`
|
||
* **Method**: `POST`
|
||
* **Query Param**:
|
||
* `power_name` (Optional) - 特定の国の命令のみ取得する場合に指定。
|
||
* `by_power` (Optional) - `true`を指定すると、結果を国ごとにグループ化して返します。
|
||
* **Request Body**:
|
||
|
||
```json
|
||
{
|
||
"game_state": { ... } // diplomacyライブラリの Game.to_dict() 形式
|
||
}
|
||
```
|
||
|
||
* **Response**:
|
||
|
||
```json
|
||
{
|
||
"possible_orders": {
|
||
"ADR": [], // ユニットがいない地域
|
||
"ANK": [ ... ], // ユニットがいる地域の命令リスト
|
||
...
|
||
}
|
||
}
|
||
```
|
||
|
||
※ `by_power=true` 指定時は、以下のように国名がキーとなります：
|
||
|
||
```json
|
||
{
|
||
"possible_orders": {
|
||
"FRANCE": {
|
||
"PAR": [ ... ],
|
||
"MAR": [ ... ]
|
||
},
|
||
"ENGLAND": { ... }
|
||
}
|
||
}
|
||
```
|
||
|
||
※ `power_name` 指定時は、その国のユニットが存在する地域のみが含まれます。
|
||
|
||
#### 命令の自動生成 (Auto Orders)
|
||
|
||
指定した国に対して、ランダムに有効な命令を生成します。
|
||
|
||
* **URL**: `/calculate/auto-orders`
|
||
* **Method**: `POST`
|
||
* **Query Param**: `power_name` (Required)
|
||
* **Request Body**:
|
||
|
||
```json
|
||
{
|
||
"game_state": { ... }
|
||
}
|
||
```
|
||
|
||
* **Response**:
|
||
|
||
```json
|
||
{
|
||
"orders": ["A PAR - BUR", "F BRE H", ...]
|
||
}
|
||
```
|
||
|
||
#### ゲームの強制終了 (Draw)
|
||
|
||
ゲームの状態を手動で「引き分け (Draw)」に変更し、フェイズを `COMPLETED` にします。
|
||
|
||
* **URL**: `/game/draw`
|
||
* **Method**: `POST`
|
||
* **Request Body**:
|
||
|
||
```json
|
||
{
|
||
"game_state": { ... }, // Game.to_dict() 形式
|
||
"winners": ["FRANCE", "GERMANY"] // (Optional) 特定の勝者を指定する場合
|
||
}
|
||
```
|
||
|
||
* **Response**:
|
||
|
||
```json
|
||
{
|
||
"game_state": { ... } // COMPLETED状態のゲーム
|
||
}
|
||
```
|
||
|
||
### 3. 可視化 (Rendering)
|
||
|
||
#### マップ画像の生成
|
||
|
||
現在の状態（および入力中の命令）を反映したSVG画像を生成します。
|
||
|
||
* **URL**: `/render`
|
||
* **Method**: `POST`
|
||
* **Request Body**:
|
||
|
||
```json
|
||
{
|
||
"game_state": { ... },
|
||
"orders": { ... }, // Optional: 入力中の命令（矢印で描画されます）
|
||
"incl_orders": true, // Optional: 命令を描画するか (default: true)
|
||
"incl_abbrev": true // Optional: 地名の略称を表示するか (default: true)
|
||
}
|
||
```
|
||
|
||
* **Response**: `image/svg+xml` (SVG画像データ)
|
||
|
||
## プロジェクト構造
|
||
|
||
* `main.py`: APIサーバー実装
|
||
* `test_api.py`: 動作確認用スクリプト
|
||
* `requirements.txt`: 依存パッケージ
|