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

wrapf

定义

wrapf() 用来将一个浮点数"环绕"到指定的范围内——简单说，就是"超出了就绕回来"。

最常见的例子就是时钟：现在是 10 点，再过 5 个小时是 15 点吗？不对，时钟上只有 1~12（或 0~11），超过最大值就从头开始，所以是 3 点。wrapf(15, 1, 13) 返回 3.0——15 超过了上限 13，就从下限 1 开始继续数。

和 clampf 的区别在于：clampf 是"超出了就截住"，wrapf 是"超出了就绕一圈回来"。在游戏开发中，环绕常用于处理角度、循环索引、昼夜时间等需要"首尾相连"的场景。

函数签名

C#

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

GDScript

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

参数说明

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

返回值

float —— 被"环绕"到 [min, max) 范围内的值。如果 value 超过 max，就从 min 开始继续数；如果 value 低于 min，就从 max 往回数。注意 max 本身不包含在范围内（这是一个"左闭右开"区间）。

代码示例

C#

// 基本用法
float a = Mathf.Wrap(15.0f, 1.0f, 13.0f);   // 3.0（15 - 13 + 1 = 3，时钟效果）
float b = Mathf.Wrap(-2.0f, 0.0f, 360.0f);  // 358.0（角度绕回）
float c = Mathf.Wrap(5.0f, 0.0f, 10.0f);    // 5.0（在范围内，不变）

// 实际使用：模拟时钟（12 小时制）
float currentHour = 11.0f;
float hoursLater = 4.0f;
float newHour = Mathf.Wrap(currentHour + hoursLater, 1.0f, 13.0f); // 3.0
GD.Print($"过了 {hoursLater} 小时后是 {newHour} 点");

// 循环播放动画帧
float totalFrames = 8.0f;
float currentFrame = 7.5f;
float nextFrame = Mathf.Wrap(currentFrame + 0.5f, 0.0f, totalFrames); // 0.0（回到开头）

GDScript

# 基本用法
var a = wrapf(15.0, 1.0, 13.0)   # 3.0（15 - 13 + 1 = 3，时钟效果）
var b = wrapf(-2.0, 0.0, 360.0)  # 358.0（角度绕回）
var c = wrapf(5.0, 0.0, 10.0)    # 5.0（在范围内，不变）

# 实际使用：模拟时钟（12 小时制）
var current_hour = 11.0
var hours_later = 4.0
var new_hour = wrapf(current_hour + hours_later, 1.0, 13.0)  # 3.0
print("过了 %f 小时后是 %f 点" % [hours_later, new_hour])

# 循环播放动画帧
var total_frames = 8.0
var current_frame = 7.5
var next_frame = wrapf(current_frame + 0.5, 0.0, total_frames)  # 0.0（回到开头）

注意事项

• 范围是左闭右开的 [min, max)：max 本身不会被返回。如果 value 恰好等于 max，会返回 min。
• 此函数处理的是浮点数（float）。如果需要对整数进行环绕，请使用 wrapi()。
• 如果 min 等于 max，行为是未定义的，请确保 min < max。
• wrapf 和 clampf 的关键区别：clampf 把超出范围的值"截"在边界上，wrapf 把超出范围的值"绕"回范围内。