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

snappedf

定义

snappedf() 用来将一个浮点数"吸附"到最近的步长倍数上——简单说，就是"按刻度对齐"。

想象一段楼梯，每级台阶高 0.5 米。你现在站在 3.7 米高的位置，但楼梯只有 3.5 米和 4.0 米两个位置有台阶。snappedf(3.7, 0.5) 会帮你"跳"到离你最近的台阶——4.0 米（因为 3.7 离 4.0 比离 3.5 更近）。

在游戏开发中，这个函数常用于：让物体对齐到网格、让移动按固定步进跳跃、让数值按固定间距变化等场景。

函数签名

C#

public static float Snapped(float x, float step)

GDScript

func snappedf(x: float, step: float) -> float

参数说明

参数	类型	必需	说明
x	float	是	要对齐的原始值
step	float	是	步长（吸附的间隔大小）

返回值

float —— 离 x 最近的 step 的整数倍。例如 snappedf(3.7, 1.0) 返回 4.0，snappedf(3.2, 1.0) 返回 3.0。

代码示例

C#

// 基本用法
float a = Mathf.Snapped(3.7f, 1.0f);   // 4.0（离 3.7 最近的整数倍是 4）
float b = Mathf.Snapped(3.2f, 1.0f);   // 3.0（离 3.2 最近的整数倍是 3）
float c = Mathf.Snapped(5.0f, 0.5f);   // 5.0（5.0 已经是 0.5 的整数倍）
float d = Mathf.Snapped(3.7f, 0.5f);   // 3.5（3.5 和 4.0 之间选更近的 3.5）

// 实际使用：让角色对齐到网格（每格 32 像素）
float playerX = 45.3f;
float gridSize = 32.0f;
float snappedX = Mathf.Snapped(playerX, gridSize); // 32.0
GD.Print($"对齐后位置: {snappedX}");

// 让滑块值按 0.1 步进
float sliderValue = 0.37f;
sliderValue = Mathf.Snapped(sliderValue, 0.1f); // 0.4

GDScript

# 基本用法
var a = snappedf(3.7, 1.0)   # 4.0（离 3.7 最近的整数倍是 4）
var b = snappedf(3.2, 1.0)   # 3.0（离 3.2 最近的整数倍是 3）
var c = snappedf(5.0, 0.5)   # 5.0（5.0 已经是 0.5 的整数倍）
var d = snappedf(3.7, 0.5)   # 3.5（3.5 和 4.0 之间选更近的 3.5）

# 实际使用：让角色对齐到网格（每格 32 像素）
var player_x = 45.3
var grid_size = 32.0
var snapped_x = snappedf(player_x, grid_size)  # 32.0
print("对齐后位置: %f" % snapped_x)

# 让滑块值按 0.1 步进
var slider_value = 0.37
slider_value = snappedf(slider_value, 0.1)  # 0.4

注意事项

• 如果 step 为 0，函数返回 0（不会报错，但也没有实际意义）。
• 当 x 恰好处于两个步长倍数的正中间时（如 snappedf(2.5, 1.0)），函数会向上取整，返回 3.0。
• 此函数处理的是浮点数（float）。如果需要对整数进行吸附，请使用 snappedi()。
• 步长 step 为负数时，其绝对值会被当作步长使用。