Jarvis : assistant Minecraft

Bot Minecraft conversationnel (commandes instantanées + IA OpenRouter) avec système de rôles, builder Litematica, spots AFK, multi-bots et site web de gestion. Le site est la seule interface : création, pilotage à distance et permissions.

Fonctionnement

Message contenant la mention (ex: "jarvis ...")
        |
        +-- 1. Commande exacte en dur      -> réponse instantanée, zéro IA
        +-- 2. Commande paramétrée (regex) -> goto, suis, tp, afk, attaque, mine, construis...
        +-- 3. Sinon                       -> IA OpenRouter (contexte de jeu + mémoire)

Toutes les actions passent par le contrôle de permissions et l'anti-spam, y compris celles demandées via l'IA ou la console du site. Les demandes non satisfaites sont journalisées (logs/unhandled.log) et visibles dans le panneau.

Prérequis

• Node.js >= 22 (local) ou Docker (serveur)
• Serveur Minecraft avec ViaVersion (le bot reste sur le protocole mineflayer 26.1)
• AuthMeReloaded sur le serveur si l'authentification en jeu est activée
• Clé OpenRouter (https://openrouter.ai/keys) pour l'IA et le logo

Démarrage rapide (local)

npm install
cp .env.example .env
# éditer .env : BOT_HOST, BOT_OWNER, ADMIN_MC_NAME, WEB_SECRET, OPENROUTER_API_KEY
npm run web    # site + gestion des bots (http://127.0.0.1:8080)
npm start      # bot seul, sans le site (debug)
npm run logo   # génère assets/logo.png via openai/gpt-5-image-mini

AuthMeReloaded

Sur un serveur cracké protégé par AuthMe, le bot s'authentifie tout seul :

• À la création d'un bot (ou à son premier démarrage), un mot de passe aléatoire de 16 caractères est généré et écrit dans le .env du bot (AUTHME_PASSWORD). Chaque bot a donc un mot de passe unique, jamais partagé entre bots.
• Première connexion : le bot envoie /register <mdp> <mdp>.
• Connexions suivantes : le bot envoie /login <mdp> (repéré par AUTHME_REGISTERED=1).
• Si le serveur répond que le compte existe déjà, le bot bascule sur /login, journalise l'événement et affiche une alerte sur le site.
• Tant que l'authentification n'est pas confirmée, le bot ne parle pas, ne se présente pas et n'exécute aucune commande (le serveur les refuserait).
• Si les messages AuthMe sont personnalisés, ajoute des mots-clés de succès dans AUTHME_SUCCESS_HINTS (séparés par des virgules) après avoir lu les logs.

Le mot de passe AuthMe est visible dans la Config d'un bot sur le site (admin only). Il est conservé par le déploiement (.env bind-monté, bots/ conservé).

Site web (bots.noahroy.fr)

Accessible publiquement derrière Nginx Proxy Manager. Fonctions :

• Documentation publique : tout ce que le bot sait faire.
• Comptes : inscription libre (pseudo Minecraft + mot de passe haché scrypt). Un administrateur valide chaque compte avant qu'il puisse piloter un bot. Le pseudo est associé à l'UUID dès qu'un bot le voit en ligne.
• Panneau : état des bots, logs en direct, console à distance (avec les permissions en jeu du joueur), actions préfaites (viens, status, stop, garde, armure, drop, AFK), spots AFK, console fusionnée de tous les bots (avec filtre par bot), gestion des schematics, suivi de construction, gestion des accès, éditeur .env (admin).
• Checklist de test (/tests) : 147 fonctionnalités à valider (Oui / Partiellement / Non + suggestion), export JSON/CSV, accessible à tout compte validé.
• Spots AFK : un admin (ou un membre) amène le bot sur place puis enregistre la position sous un nom (fer, or, shulker...). En jeu : jarvis va afk fer. Le bot tente /tp puis retombe sur la marche si le serveur refuse.
• Partage : l'admin affecte des bots à des comptes validés. Ils obtiennent le rôle friend en jeu (synchro automatique de permissions.json, par UUID).
• Sécurité : sessions signées HMAC (WEB_SECRET), cookie HttpOnly SameSite=Lax (Secure derrière HTTPS), durée 30 jours, rate-limit sur inscription/connexion, routes sensibles réservées à l'admin. Le premier compte inscrit devient admin si ADMIN_MC_NAME est vide.

Rôles en jeu : owner (propriétaire du bot), friend (comptes affectés), guest (joueurs inconnus : help, status, conversation). Gestion en jeu possible : jarvis role add <joueur> friend.

PvP : le bot n'attaque jamais un joueur par défaut. Avec ALLOW_PVP=1 (par bot), owner/friend (permission pvp) peuvent demander attaque <joueur> ; les autres refusent.

Commandes

Directes : help, stop, status, drop, viens, suis moi, tp, ping, garde, équipe-toi, version, bonjour, merci, blague, qui es-tu, au revoir, roles

Paramétrées

Commande	Effet
goto <x> <y> <z> / va en	Va aux coordonnées
goto <joueur> / rejoins <joueur>	Va vers un joueur
suis <joueur>	Suit un joueur
tp / tp <joueur>	Téléporte le bot (repli : marche si refusé)
va afk <spot>	Rejoint un spot AFK enregistré (repli : marche si refusé)
attaque <mob> / tue les zombies	Chasse un type de mob (alias FR)
mine <bloc> x64	Récolte des blocs (alias FR : pierre, fer...)
construis <nom> [ici]	Construit schematics/<nom>.litematic
garde	Chasse les hostiles proches en continu
dis <texte>	Fait parler le bot
role add/remove	Gestion des rôles (owner)

IA

Conversation libre via z-ai/glm-5.3-flash (~0,09 $/M tokens) : contexte de jeu injecté (santé, position, heure, joueurs, menaces, inventaire), mémoire courte par joueur (RAM), structured outputs avec repli. Si une demande dépasse les actions disponibles, l'IA choisit l'alternative la plus proche ou explique ; l'échec est journalisé.

Builder Litematica

Déposer un .litematic dans schematics/, puis jarvis construis maison ici. Le bot place les blocs couche par couche depuis le bas, prend les ressources dans l'inventaire, puis les coffres/barils autour, puis va les miner. Limites : pas de rotation des blocs directionnels, contenants posés vides.

Depuis le site (onglet Schematics d'un bot), tout compte ayant accès au bot peut déposer un .litematic (glisser-déposer, max 10 Mo), le lister (nombre de blocs, taille, ressources requises), le lancer (Construire ici) ou le supprimer. Le bouton Construction affiche le suivi en temps réel : coordonnées de départ et dimension, total de blocs, progression, et le tableau des ressources (besoin / en stock / manquant).

Multi-bots

Un bot = un dossier bots/<nom>/ avec son .env, permissions.json, waypoints (stockés dans data/), schematic et logs propres. Chaque bot a son pseudo, sa mention, son serveur, son modèle IA et son mot de passe AuthMe : rien n'est hérité par erreur du bot principal, sauf les valeurs par défaut du .env principal à la création (hôte, version, clé OpenRouter).

Tout se fait depuis le site : créer (en choisissant le serveur), démarrer/arrêter, console, accès, spots AFK, config. Le CLI bin/jarvis.js a été retiré.

Mémoire : chaque bot est un processus mineflayer. Par défaut le conteneur ne démarre aucun bot au boot (AUTOSTART_BOTS=0), le nombre de bots simultanés est plafonné (MAX_RUNNING_BOTS=6), chaque bot est limité à 256 Mo de tas (--max-old-space-size) et le conteneur entier à 2,5 Go (mem_limit). Uploade donc les bots à la demande depuis le site (et démarre-les progressivement).

Multi-serveurs

Les serveurs sont gérés depuis le site (bouton Serveurs, admin) : nom, hôte, port, version, auth. Chaque bot porte un SERVER_ID dans son .env et appartient à un seul serveur. Le panneau affiche un bouton par serveur (et « Tous ») qui filtre les bots, la console et l'état. Les logs, permissions, mots de passe AuthMe, spots AFK et schematics restent propres à chaque bot.

Autonomie (bots 24/7)

Un seul interrupteur (bouton « Autonomie » du panneau, par serveur) : quand il est activé, tous les bots du serveur agissent seuls, 24h/24.

• Survie : manger, respawn, fuir/combat les mobs hostiles proches.
• Rôles automatiques : Mineur, Bûcheron, Gardien, Explorateur, Bâtisseur, Fermier — l'IA choisit la tâche de chaque bot à chaque cycle (repli déterministe si l'IA est indisponible ou au-delà du plafond AI_MAX_CALLS_PER_HOUR, 20/h par bot).
• Base automatique : prise au point de spawn du premier bot ; les coffres à ≤ 48 blocs servent de stock commun, et les bots y déposent quand l'inventaire est plein.
• Chantiers : dépose un .litematic via « Schematics » — l'IA décide de le construire, éventuellement à plusieurs (build découpé en tranches, même ancre).
• Vie d'équipe : les bots annoncent en chat ce qu'ils font (max 1/min), se répondent s'ils sont mentionnés (max 2 échanges, cooldown 30 s, plafond 10/h), et l'IA reçoit le journal de chaque bot + le stock de la base. Un « briefing d'équipe » toutes les heures peut redistribuer des missions.
• L'activité de chaque bot est visible sur sa carte, dans le panneau Autonomie et dans la console.

Permissions serveur sans /op

Le bot fonctionne sans aucun privilège (tp et afk ont un repli de marche). Pour autoriser /tp sans donner l'OP, utiliser LuckPerms sur Paper :

/lp creategroup bot
/lp group bot permission set minecraft.command.tp true
/lp user <pseudo-du-bot> parent add bot

Répéter pour chaque pseudo de bot. La permission d'un ami qui exécute /tp lui-même est distincte de celle du bot.

Déploiement serveur (Debian)

Sur le PC (PowerShell, depuis la racine du projet) :

tar -czf jarvis-latest.tar.gz --exclude='node_modules' --exclude='.git' --exclude='bots' --exclude='data' --exclude='logs' --exclude='schematics' --exclude='permissions.json' --exclude='.env' --exclude='*.tar.gz' .
scp jarvis-latest.tar.gz serveur:~
ssh -t serveur "sudo bash /opt/jarvis/deploy.sh"

deploy.sh (à la racine du dépôt) s'exécute en root sur le serveur : il sauvegarde .env, permissions.json, data/, bots/, logs/ et schematics/ dans /opt/jarvis-backups/<horodatage>/, extrait l'archive dans /opt/jarvis (les données locales étant exclues de l'archive, elles sont préservées), build et démarre docker compose, puis vérifie que jarvis-web tourne.

Placeholders à renseigner dans /opt/jarvis/.env :

BOT_HOST=host.docker.internal
BOT_PORT=25565
WEB_SECRET=<32+ caracteres hex>
ADMIN_MC_NAME=<pseudo admin>
OPENROUTER_API_KEY=<cle>

Nginx Proxy Manager : proxy host bots.noahroy.fr vers http://jarvis-web:8080, certificat Let's Encrypt. Le conteneur n'expose aucun port hôte (l'hôte 8080 est occupé par Pterodactyl) ; NPM le joint par son nom sur npm_network.

Conteneur : node:22-slim, npm ci --omit=dev, CMD node src/web/server.js (qui fork les bots et les redémarre). Volumes : .env, bots/, data/, schematics/, logs/.

Logs

• Console + stdout des bots collecté par le site (panneau, console, 600 lignes)
• logs/events.log : chaque commande exécutée (joueur, action, source)
• logs/unhandled.log : demandes non satisfaites, compteur par bot sur sa carte

Architecture

src/
|-- index.js            Point d'entrée bot (mode autonome ou managé IPC)
|-- config.js           .env + défauts (dont AuthMe et sessions)
|-- core/               bot, logger, state, permissions, memory, filelog,
|                       template, authme, waypoints
|-- commands/           definitions (commandes en dur) + parser
|-- ai/                 client OpenRouter, context, parse, prompt
|-- actions/            un module par action + permissions centralisées (dont afk)
|-- builder/            parser .litematic
|-- web/                site : server (HTTP, fork, IPC), store (comptes + hachage),
|                       sessions (HMAC), pages (accueil, connexion, panneau)
scripts/generate-logo.js logo via OpenRouter
deploy.sh               déploiement serveur (sauvegarde + extraction + Docker)

Développement

npm test    # 44 tests : parser, permissions, Litematica, sessions, store, AuthMe, IPC

Licence

MIT