Shvatka — チーム制シティクエスト（スキャベンジャーハント）を Telegram Bot + API で管理する Python プラットフォーム
Shvatka — チーム制シティクエスト（スキャベンジャーハント）を Telegram Bot + API で管理する Python プラットフォーム
ひとことでいうと
Shvatka（シュヴァトカ）は、複数のチームが街中を舞台に謎を解きながらチェックポイントを巡る「都市型チームクエスト」を、まるごとオンライン管理できるオープンソースのプラットフォームです。参加者は Telegram（テレグラム）というメッセージアプリのボット機能を使うだけでゲームに参加でき、主催者はサーバーからゲームの進行・チーム管理・記録を一括してコントロールできます。自分のサーバーにインストールして使うセルフホスト型なので、参加者が何人でも追加費用はかかりません。Python で書かれており、コードも含めてすべて無償公開されています。
こんな人におすすめ
1. 謎解きイベントや街歩きゲームを主催したい人 参加者への指示の配信・チェックポイントの報告・チームごとの進捗管理を、Telegram ボット一本で自動化できます。紙の問題用紙や専用アプリを用意しなくてよいので、準備の手間が大幅に減ります。
2. Python のバックエンド開発を学びたいエンジニア Telegram Bot と REST API（外部からデータをやり取りする仕組み）を組み合わせた実践的な構成が、すべてこのリポジトリ（ソースコードの置き場）の中に揃っています。Docker（仮想の箱の中でアプリを動かす技術）や Nginx（外からのアクセスを仕切るソフト）の使い方も含めて、現代的な Python サービスの手本として参照できます。
3. 大学サークルや社内チームのイベント担当者 新入生歓迎ゲーム・チームビルディング研修・社内スキャベンジャーハントなど、参加者全員が Telegram を使う環境であれば、専用のゲームアプリなしでデジタルなイベント進行が実現できます。自前サーバーにデプロイすれば維持費ゼロで継続運用も可能です。
インストール・使い方
準備するもの
- Python 3.13 以上（3.15 未満）:
pyproject.toml（プロジェクトの設定ファイル）にバージョン範囲が明記されています。 - uv（ユーブイ）: Python のパッケージ（追加機能のセット）を高速にインストールするツール。
- Telegram Bot Token: Telegram の公式ボット作成アカウント「@BotFather」から取得するパスワードのような文字列。
- Docker（任意）: サービスをまとめて起動するときに使います。本番運用では強く推奨。
Step 1: リポジトリをダウンロードする
ターミナル（文字を入力してパソコンに命令を送る画面）を開き、以下をコピー＆ペーストして実行してください。
git clone https://github.com/bomzheg/Shvatka.git
cd Shvatka
python --versiongit clone はインターネットからソースコードをまるごと手元にコピーするコマンドです。最後の行で Python のバージョンが 3.13.x と表示されることを確認してください。
Step 2: パッケージをインストールする
pip install uv
uv syncpip install uv で高速パッケージ管理ツール「uv」を導入します。続く uv sync は uv.lock（依存関係の一覧を固定したファイル）を読み込み、必要なライブラリ（ソフトの部品）をまとめてインストールします。同じファイルを使うことで、誰の環境でも同じバージョンが揃う仕組みになっています。
Step 3: 設定ファイルを準備する
cp config_dist/config.yml config.yml
cp config_dist/ui.env .env
cp config_dist/logging.yml logging.ymlconfig_dist/ フォルダにサンプル設定が用意されています。cp はファイルをコピーするコマンドです。コピーした config.yml をテキストエディタで開き、Telegram Bot Token やデータベース接続情報を書き込んでください。
Step 4: Docker Compose で全体を一括起動する（推奨）
docker-compose up -dDocker Compose（ドッカーコンポーズ）は複数のサービスを一度に起動・管理するツールです。このコマンド一つで、Nginx（外部からのアクセスを仕切るソフト）・アプリケーションサーバー・その他必要なサービスがすべて立ち上がります。Nginx の設定は nginx/app.conf で変更できます。
Step 5: コンポーネントを個別に起動する（開発・確認時）
# Telegram ボットだけを起動する場合
python -m shvatka.tgbot
# REST API サーバーだけを起動する場合
python -m shvatka.api開発中や動作確認だけしたいときは、ボットと API をそれぞれ単独で起動することもできます。まずボットを起動して Telegram から話しかけてみると、一番早く動作が実感できます。
デモについて
Shvatka は Telegram Bot Token・データベース・各種認証情報が必要なサーバーアプリケーションです。ブラウザ上だけで完結するオンラインデモは構造上提供されていません。実際に動かすには、Telegram で @BotFather にアクセスして Bot Token を取得し、自前のサーバーまたはローカル環境（自分のパソコン）にデプロイする必要があります。
動かしてみた
リポジトリを解析して、構成ファイルとコードの内容を確認しました。実際の動作の前に知っておくと役立つ情報をまとめます。
確認できた構成の概要
| ファイル／フォルダ | 役割 |
|---|---|
shvatka/__main__.py | アプリのエントリポイント（起動の入り口） |
shvatka/main_factory.py | 依存注入（部品の組み立て）を担うファクトリ |
docker-compose.yml | 本番デプロイ用のサービス定義 |
nginx/app.conf | Nginx リバースプロキシの設定 |
uv.lock | 依存関係を固定するロックファイル |
.python-version | 開発時の Python バージョンを明示するファイル |
テストは tests/conftest.py を起点に pytest（パイテスト）で管理されており、PyCharm（パイチャーム）という IDE（統合開発環境）向けの実行構成も用意されています。パッケージとして uv や pip でインストールできる形式（pyproject.toml ベース）に整備されていることも確認できました。
試す前に知っておくとよいこと
- Python は 3.13 以上、3.15 未満 が必須です。それ以外のバージョンではインストールが通りません。
pyenv（パイエンブ）などのバージョン管理ツールで対象バージョンを用意しておくと確実です。- Docker を使う場合は、Docker Desktop（Windows/Mac）または Docker Engine（Linux）が事前に必要です。
- Telegram Bot Token がないとボットを起動できないため、@BotFather での取得を先に済ませておきましょう。
はじめの一歩 — 最初にやること
初めてセットアップするときは、次の順番で進めると迷いにくいです。
- Python 3.13 の準備:
pyenv install 3.13.0などで対象バージョンをインストールしておく。 - Telegram Bot Token の取得: Telegram アプリを開き、検索欄で「@BotFather」を探してコマンドを送り、Token（長い文字列）を控える。
- config.yml への Token 記入:
config_dist/config.ymlをコピーして Token をセットする。一番重要な設定なので先に済ませる。 uv syncで依存解決: ロックファイルに従って全ライブラリを自動インストール。手動でバージョンを探す必要なし。python -m shvatka.tgbotでまず起動: Telegram でボットに話しかけて、反応が返ってきたら成功。- 本番運用は
docker-compose up -d: 全コンポーネントが一括起動するため、サーバーへのデプロイが格段にシンプル。
用語とポイント解説
схватка（シュヴァトカ） ロシア語で「格闘・争い」を意味する単語で、都市型チームクエストゲームの形式名でもあります。かんたんに言うと、複数チームが夜の街を舞台にチェックポイントを巡って謎を解く、アウトドア競技ゲームのことです。ロシア・CIS 圏で長年親しまれており、このプロジェクトはその運営をデジタル化するために作られました。
Telegram Bot API Telegram（テレグラム）が公開している、ボットを動かすための接続仕様（API）です。かんたんに言うと、Telegram のメッセージ機能を使って自動応答するプログラムを作るための「窓口」です。HTTP ポーリング（定期的に問い合わせる方式）または Webhook（メッセージが来たら即座に通知される方式）の2種類で動作します。
REST API
HTTP 通信を使って外部プログラムとデータをやり取りする設計方式です。かんたんに言うと、「このアドレスにアクセスすればこのデータが返ってくる」というルール集のようなものです。Shvatka の shvatka.api モジュールがこの役割を担い、外部の管理ツールやダッシュボードと連携できます。
uv（ユーブイ）
Rust（ラスト）というプログラミング言語で書かれた、超高速な Python パッケージ管理ツールです。かんたんに言うと、pip（ピップ）という標準のインストールツールの高速版で、依存関係の解決が従来より大幅に速くなります。Shvatka では uv.lock というファイルで依存関係を固定し、誰がインストールしても同じ環境が再現されます。
pyproject.toml（パイプロジェクトトムル）
Python プロジェクトの標準設定ファイルです。かんたんに言うと、「このプロジェクトに必要なライブラリの一覧と、対応する Python のバージョン範囲」を一か所に書いておくファイルです。PEP 517/518 という国際的なルールに基づいており、pip や uv はこのファイルを読んで自動的に必要なものをインストールします。
Docker Compose（ドッカーコンポーズ）
複数の Docker コンテナ（仮想の箱）を一つの設定ファイルで定義し、まとめて起動・停止・管理するツールです。かんたんに言うと、「アプリ本体・データベース・Nginx を一括で動かす司令書」のようなものです。Shvatka の docker-compose.yml を使えば、コマンド一行で全サービスが起動します。
Nginx リバースプロキシ（エンジンエックス）
外部からの HTTP/HTTPS リクエストを受け取り、内部のアプリケーションサーバーに転送するソフトウェアです。かんたんに言うと、「玄関の受付係」のような役割で、SSL（暗号化通信）の処理もここで担います。Shvatka では nginx/app.conf に設定が書かれており、本番環境での安全な通信を実現します。
pytest（パイテスト）
Python の標準的なテストフレームワーク（テストを自動化するための道具）です。かんたんに言うと、コードが正しく動くかどうかを自動でチェックするプログラムのことです。Shvatka では tests/conftest.py を起点に整備されており、PyCharm 向けの実行設定も用意されているため、IDE からすぐにテストを走らせることができます。
セルフホスト クラウドサービスの代わりに、自分のサーバーやパソコンにアプリケーションを直接インストールして運用することです。かんたんに言うと、「他社のサービスに頼らず、自分の環境で動かす」運用スタイルです。参加者データが外部に出ないため、プライバシー面でも安心して使えます。
活用例
- リアル脱出ゲーム形式のイベント: 参加者が Telegram でヒントを受け取りながら市街地を巡る、本格的な謎解きイベントの運営基盤として直接使用できます。チェックポイントの報告も Telegram で完結するため、スタッフの配置を最小限にできます。
- 企業のチームビルディング研修: 社内スキャベンジャーハントを完全デジタル化できます。紙の問題用紙も専用アプリも不要になり、全員が日常使いの Telegram で参加できるので導入障壁が低いです。
- 大学サークルの新入生歓迎イベント: キャンパスや周辺エリアを舞台にした謎解きゲームを低コストで開催できます。参加人数が増えても追加費用はかからず、自前サーバーで継続運用できます。
- Python 学習者のリファレンス実装: Telegram Bot・REST API・Docker Compose・uv という現代的な技術スタックが一つのリポジトリに凝縮されており、実際に動くコードを読みながら学べる教材として活用できます。
- コミュニティイベントのデジタル化: 地域のボランティア活動や趣味グループの集まりでのゲームイベントを、Telegram ボットで無料かつ手軽に進行管理できます。
ぜひ都市型の謎解きイベント主催や Python バックエンド学習のリファレンスなどに活用してみてはいかがでしょうか。