036 返せる弾丸 / 5段階の日本語Pyxel教材

必要: Python 3.11以上、Pyxel 2.9.9、通常プレイにはGUI表示環境。
各.pyは単独実行。外部素材、別の段階、原作フォルダーは不要です。
説明はLESSON.md、画面はASCIIと図形。配布時はLICENSEとassets/NOTO-LICENSE.txtも残してください。

Windows PowerShell
  cd "C:\教材の場所\036_return_bullets"
  py -3.11 -m venv .venv
  .\.venv\Scripts\python.exe -m pip install -r requirements.txt
  .\.venv\Scripts\python.exe -B 01_motion.py
  .\.venv\Scripts\python.exe -B 05_controller.py
Python 3.12以上の場合は最初のpy -3.11を使う版に合わせてください。

macOS / Linux（python3 --versionで3.11以上を確認）
  cd "/教材の場所/036_return_bullets"
  python3 -m venv .venv
  .venv/bin/python -m pip install -r requirements.txt
  .venv/bin/python -B 01_motion.py
  .venv/bin/python -B 05_controller.py
activateは不要。同じ仮想環境のpython -m pipでインストールします。
別の作業フォルダーからも、Pythonと.pyの引用符付きフルパスで起動できます。

順序と完成範囲
01_motion.py      左右保持移動・Z保持射撃。敵/ダメージ/勝敗なし。
02_telegraph.py   確定した30tick予告、実弾、被弾/敗北。反射/勝利なし。
03_reflection.py  12tick反射、所有者、再使用と回復。コア/防壁/勝利なし。
04_barrier.py     原作A全ゲームルール。防壁の認証、コア破壊、生存勝利。
05_controller.py  原作の表紙・停止・全解放待ちと残した操作の優先順位。

操作
左右: 移動。両方保持は相殺。Z: 保持で24tickごとの普通弾。
X: 03以降、新しい押下で12tick反射（残量1、再使用36tick）。
R: リセット。後で全操作キーを一度離す。Esc: 終了。
05はSpace: 開始、P: 停止/再開、M: 表紙。場面変更後は全操作キーを離す。
05の優先順: 表紙処理→M→R→P→停止中→終了済み→通常プレイ。
原作の1/2/3編隊変更、結果N、F12は省略。通常プレイはAのみ。
原作同様、見える輪は半径17、反射判定は20です。二つを混同しないでください。

任意の検証（pythonを上の.venvの実行パスへ置き換える）
  python -B -m unittest -v test_stages.py
  python -B tools/render_qa.py
  python -B tools/check_freeze.py
純粋モデル/Controllerのテストは標準ライブラリのみ。実描画はPyxelを使います。
原作が別途ある場合だけの直接比較（読み取り専用）:
  python -B tools/verify_original.py "/原作の場所/036_return_bullets"
fixturesは不変の原作から抽出。通常プレイ/通常テストに原作は不要。

実Pyxel headlessの単体例（合成入力、実OSキー入力ではない）
  python -B 05_controller.py --headless --demo --frames 180 --screenshot complete.png --report complete.json
  python -B 01_motion.py --headless --frames 12 --screenshot initial.png
--replay-jsonはUTF-8 JSONの配列。例: [["SPACE"],[],["Z","X"],["Z"]]
各配列は一フレームで保持するキー名。新押下は直前との差から計算します。
--demoと--replay-jsonは同時指定不可。--framesは12以上。
出力の相対パスは起動時の作業フォルダー基準。親フォルダーは先に作成してください。

トラブル
- No module named pyxel: 実行中と同じ.venvのpython -m pipでrequirements.txtを入れる。
- Python構文/型注釈エラー: 3.11以上か確認。
- Linuxでvenv不可: OSのPython venvサポートを利用可能にしてから再実行。
- ウィンドウが出ない: GUI表示環境を確認。headlessは描画技術試験で普通のプレイ画面の代わりではありません。
- R/P/Space後に動かない: ZやXを含め全操作キーを離し、ウィンドウへフォーカスを戻す。
- Xで輪が出ない: 押し直しか、残量/REUSE WAITを確認。早押しの保持は予約になりません。
- Zだけでコアが減らない: 04/05は閉壁です。敵弾を一発返して壁を開けます。
- 03で緑弾がコアを通過する: コア衝突は04で追加するため正常。
- 保存エラー: 書き込み可能な既存の親フォルダーを指定。
- 文書が文字化け: UTF-8で開く。ゲーム画面は日本語字形を使用しません。

検証限界
実Pyxel2.9.9ヘッドレス、合成Controller入力、単一ファイルの日本語/空白パスと別CWDを確認。
人間の試遊、実OS入力、Windows/macOS GUI、ブラウザー、音声は未検証。
インストール手順の記載は各OS実機での新規インストール成功を保証しません。
音は未実装。原作既存デモ/試験は教材の新規検証には数えません。
再描画や編集後にfreezeが不一致になるのは正常。配布時の確認記録はQA.txt。
