Poradniki / Serwery i wydajność

server-icon.png: dokładne wymagania i API zarządzania, którego nikt nie używa

64x64, PNG, w katalogu głównym serwera — wystarczy pomylić jedną z tych trzech rzeczy, a ikona po cichu się nie pojawi. Do tego API zarządzania JSON-RPC, które zastąpiło odczytywanie konsoli.

2026-06-14

Ikona serwera to najmniej wyrozumiała drobna funkcja w Minecraft, bo każdy tryb awarii wygląda identycznie: brak ikony, brak błędu.

Trzy wymagania, wszystkie obowiązkowe

1. Dokładnie 64×64 piksele. Nie 63, nie 128. Serwer nie skaluje.
2. Format PNG. Naprawdę PNG, nie zmieniony JPG.
3. Nazwa server-icon.png, w katalogu głównym serwera — obok server.properties, nie w folderze świata.

Wystarczy pomylić jedną rzecz, a serwer uruchomi się normalnie i pokaże domyślną ikonę. Zły rozmiar albo plik, który nie jest naprawdę PNG, zaloguje jedną linię przy starcie — Couldn't load server icon — ale plik o złej nazwie lub w złym miejscu nie zaloguje nic. (Gdy nie ma w ogóle server-icon.png, serwer sięga po własny icon.png świata, jeśli taki istnieje.)

Co jeszcze to psuje

• Przeplot PNG (interlaced). Niektóre edytory domyślnie zapisują z przeplotem; czytnik Minecrafta go odrzuca. Wyeksportuj ponownie bez przeplotu.
• Głębia kolorów 16-bit. Zapisz jako 8 bitów na kanał.
• Profile kolorów. Osadzony profil ICC czasem przewraca parser. Usuń metadane przy eksporcie.
• Przezroczystość jest w porządku i renderuje się poprawnie na liście serwerów.

Serwer czyta ją raz

Serwer wczytuje server-icon.png przy starcie i nigdy więcej. Podmiana pliku na działającym serwerze nic nie zmienia aż do restartu — dlatego testowanie zmiany ikony bez restartu przekona cię, że nie zadziałała. Po restarcie klient podchwyci nową ikonę przy następnym odświeżeniu listy serwerów.

API zarządzania

Najnowsze wersje serwera udostępniają interfejs zarządzania JSON-RPC, który jest sankcjonowanym zamiennikiem parsowania wyjścia konsoli czy doklejania pluginu.

Włącz go w server.properties:

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

TLS jest domyślnie włączony i wymaga keystore'a (management-server-tls-keystore), więc albo wskaż mu jakiś, albo — tylko na localhost — wyłącz go jak wyżej; przy włączonym TLS i bez keystore'a serwer zarządzania się nie uruchomi. Port też nie ma wartości domyślnej (25585 to tylko przykład).

Następnie otwórz WebSocket na ten port, wysyłając management-server-secret z server.properties jako Authorization: Bearer <secret>, i mów JSON-RPC:

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

Metody obejmują listę graczy, status serwera, listę dozwolonych i listę banów, gamerules, ustawienia oraz parę zapis/zatrzymanie. Każda zwraca ustrukturyzowany JSON zamiast linii tekstu, którą trzeba przepuścić przez regex.

Przypnij go do localhost

Domyślnie jest to localhost i tak powinno zostać. Interfejs nie jest przeznaczony do wystawienia na internet — każdy, kto dotrze do niego z sekretem, może zatrzymać twój serwer, a sekret jest tylko tak bezpieczny jak twoje server.properties. Udostępnij go przez tunel SSH albo reverse proxy z uwierzytelnianiem, jeśli potrzebujesz zdalnego dostępu, nigdy przez zmianę hosta na 0.0.0.0.

Dlaczego to ma znaczenie

Pulpity, boty Discord i monitory dostępności historycznie działały przez czytanie logu konsoli albo używanie RCON, a jedno i drugie jest kruche. Typowane API sprawia, że widget liczby graczy nie psuje się, gdy linia logu zmieni format.

Przekonwertuj dowolny obraz na zgodny server-icon.png i przejrzyj metody JSON-RPC w Server Icon & API Tools.

Ikona serwera i API →