Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Příklady vstupů

Úvod

V tomto návodu se naučíte, jak používat systém Godotu InputEvent ("vstupní událost") k zachycení hráčského vstupu. Existuje mnoho různých typů vstupů, které může ve hře používat – klávesnice, gamepad, myš atd. – a mnoho různých způsobů, jak tyto vstupy proměnit v herní akce. Tento dokument vám ukáže některé z nejběžnějších scénářů, které můžete použít jako startovní body pro své vlastní projekty.

Poznámka

Pro podrobný přehled o tom, jak funguje systém vstupních událostí Godotu si přečtěte Používání vstupních událostí (InputEvent).

Události versus dotazování

Občas potřebujete, aby vaše hra reagovala na určitou vstupní událost – například stisknutí tlačítka pro "skok". V jiných situacích můžete chtít, aby se něco dělo, dokud je určité tlačítko stisknuté, například pohyb. V prvním případě můžete použít funkci _input() ("vstup"), která je volána vždy, když nastane vstupní událost. V druhém případě Godot poskytuje singleton Input, který můžete použít pro dotazování na stav vstupu.

Příklady:

func _input(event):
    if event.is_action_pressed("jump"):
        jump()


func _physics_process(delta):
    if Input.is_action_pressed("move_right"):
        # Move as long as the key/button is pressed.
        position.x += speed * delta

public override void _Input(InputEvent @event)
{
    if (@event.IsActionPressed("jump"))
    {
        Jump();
    }
}

public override void _PhysicsProcess(double delta)
{
    if (Input.IsActionPressed("move_right"))
    {
        // Move as long as the key/button is pressed.
        position.X += speed * (float)delta;
    }
}

Tyto možnosti vám dávají flexibilitu při kombinování druhů zpracování vstupu, které provádíte.

Po zbytek tohoto tutoriálu se zaměříme na zachycení jednotlivých událostí v _input().

Vstupní události

Vstupní události jsou objekty, které dědí ze třídy InputEvent. V závislosti na typu události objekt obsahuje specifické vlastnosti s ní související. Chcete-li se podívat, jak události skutečně vypadají, vytvořte uzel a připojte k němu následující skript:

extends Node


func _input(event):
    print(event.as_text())

using Godot;

public partial class Node : Godot.Node
{
    public override void _Input(InputEvent @event)
    {
        GD.Print(@event.AsText());
    }
}

Když stisknete klávesy, pohnete myší a vyzkoušíte další vstupy, uvidíte každou událost vypsanou ve okně výstupu. Zde je příklad takového výstupu:

A
Mouse motion at position ((971, 5)) with velocity ((0, 0))
Right Mouse Button
Mouse motion at position ((870, 243)) with velocity ((0.454937, -0.454937))
Left Mouse Button
Mouse Wheel Up
A
B
Shift
Alt+Shift
Alt
Shift+T
Mouse motion at position ((868, 242)) with velocity ((-2.134768, 2.134768))

Jak vidíte, výsledky se pro různé druhy vstupů velmi liší. Události kláves jsou dokonce vytištěny jako jejich odpovídající symboly. Uvažujme například InputEventMouseButton ("vstupní událost tlačítka myši"). Ta dědí z následujících tříd:

InputEvent - základní třída pro všechny vstupní události
InputEventWithModifiers ("vstupní událost s modifikátory") - přidává možnost zkontrolovat, zda byly stisknuty modifikátory, jako například Shift nebo Alt.
InputEventMouse ("vstupní událost myši") . přidává vlastnosti události myši, jako je její poloha position
InputEventMouseButton ("vstupní událost tlačítka myši") - obsahuje index tlačítka, které bylo stisknuto, zda se jednalo o dvojklik atd.

Tip

Při práci s událostmi je vhodné si otevřít referenční dokumentaci třídy, abyste viděli dostupné vlastnosti a metody daného typu události.

Pokud se pokusíte o přístup k vlastnosti na vstupním typu, který ji neobsahuje, můžete narazit na chyby – například při volání position na InputEventKey. Chcete-li tomu předejít, nejprve otestujte typ události:

