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

is_finite

定义

is_finite 是一个用来判断一个浮点数是否是"有限数"的函数。

什么叫有限数？就是"正常"的数——不是无穷大，也不是 NaN（Not a Number，即"非数字"）。打个比方：就像你去银行查余额，结果要么显示一个正常的金额（有限数），要么显示"系统错误"（NaN），要么显示"∞"（无穷大）。is_finite 就是帮你检查余额显示是不是正常的那个。

更具体地说，is_finite 会在以下情况返回 false：

• 数值是 NaN（Not a Number）—— 比如 0.0 / 0.0 的结果
• 数值是 正无穷大 —— 比如 1.0 / 0.0 的结果
• 数值是 负无穷大 —— 比如 -1.0 / 0.0 的结果

什么时候需要用到它？

• 在进行除法运算前，检查结果是否有效
• 验证从外部数据源（网络、文件）读取的数值是否正常
• 在数学计算链中做安全检查，防止异常值传播

函数签名

C#

// 方式一：通过 Mathf 类调用（Godot 封装）
public static bool IsFinite(float x)

// 方式二：使用 .NET 原生方法
// float.IsFinite(x)

GDScript

# 全局函数，无需前缀直接调用
func is_finite(x: float) -> bool

参数说明

参数名	类型	说明
x	float	要检查是否为有限数的浮点数

返回值

bool — 如果 x 是有限数（既不是 NaN 也不是无穷大），返回 true；否则返回 false。

代码示例

基本用法：判断浮点数是否有限

C#

using Godot;

public partial class MyNode : Node
{
    public override void _Ready()
    {
        float a = 42.0f;
        float b = float.NaN;           // 非数字
        float c = float.PositiveInfinity; // 正无穷
        float d = float.NegativeInfinity; // 负无穷

        GD.Print(Mathf.IsFinite(a));    // 输出: True  （正常的数）
        GD.Print(Mathf.IsFinite(b));    // 输出: False （NaN 不是有限数）
        GD.Print(Mathf.IsFinite(c));    // 输出: False （无穷大不是有限数）
        GD.Print(Mathf.IsFinite(d));    // 输出: False （负无穷也不是有限数）
    }
}

GDScript

extends Node

func _ready():
    var a = 42.0
    var b = NAN             # 非数字
    var c = INF             # 正无穷
    var d = -INF            # 负无穷

    print(is_finite(a))     # 输出: True  （正常的数）
    print(is_finite(b))     # 输出: False （NaN 不是有限数）
    print(is_finite(c))     # 输出: False （无穷大不是有限数）
    print(is_finite(d))     # 输出: False （负无穷也不是有限数）

实际场景：安全除法——防止异常值传播

C#

using Godot;

public partial class DamageCalculator : Node
{
    // 导出属性：基础伤害值
    [Export] public float ExBaseDamage = 100.0f;

    // 内部变量：计算结果
    private float _resultDamage;

    /// <summary>
    /// 安全计算伤害倍率，防止除零导致异常值
    /// </summary>
    public float CalculateDamageMultiplier(float resistance)
    {
        float multiplier = 1.0f / resistance;

        // 检查计算结果是否有限
        if (!Mathf.IsFinite(multiplier))
        {
            GD.PrintErr("伤害倍率计算结果异常，使用默认值 1.0");
            return 1.0f;
        }

        return multiplier;
    }

    public override void _Ready()
    {
        // 正常情况
        float result1 = CalculateDamageMultiplier(2.0f);
        GD.Print($"抗性为 2.0 时，倍率: {result1}");  // 输出: 0.5

        // 异常情况：除零
        float result2 = CalculateDamageMultiplier(0.0f);
        GD.Print($"抗性为 0.0 时，倍率: {result2}");  // 输出: 1.0（使用了默认值）
    }
}

GDScript

extends Node

# 导出属性：基础伤害值
@export var base_damage: float = 100.0

# 内部变量：计算结果
var _result_damage: float

## 安全计算伤害倍率，防止除零导致异常值
func calculate_damage_multiplier(resistance: float) -> float:
    var multiplier = 1.0 / resistance

    # 检查计算结果是否有限
    if not is_finite(multiplier):
        push_error("伤害倍率计算结果异常，使用默认值 1.0")
        return 1.0

    return multiplier

func _ready():
    # 正常情况
    var result1 = calculate_damage_multiplier(2.0)
    print("抗性为 2.0 时，倍率: ", result1)  # 输出: 0.5

    # 异常情况：除零
    var result2 = calculate_damage_multiplier(0.0)
    print("抗性为 0.0 时，倍率: ", result2)  # 输出: 1.0（使用了默认值）

注意事项

1. is_finite 等价于 !is_nan(x) && !is_inf(x)：一个数要么是 NaN，要么是无穷大，要么是有限数，这三者互斥。is_finite 就是非 NaN 且非无穷大的情况。

2. C# 中有两种写法：Mathf.IsFinite(x) 和 float.IsFinite(x) 效果完全一样，Mathf.IsFinite 是 Godot 对 .NET 原生方法的封装，两者可以互换使用。

3. NaN 具有传染性：任何涉及 NaN 的运算结果都是 NaN。如果你不及时检测并处理，NaN 会像病毒一样在计算链中传播。使用 is_finite 可以在关键节点拦截异常值。

4. 无穷大不等于大数：is_finite(999999999.0) 返回 true，因为再大的有限数也是有限数。只有真正的 INF 或 -INF 才会返回 false。