054 地下商人の帰還 / 五段階Pyxel教材
Python 3.11以上、Pyxel 2.9.9。価格は架空のゲーム規則です。
各01〜05の.pyは一つだけコピーして起動可能。原作、前段階、画像、音声、ネット接続は実行時不要。
日本語の解説はLESSON.md、段階データはlessons.json、相違点はlesson_meta.json。

Windows PowerShell
  教材フォルダーを開きます。空白や日本語のパスは引用符で囲みます。
  cd "C:\作業\地下商人 教材"
  py -3.11 -m venv .venv
  .\.venv\Scripts\python.exe -m pip install -r requirements.txt
  .\.venv\Scripts\python.exe 01_prices.py
  .\.venv\Scripts\python.exe 05_undo_forecast.py
  .\.venv\Scripts\python.exe -B test_stages.py
  3.12などを使う場合は利用中の3.11以上のバージョンを指定します。
  activate不要なのでPowerShellの実行ポリシーを変更する必要はありません。

macOS / Linux Terminal
  cd "/好きな場所/地下商人 教材"
  python3 --version
  python3 -m venv .venv
  .venv/bin/python -m pip install -r requirements.txt
  .venv/bin/python 01_prices.py
  .venv/bin/python 05_undo_forecast.py
  .venv/bin/python -B test_stages.py
  python3が3.11未満なら、インストール済みの3.11以上のpythonを指定します。

作業は各コマンドが成功してから次へ進めます。初回のpipだけネット接続が必要です。
教材の検証作業では既存のPyxel環境を利用し、新しいインストールは行っていません。

操作
  左右: 荷台の枠。Z: 売る／積む／交換元と先の指定。
  04/05の上下: 箱または売買のメニュー。Space: 03以降、次の滞在先へ。
  X: 03/04は交換元指定の取消。05は取消を優先し、それ以外は最後の確定をUndo。
  R: 初期化。Esc: 終了。確定後はキーを全て離します。R以外の複数同時押しは拒否し、全解放まで待ちます。
  Rは入力待ち中なら他の押下より優先。ただし確定後・複数キー拒否後の解放待ち中はRも待ちます。
  M1/M2という価格欄は市場1/2、枠上部のM1/M2はきのこのIDです。
  目標未満のRETURNEDも無事帰還。勝手に残りの荷物が売られることはありません。

よくあるエラー
  Python / pyが見つからない: Python 3.11以上の公式配布を用意しターミナルを開き直します。
  No module named pyxel: 実行用とpip用を同じ.venv内pythonに揃えます。
  venv作成が失敗: Linuxでは利用中Python用のvenvパッケージが別の場合があります。
    管理者やOSの公式案内で確認し、権限変更や無関係なスクリプト実行は不要です。
  File not found: 教材のあるフォルダーへcd。フルパスなら引用符で囲みます。
  No video device / SDL初期化失敗: 通常起動はデスクトップ画面のある環境が必要です。
    SSHやコンテナーでは下記headless検査を試せますが、GUI成功の証明にはなりません。
  ウィンドウで反応しない: ゲームを選んでキーを全て離してから押します。終了後はRか05のX。
  文字化け: 解説をUTF-8で開きます。PythonソースとJSONはUTF-8。ゲーム表示はASCIIです。
  開始位置が違う: 01/02/03は練習用固定荷台、04/05は空の出発箱が正しい動作です。

開発者向け検査（任意）
  python -B test_stages.py
  python -B tools/validate.py
  python 05_undo_forecast.py --headless-smoke --demo-checkpoint --screenshot "qa/local_check.png"
  --headless-smokeは自動終了。--demo-checkpointは合成キーで意味ある状態を作ります。
  05の--demo-previewは灯を捨てる前の価格低下を表示します。
  qaへの再実行で証拠ファイルが変わるためFROZEN_SHA256.jsonの固定版とは別の検査になります。
  原作比較: 環境変数PYXEL054_MODELに自分の原作model.pyの場所を指定してtest_stages.py。
  原作がなければその一テストだけskip。通常テストとゲームに原作は不要です。

権利と確認範囲
  LICENSEは原作LICENSE.txtの全文を変更せず保持。各.py先頭にも同じ全文のコメント。
  原作にあるNoto例外注記も保存していますが、この教材は字形データを配布しません。
  実施済み結果はQA.txt。Linux実Pyxelの自動描画と人の試遊を混同しません。
  Windows/macOS GUI、Python3.11実機、OSキーボード、ブラウザー、人の学習評価、音は未確認。

権利表記の補足: 教材にはNoto由来の字形データを含みません。原作LICENSEからの参照を辿れるよう、原文のSIL OFLをassets/NOTO-LICENSE.txtに文書だけ同梱しています。
