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

snappedi

定义

snappedi() 用来将一个整数"吸附"到最近的步长倍数上——和 snappedf 功能一样，只不过它处理的是整数（int）。

打个比方：一个教室里的座位是按每排 5 个排列的（第 5、10、15...个位置是每排的末尾）。你现在在第 13 个位置，但只能坐在排尾。snappedi(13, 5) 帮你跳到最近的排尾——第 15 个位置。

在游戏开发中，整数吸附常用于：将像素坐标对齐到 tile 地图的网格、将关卡编号对齐到章节间隔等场景。

函数签名

C#

// C# 中需要手动计算或使用 Mathf.Snapped 后转 int
int result = (int)Mathf.Snapped(x, step);

GDScript

func snappedi(x: int, step: int) -> int

参数说明

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

返回值

int —— 离 x 最近的 step 的整数倍。例如 snappedi(13, 5) 返回 15，snappedi(12, 5) 返回 10。

代码示例

C#

// 基本用法
int a = (int)Mathf.Snapped(13, 5);   // 15（离 13 最近的 5 的倍数是 15）
int b = (int)Mathf.Snapped(12, 5);   // 10（离 12 最近的 5 的倍数是 10）
int c = (int)Mathf.Snapped(10, 5);   // 10（10 已经是 5 的倍数）

// 实际使用：将像素坐标对齐到 tile 网格（每格 16 像素）
int pixelX = 37;
int tileSize = 16;
int tileX = (int)Mathf.Snapped(pixelX, tileSize); // 32
GD.Print($"对齐到 tile: {tileX}");

// 将分数按 10 分一档归类
int score = 73;
int band = (int)Mathf.Snapped(score, 10); // 70

GDScript

# 基本用法
var a = snappedi(13, 5)   # 15（离 13 最近的 5 的倍数是 15）
var b = snappedi(12, 5)   # 10（离 12 最近的 5 的倍数是 10）
var c = snappedi(10, 5)   # 10（10 已经是 5 的倍数）

# 实际使用：将像素坐标对齐到 tile 网格（每格 16 像素）
var pixel_x = 37
var tile_size = 16
var tile_x = snappedi(pixel_x, tile_size)  # 32
print("对齐到 tile: %d" % tile_x)

# 将分数按 10 分一档归类
var score = 73
var band = snappedi(score, 10)  # 70

注意事项

• 如果 step 为 0，函数返回 0。
• 当 x 恰好处于两个步长倍数的正中间时（如 snappedi(15, 10)），函数会向上取整，返回 20。
• 此函数处理的是整数（int）。如果需要对浮点数进行吸附，请使用 snappedf()。
• C# 中没有直接对应的整数版本，可以用 (int)Mathf.Snapped(x, step) 实现相同效果。