メインコンテンツへスキップ
見出し画像

カードが扇状に広がる手札UIをGDScriptで自作する【実録#41・Godot】

    手札のカードが、トランプのように扇(ファン)状に広がる。中央のカードは手前で正立し、端に行くほど傾いて沈む。上にスワイプすればプレイ、長押しでカード詳細が開く。枚数が増えたら横ドラッグでカルーセルのように回る。

    その戦闘画面を、Godot 4.6 と GDScript で自作しました。

    この記事は、こんな人向けです。

    • Godotでカードゲーム(デッキビルダー)の手札UIを作りたい人

    • HBoxContainer で一列に並べたものの、見た目に納得できていない人

    • 「扇状配置」を検索したけど、数式とハマりどころまで書いた記事に出会えなかった人

    先に結論を言います。扇状の手札UIは、Container を捨てて手動レイアウトにした瞬間に一気に作れます。逆に言うと、Container のまま粘っている限り一生できません。私はここで一度詰まりました。

    読み終わるころには、円弧配置の数式・ピボット回転・ジェスチャの状態管理・そして必ず踏む5つの地雷まで、まるごと分かる状態になります。

    きっかけ:HBoxで並べた手札が「ただの棚」だった

    章扉カード01

    作っているのは、個人開発のデッキビルダー(Godot製・スマホ縦持ち想定)です。戦闘画面の手札を、最初は素直に HBoxContainer に並べていました。

    動きはします。でも、ただカードが横一列に並んだ「棚」なんです。カードゲームの手札という感じがまるでしない。

    紙のカードを手に持つと、自然と扇状に広がりますよね。中央は自分の正面に立ち、両端は指でつままれて傾く。あの「手に持っている感」を出したかった。

    でも HBoxContainer は、子を等間隔で一列に並べることしかできません。カードを回転させたり、円弧に沿って重ねたりする機能は、そもそも Container の責務の外なんです。

    ここで私は選択を迫られました。Container の中で無理やり rotation をいじって粘るか、Container をやめて全部自分で座標計算するか。

    あなたなら、どちらを選びますか?

    方針:Container をやめて「手動レイアウト」にする

    章扉カード02

    答えは後者でした。Container をやめ、Control 直下にカードを絶対配置して、位置と回転を毎フレーム自分で計算する。これが唯一の正解ルートでした。

    理由はシンプルです。扇状配置に必要な「円弧上の座標」と「各カード固有の回転角」は、Container の自動整列とは根本的に相性が悪い。Container に逆らって座標を上書きしても、次のレイアウトパスで押し戻されるだけです。

    だったら最初から Container を使わない。カードは Control の子にして、position と rotation を自前の関数(私は _layout_hand_arc() と名付けました)で一括計算する。この割り切りで、扇は一瞬で形になりました。

    仕組み:扇の正体は「円弧の座標」と「下端ピボット回転」

    章扉カード03

    ここは出し惜しみせず、全部説明します。扇状配置は、たった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枚」に絞る

    章扉カード04

    デッキビルダーは手札が増えます。10枚を全部扇にすると、弧が広がりすぎて画面からはみ出す。

    そこで、同時に表示するのは窓9枚だけにしました。弧の端を横ドラッグすると、表示範囲がスライドしてカードが送られる。カルーセルです。

    「全部を一度に見せる」ことにこだわると破綻します。手に持てる枚数には限界がある、という現実のメタファーがそのままUIになりました。

    ハマった地雷は5つ。全部踏みました

    章扉カード05

    ここまでが「理解」の部分です。仕組みは全部お話ししました。

    でも、実際に作ると同じ地雷を必ず踏みます。私が踏んだのは5つ。概要だけ先に出します。

    1. queue_free() の遅延削除で、旧カードが混ざって枚数を誤カウント。中心がズレて傾きが崩れ、カードが窓の外へ消えた
    2. 手札の最小幅が画面を超えると、フッターのボタンが画面外へ押し出される(Container時代の負債)
    3. 弧の縦の盛り上がりが強すぎて、中央のカードがせり上がりすぎた
    4. ドラッグ中、暗幕オーバーレイが閉じなくなる(クリックが背後に届かない)
    5. 1画面だけ別のヘッダー部品を使っていて、見た目が不一致&型エラー

    どれも「原因を知っていれば5分、知らないと数時間溶ける」タイプです。特に1番は、症状(カードが消える)と原因(削除の遅延)が全然結びつかなくて、私はかなり悩みました。

    原因と対策・そのままのコードは、この先にまとめます。

    この先(有料)に置くもの

    章扉カード06

    無料部分で、扇状配置の理屈とジェスチャ設計は全部お話ししました。設計が分かれば、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自己検証ハーネスを、まるごと置いておきます。

     
     
    ITエンジニア9年目 / AI自動化 / note副業実録 AIを使えば、もっと楽できると気づいた。 noteで月10万円を目指す過程を、売上スクショ付きで全部公開します。 うまくいかない月も、ちゃんと出します。 「重い副業はしたくない」エンジニア・IT系の人に届けたい。

    あなたへのおすすめ