Votre premier mod Lua

Dans ce tutoriel, vous allez créer HelloNeo, un mod qui écrit dans le journal à chaque note, puis affiche un HUD avec la dernière note jouée. Il vous faut seulement NeoPiano et un éditeur de texte.

1. Créer le dossier du mod

Dans le dossier Mods de NeoPiano, créez cette arborescence :

• RépertoireMods/

  • RépertoireHelloNeo/

    • HelloNeo.uplugin
    • RépertoireCode/

      • HelloNeo.lua

Astuce

Le SDK fournit un modèle prêt à copier, Templates/ModTemplate-Lua, avec ce .uplugin, un script et un README.

2. Décrire le mod

Le fichier .uplugin porte le même nom que le dossier. Il décrit le mod et déclare ses scripts et ses capacités :

Mods/HelloNeo/HelloNeo.uplugin

{
  "FileVersion": 3,
  "FriendlyName": "Hello Neo",
  "Description": "Mon premier mod NeoPiano.",
  "CreatedBy": "Votre nom",
  "Version": 1,
  "VersionName": "1.0.0",
  "CanContainContent": false,
  "NeoModApiVersion": 5,
  "NeoModScripts": ["Code/HelloNeo.lua"],
  "NeoModCapabilities": ["ui.hud"]
}

• CanContainContent: false : un mod 100 % script, sans contenu Unreal.
• NeoModApiVersion : la version de l’API de mod visée (voir Compatibilité).
• NeoModCapabilities : ce que le mod a le droit de faire. Ici, afficher un HUD.

3. Écrire le script

Mods/HelloNeo/Code/HelloNeo.lua

-- Appelé une fois, au démarrage du mod.
function on_mod_init()
  neo.log("Hello Neo est prêt !")
end

-- Appelé à chaque note jouée. velocity va de 0 à 1.
function on_note_on(note, velocity)
  neo.log(("note %d, vélocité %.2f"):format(note, velocity))
end

NeoPiano appelle les fonctions globales de votre script quand quelque chose se passe : ce sont les callbacks. on_note_on reçoit le numéro MIDI de la note (60 = do central) et sa vélocité.

4. Tester

1. Lancez NeoPiano (ou rechargez les mods s’il est déjà ouvert).
2. Ouvrez le panneau Mods : Hello Neo est Actif.
3. Jouez quelques notes, puis ouvrez l’onglet Journal du panneau Mods : vos messages s’affichent.

5. Ajouter un HUD

Remplacez le script par celui-ci :

Mods/HelloNeo/Code/HelloNeo.lua

local NAMES = { "C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B" }

function on_mod_init()
  neo.ui.hud({ type = "label", id = "last", text = "Jouez une note" }, "top_right")
end

function on_note_on(note, velocity)
  local name = NAMES[note % 12 + 1] .. (note // 12 - 1)
  neo.ui.set("last", "text", name)
end

• neo.ui.hud(spec, ancre) crée un HUD au-dessus de la scène, dessiné par NeoPiano avec son thème.
• neo.ui.set(id, propriété, valeur) met à jour un composant sans tout reconstruire.

Enregistrez, rechargez les mods : la dernière note jouée s’affiche en haut à droite.

Rechargement à chaud

Le bouton Recharger du panneau Mods relit vos scripts et redémarre le mod, sans relancer NeoPiano. La commande console NeoMod.ReloadScripts recharge tous les mods script d’un coup.

6. L’autocomplétion

Le SDK contient Templates/neo.d.lua, des annotations LuaLS qui décrivent toute l’API. Dans VS Code avec l’extension Lua, ajoutez ce fichier à votre espace de travail :

.luarc.json

{
  "runtime.version": "Lua 5.4",
  "workspace.library": ["chemin/vers/le/SDK/Templates/neo.d.lua"]
}

Vous obtenez l’autocomplétion et la documentation de chaque fonction neo.*.

Et ensuite ?

• Ajouter un panneau et des réglages
• Sauvegarder des données d’une session à l’autre
• Comprendre les limites de la sandbox