project-revolution-online

トレーディングカードゲーム「プロジェクトレヴォリューション」を、ルールを完全に自動適用する形で オンライン対戦できるようにするプロジェクト。

ルールの拠り所は総合ルール Version 15.00 で、全文が docs/rules/ にある。総合ルールが 「詳細はフロアルールをご参照ください」と外へ投げたところは、フロアルール（Version 1.12）の第2部で、 こちらは docs/floor-rules/ にある。 用語の正は CONTEXT.md、設計上の決定は docs/adr/。 各画面の見た目の仕様と、それを目で見て確かめるための HTML のモックは docs/screens/ にある。

構成

pnpm ワークスペースのモノレポ。

パッケージ	役割
packages/engine	ルールエンジン。「盤面 ＋ 行動 → 次の盤面」の純粋関数。実行時依存を持たず、ブラウザとサーバの両方で動く（ADR-0001）
packages/server	盤面の唯一の権威（ADR-0004）
packages/cpu	自動で打つ相手（CPU）と、CPU 同士の勝率を測る仕組み。engine にだけ依存し、人の画面と同じ射影した盤面と、自分のデッキの中身だけを参照して打つ（ADR-0060・ADR-0062）
packages/client	対戦画面。受け取った盤面を描いて選んだものを送るだけで、対戦のルールの判断は持たない（ADR-0010）
packages/notices	ロビーのお知らせのファイルの形を確かめ、置き場へ上げる本体（ADR-0045）。実行時依存を持たず、画面からも読むためのもの
private/cards	カード実装。この公開リポジトリには含まれない（ADR-0002）
private/decks	対戦に使うカードのまとまりを渡すだけ。カードを名指しするため、cards と同じく含まれない

private/ は公開リポジトリに含められないパッケージの置き場で、独立した非公開リポジトリを そこへ clone する（ADR-0002）。作業ツリー上はワークスペースの一部として振る舞うが、コミット先が 別になる。

依存の向きは cards → engine の一方向で、engine は cards を知らない。カードを名指しするのは private/decks だけで、デッキの組み方もサーバの立て方も公開側にある（ADR-0002）。

開発

Node.js 22 以上。pnpm は packageManager で固定しているため、corepack が有効なら追加の準備は要らない。

pnpm install --frozen-lockfile
pnpm verify

--frozen-lockfile を付けるのは、pnpm-lock.yaml が private/ 以下の importer を持っているため。 それらが無い環境で素の pnpm install を走らせると、ロックファイルから黙って消える。

対戦する

サーバと対戦画面を別々に立てる。

pnpm serve --decks private/decks/src/index.ts   # 対戦サーバ（既定で 8787 番）
pnpm --filter @revolution/client dev            # 対戦画面（既定で 5173 番）

打った対戦は残る（ADR-0018）。既定では立てたところに revolution.sqlite ができ、サーバを 落として立て直しても、打っていた対戦はそこから戻る。 残すのは盤面ではなく、デッキとシードと 「行動と答えの並び」だけである。置き先は --store で変えられ、空文字を渡せば何も残さずに立つ。

pnpm serve --decks private/decks/src/index.ts --store ''   # 何も残さない

--decks に渡すのは、次の 3 つを export するモジュールである（ADR-0021）。 このリポジトリはどのカードを使うかを知らない（ADR-0002）ので、実行時に受け取る。

export	何を渡すか
pool	識別子で引けるカードのまとまり。ここに入っているものが、席に持ち込める全部である
presets	誰でも使える既製デッキ。{ id, name, cards } で、cards は識別子の並び
restrictions	名前の付いた禁止／制限リスト。{ id, name, limits } で、limits はカード名ごとの上限（同名のカードを合わせて数える）。空でよい。先頭のものが部屋の既定になる

識別子は公開側にとってただの文字列で、何を指すかも知らない。デッキは識別子の並びなので、 何をどの枚数入れるかは渡す側が決める。積み方の取り決めはこのリポジトリに無い。立てる時に既製 デッキが構築戦の規定（総合ルール 第3部 第1章 3-1）を満たしているかを確かめるので、満たして いなければその場で分かる。

席に着く時に選ぶのは自分のデッキである（ADR-0021）。既製デッキはコピーして自分のデッキに してから使うもので、選択肢には並ばない。ただしデッキを持てるのはログインした人だけなので、 上のようにログイン無しで立てた場合は、渡された既製デッキがそのまま選択肢になる。手元で 2 人ぶん 試すときは、席ごとに別の既製デッキを選べる。

あとは http://localhost:5173 を開くだけでよい。開くとロビーが出る（ADR-0017）ので、 そこで部屋を作るか、開いている部屋に入る。

ロビーで選ぶもの	何が起きるか
人と対戦する	部屋を作って相手を待つ。作った部屋は、ほかの人のロビーにも出る
CPU と対戦する	もう一方の席にサーバが座り、そのまま始まる（場面ごとに手へ点数を付けて選ぶ CPU。ADR-0060 の段階 2）
入る	相手を待っている部屋に入る。2 人揃ったところで始まる

名乗りは画面が用意してブラウザに覚えさせる（ADR-0017）ので、閉じても開き直せば同じ席に戻れる。 そのぶん同じブラウザで開いた 2 つのタブは同じ人になるので、手元で 2 人ぶん試すときは名乗りを ?participant= で分けるか、別のブラウザで開く。

