Aller au contenu principal

Comprendre et trouver les natives

Quand tu commences à écrire des scripts pour GTA V, le mot native revient tout le temps. Dans la pratique, une native est simplement une fonction interne du moteur de GTA V que tu peux appeler directement depuis ton script C#.

C'est quoi une native​

GTA V est développé en C++. Dans le moteur du jeu, des milliers de fonctions gèrent l'univers : faire apparaître des véhicules, modifier la vie des piétons, lancer des animations ou gérer la police.

ScriptHookVDotNet (SHVDN) simplifie les manipulations courantes avec des propriétés C# prêtes à l'emploi :

// Propriétés SHVDN classiques
ped.Health = 100;
ped.BlockPermanentEvents = true;

Sous le capot, SHVDN appelle ces fonctions internes à ta place. Mais SHVDN n'emballe qu'une petite partie de ce que le jeu permet. Dès que tu as besoin d'une action précise sans propriété C# dédiée — forcer un piéton à lever les mains, le désarmer, vérifier s'il fuit, ou l'empêcher d'agoniser au sol — tu appelles directement la fonction du moteur. Cette fonction, c'est une native.

Chaque native possède :

  • Un nom lisible : par exemple TASK_HANDS_UP, SET_PED_CONFIG_FLAG, IS_PED_FLEEING.
  • Un hash 64 bits : son identifiant dans le binaire du jeu. En C#, l'enum GTA.Native.Hash relie ces noms à leurs hashes respectifs.
  • Une signature : les paramètres attendus (handles de peds, floats, booléens) et le type de retour.

Comment trouver la native dont tu as besoin​

Tu n'as pas besoin de deviner les noms. Dans la pratique, tu trouves ce qu'il te faut de deux façons :

Chercher dans la base de données de natives​

L'outil du quotidien de tout moddeur reste la Native Database communautaire : nativedb (ou FiveM Natives).

  1. Recherche par mot-clé en anglais : écris ce que tu cherches (cuff, flee, ragdoll, weapon, seat, speech, aim).
  2. Filtre par domaine (namespace) :
    • PED : santé des piétons, drapeaux de comportement, armure.
    • TASK : mouvements, animations, scénarios, conduite, combat.
    • VEHICLE : options du véhicule, portières, sirènes, dégâts.
    • WEAPON : équipement des armes, accessoires, munitions.
    • HUD : icônes de carte (blips), affichages texte, notifications.
  3. Vérifie les paramètres et les commentaires : les développeurs y documentent souvent le rôle des arguments ou des numéros de drapeaux précis (par exemple, le flag 281 sur SET_PED_CONFIG_FLAG pour empêcher un ped d'agoniser au sol).

Lire du code existant ou décompiler une DLL​

Quand tu te demandes comment un autre mod a codé une mécanique particulière :

  • Les mods open source sur GitHub : cherche le nom de la mécanique pour voir quelles natives sont appelées et dans quel ordre.
  • Décompiler la DLL d'un mod existant : si un mod n'a pas son code public, son fichier .dll dans scripts/ reste du C# .NET compilé. Tu peux l'ouvrir dans un décompilateur gratuit comme ILSpy ou dnSpy pour explorer son code C# et repérer directement les lignes Function.Call et les natives qu'il utilise.

Appeler une native en C#​

Dans ScriptHookVDotNet, tu appelles une native avec Function.Call du namespace GTA.Native :

Appel void (exécuter une action)​

using GTA;
using GTA.Native;

// Fait lever les mains à un piéton
Function.Call(Hash.TASK_HANDS_UP, ped.Handle, -1, Game.Player.Character.Handle, -1, false);

// Empêche un piéton d'agoniser au sol avant de mourir (flag 281)
Function.Call(Hash.SET_PED_CONFIG_FLAG, ped.Handle, 281, true);

Appel avec valeur de retour​

Précise le type de retour attendu entre chevrons <T> :

using GTA;
using GTA.Native;

// Vérifie si un piéton est en fuite
bool isFleeing = Function.Call<bool>(Hash.IS_PED_FLEEING, ped.Handle);

// Récupère l'altitude du sol pour une coordonnée 3D
float groundZ = Function.Call<float>(Hash.GET_GROUND_Z_FOR_3D_COORD, pos.X, pos.Y, pos.Z, 0f, false);

Les pièges à éviter​

  • Les hashes inexistants et le piège de l'IA (« Can't find native ») : appeler un hash qui n'existe pas dans le jeu fait crasher ScriptHookV avec l'erreur Can't find native 0x.... C'est le piège numéro un quand on code avec une IA : comme la documentation du modding GTA V est rare, les modèles de langage ont tendance à halluciner des noms de natives crédibles ou des hashes inventés. Quand tu demandes à une IA d'écrire un script, fournis-lui toujours la signature exacte et le hash vérifié depuis nativedb ou FiveM docs dans ton prompt. Ne la laisse jamais inventer une native.
  • Passe des handles, jamais les objets C# : les natives travaillent avec des identifiants d'entités. Passe toujours ped.Handle ou vehicle.Handle, pas l'instance Ped ou Vehicle.
  • Attention aux floats et aux entiers : si la native attend un float, écris toujours 0f ou 1.0f plutôt que l'entier 0. Un mauvais type peut décaler les arguments dans la pile.
  • Vérifie le type de retour : le type générique T dans Function.Call<T> doit correspondre à ce qui est indiqué dans la base de données (bool, int, float, string).