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

Input.get_axis

定义

想象一个跷跷板——左边坐一个人往下压，跷跷板就向左倾斜（负值）；右边坐一个人往下压，跷跷板就向右倾斜（正值）；两边都不坐或者两边都坐，跷跷板就保持水平（0）。

get_axis 就是这样一个"跷跷板函数"：你给它两个动作名（一个代表负方向，一个代表正方向），它会返回一个 -1 到 1 之间的数值，告诉你当前的输入方向和力度。

• 按下负方向键 → 返回 -1
• 按下正方向键 → 返回 1
• 两个都不按 → 返回 0
• 两个都按 → 返回 0（互相抵消）

一句话总结

get_axis = "水平方向（或垂直方向）的输入值是多少？"——一行代码替代两个 if 判断。

函数签名

C#

public static float GetAxis(StringName negativeAction, StringName positiveAction)

GDScript

get_axis(negative_action: StringName, positive_action: StringName) -> float

参数说明

参数	类型	必需	说明
negativeAction	StringName	是	负方向动作名称。按下时返回值偏向 -1。比如 "move_left"（向左移动）
positiveAction	StringName	是	正方向动作名称。按下时返回值偏向 1。比如 "move_right"（向右移动）

返回值

float — 返回 -1 到 1 之间的浮点数：

• -1：只按下了负方向键
• 1：只按下了正方向键
• 0：两个都没按，或者两个都按了（互相抵消）
• 对于手柄摇杆，返回值可以是 -1 到 1 之间的任意小数（比如 0.7）

代码示例

基础用法

最简单的用法——获取水平方向的输入值：

C#

using Godot;

public partial class TestInput : Node
{
    public override void _Process(double delta)
    {
        // 获取水平方向输入：左键为负，右键为正
        float direction = Input.GetAxis("move_left", "move_right");

        GD.Print("水平方向: " + direction);
        // 运行结果: （按住左键）水平方向: -1
        //          （按住右键）水平方向: 1
        //          （都不按）水平方向: 0
        //          （两个都按）水平方向: 0
    }
}

GDScript

extends Node

func _process(delta: float) -> void:
    # 获取水平方向输入：左键为负，右键为正
    var direction := Input.get_axis("move_left", "move_right")

    print("水平方向: " + str(direction))
    # 运行结果: （按住左键）水平方向: -1.0
    #          （按住右键）水平方向: 1.0
    #          （都不按）水平方向: 0.0
    #          （两个都按）水平方向: 0.0

实际场景

在一个俯视角游戏中，用 get_axis 同时获取水平和垂直方向输入，实现四方向移动：

C#

using Godot;

public partial class TopDownPlayer : CharacterBody2D
{
    [Export] public float ExMoveSpeed = 300f;

    public override void _PhysicsProcess(double delta)
    {
        // 用 get_axis 一行搞定方向检测
        float horizontal = Input.GetAxis("move_left", "move_right");   // -1, 0, 1
        float vertical = Input.GetAxis("move_up", "move_down");       // -1, 0, 1

        // 组合成方向向量
        Vector2 direction = new Vector2(horizontal, vertical);

        // 归一化：防止斜向移动时速度变为 1.414 倍
        if (direction != Vector2.Zero)
        {
            direction = direction.Normalized();
        }

        Velocity = direction * ExMoveSpeed;
        MoveAndSlide();

        GD.Print($"方向: ({direction.X:F1}, {direction.Y:F1}), 速度: {Velocity}");
        // 运行结果: 方向: (1.0, 0.0), 速度: (300, 0)
        //          方向: (0.7, 0.7), 速度: (212, 212)（斜向移动已归一化）
        //          方向: (0.0, 0.0), 速度: (0, 0)
    }
}

GDScript

extends CharacterBody2D

@export var ex_move_speed: float = 300.0

func _physics_process(delta: float) -> void:
    # 用 get_axis 一行搞定方向检测
    var horizontal := Input.get_axis("move_left", "move_right")  # -1, 0, 1
    var vertical := Input.get_axis("move_up", "move_down")      # -1, 0, 1

    # 组合成方向向量
    var direction := Vector2(horizontal, vertical)

    # 归一化：防止斜向移动时速度变为 1.414 倍
    if direction != Vector2.ZERO:
        direction = direction.normalized()

    velocity = direction * ex_move_speed
    move_and_slide()

    print("方向: (%.1f, %.1f), 速度: %s" % [direction.x, direction.y, velocity])
    # 运行结果: 方向: (1.0, 0.0), 速度: (300.0, 0.0)
    #          方向: (0.7, 0.7), 速度: (212.1, 212.1)（斜向移动已归一化）
    #          方向: (0.0, 0.0), 速度: (0.0, 0.0)

进阶用法

对比"手动写 if"和"用 get_axis"两种写法，以及结合手柄摇杆的模拟输入处理：

C#

using Godot;

public partial class PlayerController : CharacterBody2D
{
    [Export] public float ExMoveSpeed = 300f;
    [Export] public float ExAcceleration = 1500f;
    [Export] public float ExFriction = 1200f;

