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

clampi

定义

clampi() 用来把一个整数限制在指定的最小值和最大值之间——和 clampf 功能完全一样，只不过它处理的是整数（int）。

打个比方：一个停车场最多只能停 50 辆车，最少也得有 0 辆车。不管你统计出来是 -5 辆（系统出错？）还是 80 辆（算错了？），实际显示的车辆数只能"夹"在 0 到 50 之间。clampi() 就是这个停车场管理员。

在游戏开发中，整数限值常用于：限制物品堆叠数量、限制等级范围、限制可选的角色数量、限制波次敌人数量等场景。

函数签名

C#

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

GDScript

func clampi(value: int, min: int, max: int) -> int

参数说明

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

返回值

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

代码示例

C#

// ===== 基础用法：三种情况 =====
int a = Mathf.Clamp(5, 0, 10);
// 运行结果: a = 5（在范围内，不变）

int b = Mathf.Clamp(-3, 0, 10);
// 运行结果: b = 0（低于下限，返回下限）

int c = Mathf.Clamp(15, 0, 10);
// 运行结果: c = 10（超过上限，返回上限）


// ===== 实际场景：物品堆叠 + 等级限制 =====
[Export] public int ExMaxStack = 64;
[Export] public int ExMaxLevel = 99;
[Export] public int ExMinLevel = 1;

private int _itemCount = 50;
private int _playerLevel = 1;

public void AddItems(int amount)
{
    // 物品堆叠不能超过上限，也不能低于 0
    _itemCount = Mathf.Clamp(_itemCount + amount, 0, ExMaxStack);
    GD.Print($"物品数量: {_itemCount}/{ExMaxStack}");
}

public void SetLevel(int level)
{
    // 等级只能在 1~99 之间
    _playerLevel = Mathf.Clamp(level, ExMinLevel, ExMaxLevel);
    GD.Print($"当前等级: {_playerLevel}");
}

// 调用示例：
// AddItems(30)   → 运行结果: 物品数量: 64/64（被上限截住）
// AddItems(-80)  → 运行结果: 物品数量: 0/64（被下限截住）
// SetLevel(-5)   → 运行结果: 当前等级: 1（等级不能低于 1）
// SetLevel(150)  → 运行结果: 当前等级: 99（等级不能超过 99）


// ===== 进阶用法：敌人波次系统 =====
[Export] public int ExMinEnemies = 3;     // 每波最少敌人数
[Export] public int ExMaxEnemies = 20;    // 每波最多敌人数
[Export] public int ExEnemiesPerWave = 2; // 每波增加的敌人数量

private int _currentWave = 0;
private int _enemyCount = 0;

public void StartNextWave()
{
    _currentWave++;

    // 敌人数量 = 基础数 + 波次 * 增量，但限制在范围内
    _enemyCount = Mathf.Clamp(
        ExMinEnemies + _currentWave * ExEnemiesPerWave,
        ExMinEnemies,
        ExMaxEnemies
    );

    GD.Print($"第 {_currentWave} 波，敌人数量: {_enemyCount}");
}

// 调用示例：
// StartNextWave() × 1   → 运行结果: 第 1 波，敌人数量: 5
// StartNextWave() × 5   → 运行结果: 第 5 波，敌人数量: 13
// StartNextWave() × 10  → 运行结果: 第 10 波，敌人数量: 20（被上限截住）

GDScript

# ===== 基础用法：三种情况 =====
var a = clampi(5, 0, 10)
# 运行结果: a = 5（在范围内，不变）

var b = clampi(-3, 0, 10)
# 运行结果: b = 0（低于下限，返回下限）

var c = clampi(15, 0, 10)
# 运行结果: c = 10（超过上限，返回上限）


# ===== 实际场景：物品堆叠 + 等级限制 =====
@export var ex_max_stack: int = 64
@export var ex_max_level: int = 99
@export var ex_min_level: int = 1

var _item_count: int = 50
var _player_level: int = 1

func add_items(amount: int) -> void:
    # 物品堆叠不能超过上限，也不能低于 0
    _item_count = clampi(_item_count + amount, 0, ex_max_stack)
    print("物品数量: %d/%d" % [_item_count, ex_max_stack])

func set_level(level: int) -> void:
    # 等级只能在 1~99 之间
    _player_level = clampi(level, ex_min_level, ex_max_level)
    print("当前等级: %d" % _player_level)

# 调用示例：
# add_items(30)   → 运行结果: 物品数量: 64/64（被上限截住）
# add_items(-80)  → 运行结果: 物品数量: 0/64（被下限截住）
# set_level(-5)   → 运行结果: 当前等级: 1（等级不能低于 1）
# set_level(150)  → 运行结果: 当前等级: 99（等级不能超过 99）


# ===== 进阶用法：敌人波次系统 =====
@export var ex_min_enemies: int = 3     # 每波最少敌人数
@export var ex_max_enemies: int = 20    # 每波最多敌人数
@export var ex_enemies_per_wave: int = 2 # 每波增加的敌人数量

var _current_wave: int = 0
var _enemy_count: int = 0

func start_next_wave() -> void:
    _current_wave += 1

    # 敌人数量 = 基础数 + 波次 * 增量，但限制在范围内
    _enemy_count = clampi(
        ex_min_enemies + _current_wave * ex_enemies_per_wave,
        ex_min_enemies,
        ex_max_enemies
    )

    print("第 %d 波，敌人数量: %d" % [_current_wave, _enemy_count])

# 调用示例：
# start_next_wave() × 1   → 运行结果: 第 1 波，敌人数量: 5
# start_next_wave() × 5   → 运行结果: 第 5 波，敌人数量: 13
# start_next_wave() × 10  → 运行结果: 第 10 波，敌人数量: 20（被上限截住）

注意事项

• 此函数只接受整数（int）参数。如果需要对浮点数进行限值，请使用 clampf()。
• 如果 min 大于 max，行为是未定义的，请确保 min <= max。
• C# 中 Mathf.Clamp() 有多个重载版本，同时支持 int 和 float 参数，编译器会根据传入的参数类型自动选择对应的重载。
• clampi 等价于 mini(maxiValue, maxi(miniValue, value))——先保证不低于下限，再保证不超过上限。
• 注意整数有范围限制（int 类型为 -2,147,483,648 到 2,147,483,647），极端大数运算时需留意溢出。