042 小さな渡し船 / 5段階のPyxel教材

共通要件: Python 3.11以上、Pyxel 2.9.9。
標準ライブラリとPyxelだけを使います。画面はASCII、解説・コメントは日本語です。
各01〜05.pyは単独で動き、原作や前段階、画像ファイルへの依存はありません。
最初から完成版を読みたいときは05_undo.py。

Windows (PowerShell / コマンドプロンプト)
1. ZIPを完全に展開し、ターミナルで展開した042_small_ferryフォルダーへ移動。
   例: cd "C:\Users\yourname\Downloads\042_small_ferry"
2. Python 3.11以上をインストールしてあることを確認。
   py -3 --version
3. 仮想環境を作り、このフォルダー内へPyxelを導入。
   py -3 -m venv .venv
   .venv\Scripts\python.exe -m pip install -r requirements.txt
4. 最初の段階を起動。
   .venv\Scripts\python.exe 01_ownership.py
   以後02_travel.py、03_tides.py、04_arrivals.py、05_undo.pyへ置き換えます。
PowerShellの実行ポリシーを変更する必要はありません。activateせず上記pythonを使います。

macOS / Linux (ターミナル)
1. 展開したフォルダーへ移動。
   例: cd "$HOME/Downloads/042_small_ferry"
2. Pythonの版を確認してから仮想環境を作ります。
   python3 --version
   python3 -m venv .venv
   .venv/bin/python -m pip install -r requirements.txt
3. 起動。
   .venv/bin/python 01_ownership.py
   最終段階: .venv/bin/python 05_undo.py

別フォルダーから起動する場合
Windows: "C:\path\042_small_ferry\.venv\Scripts\python.exe" "C:\path\042_small_ferry\05_undo.py"
PowerShellでは先頭に & を付けて引用した実行ファイルを呼びます。
macOS/Linux: "/path/042_small_ferry/.venv/bin/python" "/path/042_small_ferry/05_undo.py"
実際のフォルダーの場所へ置き換え、空白や日本語を含むパスは引用符で囲みます。

操作
矢印: 乗客・便を順に選択。端を越えると先頭/末尾へ回ります。
Z: 選んだ客の乗降、または便を実行。乗降は時間0。
Space: 一刻待機（02以降）。X: 一判断Undo（05のみ）。R: 全初期化。Esc: 終了。
矢印/Z/Space/Xを含む複数の操作キーが同時に押されていたら、その入力を拒否します。
拒否した後も、すべての操作キーを離すまで次の操作を受け付けません。
例: 左+右を拒否→左を残してZを押しても乗船しません。全キーを離してからZで乗船します。
Rの新押しだけは最優先です。同時押し中や入力待ち中でも初期化し、その後も全キーを離すまで待ちます。
05のXも単独入力が必要です。X+ZではUndoしません。EscはPyxelの終了キーです。

学習順
01_ownership.py: Hの4人を乗せ降ろし。時刻は進まず、定員3を調べる。
02_travel.py: Bの出現データ、全航路一刻、手動降船。まだ成功判定はない。
03_tides.py: 浅瀬一刻・深水二刻、出発時の潮。降船はまだ手動。
04_arrivals.py: 原作Bの自動降船、到着記録、全員を届けて成功。
05_undo.py: 時間0も一便も全状態Undo、選択操作の結果の予告。
詳細な手順・改造課題はLESSON.md。構造化した同内容はlessons.json。

うまく起動しないとき
- py/python3が見つからない: Python 3.11以上を公式配布で導入し、端末を開き直す。
- Pythonが3.10以下: 3.11以上を選び直して.venvを作成する。
- No module named pyxel: 起動に使う.venvのpythonで -m pip install -r requirements.txt を実行する。
  他のpythonに入れたPyxelは、この仮想環境には入りません。
- pipやダウンロードに失敗: 接続・プロキシ・対応するPython/Pyxelのホイールを確認。
  版を無断で変更せず、表示されたエラーを控えます。
- Linuxでvenv/ensurepipがない: OS公式のPython venvパッケージの案内を確認する。
- 窓が開かない/SDLエラー: GUIが使える端末で実行する。サーバー上なら下記headlessは検証専用。
- ダブルクリックですぐ消える: ターミナルから実行してエラーを読む。
- 文字化け: 本文・PythonはUTF-8。エディターもUTF-8で開く。ゲーム画面はASCIIのみ。
- 音が出ない: この教材は無音です。

検査（.venvのpythonを使用）
python -B -m unittest -v test_stages
python -B qa/run_checks.py
python -B qa/render_input_gate.py
python 05_undo.py --headless-smoke --demo-checkpoint --screenshot qa/manual-check.png --state-log qa/manual-check.json
headlessは自動終了する実エンジン検査で、通常の遊び方ではありません。
原作比較の再実行は任意。別に持つ原作フォルダーをPYXEL042_ORIGINALへ設定してください。
未設定でも配布フォルダー単独のテストは動き、原作依存2件だけskipします。
qa/compare_original.py --original "元の042_small_ferryフォルダー" でfixtureを再採取できます。
原作自体は変更しません。fixtureを更新したらテスト・検証・freezeをやり直します。

検証範囲はQA.txt。Linuxの実Pyxel初期画面・合成キー到達点を確認しています。
Windows/macOSのGUI、OS入力、人の遊びや学習の評価、ブラウザー、音声は未確認です。
LICENSEは原作通知の完全コピー。各段階にも同文コメントを保持しています。
