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

はじめに

音量を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 を共有すると連動する

まとめ

SpinBox は 「数値を上限・下限つきで増減できる入力ノード」 です。

  • min_value・max_value・step で数値の範囲と刻み幅を制御できる
  • prefix / suffix で単位を表示でき、追加のラベルが不要になる
  • value_changed シグナルで値の変化をリアルタイムに検知して設定や計算に使う

次回は、ドラッグ操作で数値を直感的に調整できる HSlider を紹介します。

シリーズ：Godot 4 ノード解説

この記事はGodot 4.xをもとに執筆しています。

コメント