| # GAHAKU EXAM 仕様書（実装準拠 v1.2） |
|
|
| ## 1. 概要 |
|
|
| プレーヤーにランダムで1つの英単語（お題）を与え、プレーヤーはPyxelベースのドット絵エディタでその単語を表現する。 |
| 描いたドット絵をAIへ入力し、推論結果の上位5件にお題語が含まれていれば成功とする。 |
|
|
| ゲームの目的は「できるだけ少ないドット数でAIに正解させること」。 |
|
|
| ## 2. 対象プラットフォーム |
|
|
| - デプロイ先: Hugging Face Spaces |
| - SDK: Gradio |
| - 描画エンジン: Pyxel（pyxel.js経由でWeb実行） |
| - 推論: Hugging Face Inference API（VLM優先 + フォールバック） |
|
|
| ## 3. 用語定義 |
|
|
| - お題: プレーヤーに提示される英単語 |
| - キャンバス: ドット絵を描く領域（16x16） |
| - ドット数: 背景色以外で塗られたセル数 |
| - 試行: 1回のAI判定リクエスト |
| - ラウンド: 1つのお題に対する挑戦単位 |
|
|
| ## 4. ゲームルール |
|
|
| 1. ゲーム開始時に英単語を1つランダム出題する。 |
| 2. プレーヤーは24色パレットを使い、マウスまたはタッチでドット絵を描く。 |
| 3. Pyxel内の `EXPORT` で描画データを `window.__PYXEL_PAYLOAD` に保存する。 |
| 4. Gradio側の `Sync from Pyxel`（日本語UIでは `Python側へ取り込む`）で受信確認できる。 |
| 5. `Judge with AI`（日本語UIでは `AIで判定する`）でAI判定を行う。 |
| 6. AI上位5候補にお題語が含まれる場合は成功。 |
| 7. 含まれない場合は失敗カウントを1増やす。 |
| 8. 失敗が3回に達した時点でラウンド失敗（ゲームオーバー）。 |
| 9. `Next Round`（日本語UIでは `次のラウンド`）で次ラウンドへ進む。 |
|
|
| ## 5. 機能要件 |
|
|
| ### 5.1 お題出題 |
|
|
| - お題辞書（英単語リスト）からランダムに1語を選択。 |
| - 同一ラウンド中はお題を固定。 |
| - 前ラウンドと同じ単語は可能な限り連続しないよう回避（候補数が2語以上の場合）。 |
|
|
| ### 5.2 ドット絵エディタ |
|
|
| - キャンバスサイズ: 16x16セル（固定） |
| - 画面サイズ: `pyxel.init(310, 220)` |
| - パレット: 論理24色 |
| - 実行環境が16色のみ対応の場合: |
| - 17〜24色相当はディザリングで近似表示 |
| - 入力方式: |
| - マウス: クリック/ドラッグ |
| - タッチ: タップ/スワイプ |
| - 基本ツール: |
| - ペン |
| - 消しゴム |
| - 全消去 |
| - EXPORT |
| - 画面表示: |
| - 使用ドット数（リアルタイム） |
| - 操作ガイド（`TOUCH/DRAG TO DRAW`） |
|
|
| ### 5.3 AI判定 |
|
|
| - 入力: キャンバス画像（PNG, 224x224へ最近傍拡大） |
| - 推論フロー（優先順）: |
| 1. VLMチャット補完（候補モデルを順に試行） |
| 2. Zero-shot image classification（provider live のみ） |
| 3. 画像分類モデル（`google/vit-base-patch16-224`） |
| - provider live 判定: |
| - Hugging Face model info の `inferenceProviderMapping` を参照 |
| - モデル×タスク結果をキャッシュ |
| - 出力: |
| - 上位5候補（`label`, `score`） |
| - VLM経路では順位ベース擬似スコアを付与 |
| - 正誤判定: |
| - ラベルとお題語を正規化（小文字化、記号除去、空白正規化） |
| - 上位5件内に一致があれば正解 |
|
|
| ### 5.4 スコアリング |
|
|
| - 成功時にラウンドスコアを確定。 |
| - 計算式: |
|
|
| `score = max(0, BASE_SCORE - DOT_PENALTY * used_dots - MISS_PENALTY * miss_count)` |
|
|
| - 定数: |
| - `BASE_SCORE = 1000` |
| - `DOT_PENALTY = 8` |
| - `MISS_PENALTY = 120` |
|
|
| ### 5.5 失敗条件 |
|
|
| - 不正解が3回でラウンド失敗。 |
| - 失敗時もAI上位5結果は表示される（取得できた場合）。 |
|
|
| ### 5.6 多言語対応（実装済み） |
|
|
| - UI言語: 日本語 / 英語 |
| - 言語切替: Gradioのラジオボタン |
| - 切替対象: |
| - イントロ文 |
| - ボタンラベル |
| - テキスト/JSONのラベル |
| - ラウンド情報表示 |
| - ステータスメッセージ |
| - 既定言語: 英語 |
|
|
| ### 5.7 判定演出（実装済み） |
|
|
| - Pyxel側に演出状態を保持（`idle / judging / success / fail`）。 |
| - `Judge with AI` 押下時に `judging` へ遷移。 |
| - `Next Round` 押下時に `idle` へリセット。 |
| - Pyxel上に簡易アニメーションと文言を表示: |
| - `AI JUDGING...` |
| - `CORRECT!` |
| - `NOT YET` / `TRY AGAIN` |
|
|
| ## 6. 画面仕様（現行） |
|
|
| ### 6.1 メイン画面 |
|
|
| - サイドバー（Spaces時のみ）: |
| - Loginボタン |
| - ヘッダ行: |
| - 左: タイトルと手順 |
| - 右: 言語トグル（日本語/English） |
| - エディタ表示: |
| - Pyxelキャンバス埋め込み |
| - ヘルプ文 |
| - ラウンド情報: |
| - Round / お題(Target) / 状態 / ミス / 使用ドット / ラウンドスコア / 合計スコア |
| - 操作行: |
| - `Sync from Pyxel` |
| - `Judge with AI` |
| - `Next Round` |
| - 情報表示: |
| - Statusテキスト |
| - Received JSON（開発表示） |
| - AI Top 5 |
|
|
| ### 6.2 ボタン活性 |
|
|
| - `Next Round` は常時押下可能。 |
| - ラウンドが `success` または `fail` のとき、同一ラウンドへの再判定は拒否してメッセージを返す。 |
|
|
| ## 7. 状態管理 |
|
|
| ### 7.1 ラウンド状態（Gradio State） |
|
|
| - `round_id` |
| - `round_number` |
| - `target_word` |
| - `miss_count` |
| - `round_result`（`ongoing` / `success` / `fail`） |
| - `used_dots` |
| - `round_score` |
| - `total_score` |
| - `last_top5_predictions` |
|
|
| ### 7.2 UI補助状態 |
|
|
| - `lang_state`（`ja` / `en`） |
| - `window.__PYXEL_PAYLOAD`（Pyxel→Gradio受け渡し） |
| - `window.__AI_JUDGE_STATE`（演出状態連携） |
|
|
| ## 8. 外部連携仕様 |
|
|
| ### 8.1 Inference API |
|
|
| - 認証: |
| - Spaces: OAuthトークン優先 |
| - ローカル: `HF_TOKEN` 環境変数 |
| - 主な利用API: |
| - Chat Completions（VLM） |
| - Zero-shot image classification |
| - Image classification |
| - タイムアウト: |
| - provider確認: 10秒 |
| - リトライ: |
| - 同一モデルへの自動リトライはなし |
| - モデル切替フォールバックで継続 |
|
|
| ### 8.2 モデル選定 |
|
|
| - 第一候補VLM: `Qwen/Qwen3-VL-8B-Instruct` |
| - 代替VLM候補あり（provider liveのみ実行） |
| - Zero-shot候補: |
| - `openai/clip-vit-large-patch14` |
| - `openai/clip-vit-base-patch32` |
| - 最終フォールバック: |
| - `google/vit-base-patch16-224` |
|
|
| ## 9. 非機能要件 |
|
|
| - 操作性: |
| - PC/スマートフォン対応 |
| - Pyxel表示領域は `31:22` の比率で表示 |
| - セキュリティ: |
| - トークンはクライアントへ露出しない |
| - ロギング: |
| - 判定フローをコンテナログへ出力 |
| - 例: `judge_start`, `vlm_try`, `vlm_success`, `fallback_to_image_classification` |
|
|
| ## 10. 受け入れ基準（現行実装） |
|
|
| 1. ラウンド開始時に英単語がランダム表示される。 |
| 2. 24色・16x16のドット絵編集がマウス/タッチで可能。 |
| 3. `EXPORT` → `Sync from Pyxel` でJSON受信確認ができる。 |
| 4. `Judge with AI` 実行でAI上位5ラベルが表示される。 |
| 5. 上位5にお題語が含まれると成功判定になる。 |
| 6. 不正解3回で失敗終了になる。 |
| 7. 成功時スコアがドット数とミス数を反映して算出される。 |
| 8. 第一候補VLMが利用可能な場合はVLM経路で判定できる。 |
| 9. 第一候補VLMが利用不能でもフォールバック経路で継続判定できる。 |
| 10. 日本語/英語UI切替が機能する。 |
| 11. `Next Round` 押下で判定演出が `idle` にリセットされる。 |
|
|
| ## 11. 既知の制約 |
|
|
| - `Received JSON` は開発向け表示として常時表示される。 |
| - 演出の成功/失敗遷移は `status_box.change` フックに依存するため、接続経路やUI更新順によって見え方が変わる場合がある。 |
|
|
| ## 12. 今後拡張候補 |
|
|
| - 難易度別お題セット |
| - 制限時間モード |
| - ランキング機能 |
| - お題に対する禁止色/使用色制限 |
| - 複数ラウンド合計スコア制 |
| - 開発用表示（Received JSON）の表示切替 |
|
|
