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

Input.set_mouse_mode

定义

想象你在玩不同类型的游戏：在策略游戏中，你能看到鼠标箭头自由移动；在射击游戏中，鼠标"消失"了，变成准星，移动鼠标直接转动视角；在菜单界面里，鼠标被"关"在窗口里不能跑到外面去。这些不同的鼠标行为，就是通过设置"鼠标模式"来控制的。

set_mouse_mode 就是用来切换这些模式的开关。Godot 提供了五种鼠标模式，每种模式适用于不同的游戏类型。

一句话总结

set_mouse_mode = "告诉游戏，鼠标应该怎么表现"——显示、隐藏、锁定、限制，随你选择。

鼠标模式一览

模式	鼠标可见	能跑出窗口	适合场景
Visible	能看到	能	普通菜单、策略游戏
Hidden	看不到	能	自定义鼠标外观
Captured	看不到	不能（鼠标被"抓住"了）	第一人称射击
Confined	能看到	不能（被"关"在窗口里）	窗口化游戏
ConfinedHidden	看不到	不能	窗口化的第一人称游戏

函数签名

C#

// 设置鼠标模式
public static void SetMouseMode(Input.MouseMode mode)

// 获取当前鼠标模式
public static Input.MouseMode GetMouseMode()

GDScript

# 设置鼠标模式（直接赋值属性）
Input.mouse_mode = Input.MOUSE_MODE_VISIBLE

# 获取当前鼠标模式（直接读取属性）
var current_mode = Input.mouse_mode

参数说明

参数	类型	必需	说明
mode	Input.MouseMode	是	鼠标模式枚举值，决定鼠标的显示和行为方式。可选值见下表

鼠标模式枚举值详情：

枚举值	C# 写法	GDScript 写法	说明
Visible	Input.MouseModeEnum.Visible	Input.MOUSE_MODE_VISIBLE	默认模式。鼠标正常显示，可以自由移出游戏窗口
Hidden	Input.MouseModeEnum.Hidden	Input.MOUSE_MODE_HIDDEN	鼠标不可见，但仍然可以移出窗口。适合用自定义精灵代替鼠标
Captured	Input.MouseModeEnum.Captured	Input.MOUSE_MODE_CAPTURED	鼠标被"捕获"：不可见且无法离开窗口，移动数据通过 InputEventMouseMotion.Relative 获取。适合第一人称视角控制
Confined	Input.MouseModeEnum.Confined	Input.MOUSE_MODE_CONFINED	鼠标可见，但被限制在游戏窗口内，不能移出窗口
ConfinedHidden	Input.MouseModeEnum.ConfinedHidden	Input.MOUSE_MODE_CONFINED_HIDDEN	鼠标不可见且被限制在窗口内。相当于 Hidden + Confined 的组合

返回值

SetMouseMode 没有返回值（void）。

GetMouseMode 返回当前的 Input.MouseMode（C#）或 Input.MouseMode 枚举值（GDScript）。

代码示例

基础用法

切换不同的鼠标模式：

C#

using Godot;

public partial class TestMouseMode : Node
{
    public override void _Ready()
    {
        // 设置鼠标为可见模式（默认值）
        Input.SetMouseMode(Input.MouseModeEnum.Visible);
        GD.Print("当前模式: " + Input.GetMouseMode());
        // 运行结果: 当前模式: Visible

        // 切换为隐藏模式（鼠标看不见了）
        Input.SetMouseMode(Input.MouseModeEnum.Hidden);
        GD.Print("当前模式: " + Input.GetMouseMode());
        // 运行结果: 当前模式: Hidden

        // 切换为捕获模式（第一人称射击游戏常用）
        Input.SetMouseMode(Input.MouseModeEnum.Captured);
        GD.Print("当前模式: " + Input.GetMouseMode());
        // 运行结果: 当前模式: Captured
    }
}

GDScript

extends Node

func _ready() -> void:
    # 设置鼠标为可见模式（默认值）
    Input.mouse_mode = Input.MOUSE_MODE_VISIBLE
    print("当前模式: " + str(Input.mouse_mode))
    # 运行结果: 当前模式: 0

    # 切换为隐藏模式（鼠标看不见了）
    Input.mouse_mode = Input.MOUSE_MODE_HIDDEN
    print("当前模式: " + str(Input.mouse_mode))
    # 运行结果: 当前模式: 1

    # 切换为捕获模式（第一人称射击游戏常用）
    Input.mouse_mode = Input.MOUSE_MODE_CAPTURED
    print("当前模式: " + str(Input.mouse_mode))
    # 运行结果: 当前模式: 2

