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

cos

定义

cos() 是余弦函数——给你一个角度，它告诉你这个角度在单位圆上对应的水平位置（横坐标）。

继续用摩天轮的比喻：想象你从摩天轮的正上方往下看。有一个人坐在座舱上旋转，cos() 告诉你这个人此刻在摩天轮中心的左边多远或者右边多远。当座舱在正右方（0 度）时，cos() 返回最大值 1；在正左方（180 度）时返回最小值 -1；在正上方和正下方时恰好返回 0。

余弦函数的输出也永远在 -1 到 1 之间来回波动。事实上，cos() 和 sin() 就像一对双胞胎——cos() 的图像和 sin() 的图像形状完全相同，只是"错开"了 90 度（四分之一圈）。

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

cos() 接收的参数是弧度（radian），不是度数。90 度 = PI/2 弧度，180 度 = PI 弧度。如果你手头是度数，需要先用 deg_to_rad() 转换。

函数签名

C#

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

GDScript

func cos(angle_rad: float) -> float

参数说明

参数	类型	必需	说明
angleRad / angle_rad	float	是	角度值，单位为弧度。不是度数！180 度 = PI 弧度

返回值

类型： float

返回给定角度的余弦值，范围固定在 -1.0 到 1.0 之间。

输入（弧度）	输出	说明
0	1.0	正右方，离中心最远（右）
PI/2（约 1.571）	0.0	正上方，和中心水平对齐
PI（约 3.14159）	-1.0	正左方，离中心最远（左）
3*PI/2（约 4.712）	0.0	正下方，又和中心水平对齐

代码示例

基础用法：计算不同角度的余弦值

C#

using Godot;

public partial class CosExample : Node
{
    public override void _Ready()
    {
        // 0 度的余弦值
        float r1 = Mathf.Cos(0f);
        GD.Print("cos(0) = " + r1);
        // 运行结果: cos(0) = 1

        // 90 度 = PI/2 弧度
        float r2 = Mathf.Cos(Mathf.Pi / 2f);
        GD.Print("cos(PI/2) = " + r2);
        // 运行结果: cos(PI/2) = 0（浮点精度下约为 6.12e-17）

        // 180 度 = PI 弧度
        float r3 = Mathf.Cos(Mathf.Pi);
        GD.Print("cos(PI) = " + r3);
        // 运行结果: cos(PI) = -1

        // 45 度 = PI/4 弧度
        float r4 = Mathf.Cos(Mathf.Pi / 4f);
        GD.Print("cos(PI/4) = " + r4);
        // 运行结果: cos(PI/4) = 0.707107（即 sqrt(2)/2）
    }
}

GDScript

extends Node

func _ready():
    # 0 度的余弦值
    var r1 = cos(0.0)
    print("cos(0) = ", r1)
    # 运行结果: cos(0) = 1

    # 90 度 = PI/2 弧度
    var r2 = cos(PI / 2.0)
    print("cos(PI/2) = ", r2)
    # 运行结果: cos(PI/2) = 0（浮点精度下约为 6.12e-17）

    # 180 度 = PI 弧度
    var r3 = cos(PI)
    print("cos(PI) = ", r3)
    # 运行结果: cos(PI) = -1

    # 45 度 = PI/4 弧度
    var r4 = cos(PI / 4.0)
    print("cos(PI/4) = ", r4)
    # 运行结果: cos(PI/4) = 0.707107（即 sqrt(2)/2）

实际场景：计算方向向量（让角色朝某角度移动）

C#

using Godot;

public partial class Bullet : Node2D
{
    // 导出属性：子弹飞行速度（像素/秒）
    [Export] public float ExSpeed = 300f;

    // 内部变量：飞行方向
    private Vector2 _direction;

    public override void _Ready()
    {
        // 假设子弹朝 45 度方向飞行
        float angle = Mathf.DegToRad(45f);

        // cos 计算水平分量，sin 计算垂直分量
        _direction = new Vector2(Mathf.Cos(angle), Mathf.Sin(angle));

        GD.Print($"飞行方向: {_direction}");
        // 运行结果: 飞行方向: (0.707107, 0.707107)
    }

