
カードが扇状に広がる手札UIをGDScriptで自作する【実録#41・Godot】
手札のカードが、トランプのように扇(ファン)状に広がる。中央のカードは手前で正立し、端に行くほど傾いて沈む。上にスワイプすればプレイ、長押しでカード詳細が開く。枚数が増えたら横ドラッグでカルーセルのように回る。
その戦闘画面を、Godot 4.6 と GDScript で自作しました。
この記事は、こんな人向けです。
Godotでカードゲーム(デッキビルダー)の手札UIを作りたい人
HBoxContainer で一列に並べたものの、見た目に納得できていない人
「扇状配置」を検索したけど、数式とハマりどころまで書いた記事に出会えなかった人
先に結論を言います。扇状の手札UIは、Container を捨てて手動レイアウトにした瞬間に一気に作れます。逆に言うと、Container のまま粘っている限り一生できません。私はここで一度詰まりました。
読み終わるころには、円弧配置の数式・ピボット回転・ジェスチャの状態管理・そして必ず踏む5つの地雷まで、まるごと分かる状態になります。
きっかけ:HBoxで並べた手札が「ただの棚」だった

作っているのは、個人開発のデッキビルダー(Godot製・スマホ縦持ち想定)です。戦闘画面の手札を、最初は素直に HBoxContainer に並べていました。
動きはします。でも、ただカードが横一列に並んだ「棚」なんです。カードゲームの手札という感じがまるでしない。
紙のカードを手に持つと、自然と扇状に広がりますよね。中央は自分の正面に立ち、両端は指でつままれて傾く。あの「手に持っている感」を出したかった。
でも HBoxContainer は、子を等間隔で一列に並べることしかできません。カードを回転させたり、円弧に沿って重ねたりする機能は、そもそも Container の責務の外なんです。
ここで私は選択を迫られました。Container の中で無理やり rotation をいじって粘るか、Container をやめて全部自分で座標計算するか。
あなたなら、どちらを選びますか?
方針:Container をやめて「手動レイアウト」にする

答えは後者でした。Container をやめ、Control 直下にカードを絶対配置して、位置と回転を毎フレーム自分で計算する。これが唯一の正解ルートでした。
理由はシンプルです。扇状配置に必要な「円弧上の座標」と「各カード固有の回転角」は、Container の自動整列とは根本的に相性が悪い。Container に逆らって座標を上書きしても、次のレイアウトパスで押し戻されるだけです。
だったら最初から Container を使わない。カードは Control の子にして、position と rotation を自前の関数(私は _layout_hand_arc() と名付けました)で一括計算する。この割り切りで、扇は一瞬で形になりました。
仕組み:扇の正体は「円弧の座標」と「下端ピボット回転」

ここは出し惜しみせず、全部説明します。扇状配置は、たった2つの数式で決まります。
1. 円弧上の座標
カードを半径 R の円の内側に、中心角 θ ずつずらして並べます。円の最下点を基準にすると、各カードの座標はこうなります。
x = R · sin(θ)
y = R · (1 - cos(θ))
θ が 0(中央)のとき x=0, y=0。θ が大きくなる(端に行く)ほど、x は横に開き、y は下に沈む。これで「中央が手前、端が下がる」扇の骨格ができます。
θ は、カードのインデックスと「1枚あたりの角度」から決めます。中央を0として左右に振り分けるだけです。
2. 下端中央ピボットの回転
座標だけだと、カードは傾きません。ここで回転の中心(ピボット)をカードの下端中央にするのが肝です。
Godotの Control は既定でピボットが左上(0,0)です。これを下端中央に移すと、カードは「持ち手を固定して先端を開く」ように傾きます。まさに手に持ったカードの動きです。
card.pivot_offset = Vector2(card.size.x / 2.0, card.size.y)
card.rotation = θ # 座標と同じθを回転にも使う
座標のθと回転のθを揃えるのがポイントです。これで円弧に沿ってカードが放射状に傾きます。
3. ジェスチャの割り当て
見た目ができたら、操作です。ここも設計を全部見せます。
上スワイプ → そのカードをプレイ
長押し → カード詳細(大きなカード型オーバーレイ)を表示
タップ即プレイは廃止(誤爆が多いので捨てた)
横ドラッグ → 枚数が多いとき、弧を回して隠れたカードを送る(カルーセル)
これらを1つの _on_card_gui_input() の中で、状態を見ながら振り分けます。スワイプ・長押し・カルーセルは同じ指の動きから始まるので、競合を状態機械で整理しないと必ず誤爆します。ここが実装の本当の山場でした。
カルーセル:全部見せず「窓9枚」に絞る

デッキビルダーは手札が増えます。10枚を全部扇にすると、弧が広がりすぎて画面からはみ出す。
そこで、同時に表示するのは窓9枚だけにしました。弧の端を横ドラッグすると、表示範囲がスライドしてカードが送られる。カルーセルです。
「全部を一度に見せる」ことにこだわると破綻します。手に持てる枚数には限界がある、という現実のメタファーがそのままUIになりました。
ハマった地雷は5つ。全部踏みました

ここまでが「理解」の部分です。仕組みは全部お話ししました。
でも、実際に作ると同じ地雷を必ず踏みます。私が踏んだのは5つ。概要だけ先に出します。
1. queue_free() の遅延削除で、旧カードが混ざって枚数を誤カウント。中心がズレて傾きが崩れ、カードが窓の外へ消えた
2. 手札の最小幅が画面を超えると、フッターのボタンが画面外へ押し出される(Container時代の負債)
3. 弧の縦の盛り上がりが強すぎて、中央のカードがせり上がりすぎた
4. ドラッグ中、暗幕オーバーレイが閉じなくなる(クリックが背後に届かない)
5. 1画面だけ別のヘッダー部品を使っていて、見た目が不一致&型エラー
どれも「原因を知っていれば5分、知らないと数時間溶ける」タイプです。特に1番は、症状(カードが消える)と原因(削除の遅延)が全然結びつかなくて、私はかなり悩みました。
原因と対策・そのままのコードは、この先にまとめます。
この先(有料)に置くもの

無料部分で、扇状配置の理屈とジェスチャ設計は全部お話ししました。設計が分かれば、AIに指示して骨組みは書けると思います。
この先の有料部分に置くのは、コードそのものではなく「自力でやると必ず溶かす一次情報」です。
5つの地雷の原因と対策の完全版(症状→なぜ起きるか→どう直したか)
_layout_hand_arc() のそのまま動くコード全文
ジェスチャ状態機械(スワイプ・長押し・カルーセルの競合整理)の判定ロジック
半径・1枚あたり角度・窓枚数のパラメータ早見表(ここが一番時間を溶かす)
見た目の崩れを機械的に検出するPNG自己検証ハーネスの作り方
同じUIをゼロから作ると、この5つの地雷を1つずつ踏み直し、パラメータを手当たり次第にいじる時間が待っています。この記事は、その試行錯誤を省略するためのものです。
◀ 前回: 仕様書14本からGodotゲーム82ファイルをClaude Codeで実装する方法【実録#40・仕様書から丸ごと実装】
📚 シリーズ全話はまとめマガジンへ
https://note.com/lazy_engineer/m/m03a726b1673c
💡 ここから先は有料です(¥300)
扇状手札UIの「動くコード全文」と、私が実際に溶かした5つの地雷の回避手順・パラメータ早見表・PNG自己検証ハーネスを、まるごと置いておきます。