Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

Exemples d'entrée

Introduction

Dans ce tutoriel, vous apprendrez comment utiliser le système InputEvent de Godot pour capturer les entrées du joueur. Il existe de nombreux types d'entrée différents que votre jeu peut utiliser - clavier, manette de jeu, souris, etc. - et de nombreuses façons de transformer ces entrées en actions dans votre jeu. Ce document vous présentera certains des scénarios les plus courants, que vous pourrez utiliser comme point de départ pour vos propres projets.

Note

Pour un aperçu détaillé du fonctionnement du système d'événements d'entrée de Godot, voir Utilisation d'InputEvent.

Événements comparés aux sondages

Parfois, vous voulez que votre jeu réponde à un certain événement d'entrée - en appuyant sur le bouton "sauté", par exemple. Pour d'autres situations, vous pourriez vouloir que quelque chose se produise tant qu'une touche est enfoncée, comme un mouvement. Dans le premier cas, vous pouvez utiliser la fonction _input(), qui sera appelée à chaque fois qu'un événement d'entrée se produit. Dans le second cas, Godot fournit le singleton Input, que vous pouvez utiliser pour interroger l'état d'une entrée.

Exemples :

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

Cela vous donne la flexibilité de combiner le type de traitement des entrées que vous effectuez.

Pour le reste de ce tutoriel, nous allons nous concentrer sur la capture d'événements individuels dans _input().

Événement d’entrée

Les événements d'entrée sont des objets qui héritent de InputEvent. Selon le type d'événement, l'objet contiendra des propriétés spécifiques liées à cet événement. Pour voir à quoi ressemblent réellement les événements, ajoutez un nœud et attachez le script suivant :

extends Node


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

Lorsque vous appuyez sur les touches, déplacez la souris et effectuez d'autres entrées, vous verrez chaque événement défiler dans la fenêtre de sortie. Voici un exemple de la sortie :

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))

Comme vous pouvez le voir, les résultats sont très différents pour les différents types de saisie. Les événements de touches sont même imprimés en tant que symboles de touches. Par exemple, considérons InputEventMouseButton. Il hérite des classes suivantes :

  • InputEvent - la classe de base pour tous les événements d'entrée

  • InputEventWithModifiers - ajoute la possibilité de vérifier si des modificateurs sont pressés, comme Shift ou Alt.

  • InputEventMouse - ajoute les propriétés des événements de la souris, comme position

  • InputEventMouseButton - contient l'index du bouton qui a été pressé, si c'était un double-clic, etc.

Astuce

C'est une bonne idée de garder la référence de la classe ouverte lorsque vous travaillez avec des événements afin de pouvoir vérifier les propriétés et les méthodes disponibles du type d'événement.

Vous pouvez rencontrer des erreurs si vous essayez d'accéder à une propriété sur un type d'entrée qui ne la contient pas - en appelant position sur InputEventKey par exemple. Pour éviter cela, assurez-vous de tester d'abord le type d'événement :

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

InputMap

The InputMap is the most flexible way to handle a variety of inputs. You use this by creating named input actions, to which you can assign any number of input events, such as keypresses or mouse clicks. To see them, and to add your own, open Project -> Project Settings and select the InputMap tab:

../../_images/inputs_inputmap.webp

Astuce

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.

Capturer les actions

Une fois que vous avez défini vos actions, vous pouvez les traiter dans vos scripts en utilisant is_action_pressed() et is_action_released() en passant le nom de l'action que vous recherchez :

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

Événements clavier

Les événements clavier sont capturés dans InputEventKey. Bien qu'il soit recommandé d'utiliser plutôt des actions d'entrées, il peut y avoir des cas où vous voulez examiner spécifiquement des événements clavier. Pour cet exemple, vérifions la touche T :

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

Astuce

See @GlobalScope_Key for a list of keycode constants.

Avertissement

En raison de la rémanence du clavier, toutes les entrées de touche peuvent ne pas être enregistrées à un moment donné si vous appuyez sur trop de touches à la fois. En raison de leur emplacement sur le clavier, certaines touches sont plus sujettes à la rémanence que d'autres. Certains claviers disposent d'une fonction anti-rémanence au niveau matériel, mais cette fonction n'est généralement pas présente sur les claviers bas de gamme et les claviers d'ordinateurs portables.

Par conséquent, il est recommandé d'utiliser une disposition de clavier par défaut qui est conçue pour bien fonctionner sur un clavier sans anti-rémanence. Voir cette question de Gamedev Stack Exchange pour plus d'informations.

Modificateurs de clavier

Les propriétés des modificateurs sont héritées de InputEventWithModifiers. Cela vous permet de vérifier les combinaisons de modificateurs à l'aide de propriétés booléennes. Imaginons que vous vouliez qu'une chose se produise lorsque la touche T est pressée, mais que quelque chose de différent se produise lorsque c'est Shift + T :

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")

Astuce

See @GlobalScope_Key for a list of keycode constants.

Événements souris

Les événements souris proviennent de la classe InputEventMouse, et sont séparés en deux types : InputEventMouseButton et InputEventMouseMotion. Notez que cela signifie que tous les événements souris contiendront une propriété position.

Boutons de la souris

Capturing mouse buttons is very similar to handling key events. @GlobalScope_MouseButton contains a list of MOUSE_BUTTON_* constants for each possible button, which will be reported in the event's button_index property. Note that the scrollwheel also counts as a button - two buttons, to be precise, with both MOUSE_BUTTON_WHEEL_UP and MOUSE_BUTTON_WHEEL_DOWN being separate events.

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")

Mouvement de la souris

InputEventMouseMotion les événements se produisent à chaque fois que la souris bouge. Vous pouvez trouver la distance du mouvement avec la propriété relative.

Here's an example using mouse events to drag-and-drop a Sprite2D node:

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

Événements tactiles

Si vous utilisez un appareil avec un écran tactile, vous pouvez générer des événements tactiles. InputEventScreenTouch est équivalent à un événement de clic de souris, et InputEventScreenDrag fonctionne à peu près de la même manière qu'un mouvement de souris.

Astuce

Pour tester vos événements tactiles sur un appareil sans écran tactile, ouvrez Paramètres de projet et allez à la section "Input Devices/Pointing". Activez "Emulate Touch From Mouse" et votre projet interprétera les clics et les mouvements de la souris comme des événements tactiles.