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

fposmod

定义

fposmod() 用来计算两个浮点数相除的正数余数——和 fmod 类似，但保证结果始终是非负数。

还是蛋糕的比喻：如果你有 -10.5 块蛋糕（欠了别人 10.5 块），要按每人 3 块来算。fmod(-10.5, 3) 返回 -1.5（负数余数），但 fposmod(-10.5, 3) 返回 1.5（正数余数）。它的思路是：借一块蛋糕凑整份，分完后把剩下的还回去。

在游戏开发中，当你需要把一个值"绕回"到某个正数范围内时（比如把任意角度映射到 0~360 度），fposmod 就非常有用，因为它不会出现负数的情况。

函数签名

C#

// C# 中需要手动实现，或使用 Mathf.PosMod（如果可用）
float result = Mathf.PosMod(x, y);
// 手动实现方式：
// float result = (x % y + y) % y;

GDScript

func fposmod(x: float, y: float) -> float

参数说明

参数	类型	必需	说明
x	float	是	被除数
y	float	是	除数，不能为 0，且应为正数才能保证结果有意义

返回值

float —— x 除以 y 的非负余数。结果始终大于或等于 0，小于 y。例如 fposmod(-10.5, 3.0) 返回 1.5，而 fmod(-10.5, 3.0) 返回 -1.5。

代码示例

C#

// 基本用法
float a = Mathf.PosMod(10.5f, 3.0f);    // 1.5
float b = Mathf.PosMod(-10.5f, 3.0f);   // 1.5（注意：与 fmod 的结果不同）
float c = Mathf.PosMod(7.5f, 2.5f);     // 0.0

// 对比 fmod 和 fposmod 处理负数
float fmodResult = -10.5f % 3.0f;        // -1.5
float fposmodResult = Mathf.PosMod(-10.5f, 3.0f); // 1.5
GD.Print($"fmod: {fmodResult}, fposmod: {fposmodResult}");

// 实际使用：将任意角度映射到 0~360 度范围
float angle = -45.0f;
float normalized = Mathf.PosMod(angle, 360.0f); // 315.0
GD.Print($"归一化角度: {normalized}");

GDScript

# 基本用法
var a = fposmod(10.5, 3.0)    # 1.5
var b = fposmod(-10.5, 3.0)   # 1.5（注意：与 fmod 的结果不同）
var c = fposmod(7.5, 2.5)     # 0.0

# 对比 fmod 和 fposmod 处理负数
var fmod_result = fmod(-10.5, 3.0)      # -1.5
var fposmod_result = fposmod(-10.5, 3.0) # 1.5
print("fmod: %f, fposmod: %f" % [fmod_result, fposmod_result])

# 实际使用：将任意角度映射到 0~360 度范围
var angle = -45.0
var normalized = fposmod(angle, 360.0)  # 315.0
print("归一化角度: %f" % normalized)

注意事项

• 除数不能为 0：如果 y 为 0，会导致除零错误。
• 与 fmod 的关键区别：fmod 的余数与被除数同号（可能为负），fposmod 的余数始终非负。选择哪个取决于你是否需要负数余数。
• 如果除数 y 为负数，fposmod 的结果可能不符合预期，建议除数始终使用正数。
• C# 中如果没有 Mathf.PosMod()，可以用 (x % y + y) % y 手动实现相同效果。