    public override void _Process(double delta)
    {
        // 每帧沿方向移动
        Position += _direction * ExSpeed * (float)delta;
        // 运行结果: 子弹沿 45 度方向匀速飞行
    }
}

GDScript

extends Node2D

## 导出属性：子弹飞行速度（像素/秒）
@export var ex_speed: float = 300.0

## 内部变量：飞行方向
var _direction: Vector2

func _ready():
    # 假设子弹朝 45 度方向飞行
    var angle := deg_to_rad(45.0)

    # cos 计算水平分量，sin 计算垂直分量
    _direction = Vector2(cos(angle), sin(angle))

    print("飞行方向: ", _direction)
    # 运行结果: 飞行方向: (0.707107, 0.707107)

func _process(delta):
    # 每帧沿方向移动
    position += _direction * ex_speed * delta
    # 运行结果: 子弹沿 45 度方向匀速飞行

进阶用法：用 cos 制作来回摆动的钟摆效果

C#

using Godot;

public partial class Pendulum : Node2D
{
    // 导出属性：摆动幅度（弧度）
    [Export] public float ExSwingAmplitude = Mathf.Pi / 4f; // 45 度

    // 导出属性：摆动周期（秒）
    [Export] public float ExSwingPeriod = 2f;

    // 导出属性：摆臂长度
    [Export] public float ExArmLength = 150f;

    public override void _Process(double delta)
    {
        // 用 cos 实现两端慢、中间快的自然摆动
        float t = (float)Time.GetTicksMsec() / 1000f;
        float swing = Mathf.Cos(2f * Mathf.Pi * t / ExSwingPeriod);

        // 当前角度 = 最大幅度 * cos值
        float currentAngle = ExSwingAmplitude * swing;

        // 计算摆锤位置
        float endX = Mathf.Sin(currentAngle) * ExArmLength;
        float endY = Mathf.Cos(currentAngle) * ExArmLength;

        Rotation = currentAngle;

        GD.Print($"摆动角度: {Mathf.RadToDeg(currentAngle):F1} 度");
        // 运行结果: 摆动角度: 22.5 度（角度在 -45 到 45 之间来回变化）
    }
}

GDScript

extends Node2D

## 导出属性：摆动幅度（弧度）
@export var ex_swing_amplitude: float = PI / 4.0  # 45 度

## 导出属性：摆动周期（秒）
@export var ex_swing_period: float = 2.0

## 导出属性：摆臂长度
@export var ex_arm_length: float = 150.0

func _process(delta):
    # 用 cos 实现两端慢、中间快的自然摆动
    var t := Time.get_ticks_msec() / 1000.0
    var swing := cos(2.0 * PI * t / ex_swing_period)

    # 当前角度 = 最大幅度 * cos值
    var current_angle := ex_swing_amplitude * swing

    # 计算摆锤位置
    var end_x := sin(current_angle) * ex_arm_length
    var end_y := cos(current_angle) * ex_arm_length

    rotation = current_angle

    print("摆动角度: %.1f 度" % rad_to_deg(current_angle))
    # 运行结果: 摆动角度: 22.5 度（角度在 -45 到 45 之间来回变化）

注意事项

1. 参数是弧度，不是度数：和 sin() 一样，cos() 接收弧度。cos(90) 不等于 cos(90度)。需要用 deg_to_rad() 转换后再传入。
2. 输出范围固定：余弦函数的返回值永远在 -1 到 1 之间。
3. 与 sin() 的关系：cos(angle) = sin(angle + PI/2)。也就是说，余弦函数就是"提前了 90 度"的正弦函数。它们的波形完全相同，只是起点不同。
4. 浮点精度问题：cos(PI/2) 在数学上应该等于 0，但实际结果可能是一个非常接近 0 的极小数。判断时应该用 Mathf.IsZeroApprox() 而不是 == 0。
5. C# 中的选择：推荐使用 Mathf.Cos()（返回 float），而不是 Math.Cos()（返回 double）。