Guides / Serveurs et performances

server-icon.png : les exigences exactes, et l'API de gestion que personne n'utilise

64x64, PNG, à la racine du serveur — une seule de ces trois conditions manquante et l'icône n'apparaît tout simplement pas. Plus l'API de gestion JSON-RPC qui a remplacé l'analyse de la console.

2026-06-14

L'icône de serveur est la petite fonctionnalité la moins indulgente de Minecraft, car tous les cas d'échec se ressemblent : pas d'icône, pas d'erreur.

Trois exigences, toutes obligatoires

1. Exactement 64×64 pixels. Pas 63, pas 128. Le serveur ne redimensionne pas.
2. Format PNG. Un vrai PNG, pas un JPG renommé.
3. Nommé server-icon.png, à la racine du serveur — à côté de server.properties, pas dans le dossier du monde.

Une seule erreur et le serveur démarre normalement en affichant l'icône par défaut. Une mauvaise taille ou un fichier qui n'est pas vraiment un PNG écrit bien une ligne au démarrage — Couldn't load server icon — mais un fichier mal nommé ou mal placé n'écrit rien. (Sans aucun server-icon.png, le serveur se rabat sur le icon.png du monde lui-même s'il en existe un.)

Ce qui casse aussi l'icône

• PNG entrelacé. Certains éditeurs enregistrent en entrelacé par défaut ; le lecteur de Minecraft le rejette. Réexportez en non entrelacé.
• Profondeur de couleur 16 bits. Enregistrez en 8 bits par canal.
• Profils de couleur. Un profil ICC intégré fait parfois échouer l'analyseur. Supprimez les métadonnées à l'export.
• La transparence est acceptée et s'affiche correctement dans la liste des serveurs.

Le serveur ne la lit qu'une fois

Le serveur charge server-icon.png à son démarrage et plus jamais ensuite. Remplacer le fichier sur un serveur en cours d'exécution ne change rien avant un redémarrage — c'est pourquoi tester un changement d'icône sans redémarrer vous convaincra que ça n'a pas fonctionné. Après un redémarrage, un client récupère la nouvelle icône lors de son prochain rafraîchissement de la liste des serveurs.

L'API de gestion

Les versions récentes du serveur exposent une interface de gestion JSON-RPC, qui est le remplacement officiel à l'analyse de la sortie console ou à l'ajout d'un plugin.

Activez-la dans server.properties :

management-server-enabled=true
management-server-host=localhost
management-server-port=25585
management-server-tls-enabled=false

TLS est activé par défaut et nécessite un keystore (management-server-tls-keystore), donc pointez-le vers un keystore ou — uniquement sur localhost — désactivez-le comme ci-dessus ; avec TLS activé et sans keystore, le serveur de gestion ne démarre pas. Le port n'a pas non plus de valeur par défaut (25585 n'est qu'un exemple).

Ouvrez ensuite un WebSocket vers ce port, en envoyant le management-server-secret de server.properties comme Authorization: Bearer <secret>, et parlez JSON-RPC :

{ "jsonrpc": "2.0", "id": 1, "method": "minecraft:players" }

Les méthodes couvrent la liste des Joueurs, l'état du serveur, la liste d'autorisation et la liste de bannissement, les gamerules, les paramètres, ainsi qu'une paire sauvegarde/arrêt. Chacune renvoie du JSON structuré au lieu d'une ligne de texte à traiter aux regex.

Liez-la à localhost

La valeur par défaut est localhost et elle doit y rester. L'interface n'est pas destinée à être exposée à internet — quiconque l'atteint avec le secret peut arrêter votre serveur, et le secret n'est aussi sûr que votre server.properties. Exposez-la via un tunnel SSH ou un proxy inverse avec authentification si vous avez besoin d'un accès distant, jamais en changeant l'hôte pour 0.0.0.0.

Pourquoi c'est important

Les tableaux de bord, les bots Discord et les moniteurs de disponibilité ont historiquement fonctionné en lisant le journal de la console ou en utilisant RCON, deux méthodes fragiles. Une API typée signifie qu'un widget de nombre de Joueurs ne casse pas quand une ligne de journal change de format.

Convertissez n'importe quelle image en server-icon.png conforme et parcourez les méthodes JSON-RPC dans les Server Icon & API Tools.

Icône de serveur et API →