Manettes de jeu

Les déclencheurs de manette vous permettent d’associer les entrées standard d’une manette aux fonctions du jeu. Les entrées de manette proposent des liaisons pour :

• Sticks gauche et droit (direction et clics)
• Croix directionnelles gauche et droite. La croix de droite correspond généralement aux boutons « A », « B », « X » et « Y » de la manette Xbox et aux boutons « carré », « cercle », « triangle » et « croix » de la manette Playstation.
• Gâchettes gauche et droite
• Boutons de tranche gauche et droit
• Boutons Start, Back et Guide

Boutons numériques

Les boutons numériques génèrent des événements pressed, released et repeated. Voici un exemple montrant comment détecter l’entrée d’un bouton numérique (enfoncé ou relâché) :

function on_input(self, action_id, action)
    if action_id == hash("gamepad_lpad_left") then
        if action.pressed then
            -- start moving left
        elseif action.released then
            -- stop moving left
        end
    end
end

Sticks analogiques

Les sticks analogiques génèrent des événements d’entrée continus lorsque le stick est déplacé en dehors de la zone morte définie dans le fichier de paramètres des manettes (voir ci-dessous). Voici un exemple montrant comment détecter l’entrée d’un stick analogique :

function on_input(self, action_id, action)
    if action_id == hash("gamepad_lstick_down") then
        -- left stick was moved down
        print(action.value) -- a value between 0.0 an -1.0
    end
end

Les sticks analogiques génèrent également des événements pressed et released lorsqu’ils sont déplacés dans les directions cardinales au-delà d’une certaine valeur seuil. Cela permet aussi d’utiliser facilement un stick analogique comme entrée directionnelle numérique :

function on_input(self, action_id, action)
    if action_id == hash("gamepad_lstick_down") and action.pressed then
        -- left stick was moved to its extreme down position
    end
end

Plusieurs manettes

Defold prend en charge plusieurs manettes par l’intermédiaire du système d’exploitation hôte. Les actions définissent le champ gamepad de la table action sur le numéro de la manette dont provient l’entrée :

function on_input(self, action_id, action)
    if action_id == hash("gamepad_start") then
        if action.gamepad == 0 then
          -- gamepad 0 wants to join the game
        end
    end
end

Connexion et déconnexion

Les liaisons d’entrée des manettes proposent également deux liaisons distinctes nommées Connected et Disconnected pour détecter la connexion d’une manette (y compris celles connectées dès le démarrage) ou sa déconnexion.

function on_input(self, action_id, action)
    if action_id == hash("gamepad_connected") then
        if action.gamepad == 0 then
          -- gamepad 0 was connected
        end
    elseif action_id == hash("gamepad_disconnected") then
        if action.gamepad == 0 then
          -- gamepad 0 was disconnected
        end
    end
end

Entrées brutes des manettes

Les liaisons d’entrée des manettes proposent également une liaison distincte nommée Raw qui fournit les entrées non filtrées (sans application de zone morte) des boutons, des axes et des chapeaux directionnels de toute manette connectée.

function on_input(self, action_id, action)
    if action_id == hash("raw") then
        pprint(action.gamepad_buttons)
        pprint(action.gamepad_axis)
        pprint(action.gamepad_hats)
    end
end

Fichier de paramètres des manettes

La configuration des entrées de manette utilise un fichier de correspondance distinct pour chaque type de manette physique. Les correspondances propres à chaque manette physique sont définies dans un fichier gamepads. Defold fournit un fichier gamepads intégré contenant les paramètres des manettes courantes :

Si vous devez créer un nouveau fichier de paramètres des manettes, nous proposons un outil simple pour vous aider :

Cliquez pour télécharger gdc.zip.

Il comprend des exécutables pour Windows, Linux et macOS. Exécutez-le depuis la ligne de commande :

./gdc

L’outil vous demandera d’appuyer sur différents boutons de votre manette connectée. Il produira ensuite un nouveau fichier gamepads contenant les correspondances correctes pour votre manette. Enregistrez le nouveau fichier ou fusionnez-le avec votre fichier gamepads existant, puis mettez à jour le paramètre dans game.project :

Manettes non identifiées

Lorsqu’une manette est connectée et qu’aucune correspondance n’existe pour elle, elle ne génère que des actions connected, disconnected et raw. Dans ce cas, vous devez associer manuellement les données brutes de la manette aux actions de votre jeu.

Vous pouvez vérifier si une action d’entrée de manette provient ou non d’une manette inconnue en lisant la valeur gamepad_unknown de action :

function on_input(self, action_id, action)
    if action_id == hash("connected") then
        if action.gamepad_unknown then
            print("The connected gamepad is unidentified and will only generate raw input")
        else
            print("The connected gamepad is known and will generate input actions for buttons and sticks")
        end
    end
end

Manettes en HTML5

Les manettes sont prises en charge dans les builds HTML5 et génèrent les mêmes événements d’entrée que sur les autres plateformes. Leur prise en charge repose sur l’API Gamepad, disponible dans la plupart des navigateurs (consultez ce tableau de compatibilité). Si le navigateur ne prend pas en charge l’API Gamepad, Defold ignore sans avertissement tous les déclencheurs de manette de votre projet. Vous pouvez vérifier si le navigateur prend en charge l’API Gamepad en vérifiant si la fonction getGamepads existe sur l’objet navigator :

local function supports_gamepads()
    return not html5 or (html5.run('typeof navigator.getGamepads === "function"') == "true")
end

if supports_gamepads() then
    print("Platform supports gamepads")
end

Si votre jeu s’exécute à l’intérieur d’un iframe, vous devez également vous assurer que cet iframe dispose de l’autorisation gamepad :

<iframe allow="gamepad"></iframe>

Manette standard

Si le navigateur identifie une manette connectée comme une manette standard, elle utilise les correspondances de Standard Gamepad dans le fichier de paramètres des manettes (des correspondances pour Standard Gamepad sont incluses dans le fichier default.gamepads de /builtins). Une manette standard est définie comme ayant 16 boutons et deux sticks analogiques, avec une disposition des boutons semblable à celle d’une manette PlayStation ou Xbox (consultez la définition du W3C et la disposition des boutons pour en savoir plus). Si la manette connectée n’est pas identifiée comme une manette standard, Defold recherche dans le fichier de paramètres des manettes des correspondances adaptées au type de manette physique.

Manettes sous Windows

Sous Windows, seules les manettes XBox 360 sont actuellement prises en charge. Pour connecter votre manette 360 à votre ordinateur Windows, assurez-vous qu’elle est correctement configurée.

Manettes sous Android

Les manettes sont prises en charge dans les builds Android et génèrent les mêmes événements d’entrée que sur les autres plateformes. Leur prise en charge repose sur le système d’entrée Android pour les événements de touche et de mouvement. Les événements d’entrée Android sont convertis en événements de manette Defold à l’aide du même fichier gamepad que celui décrit ci-dessus.

Lorsque vous ajoutez des liaisons de manette supplémentaires sous Android, vous pouvez utiliser les tables de correspondance suivantes pour convertir les événements d’entrée Android en valeurs du fichier gamepad :

(Définitions Android de KeyEvent)

(Définitions Android de MotionEvent)

Utilisez cette table de correspondance avec une application de test de manette du Google Play Store pour déterminer à quel événement de touche correspond chaque bouton de votre manette.