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

wrapi

定义

wrapi() 用来将一个整数"环绕"到指定的范围内——和 wrapf 功能完全一样，只不过它处理的是整数（int）。

还是时钟的例子，但这次我们用游戏中的回合数来比喻：一个 4 人轮流游戏，玩家编号是 0、1、2、3。现在是 3 号玩家的回合，下一个应该是 4 号吗？不对，只有 4 个人，所以绕回到 0 号。wrapi(4, 0, 4) 返回 0——超出了就从头来。

在游戏开发中，整数环绕常用于：循环切换武器槽、轮流回合制游戏中的玩家轮转、循环访问数组索引等场景。

函数签名

C#

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

GDScript

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

参数说明

参数	类型	必需	说明
value	int	是	要环绕的原始整数值
min	int	是	范围的最小值（下限）
max	int	是	范围的最大值（上限，不包含）

返回值

int —— 被"环绕"到 [min, max) 范围内的整数。如果 value 大于或等于 max，就从 min 开始继续数；如果 value 小于 min，就从 max 往回数。注意 max 本身不包含在范围内。

代码示例

C#

// 基本用法
int a = Mathf.Wrap(4, 0, 4);    // 0（4 >= max(4)，绕回到 min(0)）
int b = Mathf.Wrap(-1, 0, 4);   // 3（低于 min，从 max 往回数）
int c = Mathf.Wrap(2, 0, 4);    // 2（在范围内，不变）

// 实际使用：4 人轮流游戏，切换当前玩家
int currentPlayer = 3;
int totalPlayers = 4;
int nextPlayer = Mathf.Wrap(currentPlayer + 1, 0, totalPlayers); // 0
GD.Print($"下一个玩家: {nextPlayer}");

// 循环切换武器槽（3 个武器槽：0、1、2）
int currentSlot = 2;
int slotCount = 3;
int nextSlot = Mathf.Wrap(currentSlot + 1, 0, slotCount); // 0
GD.Print($"切换到武器槽: {nextSlot}");

GDScript

# 基本用法
var a = wrapi(4, 0, 4)    # 0（4 >= max(4)，绕回到 min(0)）
var b = wrapi(-1, 0, 4)   # 3（低于 min，从 max 往回数）
var c = wrapi(2, 0, 4)    # 2（在范围内，不变）

# 实际使用：4 人轮流游戏，切换当前玩家
var current_player = 3
var total_players = 4
var next_player = wrapi(current_player + 1, 0, total_players)  # 0
print("下一个玩家: %d" % next_player)

# 循环切换武器槽（3 个武器槽：0、1、2）
var current_slot = 2
var slot_count = 3
var next_slot = wrapi(current_slot + 1, 0, slot_count)  # 0
print("切换到武器槽: %d" % next_slot)

注意事项

• 范围是左闭右开的 [min, max)：max 本身不会被返回。如果 value 恰好等于 max，会返回 min。
• 此函数处理的是整数（int）。如果需要对浮点数进行环绕，请使用 wrapf()。
• 如果 min 等于 max，行为是未定义的，请确保 min < max。
• wrapi 特别适合用于数组索引的循环访问，搭配数组的 size() 方法使用可以避免越界错误。