Godot入門：SpinBoxの使い方と活用法

はじめに
SpinBoxとは？
このノードを使うべき場面
主なプロパティと機能
もっと使いこなす：カスタマイズできるパラメータ
まとめ
シリーズ：Godot 4 ノード解説

はじめに

音量を1〜100の数値で細かく設定したい、最大ライフを数字で入力させたい——こういった「数値をUI上で増減させる」場面で便利なのが SpinBox です。テキスト入力と上下ボタンの両方で数値を変えられます。

この記事では、SpinBox の仕組みと使いどころ、よく触るプロパティを紹介します。

SpinBoxとは？

SpinBox は 数値をテキスト入力または右端の「▲▼」ボタンで増減できるUIノードです。最小値・最大値・ステップ幅を設定すると、その範囲を超えた値を自動でクランプしてくれます。

エアコンのリモコンで温度を「▲」「▼」ボタンで1℃ずつ変えるイメージです。SpinBox はその仕組みをゲームのUIに再現し、数値の上限・下限・刻み幅を自動で管理してくれます。

継承ツリーは SpinBox → Range → Control → CanvasItem → Node です。ProgressBar・HSlider と同じ Range クラスを継承しているため、min_value・max_value・value・step が共通プロパティです。

SpinBox の各部名称（テキスト欄・▲▼ボタン・prefix・suffix） — 数値欄に直接入力するか、▲▼ボタンで増減できる

このノードを使うべき場面

音量・明るさの数値設定：スライダーより正確な数値入力が必要な設定項目
ゲームパラメータの調整：開発中にキャラクターのHP・攻撃力などをリアルタイムで変更するデバッグUI
エディタ風ツール：レベルエディタやマップエディタで数値プロパティを入力する場面
アイテム購入数の指定：ショップで購入個数を増減して合計金額を確認するUI
タイマー設定：分・秒を個別の SpinBox で入力するカウントダウン設定画面

別のノードが適切な場面：

ざっくりした範囲を直感的に調整したい → HSlider（035）の方が操作しやすい
自由なテキストも入力させたい → LineEdit に数値バリデーションを自分で実装する

主なプロパティと機能

プロパティ	型	役割
`value`	float	現在の数値。ここを変えると表示が更新される
`min_value`	float	設定できる最小値（デフォルト: 0）
`max_value`	float	設定できる最大値（デフォルト: 100）
`step`	float	▲▼ボタン1回で増減する量（デフォルト: 1）
`rounded`	bool	`true` にすると整数値のみに丸める
`prefix`	String	数値の前に表示するテキスト（例: “音量: “）
`suffix`	String	数値の後ろに表示するテキスト（例: ” %”）
`editable`	bool	`false` にするとテキスト直接入力を禁止し、ボタン操作のみにする
`value_changed`（シグナル）	Signal	値が変わるたびに新しい値（float）を引数として発火する

コード例：音量設定（0〜100、整数、% 表示）

@onready var volume_spin: SpinBox = $VolumeSpinBox

func _ready() -> void:
    volume_spin.min_value = 0
    volume_spin.max_value = 100
    volume_spin.step     = 1
    volume_spin.rounded  = true
    volume_spin.suffix   = " %"
    volume_spin.value    = SaveData.volume

    volume_spin.value_changed.connect(_on_volume_changed)

func _on_volume_changed(val: float) -> void:
    SaveData.volume = int(val)
    AudioServer.set_bus_volume_db(
        AudioServer.get_bus_index("Master"),
        linear_to_db(val / 100.0)
    )

コード例：購入個数スピナー（1〜在庫数、合計金額をリアルタイム更新）

@onready var qty_spin: SpinBox  = $QtySpinBox
@onready var total_label: Label = $TotalLabel

const ITEM_PRICE = 150

func setup(stock: int) -> void:
    qty_spin.min_value = 1
    qty_spin.max_value = stock
    qty_spin.step      = 1
    qty_spin.value     = 1
    qty_spin.value_changed.connect(_on_qty_changed)
    _on_qty_changed(1)

func _on_qty_changed(val: float) -> void:
    total_label.text = "合計: %d G" % [int(val) * ITEM_PRICE]

prefix / suffix を使ったSpinBoxのバリエーション — prefix と suffix を使うと「音量: 75 %」のように単位付きの表示が作れる

もっと使いこなす：カスタマイズできるパラメータ

まずは基本を動かしてみてから、余裕が出たら試してみてください。

パラメータ・テクニック	変えると何が起きるか
`step` を小数にする（例: 0.1）	▲▼ボタン1回で0.1ずつ増減する。速度倍率・スケール調整など小数点が必要な設定に
`rounded` を `true` に	小数点以下を丸めて整数のみ表示する。個数・レベルなど整数値専用の入力に
`prefix` / `suffix` を設定する	単位（%・G・秒など）をつけて意味が伝わりやすくなる。追加コードなしで表示できる
`editable` を `false` に	テキスト直接入力を禁止し、ボタン操作だけにできる。不正な値の入力を防ぎたいときに
HSlider と並べて使う	スライダーで大まかに・SpinBoxで正確にという「二刀流」UIが作れる。同じ `value` を共有すると連動する