備忘録

← トップページへもどる

このページの使い方

学習を進める中で出てきた疑問・つまずき・調べたことを、その都度ここに積み上げていきます。 あとから「あれ何だったっけ」となったときに戻ってくる場所です。 新しい項目は下に追記していきます。

Python について

Q. インデントはタブとスペースのどちらで書くべき？

A. 半角スペース 4 つを推奨します。タブだけで統一してあれば Python は正しく動くので、 現状のコードを慌てて直す必要はありません。ただし次の 2 つの理由から、早いうちに スペースへ寄せておくほうが安全です。

• 混ざると即エラーになる — タブとスペースが同じファイル内に混在すると TabError: inconsistent use of tabs and spaces で止まります。 解説ページからコードを一部コピーしたときなど、気づかないうちに混ざるのが厄介です
• Python の公式スタイル（PEP 8）がスペース 4 つ — 世の中のサンプルコードや ライブラリのソースもほぼこれに従っているため、読むときも書くときも揃っていると楽です

Q. self という名前は me などに変えてもいい？

A. 変えられます。self は Python の予約語ではなく、 「メソッドの 1 つめの引数」に慣習でつけているただの変数名です。 次のコードは実際に動きます（15 と表示されます）。

class Counter:
    def __init__(me, start):      # self ではなく me
        me.value = start

    def add(watashi, n):          # メソッドごとに名前が違ってもよい
        watashi.value += n

    def show(self):               # ここだけ self
        print("いまの値:", self.value)

c = Counter(10)
c.add(5)
c.show()                          # → いまの値: 15

ポイントは「名前が何か」ではなく「1 つめの引数である」ことです。 c.add(5) と書くと、Python が裏で Counter.add(c, 5) のように 呼び出し元のインスタンスを 1 つめの引数として自動で渡します。 受け取る側の名前は self でも me でも watashi でも、渡ってくる中身は同じです。

Q. __init__ の前後のアンダーバー 2 つには意味がある？

A. あります。前後をアンダースコア 2 つで挟んだ名前は、 「Python 本体が特別扱いする名前」という目印です。 これらは自分で呼ぶメソッドではなく、決まったタイミングで Python が勝手に呼ぶメソッドで、 特殊メソッド（マジックメソッド、ダンダーメソッド）と呼ばれます。

実際に動かすと、呼んでいないのに呼ばれることが確認できます。

class Team:
    def __init__(self, name, members):   # Team(...) で呼ばれる
        self.name = name
        self.members = members

    def __str__(self):                   # print(t) で呼ばれる
        return "チーム" + self.name

    def __len__(self):                   # len(t) で呼ばれる
        return len(self.members)


t = Team("A", ["山田", "鈴木", "佐藤"])
print(t)        # → チームA
print(len(t))   # → 3

__str__ も __len__ も、コードのどこにも「呼び出し」を書いていません。 print や len が裏で探しにきているのです。 App() で __init__ が呼ばれるのも、まったく同じ仕組みです。

なぜこんな変な見た目なのか

普通の名前とぶつからないようにするためです。 もし init という名前だったら、自分で「初期化用の init メソッド」を 作りたくなったときに衝突します。前後をアンダースコア 2 つで挟むことで、 「ここは Python 側が予約している領域」と見ただけで区別できるようにしています。

Q. 処理をどこで関数に分ければいい？ 分ける基準は？

A. 行数ではなく 「名前がつけられるか」 で決めます。 「この 5 行は何をしているか」を短い名前で言い切れるなら、それは関数にしてよいまとまりです。 逆に move_and_grow のように「〜と〜」でしか言えないなら、 まだ 2 つの仕事が混ざっているサインです。

分けどきの 4 つのサイン

    def update(self):
        self.make_flower()      # 花を作る
        self.move_flowers()     # 花を動かす
        self.move_hiyoko()      # ヒヨコを動かす

「主語が違う」の見つけ方

いちばん見落としやすいのがこれです。関数の名前は 花 の話をしているのに、 中身に ヒヨコ のルールが紛れ込んでいる、という状態です。

切り出すと、呼び出し側は 1 行で意図が読めるようになります。

HIYOKO_SCALE_MAX = 16   # ヒヨコの大きさの上限

    def grow_hiyoko(self):
        """ヒヨコを1段階大きくする（上限まで）"""
        self.hiyoko_scale = min(self.hiyoko_scale + 1, HIYOKO_SCALE_MAX)
        self.put_on_ground()

    # 呼び出し側（花の移動処理の中）
            if pyxel.pget(x + 1, y + 2) == pyxel.COLOR_YELLOW:
                self.grow_hiyoko()      # ヒヨコが大きくなる
                continue

名前のつけ方