func _input(event):
    if event is InputEventMouseButton:
        print("mouse button event at ", event.position)

public override void _Input(InputEvent @event)
{
    if (@event is InputEventMouseButton mouseEvent)
    {
        GD.Print("mouse button event at ", mouseEvent.Position);
    }
}

Mapa vstupů (InputMap)

InputMap je nejflexibilnější způsob, jak zpracovávat různé vstupy. Použijete ji vytvořením pojmenovaných vstupních akcí, kterým můžete přiřadit libovolný počet vstupních událostí, jako stisknutí klávesy nebo kliknutí myší. Chcete-li akce zobrazit a přidat vlastní, otevřete Projekt -> Nastavení projektu a vyberte záložku Mapa vstupů:

Tip

A new Godot project includes a number of default actions already defined. To see them, turn on Show Built-in Actions in the InputMap dialog.

While not strictly required, it's recommended to use the snake_case naming convention for input action names.

Zachycení akcí

Když máde vydefinované akce, můžete je zpracovat ve skriptech pomocí is_action_pressed() ("je akce stisknuta") a is_action_released() ("je akce puštěna"). Těm můžete předat název akce, kterou hledáte:

func _input(event):
    if event.is_action_pressed("my_action"):
        print("my_action occurred!")

public override void _Input(InputEvent @event)
{
    if (@event.IsActionPressed("my_action"))
    {
        GD.Print("my_action occurred!");
    }
}

Události klávesnice

Události klávesnice jsou zachyceny v InputEventKey ("vstupní událost klávesy"). Přestože doporučujeme používat zejména vstupní akce, mohou nastat případy, kdy se budete chtít podívat na události konkrétních kláves. Pro tento příklad se podívejme na T:

func _input(event):
    if event is InputEventKey and event.pressed:
        if event.keycode == KEY_T:
            print("T was pressed")

public override void _Input(InputEvent @event)
{
    if (@event is InputEventKey keyEvent && keyEvent.Pressed)
    {
        if (keyEvent.Keycode == Key.T)
        {
            GD.Print("T was pressed");
        }
    }
}

Tip

Seznam konstant popisujících kódy kláves najdete v @GlobalScope_Key.

Varování

Pokud stisknete příliš mnoho kláves najednou, nemusí být kvůli ghostingu klávesnice zaregistrovány všechny klávesové vstupy. Vzhledem ke svému umístění na klávesnici jsou některé klávesy náchylnější k ghostování než jiné. Některé klávesnice disponují antighostingem na hardwarové úrovni, ale tato funkce obecně není na levnějších a notebookových klávesnicích přítomna.

Proto se doporučuje použít výchozí rozvržení klávesnice, které je navrženo tak, aby dobře fungovalo na klávesnici bez antighostingu. Další informace najdete v této otázce na Gamedev Stack Exchange.

Klávesnicové modifikátory

Vlastnosti modifikátorů jsou zděděny z InputEventWithModifiers ("vstupní událost s modifikátory"). To vám umožňuje kontrolovat kombinace modifikátorů pomocí booleovských vlastností. Řekněme, že chcete, aby se při stisknutí T stala jedna věc, ale při stisknutí Shift + T jiná:

func _input(event):
    if event is InputEventKey and event.pressed:
        if event.keycode == KEY_T:
            if event.shift_pressed:
                print("Shift+T was pressed")
            else:
                print("T was pressed")

public override void _Input(InputEvent @event)
{
    if (@event is InputEventKey keyEvent && keyEvent.Pressed)
    {
        switch (keyEvent.Keycode)
        {
            case Key.T:
                GD.Print(keyEvent.ShiftPressed ? "Shift+T was pressed" : "T was pressed");
                break;
        }
    }
}

Tip

Seznam konstant popisujících kódy kláves najdete v @GlobalScope_Key.

Události myši