实际场景

在一个第一人称游戏中，按 ESC 键在"游戏模式"（鼠标捕获）和"暂停菜单模式"（鼠标可见）之间切换：

C#

using Godot;

public partial class FPSGame : Node3D
{
    private bool _isPaused = false;
    private Control _pauseMenu;

    public override void _Ready()
    {
        _pauseMenu = GetNode<Control>("PauseMenu");
        // 游戏开始时，捕获鼠标（第一人称控制）
        Input.SetMouseMode(Input.MouseModeEnum.Captured);
    }

    public override void _UnhandledInput(InputEvent @event)
    {
        // 按 ESC 键切换暂停状态
        if (@event.IsActionPressed("ui_cancel"))
        {
            _isPaused = !_isPaused;

            if (_isPaused)
            {
                // 暂停：显示鼠标，显示菜单
                Input.SetMouseMode(Input.MouseModeEnum.Visible);
                _pauseMenu.Visible = true;
                GetTree().Paused = true;
                GD.Print("游戏暂停，鼠标可见");
                // 运行结果: 游戏暂停，鼠标可见
            }
            else
            {
                // 继续：重新捕获鼠标，隐藏菜单
                Input.SetMouseMode(Input.MouseModeEnum.Captured);
                _pauseMenu.Visible = false;
                GetTree().Paused = false;
                GD.Print("继续游戏，鼠标已捕获");
                // 运行结果: 继续游戏，鼠标已捕获
            }
        }
    }
}

GDScript

extends Node3D

var _is_paused: bool = false
@onready var _pause_menu: Control = $PauseMenu

func _ready() -> void:
    # 游戏开始时，捕获鼠标（第一人称控制）
    Input.mouse_mode = Input.MOUSE_MODE_CAPTURED

func _unhandled_input(event: InputEvent) -> void:
    # 按 ESC 键切换暂停状态
    if event.is_action_pressed("ui_cancel"):
        _is_paused = not _is_paused

        if _is_paused:
            # 暂停：显示鼠标，显示菜单
            Input.mouse_mode = Input.MOUSE_MODE_VISIBLE
            _pause_menu.visible = true
            get_tree().paused = true
            print("游戏暂停，鼠标可见")
            # 运行结果: 游戏暂停，鼠标可见
        else:
            # 继续：重新捕获鼠标，隐藏菜单
            Input.mouse_mode = Input.MOUSE_MODE_CAPTURED
            _pause_menu.visible = false
            get_tree().paused = false
            print("继续游戏，鼠标已捕获")
            # 运行结果: 继续游戏，鼠标已捕获

进阶用法

实现一个完整的鼠标模式管理器，支持按键切换所有五种模式，并在屏幕上实时显示当前模式信息：

C#

using Godot;

public partial class MouseModeManager : Control
{
    private Label _statusLabel;
    private int _modeIndex = 0;

    // 五种鼠标模式
    private readonly Input.MouseModeEnum[] _modes = new Input.MouseModeEnum[]
    {
        Input.MouseModeEnum.Visible,
        Input.MouseModeEnum.Hidden,
        Input.MouseModeEnum.Captured,
        Input.MouseModeEnum.Confined,
        Input.MouseModeEnum.ConfinedHidden
    };

    private readonly string[] _modeNames = new string[]
    {
        "Visible（可见，可移出窗口）",
        "Hidden（隐藏，可移出窗口）",
        "Captured（捕获，不可移出窗口）",
        "Confined（可见，不可移出窗口）",
        "ConfinedHidden（隐藏，不可移出窗口）"
    };

    public override void _Ready()
    {
        _statusLabel = GetNode<Label>("StatusLabel");
        UpdateStatusLabel();
    }

    public override void _UnhandledInput(InputEvent @event)
    {
        // 按 Tab 键循环切换鼠标模式
        if (@event.IsActionPressed("cycle_mouse_mode"))
        {
            _modeIndex = (_modeIndex + 1) % _modes.Length;

            // 注意：切换到 Captured 模式时，需要玩家点击窗口才能生效
            Input.SetMouseMode(_modes[_modeIndex]);
            UpdateStatusLabel();

            GD.Print("切换到模式: " + _modeNames[_modeIndex]);
            // 运行结果: 切换到模式: Visible（可见，可移出窗口）
            //          切换到模式: Hidden（隐藏，可移出窗口）
            //          切换到模式: Captured（捕获，不可移出窗口）
        }

        // 按 Escape 键回到可见模式（安全退出）
        if (@event.IsActionPressed("ui_cancel"))
        {
            Input.SetMouseMode(Input.MouseModeEnum.Visible);
            _modeIndex = 0;
            UpdateStatusLabel();

            GD.Print("安全退出：恢复可见模式");
            // 运行结果: 安全退出：恢复可见模式
        }
    }

