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

asin

定义

asin() 是反正弦函数（arc sine）——它是 sin() 的"反过来的操作"。

如果 sin() 是问"给我一个角度，告诉我它在圆上的垂直位置"，那 asin() 就是反过来问"我知道圆上的垂直位置了，你告诉我对应的角度是多少"。

打个比方：sin() 就像你告诉出租车司机"往东走 500 米再往北走 300 米"，司机到了目的地。而 asin() 就像你站在目的地打电话问司机"我这里的纬度是多少"——从位置反推出角度。

重要限制：因为 sin() 的输出范围是 -1 到 1，所以 asin() 的输入也只能是 -1 到 1 之间的数。超出这个范围，函数就"算不了"了。

角度单位是弧度，不是度数

asin() 返回的结果是弧度，不是度数。如果需要度数，用 rad_to_deg() 转换。

函数签名

C#

// 使用 Godot 的 Mathf（推荐，返回 float）
public static float Asin(float s)

GDScript

func asin(s: float) -> float

参数说明

参数	类型	必需	说明
s	float	是	正弦值，必须在 -1.0 到 1.0 之间（含端点）。超出此范围会返回 NaN

返回值

类型： float

返回一个弧度值，范围在 -PI/2 到 PI/2 之间（即 -90 度到 90 度）。

输入	输出（弧度）	输出（约等于度数）	说明
0.0	0.0	0 度	sin(0) = 0，反过来也成立
1.0	PI/2	90 度	sin(90度) = 1 的逆运算
-1.0	-PI/2	-90 度	sin(-90度) = -1 的逆运算
0.5	PI/6	30 度	sin(30度) = 0.5 的逆运算

代码示例

基础用法：从正弦值反推角度

C#

using Godot;

public partial class AsinExample : Node
{
    public override void _Ready()
    {
        // 已知正弦值，反推角度
        float a1 = Mathf.Asin(0f);
        GD.Print("asin(0) = " + a1 + " 弧度 = " + Mathf.RadToDeg(a1) + " 度");
        // 运行结果: asin(0) = 0 弧度 = 0 度

        float a2 = Mathf.Asin(1f);
        GD.Print("asin(1) = " + a2 + " 弧度 = " + Mathf.RadToDeg(a2) + " 度");
        // 运行结果: asin(1) = 1.5707964 弧度 = 90 度

        float a3 = Mathf.Asin(0.5f);
        GD.Print("asin(0.5) = " + a3 + " 弧度 = " + Mathf.RadToDeg(a3) + " 度");
        // 运行结果: asin(0.5) = 0.523599 弧度 = 30 度

        float a4 = Mathf.Asin(-1f);
        GD.Print("asin(-1) = " + a4 + " 弧度 = " + Mathf.RadToDeg(a4) + " 度");
        // 运行结果: asin(-1) = -1.5707964 弧度 = -90 度
    }
}

GDScript

extends Node

func _ready():
    # 已知正弦值，反推角度
    var a1 = asin(0.0)
    print("asin(0) = ", a1, " 弧度 = ", rad_to_deg(a1), " 度")
    # 运行结果: asin(0) = 0 弧度 = 0 度

    var a2 = asin(1.0)
    print("asin(1) = ", a2, " 弧度 = ", rad_to_deg(a2), " 度")
    # 运行结果: asin(1) = 1.5707964 弧度 = 90 度

    var a3 = asin(0.5)
    print("asin(0.5) = ", a3, " 弧度 = ", rad_to_deg(a3), " 度")
    # 运行结果: asin(0.5) = 0.523599 弧度 = 30 度

    var a4 = asin(-1.0)
    print("asin(-1) = ", a4, " 弧度 = ", rad_to_deg(a4), " 度")
    # 运行结果: asin(-1) = -1.5707964 弧度 = -90 度

实际场景：根据垂直方向分量计算仰角

C#

using Godot;

public partial class LaunchAngle : Node
{
    public override void _Ready()
    {
        // 已知炮弹发射方向的归一化向量
        Vector2 launchDir = new Vector2(0.866f, 0.5f); // 大约 30 度方向

        // launchDir.Y 就是 sin(角度)，因为方向向量已归一化
        float angle = Mathf.Asin(launchDir.Y);

        GD.Print($"发射方向: {launchDir}");
        GD.Print($"仰角: {Mathf.RadToDeg(angle):F1} 度");
        // 运行结果: 发射方向: (0.866, 0.5)
        // 运行结果: 仰角: 30.0 度
    }
}

GDScript

extends Node