    public override void _PhysicsProcess(double delta)
    {
        // ===== 对比：两种写法完全等价 =====

        // 写法1：手动 if 判断（啰嗦但直观）
        float dirOld = 0f;
        if (Input.IsActionPressed("move_left"))  dirOld -= 1f;
        if (Input.IsActionPressed("move_right")) dirOld += 1f;

        // 写法2：用 get_axis（简洁，推荐）
        float dirNew = Input.GetAxis("move_left", "move_right");

        GD.Print($"手动写法: {dirOld}, get_axis: {dirNew}");
        // 运行结果: 手动写法: 1, get_axis: 1（两者完全一致）

        // ===== 实际应用：带加速度和摩擦力的移动 =====
        float direction = dirNew;

        if (direction != 0f)
        {
            // 有输入时加速
            Velocity = new Vector2(
                Mathf.MoveToward(Velocity.X, direction * ExMoveSpeed, ExAcceleration * (float)delta),
                Velocity.Y
            );
        }
        else
        {
            // 没有输入时减速（摩擦力）
            Velocity = new Vector2(
                Mathf.MoveToward(Velocity.X, 0f, ExFriction * (float)delta),
                Velocity.Y
            );
        }

        MoveAndSlide();

        // ===== 手柄摇杆的特殊之处 =====
        // 如果 move_left/move_right 绑定了手柄摇杆，
        // get_axis 返回的不是 -1 或 1，而是 -1.0 ~ 1.0 之间的小数
        // 比如轻轻推摇杆可能返回 0.3，推到底才返回 1.0
        // 这就是"模拟输入"——能感知按压的力度大小
        float rawAxis = Input.GetAxis("move_left", "move_right");
        GD.Print($"原始轴值: {rawAxis:F2}");
        // 运行结果: （手柄轻轻推）原始轴值: 0.30
        //          （手柄推到底）原始轴值: 1.00
        //          （键盘按键）原始轴值: 1.00（键盘只有 0 和 1）
    }
}

GDScript

extends CharacterBody2D

@export var ex_move_speed: float = 300.0
@export var ex_acceleration: float = 1500.0
@export var ex_friction: float = 1200.0

func _physics_process(delta: float) -> void:
    # ===== 对比：两种写法完全等价 =====

    # 写法1：手动 if 判断（啰嗦但直观）
    var dir_old := 0.0
    if Input.is_action_pressed("move_left"):  dir_old -= 1.0
    if Input.is_action_pressed("move_right"): dir_old += 1.0

    # 写法2：用 get_axis（简洁，推荐）
    var dir_new := Input.get_axis("move_left", "move_right")

    print("手动写法: %s, get_axis: %s" % [dir_old, dir_new])
    # 运行结果: 手动写法: 1.0, get_axis: 1.0（两者完全一致）

    # ===== 实际应用：带加速度和摩擦力的移动 =====
    var direction := dir_new

    if direction != 0.0:
        # 有输入时加速
        velocity = Vector2(
            move_toward(velocity.x, direction * ex_move_speed, ex_acceleration * delta),
            velocity.y
        )
    else:
        # 没有输入时减速（摩擦力）
        velocity = Vector2(
            move_toward(velocity.x, 0.0, ex_friction * delta),
            velocity.y
        )

    move_and_slide()

    # ===== 手柄摇杆的特殊之处 =====
    # 如果 move_left/move_right 绑定了手柄摇杆，
    # get_axis 返回的不是 -1 或 1，而是 -1.0 ~ 1.0 之间的小数
    # 比如轻轻推摇杆可能返回 0.3，推到底才返回 1.0
    # 这就是"模拟输入"——能感知按压的力度大小
    var raw_axis := Input.get_axis("move_left", "move_right")
    print("原始轴值: %.2f" % raw_axis)
    # 运行结果: （手柄轻轻推）原始轴值: 0.30
    #          （手柄推到底）原始轴值: 1.00
    #          （键盘按键）原始轴值: 1.00（键盘只有 0 和 1）

注意事项

• 两个方向都按会返回 0：如果玩家同时按下了左键和右键（move_left 和 move_right），get_axis 会返回 0，相当于"互相抵消"。这是预期行为，不需要额外处理。
• 只处理一个维度：get_axis 每次调用只能获取一个轴的输入（水平或垂直）。如果需要同时获取二维方向（比如俯视角游戏的上下左右移动），需要调用两次分别获取水平和垂直方向，或者直接使用 get_vector。
• 支持手柄模拟输入：如果动作绑定了手柄摇杆，get_axis 会返回 -1.0 到 1.0 之间的精确小数值（比如 0.35），能反映摇杆的推动程度。如果是键盘按键，则只返回 -1、0 或 1。
• 必须在 Input Map 中定义动作：两个参数都是动作名称，需要事先在项目设置的 Input Map 中定义。
• C# 差异：C# 中方法名用 PascalCase（Input.GetAxis），GDScript 中用 snake_case（Input.get_axis）。