合言葉を決めて待ち合わせることもできる。URL に付けると、ロビーを通らずその部屋に入る。

http://localhost:5173/?participant=あ&room=あいことば
http://localhost:5173/?participant=い&room=あいことば

名乗り（participant）は認証ではない（ADR-0009）。これを知っている人がその席に座れるので、 切れても同じ名乗りで開き直せば続きから打てる。

これは手元で立てたときの形である。 ログインを持たせると名乗りは受け付けなくなり、席は Cookie のセッションで決まる（ADR-0019、「ログインできるようにする」）。

立てるにはカードの実装が要る。無い場合は下を参照。

CPU 同士の勝率を測る

CPU を変更するときは、前の CPU に勝ち越すことを確認してから入れる（ADR-0060）。

pnpm cpu-compare --decks private/decks/src/index.ts --challenger random --baseline random

既製デッキの組み合わせすべてを順に回し、既定で 200 回のデュエルを打つ。2 回のデュエルを 1 組にし、 同じシード・同じデッキで CPU の席だけを入れ替えるので、山札の並びも先攻・後攻も同じになる。 **決着したデュエルの勝率の 95% 信頼区間（Wilson）の下限が 50% を上回れば「勝ち越し」**と判定する （ADR-0061）。デュエルの数（--duels）・最初のシード（--seed）・使う既製デッキ（--presets）・ 1 回のデュエルの手の数の上限（--max-actions）を変更できる。選べる CPU の名前は packages/cpu/src/players.ts にある。

デプロイ

画面は Vercel で配信し、対戦サーバは常駐する 1 台のマシンに置く（ADR-0013、ADR-0014、 ADR-0015）。両者は同じオリジンである必要はなく、接続先は画面側が保持している。

対戦サーバのデプロイ

カードはデプロイ先でビルドさせない（ADR-0002）。ビルドは手元だけで行い、デプロイ先には 出来上がった 1 ファイルだけを渡す。

pnpm build:server --decks private/decks/src/index.ts    # dist/serve.cjs を書き出すだけ

デプロイまでまとめて行うにはこちら。ビルド → 転送 → 差し替えて再起動を順に行い、途中で 失敗すればそこで止まる。

pnpm deploy:server --decks private/decks/src/index.ts --host <ユーザ>@<ホスト> --key <秘密鍵>

デプロイ先は引数か環境変数で渡す。このリポジトリはデプロイ先の情報を持たない。

環境変数	意味
REVOLUTION_DEPLOY_HOST	デプロイ先（<ユーザ>@<ホスト>）
REVOLUTION_DEPLOY_KEY	使用する秘密鍵
REVOLUTION_DEPLOY_PATH	デプロイ先でのパス
REVOLUTION_DEPLOY_UNIT	デプロイ先の常駐単位（systemd サービス）の名前

デプロイ先に何を用意するかは ADR-0015 を参照。待ち受けポートは PORT、対戦の記録先は STORE で指定できるため、どちらもビルドし直さずに変更できる。

検証環境へのデプロイ

ログインを含む画面変更を、本番より前に一通り確認するための常設の検証環境がある （ADR-0025）。デプロイ方法は同じだが、コマンドと環境変数を分けている。

pnpm deploy:server:verify --decks private/decks/src/index.ts --host <ユーザ>@<ホスト> --key <秘密鍵>

環境変数	意味
REVOLUTION_DEPLOY_HOST_VERIFY	デプロイ先（<ユーザ>@<ホスト>）
REVOLUTION_DEPLOY_KEY_VERIFY	使用する秘密鍵
REVOLUTION_DEPLOY_PATH_VERIFY	デプロイ先でのパス
REVOLUTION_DEPLOY_UNIT_VERIFY	デプロイ先の常駐単位の名前

本番用の環境変数（REVOLUTION_DEPLOY_HOST など、末尾に _VERIFY が付かないもの）とは 名前が異なるため、片方だけを設定していても、もう一方のコマンドには読み込まれない。引数を 省略しても意図しないデプロイ先に届くことはなく、pnpm deploy:server と pnpm deploy:server:verify は常に別々の宛先を向く。

デプロイ先には絶対パスで STORE を指定すること（ADR-0018）。既定値の revolution.sqlite は相対パスのため、常駐単位の作業ディレクトリを基準に解決される。指定しなければ / が基準に なり、意図しない場所に作成されてしまう。/run や PrivateTmp 配下も再起動時に消えるため避ける。

保存先ディレクトリは常駐単位自身に用意させるのが自然である。StateDirectory はその単位の 実行ユーザーの所有物として作成され（ADR-0015 の「専用ユーザーで実行する」という方針と 合致する）、再起動しても残る。

[Service]
StateDirectory=revolution
Environment=STORE=/var/lib/revolution/revolution.sqlite

バックアップは別の場所に取り、取得できていることを確認する仕組みも用意する。 送信し続けて いるつもりでも失敗している場合、次に使おうとしたときに初めて気づくことになる（ADR-0015）。

接続の記録を読む

ログイン済みの人が対戦サーバに繋ぐたびに、置き場の connections 表へ「どの身元が、いつ」を 1 行残す。IP アドレスも端末の情報も残さない。 数えるのは繋いだ時点だけで、繋いでいる 時間は測らない。ログインの設定が無い手元の起動では残さない。書けなくても接続と対戦は止まらず、 サーバのログに 接続を記録できませんでした: が出る。

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