func _ready():
    # 已知炮弹发射方向的归一化向量
    var launch_dir := Vector2(0.866, 0.5)  # 大约 30 度方向

    # launch_dir.y 就是 sin(角度)，因为方向向量已归一化
    var angle := asin(launch_dir.y)

    print("发射方向: ", launch_dir)
    print("仰角: %.1f 度" % rad_to_deg(angle))
    # 运行结果: 发射方向: (0.866, 0.5)
    # 运行结果: 仰角: 30.0 度

进阶用法：验证 asin 和 sin 的互逆关系

C#

using Godot;

public partial class InverseCheck : Node
{
    public override void _Ready()
    {
        // sin 和 asin 是互逆函数：asin(sin(x)) = x（在 -PI/2 到 PI/2 范围内）
        float[] testAngles = { 0f, Mathf.Pi / 6f, Mathf.Pi / 4f, Mathf.Pi / 3f };

        foreach (float angle in testAngles)
        {
            float sineVal = Mathf.Sin(angle);
            float recovered = Mathf.Asin(sineVal);

            GD.Print($"原始角度: {Mathf.RadToDeg(angle):F1} 度 -> " +
                     $"sin = {sineVal:F4} -> " +
                     $"asin = {Mathf.RadToDeg(recovered):F1} 度");
        }
        // 运行结果: 原始角度: 0.0 度 -> sin = 0.0000 -> asin = 0.0 度
        // 运行结果: 原始角度: 30.0 度 -> sin = 0.5000 -> asin = 30.0 度
        // 运行结果: 原始角度: 45.0 度 -> sin = 0.7071 -> asin = 45.0 度
        // 运行结果: 原始角度: 60.0 度 -> sin = 0.8660 -> asin = 60.0 度

        // 注意：超出 -PI/2 ~ PI/2 范围的角度无法完全还原
        float bigAngle = Mathf.DegToRad(120f); // 120 度
        float sin120 = Mathf.Sin(bigAngle);
        float recoveredBig = Mathf.Asin(sin120);
        GD.Print($"120 度 -> sin = {sin120:F4} -> asin = {Mathf.RadToDeg(recoveredBig):F1} 度（不是 120 度！）");
        // 运行结果: 120 度 -> sin = 0.8660 -> asin = 60.0 度（不是 120 度！）
    }
}

GDScript

extends Node

func _ready():
    # sin 和 asin 是互逆函数：asin(sin(x)) = x（在 -PI/2 到 PI/2 范围内）
    var test_angles := [0.0, PI / 6.0, PI / 4.0, PI / 3.0]

    for angle in test_angles:
        var sine_val := sin(angle)
        var recovered := asin(sine_val)

        print("原始角度: %.1f 度 -> sin = %.4f -> asin = %.1f 度" % [
            rad_to_deg(angle), sine_val, rad_to_deg(recovered)])
    # 运行结果: 原始角度: 0.0 度 -> sin = 0.0000 -> asin = 0.0 度
    # 运行结果: 原始角度: 30.0 度 -> sin = 0.5000 -> asin = 30.0 度
    # 运行结果: 原始角度: 45.0 度 -> sin = 0.7071 -> asin = 45.0 度
    # 运行结果: 原始角度: 60.0 度 -> sin = 0.8660 -> asin = 60.0 度

    # 注意：超出 -PI/2 ~ PI/2 范围的角度无法完全还原
    var big_angle := deg_to_rad(120.0)  # 120 度
    var sin_120 := sin(big_angle)
    var recovered_big := asin(sin_120)
    print("120 度 -> sin = %.4f -> asin = %.1f 度（不是 120 度！）" % [
        sin_120, rad_to_deg(recovered_big)])
    # 运行结果: 120 度 -> sin = 0.8660 -> asin = 60.0 度（不是 120 度！）

注意事项

1. 输入范围严格限制：asin() 只接受 -1 到 1 之间的值。传入 1.5 或 -2 这样的数会返回 NaN（Not a Number）。如果不确定输入是否在范围内，先用 Mathf.Clamp(value, -1f, 1f) 限制一下。
2. 输出范围有限：asin() 只能返回 -PI/2 到 PI/2 之间的角度（即 -90 度到 90 度）。这意味着它"看"不到上半圆以外的角度。如果需要判断完整的 360 度方向，应该用 atan2()。
3. 返回的是弧度：结果需要用 rad_to_deg() 转换才能得到度数。
4. 与 sin() 的互逆关系有限制：asin(sin(x)) = x 只在 x 位于 -PI/2 到 PI/2 之间时成立。超出这个范围，反推回来的角度会"折叠"回来。
5. C# 中的选择：推荐使用 Mathf.Asin()（返回 float），而不是 Math.Asin()（返回 double）。