    private void UpdateStatusLabel()
    {
        Input.MouseModeEnum current = Input.GetMouseMode();
        _statusLabel.Text = $"鼠标模式: {_modeNames[_modeIndex]}\n" +
                           $"按 Tab 切换模式 | 按 ESC 恢复可见";
    }
}

GDScript

extends Control

@onready var _status_label: Label = $StatusLabel
var _mode_index: int = 0

# 五种鼠标模式
var _modes: Array = [
    Input.MOUSE_MODE_VISIBLE,
    Input.MOUSE_MODE_HIDDEN,
    Input.MOUSE_MODE_CAPTURED,
    Input.MOUSE_MODE_CONFINED,
    Input.MOUSE_MODE_CONFINED_HIDDEN
]

var _mode_names: Array = [
    "Visible（可见，可移出窗口）",
    "Hidden（隐藏，可移出窗口）",
    "Captured（捕获，不可移出窗口）",
    "Confined（可见，不可移出窗口）",
    "ConfinedHidden（隐藏，不可移出窗口）"
]

func _ready() -> void:
    _update_status_label()

func _unhandled_input(event: InputEvent) -> void:
    # 按 Tab 键循环切换鼠标模式
    if event.is_action_pressed("cycle_mouse_mode"):
        _mode_index = (_mode_index + 1) % _modes.size()

        # 注意：切换到 Captured 模式时，需要玩家点击窗口才能生效
        Input.mouse_mode = _modes[_mode_index]
        _update_status_label()

        print("切换到模式: " + _mode_names[_mode_index])
        # 运行结果: 切换到模式: Visible（可见，可移出窗口）
        #          切换到模式: Hidden（隐藏，可移出窗口）
        #          切换到模式: Captured（捕获，不可移出窗口）

    # 按 Escape 键回到可见模式（安全退出）
    if event.is_action_pressed("ui_cancel"):
        Input.mouse_mode = Input.MOUSE_MODE_VISIBLE
        _mode_index = 0
        _update_status_label()

        print("安全退出：恢复可见模式")
        # 运行结果: 安全退出：恢复可见模式

func _update_status_label() -> void:
    var current = Input.mouse_mode
    _status_label.text = "鼠标模式: %s\n按 Tab 切换模式 | 按 ESC 恢复可见" % _mode_names[_mode_index]

注意事项

• Captured 模式的特殊行为：在 Web 平台和某些桌面环境中，设置 Captured 模式后鼠标不会立即被捕获，需要玩家点击一下游戏窗口才会真正生效。这是操作系统的安全限制，防止网页或程序偷偷锁定用户的鼠标。在代码中切换到 Captured 模式后，建议给用户一个提示（如"点击屏幕开始游戏"）。
• ESC 键自动解锁：在 Godot 编辑器中运行时，按 ESC 键会自动将鼠标模式恢复为 Visible，这是编辑器的调试功能。在导出的正式版本中不会有这个行为。
• Hidden 和 Captured 的区别：Hidden 只是把鼠标光标藏起来了，鼠标仍然可以移出窗口；Captured 则是把鼠标完全"抓住"了，不能移出窗口，同时隐藏光标。如果你只是想用自定义图片代替鼠标箭头，用 Hidden 就够了；如果你要做第一人称视角控制，必须用 Captured。
• GDScript 用属性赋值：在 GDScript 中，鼠标模式是通过 Input.mouse_mode 属性直接赋值的，而不是调用方法。这是 GDScript 和 C# 在使用方式上的一个显著区别。C# 中使用 Input.SetMouseMode() 方法。
• 切换模式时注意状态：如果你在游戏暂停时切换了鼠标模式（比如从 Captured 切到 Visible），记得在游戏恢复时把模式改回去，否则玩家会发现鼠标行为不对。
• C# 差异：C# 中使用 Input.SetMouseMode(Input.MouseModeEnum.Visible) 方法设置，Input.GetMouseMode() 方法获取；GDScript 中直接读写 Input.mouse_mode 属性。