• 動詞 + 対象で揃える — make_flower / move_flowers / move_hiyoko / grow_hiyoko。規則が一貫していると、 中身を読まずに役割が推測できます
• 単数・複数を使い分ける — 1 個作る make_flower は単数、 全部を動かす move_flowers は複数。あとで「1 個だけ動かす関数」が 欲しくなったときに名前が空きます
• 16 のような数字は定数にする — 名前がつくと、 その数字が何のための値なのかがコードから読み取れます

逆に、分けてはいけないとき

たとえば pyxel.btn() による入力の読み取りが move_hiyoko と make_flower の両方に散らばっていても、この規模なら問題ありません （Pyxel 付属のサンプルもこの書き方です）。 「タイトル画面では入力を無視したい」のように実際に困りごとが起きてから、 入力係の関数へまとめれば十分です。

Q. / と // はどう使い分ける？

A. / はふつうの割り算で、答えはつねに小数（float）になります。 // は切り捨て除算で、小数点以下を捨てます。 「1 きざみの整数でないと意味がないもの」には //、 「途中の値にも意味があるもの」には / を使う、というのが基本の分かれ道です。

使い分けの目安

実例：ヒヨコの足元が地面に沈んだ話

put_on_ground() を最初こう書いていました。 hiyoko_scale は花を当てるたびに 0.2 ずつ増えるので、途中から小数になります。

self.hiyoko_y = GROUND_Y - HIYOKO_HEIGHT * (self.hiyoko_scale + 1) // 2

すると足元の位置が地面（GROUND_Y = 111）から最大 0.8 ドットずれます。

// で切り捨てると 引く量が減る ので、Y 座標が下へずれて足元が地面へ埋まります。 111.6 や 111.8 は描画時に四捨五入されて 112、 つまり地面のタイルに 1 ドット食い込んだ状態です。 大きくなるたびに沈んだり戻ったりするので、見た目がわずかに揺れます。

つまずきやすい 2 点