Události myši pocházejí z třídy InputEventMouse ("vstupní událost myši") a jsou rozděleny do dvou typů: InputEventMouseButton ("vstupní událost tlačítka myši") a InputEventMouseMotion ("vstupní událost pohybu myši"). Povšimněte si, že všechny události myši obsahují vlastnost polohy position.

Tlačítka myši

Zachycení tlačítek myši je velmi podobné zpracování klávesových událostí. @GlobalScope_MouseButton obsahuje seznam konstant MOUSE_BUTTON_* pro každé možné tlačítko, které jsou hlášeny ve vlastnosti button_index události. Kolečko myši se také počítá jako tlačítko - přesněji dvě tlačítka, přičemž MOUSE_BUTTON_WHEEL_UP ("kolečko nahoru") a MOUSE_BUTTON_WHEEL_DOWN ("kolečko dolů") jsou samostatné události.

func _input(event):
    if event is InputEventMouseButton:
        if event.button_index == MOUSE_BUTTON_LEFT and event.pressed:
            print("Left button was clicked at ", event.position)
        if event.button_index == MOUSE_BUTTON_WHEEL_UP and event.pressed:
            print("Wheel up")

public override void _Input(InputEvent @event)
{
    if (@event is InputEventMouseButton mouseEvent && mouseEvent.Pressed)
    {
        switch (mouseEvent.ButtonIndex)
        {
            case MouseButton.Left:
                GD.Print($"Left button was clicked at {mouseEvent.Position}");
                break;
            case MouseButton.WheelUp:
                GD.Print("Wheel up");
                break;
        }
    }
}

Pohyb myši

Události InputEventMouseMotion nastanou při každém pohybu myši. Vzdálenost pohybu můžete zjistit pomocí vlastnosti relative.

Zde je příklad použití událostí myši k přetažení uzlu Sprite2D:

extends Node


var dragging = false
var click_radius = 32 # Size of the sprite.


func _input(event):
    if event is InputEventMouseButton and event.button_index == MOUSE_BUTTON_LEFT:
        if (event.position - $Sprite2D.position).length() < click_radius:
            # Start dragging if the click is on the sprite.
            if not dragging and event.pressed:
                dragging = true
        # Stop dragging if the button is released.
        if dragging and not event.pressed:
            dragging = false

    if event is InputEventMouseMotion and dragging:
        # While dragging, move the sprite with the mouse.
        $Sprite2D.position = event.position

using Godot;

public partial class MyNode2D : Node2D
{
    private bool _dragging = false;
    private int _clickRadius = 32; // Size of the sprite.

    public override void _Input(InputEvent @event)
    {
        Sprite2D sprite = GetNodeOrNull<Sprite2D>("Sprite2D");
        if (sprite == null)
        {
            return; // No suitable node was found.
        }

        if (@event is InputEventMouseButton mouseEvent && mouseEvent.ButtonIndex == MouseButton.Left)
        {
            if ((mouseEvent.Position - sprite.Position).Length() < _clickRadius)
            {
                // Start dragging if the click is on the sprite.
                if (!_dragging && mouseEvent.Pressed)
                {
                    _dragging = true;
                }
            }
            // Stop dragging if the button is released.
            if (_dragging && !mouseEvent.Pressed)
            {
                _dragging = false;
            }
        }
        else
        {
            if (@event is InputEventMouseMotion motionEvent && _dragging)
            {
                // While dragging, move the sprite with the mouse.
                sprite.Position = motionEvent.Position;
            }
        }
    }
}

Dotykové události

Pokud používáte zařízení s dotykovou obrazovkou, můžete generovat dotykové události. InputEventScreenTouch ("vstupní událost dotyku obrazovky") je ekvivalentní události kliknutí myší a InputEventScreenDrag ("vstupní událost tažení obrazovky") funguje v podstatě stejně jako pohyb myši.

Tip

Chcete-li otestovat dotykové události na zařízení bez dotykové obrazovky, otevřete Nastavení projektu a přejděte do části "Vstupní zařízení/Dotyk". Povolte „Emulovat dotyk z myši“ a váš projekt bude kliknutí myší a pohyb interpretovat jako dotykové události.