Aller au contenu

Référence de l'API Lua (Custom Natives)

Affichage et Log

log(msg)

Écrire un message dans la console de l'éditeur et dans le fichier de log du mod loader. (Utile pour le débogage.)

  • Paramètres :
  • msg (string): Le message à écrire.

print(...)

Similaire à log, mais accepte de multiples arguments qui seront séparés par des tabulations dans la sortie du log.

  • Paramètres :
  • ... (any): Les valeurs à afficher.

msgbox(msg)

Affiche une boîte de dialogue Windows bloquante au-dessus du jeu avec une icône d'information.

  • Paramètres :
  • msg (string): Le texte à afficher dans la boîte de dialogue.

Rendu 2D (DirectX)

draw_text(x, y, text, [color])

Dessine du texte à l'écran par-dessus le jeu.

  • Paramètres :
  • x (int): Position X sur l'écran.
  • y (int): Position Y sur l'écran.
  • text (string): Le texte à dessiner.
  • color (int, optionnel): La couleur au format ARGB (ex: 0xFFFFFFFF pour blanc). Par défaut : blanc.

draw_rect(x, y, w, h, [color])

Dessine un rectangle coloré à l'écran.

  • Paramètres :
  • x (int): Position X (coin supérieur gauche).
  • y (int): Position Y (coin supérieur gauche).
  • w (int): Largeur du rectangle.
  • h (int): Hauteur du rectangle.
  • color (int, optionnel): Couleur au format ARGB (ex: 0xFF000000 pour noir opaque). Par défaut : noir opaque.

Entrées et Contrôle (Input)

is_key_down(vk_code)

Vérifie de manière asynchrone si une touche clavier est enfoncée, en s'assurant que la fenêtre du jeu est bien au premier plan.

  • Paramètres :
  • vk_code (int): Le code Windows Virtual-Key (VK) de la touche (ex: 0x73 pour F4).
  • Retour : true si la touche est pressée, false sinon.

set_menu_open(bool)

Indique au moteur si votre menu/interface personnalisée est ouverte. Ceci permet de bloquer ou gérer les inputs du jeu en arrière-plan proprement.

  • Paramètres :
  • bool (boolean): true pour indiquer que le menu est ouvert.

Modding et Appels Natifs

declare_mod_file(relPath)

Ajoute un script à la liste du fichier manifest.lua de votre mod, de sorte qu'il soit automatiquement chargé au prochain démarrage ou lors d'un rechargement à chaud.

  • Paramètres :
  • relPath (string): Chemin relatif du fichier Lua depuis le dossier du mod.
  • Retour : true si l'ajout a réussi.

call_native(name, ...)

Appelle dynamiquement une fonction native du moteur de GTA IV par son nom de chaîne de caractères.

  • Paramètres :
  • name (string): Le nom de la fonction native (ex: "SET_CHAR_HEALTH").
  • ... (any): Les arguments requis par le natif.
  • Retour : La valeur retournée par le natif (le format dépend de la fonction, renvoie des bytes bruts pour les non typées).

call_native_out(name, outputCount, ...)

Appelle une fonction native de GTA IV qui utilise des pointeurs/références pour retourner de multiples valeurs.

  • Paramètres :
  • name (string): Le nom de la fonction native.
  • outputCount (int): Le nombre d'arguments de sortie (pointeurs) requis (max 4).
  • ... (any): Les arguments d'entrée classiques du natif.
  • Retour : Retourne le résultat standard du natif suivi des valeurs (sous forme de chaîne brute de 4 octets) de chaque argument de sortie déréférencé.

call_native_probe(name, ...)

Similaire à call_native, mais isole l'appel avec un block d'exception (SEH) pour empêcher le jeu entier de crasher en cas d'arguments invalides ou instables.

  • Paramètres : Identique à call_native.
  • Retour : Retourne deux valeurs : crashed (boolean, true si l'appel a causé un crash intercepté) et rawResult (le buffer brut de retour de 4 octets).

string_addr(s)

Récupère l'adresse mémoire brute pointant sur une chaîne de caractères Lua. Utile comme outil de diagnostic approfondi.

  • Paramètres :
  • s (string): La chaîne Lua.
  • Retour : (int) L'adresse mémoire pointant vers le contenu.

native_info(name)

Récupère les métadonnées et la signature complètes connues par le modloader pour un natif spécifique.

  • Paramètres :
  • name (string): Nom du natif.
  • Retour : Une table contenant les informations de signature (paramètres avec type int, float, etc., ainsi que le type de retour), ou nil si inconnu.

native_available(name)

Vérifie si un natif existe dans la base de données interne et s'il a pu être correctement résolu par le jeu en mémoire.

  • Paramètres :
  • name (string): Nom du natif.
  • Retour : true si la fonction est complètement utilisable, false sinon.

is_script_tick_fallback()

Vérifie si l'exécution actuelle se fait via la boucle de sécurité de rendu (fallback EndScene) dans les cas où le thread de script natif du jeu est inactif ou bloqué pendant plus de 3 secondes.

  • Retour : true si l'on est dans le fallback.

Événements (Callbacks)

Le moteur LuaModLoader appelle automatiquement certaines fonctions globales dans vos scripts si vous les définissez.

onTick()

Appelé à chaque image (frame) du jeu. C'est ici que vous devez placer la logique principale de votre mod (vérifier les touches, mettre à jour l'interface, faire spawner des entités, etc.).

  • Exemple : 
    function onTick()
    if is_key_down(0x73) then -- Touche F4
        -- Code exécuté à chaque frame si F4 est appuyé
    end
end

onUnload()

Appelé juste avant que votre mod ne soit déchargé ou arrêté (par exemple lors d'un rechargement à chaud ou si l'utilisateur l'arrête via le menu). Utile pour nettoyer les entités créées ou sauvegarder des données.

  • Exemple : 
    function onUnload()
    log("Le mod va s'arrêter, nettoyage en cours...")
end

Note : Il n'y a pas de fonction onLoad() spécifique à définir. Le chargement (initialisation) se fait tout simplement en écrivant votre code dans la portée globale du fichier, en dehors de toute fonction. Ce code global est exécuté une seule fois lorsque le fichier est chargé.