16 * (1.2 + 1) // 2      # → 17.0   最後に切り捨て
16 * ((1.2 + 1) // 2)    # → 16.0   先に切り捨てるとこうなる

-7 // 2      # → -4   小さいほうへ
int(-7 / 2)  # → -3   0 に近いほうへ

Q. 関数の定義は、呼び出す行より下にあってもいい？（C では定義が先）

A. Python は関数定義の位置に制限がありません。 update() の中で self.move_boy() を呼び、move_boy() の定義は その下にある——という candy_hunt.py の書き方で問題ありません。

理由は「名前をいつ探すか」が C と Python で違うからです。

Python の def は「この名前で、この中身を覚えておいて」という命令文です。 関数の中身はそのとき読まれません。中の move_boy という名前を探しにいくのは、 update() が実際に呼ばれた瞬間です。そのときには ファイルはすでに最後まで読み終わっていて、move_boy も登録済みなので見つかります。

ただし、位置が効く場面が 3 つある

「制限がない」のは関数の中身の話です。次の 3 つは ファイルを読み込んだ瞬間に実行されるので、順番どおりに書く必要があります。

App()          # ← 先頭に置くと…

class App:
    ...

# NameError: name 'App' is not defined

def f(size=BOY_SIZE):    # ← この行を読んだ時点で BOY_SIZE を探す
    print(size)

BOY_SIZE = 8             # 遅すぎる

# NameError: name 'BOY_SIZE' is not defined

class App:
    size = BOY_SIZE      # ← メソッドの外なので、すぐ実行される

BOY_SIZE = 8

# NameError: name 'BOY_SIZE' is not defined

自由なぶん、注意すること

def rarely_used():
    print(mistyped_name)     # 存在しない名前

print("読み込みは通る")       # ← ここまでは何ごともなく動く
rarely_used()                # ← 呼ばれて初めて NameError

では、どう並べるのがよいか

順番は自由なので、読みやすさで決めます。よくあるのは次の並べ方です。

• 呼ぶ側を上、呼ばれる側を下 — update() を読めば全体の流れが分かり、 細かい中身は下に読み進めればよい。candy_hunt.py はこの形です
• 関係の深いものを近くに置く — move_boy() と check_candy() のように、 update() から呼ばれるものをそのすぐ下にまとめる
• 定数はいちばん上 — BOY_SIZE などは、上の「例外 2・3」に引っかからないよう ファイルの先頭にまとめておくと安全です

Pyxel について

Q. .pyxres ファイルの中身は読める？ 何が入っている？

A. 読めます。.pyxres は独自の暗号化バイナリではなく、 中身が 1 個の TOML テキストファイルだけの ZIP です。 拡張子を .zip に変えれば、普通の解凍ソフトでも開けます。

import zipfile

z = zipfile.ZipFile("step0/assets.pyxres")
print(z.namelist())
# → ['pyxel_resource.toml']

print(z.read("pyxel_resource.toml").decode("utf-8")[:200])

取り出した pyxel_resource.toml は、こんな中身です。

format_version = 1

[[images]]
width = 256
height = 256
data = [[0, 0, 0, 0, 0, 0, 6, 7, 7, 6, 0], [0, 0, 0, 6, 6, 6, 6, 7, 7, 6, ...

[[tilemaps]]
...

[[sounds]]
...

[[musics]]
...

[[images]] の data は、1 行が画像の 1 ライン、 数字 1 つがドット 1 個のパレット番号です。 上の 6, 7, 7, 6 は、宇宙船のてっぺんの 「■6 = 淡い青、■7 = 白」 の並びそのものです。右端の連続する 0（黒＝未使用）は省略されるので、 行ごとに長さが違って見えます。

Q. 座標や速さに小数を使ってもいい？ SHIP_SPEED = 0.2 でもちゃんと動いたのはなぜ？

A. 使えます。Pyxel の描画命令は座標を小数（float）で受け取り、 画面に出すときにいちばん近いドットへ四捨五入します。 付属の型定義ファイル（pyxel/__init__.pyi）を見ると、はっきり float と書いてあります。

def blt(
    x: float,
    y: float,
    ...

どう丸められるかを実際に試した結果が次です （pyxel.Image に pset して、どのドットが点いたかを調べたもの）。

四捨五入で、.5 はつねに切り上げです（切り捨てではありません）。

なぜ 1 より遅くなるのか

SHIP_SPEED = 0.2 にすると、self.ship_x は 0.2 ずつ、小数のまま変わっていきます。画面に出るのは丸めたあとの整数なので、 値が 1 ドットぶん動くまでに 5 フレームかかります。 1 秒 = 30 フレームなので、1 秒あたり 6 ドット。SHIP_SPEED = 1（1 秒に 30 ドット） と比べて、ちょうど 5 分の 1 の速さです。

Q. blt() の scale で絵を大きくしたら位置がズレた。XY はどう計算する？

A. scale は 絵の中心を固定したまま拡大します。 blt() に渡す x, y は「scale が 1 のときの左上」を指す座標のままで、 scale を上げるとそこから上下左右へ均等に絵が広がります。

4×4 の絵を blt(10, 10, img, 0, 0, 4, 4, None, 0, scale) で描き、 実際に色が付いたドットを pget で数えた結果です。

どの scale でも中心は (12, 12) のまま動いていません。 幅をマイナスにして左右反転させても（w = -4）、結果はまったく同じでした。

足元を地面に固定したいとき

キャラクターが大きくなっても地面に立っているように見せたい、というのはよくある要求です。 「下端＝地面のY」になるよう、上の式を y について解きます。

中心Y + 高さ × scale ÷ 2 = 地面Y
       ↓  中心Y = y + 高さ ÷ 2 を代入して整理

y = 地面Y − 高さ × (scale + 1) ÷ 2

x は補正が要りません。横方向の中心は scale によらず保たれるので、 x を触ると逆にズレます。直すのは y だけです。

高さ 16 ドット・地面 Y = 111 で計算するとこうなります。

コードの形

「ぶつかった瞬間に差分を引く」のではなく、scale から毎回 Y を計算し直す形にしておくと、 あとで縮ませたりリセットしたりしても崩れません。

GROUND_Y = 111          # ヒヨコの足元を置くY座標

    def put_on_ground(self):
        """ヒヨコの足元が地面につくようにY座標を決める"""
        self.hiyoko_y = GROUND_Y - HIYOKO_HEIGHT * (self.hiyoko_scale + 1) / 2

あとは大きさを変えたところで呼ぶだけです。

        self.hiyoko_scale = 1           # 初期化のとき
        self.put_on_ground()

        self.hiyoko_scale = min(self.hiyoko_scale + 0.2, HIYOKO_SCALE_MAX)  # 花にぶつかって大きくなったとき
        self.put_on_ground()

Q. 1 つのフォルダに複数の作品がある。pyxel package で別々にパッケージ化できる？

A. できますが、そのままだと出力が上書きされます。 pyxel package は「フォルダの中身を丸ごと」ZIP に詰め、 どれを起動スクリプトにするかを記録するだけのコマンドです。 出力ファイル名は フォルダ名で決まるため、同じフォルダを 2 回パッケージ化すると 2 回目が 1 回目を警告なしに上書きします。

pyxel package step0-learning step0-learning/hiyoko_anime.py
  → step0-learning.pyxapp    起動 = hiyoko_anime.py

pyxel package step0-learning step0-learning/fish_clock.py
  → step0-learning.pyxapp    起動 = fish_clock.py　← 同じ名前で上書き

中身も毎回フォルダ内の全ファイルが入ります。作品が 2 つあれば、 どちらの .pyxapp にも相手のスクリプトとリソースが同梱されます。

解決：作品ごとにサブフォルダを切る

APP_DIR のいちばん下のフォルダ名が出力名になります。 作品ごとにフォルダを分ければ、名前は自動で分かれ、中身も必要なファイルだけになります。

step0-learning/
├── hiyoko_anime/
│   ├── hiyoko_anime.py
│   └── learning_bgm.pyxres
└── fish_clock/
    ├── fish_clock.py
    └── fish_clock.pyxres

pyxel package step0-learning/hiyoko_anime step0-learning/hiyoko_anime/hiyoko_anime.py
pyxel app2html hiyoko_anime.pyxapp

pyxel package step0-learning/fish_clock step0-learning/fish_clock/fish_clock.py
pyxel app2html fish_clock.pyxapp

実測したサイズの差です（作品 2 つ・pyxel 2.9.9）。

Q. 「分が 00 の間ずっと」のような条件で、1 回だけ処理したい

A. 「前回の値」を覚えておき、変わった瞬間だけ動かします。 条件そのものを厳しくしても解決しません。update() は 1 秒に fps 回呼ばれるので、 「分が 00」のような条件はその 1 分間ずっと真だからです。

時報で起きたのがこれでした。fps=15 なので play_chime() が 900 回呼ばれ、 pyxel.play() は呼ぶたびに先頭から鳴らし直すため、 チャイムの出だしだけが延々と繰り返される音になります。

書き方

__init__() で「前回の値」を用意します。

        self.last_minute = datetime.now().minute    # 前回のフレームで見た「分」

update() では、値が変わったときだけ中を通します。

        # 分が変わった瞬間だけ判定する
        if self.minute != self.last_minute:
            if self.minute == 0:
                self.play_chime()
            self.last_minute = self.minute      # これが無いと 1 分間鳴り続ける

この形は時報だけのものではありません。 「HP が 0 になった瞬間にゲームオーバーの音を鳴らす」「スコアが 1000 を超えた瞬間に演出を出す」など、 状態がずっと続くのに処理は 1 回でいい場面すべてで同じ書き方をします。

Q. 音をもっと長く伸ばしたい。SPEED が 99 までしか入らない

A. SPEED を上げるのではなく、同じ音を複数ステップ並べます。 そのうえで EFX は最後のステップだけに付けるのがコツです。

SPEED は「1 音の長さ」で、120 で 1 音 1 秒。エディタの入力欄は 2 桁なので 99（＝0.825 秒）が上限になります。長さが足りないときは音の数を増やすのが素直な解決です。

エディタでの操作は「同じ音を 4 回入力し、EFX 欄は 4 つ目だけ F」です。 同じ高さの音が続くので途切れず、最後だけきれいに減衰します。 もっと伸ばしたいときは音の数を増やします（8 つ並べれば約 4.5 秒）。

EFX で減衰の始まりを変える

並べる方法と組み合わせて「4 つ並べて最後だけ H」にすると 9999999999999999997300000 となり、いちばん長く伸びます。

どうしても SPEED を大きくしたいとき

99 の制限はエディタの入力欄が 2 桁だからで、値そのものに上限はありません。 pyxel.load() の直後にコードから書き換えられます。

        pyxel.sounds[0].speed = 200     # エディタの上限 99 を超えて設定できる

Q. 2 つの効果音を同時に鳴らしたのに、片方しか聞こえない／「出た」感じがしない

原因は2 段階あります。まず ①チャンネルの上書きを疑い、 それが違えば ②マスキング（音が似すぎて混ざる）を疑います。

① 同じチャンネルに 2 回鳴らすと、あとの 1 回が前を消す

Pyxel の play(ch, snd) は、そのチャンネルで鳴っているものを止めて、 新しい音に差し替える命令です。停止と再生が 1 つになっている、と考えてください。

            pyxel.play(CH_SE, SOUND_CANDY)      # ch2 ＝ お菓子の音
            ...
                pyxel.play(CH_SE, SOUND_GHOST)   # ← 同じ ch2！ 上書きされる

やっかいなのは、この 2 行が同じフレームの中で走ることです。 音が出るのはフレームの終わりなので、お菓子の音は 1 サンプルも鳴らないまま消えます。 「片方が途中で切れる」のではなく、最初からなかったことになります。

② 似すぎている音は、2 つでも 1 つに聞こえる（マスキング）

チャンネルを分けても弱いままなら、こちらです。 耳は同時に鳴る似た音を 1 つにまとめて聞きます。とくに あとから鳴った小さい音・短い音は、先に鳴っている音に隠されます。 これをマスキングと呼びます。

step1 の 2 つの音は、埋もれる条件がそろっていました。

手当ては 4 つ。1 つでも効きますが、2 つ以上ずらすと確実です。

Q. Web に公開した Pyxel 作品を全画面にしたい。F11 が効かない

A. ページに「全画面」ボタンを自分で足します。 pyxel app2html が出力する HTML には、全画面にする仕組みがまったく入っていません。 読み込まれる pyxel.js（2.9.9）を確認しましたが、 requestFullscreen に類する処理は 1 行もありませんでした。

なぜ F11 が効かなくなるのか

アプリが起動した瞬間から、Pyxel の wasm ランタイムが document に キー入力のハンドラを付け、自分が使うキーの既定の動作を打ち消します。 F11 もその対象に入っているため、ブラウザの全画面切り替えまで一緒に止まってしまいます。

実際に keydown を投げて、既定動作が打ち消されるか（defaultPrevented）を測りました。

起動前は素通りしていたものが、起動後だけ打ち消されています。 ページ側の JavaScript が原因で、ブラウザの設定や Pyxel の不具合ではありません。

対策 1：ブラウザのメニューから全画面にする（コード変更なし）

Chrome なら右上の ⋮ メニューの中に全画面のアイコンがあります。 メニュー操作はページのキー処理を経由しないので、こちらからなら全画面にできます。 今すぐ確かめたいときはこれが手軽です。

対策 2：公開する HTML に「全画面」ボタンを足す

app2html が出力する HTML は、実質 4 行しかない小さなファイルです。 その後ろにボタンとスクリプトを足すだけで、全画面ボタンを付けられます。

<meta charset="utf-8">

<style>
  #fs-btn {
    position: fixed; right: 12px; bottom: 12px; z-index: 9999;
    padding: 8px 14px; color: #fff; background: rgba(50,50,50,.8);
    border: 1px solid #888; border-radius: 6px; cursor: pointer;
  }
  /* 全画面のあいだはボタンを隠す（抜けるときは ESC） */
  :root:fullscreen #fs-btn { display: none; }
  :root:-webkit-full-screen #fs-btn { display: none; }
</style>
<button id="fs-btn">全画面</button>
<script>
const fsBtn = document.getElementById("fs-btn");

fsBtn.addEventListener("click", async () => {
  try {
    await document.documentElement.requestFullscreen();
  } catch (e) {
    console.log("[fs] 全画面にできませんでした:", e.name, e.message);
  }
  document.getElementById("canvas").focus();   // キー入力を戻す
});

document.addEventListener("fullscreenchange", () => {
  fsBtn.hidden = !!document.fullscreenElement;   // 全画面のあいだは隠す
  document.getElementById("canvas").focus();
});
</script>

足すときに引っかかった 3 点

<body>
  <div id="pyxel-screen">
    <canvas id="canvas">   ← ゲーム画面。ウィンドウの大きさに合わせて拡大される
  </div>
  <button id="fs-btn">    ← ここに足す
</body>

Q. pyxel.init() より先に pyxel.load() を書いたらエラーになった。init() は何をしている？

A. pyxel.init() は「ウィンドウを開く関数」だと思われがちですが、 それ以上に大事な仕事をしています。画像・音・色をしまっておくための「空の入れ物」を用意することです。 pyxel.load() はその入れ物に .pyxres の中身を流し込む関数なので、 入れ物が無いうちに呼ぶと、中身の行き場がなくてエラーになります。

import pyxel

pyxel.load("candy_hunt.pyxres")   # ← init より前だと、ここで落ちる
pyxel.init(160, 120)

thread '<unnamed>' panicked at pyxel-core\src\pyxel.rs:48:31:
Pyxel not initialized
pyo3_runtime.PanicException: Pyxel not initialized

Pyxel not initialized は「Pyxel はまだ初期化されていない」という意味です。 load だけの話ではなく、cls・blt・text・btn・play など エンジンの中身に触る関数はすべて同じエラーになります。

init() が用意する枠は、実際に数えると次のとおりでした（pyxel 2.9.9 で実測）。

load() がしているのは、この空っぽの枠に .pyxres の中身を上書きすることです。 リソースエディタで描いた絵が「イメージバンク 0」に入るのも、 init() が先に 0 番の枠を作っているからです。

順番の覚え方：init → load → 自分の変数 → run

class App:
    def __init__(self):
        pyxel.init(SCREEN_WIDTH, SCREEN_HEIGHT, title="Candy Hunt")   # 1. 入れ物を作る
        pyxel.load("candy_hunt.pyxres")                               # 2. 絵と音を入れる
        self.boy_x = 76                                               # 3. 自分の変数を決める
        pyxel.run(self.update, self.draw)                             # 4. ループを始める

3 番と 2 番は入れ替えても動きますが、1 番がいちばん先、4 番がいちばん最後という点は動かせません。

Q. お菓子を「取った」感じが薄い。かすっただけで次のお菓子が出てしまう

A. 当たり判定の四角が、絵の見た目より大きいからです。 判定は 8×8 の四角どうしで行っていますが、 （1）絵は 8×8 のマス全部に色が付いているわけではなく、 （2）四角が1 ドットでも重なれば当たりという条件なので、 角がかすっただけで成立してしまいます。

step1 で描いた絵を実際に数えると、こうなっていました。

男の子は左右に 1 ドットずつ、お菓子は上下に 1 ドットずつ余白があります。 つまり四角が触れていても、絵にはまだすき間がある状態が起こります。

どれくらい「かすっている」のか

男の子を中央に固定して、お菓子を 1 ドットずつずらしながら 「当たりと判定されるか」「絵が実際に重なっているか」を全通り調べました。

外周のピンクのマスが、まさに「追いかけているだけで取れてしまう」感覚の正体です。

対策：判定の四角を、絵より小さくする

ゲームでは「絵の大きさ」と「当たり判定の大きさ」を別々に決めるのが普通です。 絵の中央だけを判定に使うようにすると、「ちゃんと重なったときだけ当たる」ようになります。

定数を 2 つ足します。

BOY_SIZE = 8            # 男の子の絵の大きさ（縦横とも 8 ドット）
BOY_SPEED = 2           # 1 フレームで進むドット数

CANDY_SIZE = 8          # お菓子の絵の大きさ

HIT_SIZE = 4                                # 当たり判定に使う四角の大きさ（絵の中央だけを見る）
HIT_OFFSET = (BOY_SIZE - HIT_SIZE) // 2     # 絵の左上から、判定の四角までの距離（= 2）

そして check_candy() の呼び出しを差しかえます。

    def check_candy(self):
        """お菓子にしっかり重なったら、スコアを増やして次の場所へ置きなおす"""
        if is_hit(self.boy_x + HIT_OFFSET, self.boy_y + HIT_OFFSET, HIT_SIZE,
                  self.candy_x + HIT_OFFSET, self.candy_y + HIT_OFFSET, HIT_SIZE):
            self.score += 1
            self.place_candy()

どのサイズにするか

全通り調べた結果です。HIT_SIZE を変えたときの手ごたえの目安にしてください。

4 にすると、当たった瞬間には必ず 6 ドット以上が重なっているので、 見た目に「乗った」と分かります。2 はほぼ完全に重ねる必要があり、 お化けから逃げながら取るには厳しすぎるでしょう。

「取った実感」はもう一つの方向からも作れる

当たり判定を直すのは「取れるタイミングを正しくする」対策です。 これとは別に、「取れたことを分かりやすく伝える」という対策もあります。

• 効果音を鳴らす — いちばん効果が大きい（step1 フェーズ 9）
• スコアの数字を数フレームだけ色を変える
• 取った場所に小さな光を数フレーム描く

どれも「判定が正しいこと」の上に乗せるものなので、まず判定を直すのが先です。

Q. お化けの速さはどう決める？ GHOST_SPEED = 1 でも速く感じる

A. その感覚は正しいです。男の子の半分の速さでも、全力で逃げ続けて 5 秒で捕まります。 「半分の速さなら余裕で逃げられる」という直感が当たらないのは、 画面が狭くて、必ず壁に突き当たるからです。

実際に数えてみました（画面 160×120、BOY_SPEED = 2、 お化けは左上 (0, 0) から出発、判定は HIT_SIZE = 4）。 男の子はお菓子を無視して、お化けから遠ざかる向きへ全力で逃げ続けるという条件です。

速さに小数を使うときの落とし穴

Pyxel は座標に小数を渡せる（#float-coord）ので GHOST_SPEED = 0.5 はそのまま動きます。ただし どんな小数でもよいわけではありません。

move_ghost() は「小さければ増やす／大きければ減らす」なので、 == になったところで初めて止まります。 ぴったり == にならない速さだと、目標をまたいで永久に往復します。 実際に 400 フレーム動かして確かめた結果です。

速さ以外で難しさを調整する手

「捕まるまでの秒数」は速さだけで決まるものではありません。次の手も使えます。

• 出てくる場所を遠くする — 男の子から見ていちばん遠い角から出す
• しばらく動かさない — 出現から数十フレームは止まっている「猶予」を作る
• 増えるペースを変える — step1 は「お菓子 5 個ごとに 1 体」。ここを 8 個ごとにするだけでも、ずいぶん楽になります（フェーズ 8）
• お化けごとに速さを変える — 全部同じ速さだと重なって 1 体に見えるので、 1 と 0.5 を混ぜると散らばって見た目にも分かりやすくなります

「2 進数で正確」なだけでは足りない ── 0.75 の落とし穴

上で「1 を 2 で割っていった数なら安全」と書きましたが、これだけでは足りません。 0.75 は 0.5 + 0.25 なので 2 進数でぴったり表せますが、 それでも往復します。

男の子が x = 76 で止まっているとき（実測）

  速さ 1     → 76.0, 76.0, 76.0 …          ぴったり止まる
  速さ 0.75  → 75.75, 76.5, 75.75, 76.5 …  ★ 往復（振れ幅 0.75）
  速さ 0.5   → 76.0, 76.0, 76.0 …          ぴったり止まる
  速さ 0.25  → 76.0, 76.0, 76.0 …          ぴったり止まる

理由は「お化けが立てる座標」に男の子の座標が含まれていないからです。 お化けは 0 から速さの倍数の位置しか通れません。

男の子の座標は BOY_SPEED = 2 なので必ず偶数です。 0.75 の倍数で偶数になるのは 6 の倍数だけなので、 76 のような座標にはどうやっても乗れません。

いちばん安全なのは、小数を使わないこと

そもそも「1 回に進む量」を減らすかわりに、「動く回数」を減らすと、 座標はずっと整数のままになります。小数の話が丸ごと消えます。

class Ghost:
    def __init__(self, x, y, move_every):
        self.x = x
        self.y = y
        self.move_every = move_every        # 何フレームに 1 回動くか

    def move(self, target_x, target_y):
        if pyxel.frame_count % self.move_every != 0:
            return                          # 今回は自分の番ではない

        if self.x < target_x:
            self.x += 1                     # 進むのはいつも 1 ドット
        ...

見た目も変わりません。描画はどうせ整数のドットに丸められるので、 「0.5 ずつ進む」も「2 フレームに 1 ドット進む」も画面上は同じです。 それでいて 1/3 のような、小数では扱えない速さが使えます。

Q. 「描かない」と、なぜ点滅になるの？ continue の行の意味が分からない

A. ポイントは「消す命令はない。描かなければ、それが消えたということ」です。

        for ghost in self.ghosts:
            if pyxel.frame_count - ghost.born_frame < 30 and not is_blink_on():
                continue                # 出てきて 1 秒は、点滅の消える側で描かない

            pyxel.blt(ghost.x, ghost.y, 0, 8, 0,
                      GHOST_SIZE, GHOST_SIZE, pyxel.COLOR_BLACK)

① 画面は毎フレーム、まっさらから描き直している

draw() のいちばん上を思い出してください。

    def draw(self):
        pyxel.cls(pyxel.COLOR_BLACK)        # ← 毎フレーム、画面を黒で塗りつぶす
        ...

1 フレームごとに、画面はいったん全部消えています。 そのあと blt() で描いたものだけが見えます。 つまり画面は「前のフレームの続き」ではなく、毎回ゼロから作り直したものです。

② continue は「この 1 個だけ飛ばして、次へ」

for の中で continue に来ると、その下は実行せずに、次の 1 個へ進みます。

ここでやりたいのは「この 1 体だけ、今回は描かない」なので continue です。 return にすると、そのあとの男の子やスコアまで描かれなくなります。

③ 条件は 2 つに分かれている

and でつないであるので、両方そろったときだけ continue します。

表にすると、描かないのは 4 通りのうち 1 つだけです。

1 秒たつと 1 つめの条件がずっと False になるので、 and 全体も必ず False。以後は毎フレーム必ず描かれ、点滅が止まります。 「点滅をやめる処理」を別に書く必要はありません。

読みにくいと感じたら、名前を付けて分ける

and not が並ぶと、頭の中で 2 回ひっくり返すことになります。 途中に名前を付けると、そのまま読めるようになります。

        for ghost in self.ghosts:
            is_new = pyxel.frame_count - ghost.born_frame < 30      # 出てきたばかり？

            if is_new and not is_blink_on():
                continue

            pyxel.blt(...)

あるいは「描く条件」のほうを書くと、continue がいらなくなります。

        for ghost in self.ghosts:
            is_new = pyxel.frame_count - ghost.born_frame < 30

            if not is_new or is_blink_on():      # 出て 1 秒たった、または 見える側なら描く
                pyxel.blt(...)

Q. walk_timer = 1 としているのは、walk_timer = 0 ではだめ？

A. だめです。0 という値そのものに「止まっている」という意味を持たせているので、 歩き出すところで 0 を入れるのは「歩き出さなかったことにする」のと同じになります。 （step2 フェーズ 4 の try_move() の最終行の話です）

        self.player_x = next_x
        self.player_y = next_y
        self.walk_timer = 1                     # ← ここを 0 にすると壊れる

① 実際に 0 にすると、こうなります

上キーを押しっぱなしにしたときの、最初の 6 フレームです。

=== walk_timer = 1（正しいほう）===
  f0 timer=1  盤面 y=3  from_y=4  画面 py=73
  f1 timer=2  盤面 y=3  from_y=4  画面 py=72     ← 1 フレームに 1 ドット
  f2 timer=3  盤面 y=3  from_y=4  画面 py=71
  f3 timer=4  盤面 y=3  from_y=4  画面 py=70

=== walk_timer = 0（まちがい）===
  f0 timer=0  盤面 y=3  from_y=4  画面 py=74
  f1 timer=0  盤面 y=2  from_y=4  画面 py=74     ← 1 フレームに 1 マス！
  f2 timer=0  盤面 y=2  from_y=4  画面 py=74     ← 絵はまったく動かない
  f3 timer=0  盤面 y=2  from_y=4  画面 py=74

絵は出発地点に張りついたまま、盤面の上だけ猛スピードで進みます。 壁にぶつかるまで一瞬です。原因は 2 つあります。

② タイマーが一度も進まないので、到着処理も走らない

    def update(self):
        if self.walk_timer > 0:                 # ← 0 のままなので、ここに一度も入れない
            self.walk_timer += 1
            if self.walk_timer > MOVE_FRAMES:
                self.walk_timer = 0
                self.from_x = self.player_x     # ← だから、これも実行されない
                self.from_y = self.player_y

self.from_y がずっと最初の値のままです。 slide_pos() は from_y を出発点にして描くので、 player_y がいくら進んでも絵は最初のマスから動きません。 上の実測で py=74 が並んでいるのが、それです。

③ 毎フレーム、キーを見に行ってしまう

        if self.walk_timer == 0:                # ← ずっと成り立ってしまう
            self.handle_key()

pyxel.btn() は押しているあいだ、ずっと True です。 「歩いているあいだはキーを見ない」というブレーキが効かなくなるので、 1 フレームに 1 マス＝毎秒 30 マス進みます。

④ では、なぜ 1 なのか（0 始まりの 0〜7 ではだめ？）

walk_timer は「歩き始めてから何フレーム経ったか」を表す数です。 キーを押したそのフレームは、もう1 フレーム目なので 1 から始めます。

そして 1〜8 の 8 段階が、1〜8 ドットにそのまま対応します。 0 始まりで 0〜7 にすると「0 ドットの回」ができてしまい、 1 マス歩くのに 9 フレームぶんの位置が必要になります。 0 ドットの絵（＝出発マスにいる姿）は、キーを押す前のフレームですでに描かれているので、 動き出す最初の 1 枚は 1 ドットが正解です。

Q. 主人公の目を黒く描いたのに、画面では目が出てこない（透過色はどう選ぶ？）

A. 透過色（colkey）に黒を指定していたからです。 blt() の最後の引数は「この 1 色だけは描かない」という意味なので、 背景を黒で塗った絵に pyxel.COLOR_BLACK を渡すと、 黒で描いたものはすべて抜けます——目もいっしょに。 （step2 フェーズ 5 で実際に直した話です）

① 実際のドットで見ると

sokoban.pyxres の主人公（下向き・コマ A）を、色番号のまま並べたものです。

  以前（背景も目も黒）        いま（背景だけグレー）
    0 0 a a a a 0 0            d d a a a a d d
    0 a a a a a a 0            d a a a a a a d
    9 a a a a a a 9            9 a a a a a a 9
    9 a 0 a a 0 a 9            9 a 0 a a 0 a 9   ← 0 が目
    9 a a 7 7 a a 9            9 a a 7 7 a a 9
    0 0 a a a a 0 0            d d a a a a d d
    0 a 0 0 0 0 a 0            d a d d d d a d
    0 a 0 0 0 0 a 0            d a d d d d a d

  0 = 黒   9 = オレンジ   a = 黄   7 = 白   d = グレー（13）

左は 0 が「背景」と「目」の両方に使われています。 プログラムには、どちらがどちらか区別できません。 右は背景だけ d に塗り替えたので、0 は目だけになりました。

② 直し方は 2 か所

pyxel.blt(px, py, 0, u, v, 8, 8, pyxel.COLOR_GRAY)

③ 透過色に選んでよい色の条件

その絵の中で、背景以外に 1 ドットも使っていない色であることです。 もし犬の体にグレーを使っていたら、そこに穴があきます（背景と同じ扱いで抜かれる）。

④ 透過色は blt() ごとに指定する

1 枚の絵につき 1 色ではなく、描くたびに指定するものです。 だから絵によって背景の色を変えてかまいません。 倉庫番では 3 通りを使い分けています。

環境・ツールについて

Q. Pyxel のウィンドウが閉じられない

A. Esc キーで終了します。ウィンドウ右上の × でも閉じられます。 ターミナルから起動したまま固まってしまった場合は、ターミナルで Ctrl + C を押すと強制終了できます。

Q. 付属のサンプルはどこにある？

A. ターミナルで pyxel copy_examples を実行すると、 カレントディレクトリに pyxel_examples/ フォルダが作られ、その中に展開されます。 実行は pyxel run 01_hello_pyxel.py のように行います。

Q. 閉じ """ の手前にあるカーソルを、次の行へ楽に送りたい

A. Ctrl + Enter を押します。カーソルが行のどこにあっても、 その行の下に新しい行を作って移動するコマンド（editor.action.insertLineAfter）で、 VS Code の標準キーバインドなので設定は要りません。インデントも自動で揃います。

関数の説明文（docstring）を書くとき、""" と打つと閉じ側の """ が自動で補完され、 説明文を入力し終えたカーソルは閉じ """ の手前で止まります。 ここからわざわざ → キーで閉じ引用符を通り過ぎる必要はありません。

上下セットで覚えておくと便利です。

• Ctrl + Enter … 現在行の下に行を挿入して移動
• Ctrl + Shift + Enter … 現在行の上に行を挿入して移動