最后同步日期：2026-04-15 | Godot 官方原文 — clampf

clampf

定义

clampf() 用来把一个浮点数限制在指定的最小值和最大值之间——简单说，就是"画一条线，不许超出"。

想象温度计的刻度范围是 0 到 100 度。不管外面实际温度是 -20 度还是 200 度，温度计上最多只能显示 0 到 100 之间的值。clampf() 就是这个温度计：你给它一个值和两个边界，它帮你把值"夹"在这个范围之内。

在游戏开发中，浮点数限值无处不在：角色的生命值不能超过上限也不能低于 0、移动速度不能超过最大值、UI 进度条的值必须在 0~1 之间等等。和 clamp() 的区别在于，clampf() 明确只处理浮点数（带小数点的数）。

函数签名

C#

public static float Clamp(float value, float min, float max)

GDScript

func clampf(value: float, min: float, max: float) -> float

参数说明

参数	类型	必需	说明
value	float	是	要限制的原始值
min	float	是	允许的最小值
max	float	是	允许的最大值

返回值

float —— 被"夹"在 [min, max] 范围内的值。如果 value 小于 min，返回 min；如果 value 大于 max，返回 max；否则返回 value 本身。

代码示例

C#

// ===== 基础用法：三种情况 =====
float a = Mathf.Clamp(5.0f, 0.0f, 10.0f);
// 运行结果: a = 5.0（在范围内，不变）

float b = Mathf.Clamp(-3.0f, 0.0f, 10.0f);
// 运行结果: b = 0.0（低于下限，返回下限）

float c = Mathf.Clamp(15.0f, 0.0f, 10.0f);
// 运行结果: c = 10.0（超过上限，返回上限）


// ===== 实际场景：角色生命值 + 进度条 =====
[Export] public float ExMaxHealth = 100.0f;

private float _currentHealth = 85.0f;

public void Heal(float amount)
{
    // 回血后不能超过最大生命值
    _currentHealth = Mathf.Clamp(_currentHealth + amount, 0.0f, ExMaxHealth);
    GD.Print($"治疗后血量: {_currentHealth}");
}

public void TakeDamage(float damage)
{
    // 受伤后不能低于 0
    _currentHealth = Mathf.Clamp(_currentHealth - damage, 0.0f, ExMaxHealth);

    // 计算血量百分比（0~1），用于 UI 进度条
    float healthPercent = Mathf.Clamp(_currentHealth / ExMaxHealth, 0.0f, 1.0f);
    GD.Print($"血量百分比: {healthPercent:P0}");
}

// 调用示例：
// Heal(30.0f)        → 运行结果: 治疗后血量: 100.0（被上限截住）
// TakeDamage(200.0f)  → 运行结果: 血量百分比: 0%（被下限截住）


// ===== 进阶用法：渐变透明度控制 =====
[Export] public float ExFadeSpeed = 2.0f;

private float _alpha = 1.0f;      // 当前透明度（1.0 完全可见，0.0 完全透明）
private bool _isFadingOut = true;

public override void _Process(double delta)
{
    if (_isFadingOut)
    {
        // 逐渐变透明
        _alpha -= ExFadeSpeed * (float)delta;
    }
    else
    {
        // 逐渐变可见
        _alpha += ExFadeSpeed * (float)delta;
    }

    // 透明度只能在 0.0 ~ 1.0 之间
    _alpha = Mathf.Clamp(_alpha, 0.0f, 1.0f);

    // 到达边界时切换方向
    if (_alpha <= 0.0f) _isFadingOut = false;
    if (_alpha >= 1.0f) _isFadingOut = true;

    GD.Print($"当前透明度: {_alpha:F2}");
}

// 运行结果（逐帧输出）:
// 当前透明度: 0.98
// 当前透明度: 0.94
// ...（持续减少直到 0.00，然后开始增加）
// 当前透明度: 0.00（到底，开始恢复）

GDScript

# ===== 基础用法：三种情况 =====
var a = clampf(5.0, 0.0, 10.0)
# 运行结果: a = 5.0（在范围内，不变）

var b = clampf(-3.0, 0.0, 10.0)
# 运行结果: b = 0.0（低于下限，返回下限）

var c = clampf(15.0, 0.0, 10.0)
# 运行结果: c = 10.0（超过上限，返回上限）


# ===== 实际场景：角色生命值 + 进度条 =====
@export var ex_max_health: float = 100.0

var _current_health: float = 85.0

func heal(amount: float) -> void:
    # 回血后不能超过最大生命值
    _current_health = clampf(_current_health + amount, 0.0, ex_max_health)
    print("治疗后血量: %f" % _current_health)

func take_damage(damage: float) -> void:
    # 受伤后不能低于 0
    _current_health = clampf(_current_health - damage, 0.0, ex_max_health)

    # 计算血量百分比（0~1），用于 UI 进度条
    var health_percent = clampf(_current_health / ex_max_health, 0.0, 1.0)
    print("血量百分比: %.0f%%" % (health_percent * 100))

# 调用示例：
# heal(30.0)        → 运行结果: 治疗后血量: 100.0（被上限截住）
# take_damage(200.0) → 运行结果: 血量百分比: 0%（被下限截住）


# ===== 进阶用法：渐变透明度控制 =====
@export var ex_fade_speed: float = 2.0

var _alpha: float = 1.0      # 当前透明度（1.0 完全可见，0.0 完全透明）
var _is_fading_out: bool = true

func _process(delta: float) -> void:
    if _is_fading_out:
        # 逐渐变透明
        _alpha -= ex_fade_speed * delta
    else:
        # 逐渐变可见
        _alpha += ex_fade_speed * delta

    # 透明度只能在 0.0 ~ 1.0 之间
    _alpha = clampf(_alpha, 0.0, 1.0)

    # 到达边界时切换方向
    if _alpha <= 0.0:
        _is_fading_out = false
    if _alpha >= 1.0:
        _is_fading_out = true

    print("当前透明度: %.2f" % _alpha)

# 运行结果（逐帧输出）:
# 当前透明度: 0.98
# 当前透明度: 0.94
# ...（持续减少直到 0.00，然后开始增加）
# 当前透明度: 0.00（到底，开始恢复）

注意事项

• 此函数只接受浮点数（float）参数。如果需要对整数进行限值，请使用 clampi()。
• 如果 min 大于 max，行为是未定义的（可能返回 min 或 max，取决于具体实现），请确保 min <= max。
• clampf 是游戏开发中使用频率极高的函数之一，几乎所有涉及浮点数范围控制的场景都会用到它。
• clampf 等价于 minf(maxfValue, maxf(minfValue, value))——先保证不低于下限，再保证不超过上限。
• 浮点数比较可能受精度影响。如果需要判断两个浮点数是否"近似相等"，请使用 is_equal_approx()。