godot-utils

SKILL.md 节选

# GDScript 工具函数库

> **用途**：提供可复用的 GDScript 工具函数，加速游戏开发  
> **版本**：v1.0 · 2026-04-24  
> **适用**：Godot 4.x

---

## 目录

1. [数学工具](#1-数学工具)
2. [向量工具](#2-向量工具)
3. [随机工具](#3-随机工具)
4. [时间工具](#4-时间工具)
5. [字符串工具](#5-字符串工具)
6. [数组工具](#6-数组工具)
7. [节点工具](#7-节点工具)
8. [文件工具](#8-文件工具)
9. [调试工具](#9-调试工具)
10. [缓动工具](#10-缓动工具)

---

## 使用方式

### 方式 1：复制到项目
直接复制需要的函数到你的脚本中。

### 方式 2：Autoload
创建 `res://autoload/utils.gd`，在项目设置中注册为 Autoload（名称 `Utils`），然后全局调用 `Utils.xxx()`。

---

## 1. 数学工具

```gdscript
class_name MathUtils

## 线性插值，支持 clamp
static func lerp_clamped(from: float, to: float, weight: float) -> float:
    return lerpf(from, to, clampf(weight, 0.0, 1.0))

## 平滑阻尼（类似 Unity 的 SmoothDamp）
static func smooth_damp(current: float, target: float, velocity: float, smooth_time: float, delta: float) -> Array:
    var omega := 2.0 / smooth_time
    var x := omega * delta
    var exp_factor := 1.0 / (1.0 + x + 0.48 * x * x + 0.235 * x * x * x)
    var change := current - target
    var temp := (velocity + omega * change) * delta
    var new_velocity := (velocity - omega * temp) * exp_factor
    var new_value := target + (change + temp) * exp_factor
    return [new_value, new_velocity]

## 重映射值从一个范围到另一个范围
static func remap(value: float, from_min: float, from_max: float, to_min: float, to_max: float) -> float:
    return to_min + (value - from_min) * (to_max - to_min) / (from_max - from_min)

## 重映射并 clamp
static func remap_clamped(value: float, from_min: float, from_max: float, to_min: float, to_max: float) -> float:
    var t := clampf((value - from_min) / (from_max - from_min), 0.0, 1.0)
    return lerpf(to_min, to_max, t)

## 角度归一化到 [-180, 180]
static func normalize_angle(degrees: float) -> float:
    degrees = fmod(degrees + 180.0, 360.0)
    if degrees < 0:
        degrees += 360.0
    return degrees - 180.0

## 角度归一化到 [0, 360]
static func normalize_angle_positive(degrees: float) -> float:
    degrees = fmod(degrees, 360.0)
    if degrees < 0:
        degrees += 360.0
    return degrees

## 弧度归一化到 [-PI, PI]
static func normalize_radians(radians: float) -> float:
    radians = fmod(radians + PI, TAU)
    if radians < 0:
        radians += TAU
    return radians - PI

## 检查两个浮点数是否近似相等
static func approx_equal(a: float, b: float, epsilon := 0.0001) -> bool:
    return absf(a - b) < epsilon

## 检查值是否在范围内
static func in_range(value: float, min_val: float, max_val: float) -> bool:
    return value >= min_val and value <= max_val

## 取模（支持负数，结果总是正数）
static func positive_mod(a: int, b: int) -> int:
    return ((a % b) + b) % b

## 取模浮点版
static func positive_fmod(a: float, b: float) -> float:
    return fmod(fmod(a, b) + b, b)
```

---

## 2. 向量工具

```gdscript
class_name VectorUtils

## Vector2 平滑阻尼
static func smooth_damp_v2(current: Vector2, target: Vector2, velocity: Vector2, smooth_time: float, delta: float) -> Array:
    var result_x := MathUtils.smooth_damp(current.x, target.x, velocity.x, smooth_time, delta)
    var result_y := MathUtils.smooth_damp(current.y, target.y, velocity.y, smooth_time, delta)
    return [Vector2(result_x[0], result_y[0]), Vector2(result_x[1], result_y[1])]

## Vector3 平滑阻尼
static func smooth_damp_v3(current: Vector3, target: Vector3, velocity: Vector3, smooth_time: float, delta: float) -> Array:
    var result_x := MathUtils.smooth_damp(current.x, target.x, velocity.x, smooth_time, delta)
    var result_y := MathUtils.smooth_damp(current.y, target.y, velocity.y, smooth_time, delta)

SKILL.md 不止这些内容，安装后可阅读全文。

技能包内容

共 1 个文件，合计 28.5 KiB