Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Konfigurační soubory

Konfigurační soubory jsou soubory, které slouží ke konfiguraci samotného serveru, pluginů a módů.

Základní práce s konfiguračními soubory

Obecně je pro projevení změn u serverových souborů (např. server.properties, server-icon.png, nebo spigot.yml) zapotřebí server restartovat (restartovat, nikoli reloadnout!). Existují však výjimky, jako například purpur.yml nebo velocity.toml, u kterých jdou změny načíst bez restartu pomocí příkazů purpur reload a velocity reload.

Co se týče konfiguračních souborů pluginů, většina pluginů má pro načtení změn příkaz. Více se dozvíte v dokumentaci pluginu, například EssentialsX mají příkaz essentials reload. V případě, kdy plugin příkaz pro reload nemá, server restartujte.

Příkaz reload ani pluginy pro reloadnutí pluginů, jako například PlugManX, nepoužívejte. Z jakého důvodu se dočtete zde.

Pokud nevíte, kde najít nějakou konkrétní věc v konfiguraci, neptejte se na konkrétní řádek. Uvádět řádky je špatné, jelikož se můžou v závislosti na verzi pluginu a konkrétní konfiguraci uživatele lišit. Řádky jsou z pohledu pluginu irelevantní.

V případě, kdy hledáte v konfiguraci konkrétní text, vyhledávání v textu zapnete prakticky ve všech aplikacích pomocí klávesové zkratky Ctrl + F.

V případě, kdy hledáte určitou věc, ale nevíte, jak se konkrétně jmenuje, hledejte dle klíčových slov.

Pokud hledáte specifický souvislý text, dejte si pozor na kódy barev. Pokud byste v konfiguračním souboru s následujícím obsahem hledali “server skyblock is full”, nic byste v souboru nenašli

Server &lSkyBlock is full

To stejné platí i pro proměnné

Server %gamemode% is full

Reset konfiguračních souborů

Konfigurační soubory se resetují zejména ve dvou případech:

  1. Konfigurační soubor byl upraven při vypnutém serveru.

V některých případech může být config resetován, pokud je manuálně upraven při běhu serveru. Děje se to např. u BungeeCord nebo Multiverse-Core configu. Není to však standardem. V takovém případě je nutné config upravovat při vypnutém serveru, nebo k upravení hodnot v configu použít příkaz, pokud takový příkaz existuje (např. mv config prefixchat false u Multiverse-Core)

  1. Soubor není validní

Každý konfigurační formát má svá pravidla, které je nutno dodržet. V opačném případě soubor není validní. V případě porušení těchto pravidel může být konfigurační soubor resetován do výchozího nebo zálohovaného stavu.

Pokud nevíte, kde se v souboru nachází chyba, před uložením zkontrolujte validitu přes validátor, a soubor uložte až v moment, kdy si jste jisti, že je soubor validní.

Typy

Když program (server, plugin) čte konfigurační soubor, očekává, že hodnota má určitý typ. V případě, kdy je použit typ jiný, než program očekává (například místo čísla je poskytnut textový řetězec), nastane chyba. To se například stane, když u hodnoty, která očekává číslo, použijete textový řetězec.

Konkrétním příkladem takové chyby je např. situace, kdy byste přešli z novější verze Paperu na verzi, která ještě v konfiguraci nepodporuje hodnotu default. V takovém případě se server zhroutí, jelikož u polí, které očekávají čislo, bude textový řetězec default.

  • Textový řetězec (String)

String je zjednodušeno řečeno text.

chatrequireslogin: "Chat Requires Login"
  • Celé číslo (Integer)

Integer je zjednodušeně řečeno celé číslo.

max-players: 20
  • Desetinné číslo (Double/Float)

Typ double a float je zjednodušeně řečeno desetinné číslo.

spawn-location:
  x: 2.5
  y: 50
  z: 2.5

U desetinných čísel lze většinou zapsat i celé číslo (a naopak), jak je ukázáno u y. Na desetinný typ bude hodnota převedena automaticky. To stejné platí například i u boolean - textový řetězec “true” bude automaticky převeden na hodnotu typu boolean. Pokud je však použit textový řetězec, jako například “hello”, i když je očekáváno číslo, kdy program není schopen tento typ správně převést na očekávaný typ, nastane chyba.

  • boolean

Hodnota typu boolean může být buď true, nebo false. To lze do běžné řeči přeložit jako ano/ne, pravda/nepravda, nebo zapnuto/vypnuto (záleží na kontextu)

send-position: true
  • List (Array)

List/seznam (Array) obsahuje list určitých hodnot. Ve formátu Y(A)ML se standardně zapisuje dvěma způsoby:

player-list: ["Notch", "Cake"]

a

player-list:
- "Notch"
- "Cake"

Tyto zápisy jsou identické.

︌

V případě, kdy server/plugin očekává, že bude číst typ list, je nutno, aby tento typ listem zůstal, tedy pokud původní hodnota vypadá následovně:

player-list: ["Notch", "Cake"]

nelze jako hodnotu nastavit textový řětězec, i když je v listu pouze jedna hodnota. V takovém případě nastane chyba, jelikož plugin očekává list, ale narazí na textový řetězec.

player-list: "Notch"

To lze jednoduše opravit nastavením hodnoty zpět na typ listu.

player-list: ["Notch"]

Prázdný list ve formátu YML vypadá následovně:

player-list: []

Komentáře

Komentář v konfiguračním souboru je text, který bude při parsování souboru ignorován. Například komentář ve formátu Y(A)ML začíná znakem #.

To zjednodušeně řečeno znamená, že program (server, plugin) text za # ignoruje, a na nastavení tedy nemá vliv.

delay: 500 # in milliseconds <- poznámka
# delay: "500" zde je zakomentovaný celý řádek, takže je to stejné, jako by řádek v souboru nebyl

Samozřejmě ale znak # lze bez problému použít v hodnotách textových řetězců, např.

content: "Pozice: #1"

Formáty konfiguračních souborů

Každý konfigurační soubor má svůj formát a každý formát má svá pravidla. V případě, kdy tato pravidla nejsou dodržena, formát není validní. Nejčastěji pak plugin nebo jeho část nebude fungovat, případně může dojít k vypnutí/zhroucení serveru, zejména se tak děje u serverových souborů (např. spigot.yml).

YML/YAML

Nejrozšířenějším formátem konfiguračních souborů u pluginů je YML.

Takový Y(A)ML soubor může vypadat například následovně:

server_connect_timeout: 5000
remote_ping_cache: -1
player_limit: -1
permissions:
  default:
  - bungeecord.command.server
  - bungeecord.command.list
timeout: 30000
log_commands: false
network_compression_threshold: 256
online_mode: true

Pravidla Y(A)ML

Jak již bylo zmíněno, každý konfigurační formát má svá pravidla, která je nutno dodržet. Pokud jsou tato pravidla porušena, soubor není validní a důsledkem může být od nefunkční části pluginu po nefunkční celý plugin až server (server se zhroutí).

Pro odsazení se standardně používají buď 2, nebo 4 mezery. V YML formátu je nutno respektovat odsazení, tzn. každý klíč spadající pod sekci musí být od kraje stejně daleko, jako všechny ostatní klíče v této sekci, tzn. první příklad není validní YML, ale druhý ano.

colors:
  red: "#ff0000"
   blue: "#0000ff"
  green: "#00ff00"

colors:
  red: "#ff0000"
  blue: "#0000ff"
  green: "#00ff00"

Pro odsazení nemůže být použit tab, ale pouze mezera (některé editory jako např. VSCode tab automaticky nahradí mezerami). Taktéž názvy klíčů (ve stejné sekci) nesmí být duplicitní.

Níže jsou uvedeny příklady dalších nejčastějších chyb u Y(A)ML formátu.

Příklady nejčastějších chyb

V této části jsou uvedeny příklady nejčastějších chyb u YML formátu. Mezi další chyby patří i záměna typů, což je rozebráno v této části.

servers:
  survival:
    address: guardian.hostify.cz:59700
    motd: Just another Bungee server
    restricted: false
  lobby: guardian.hostify.cz:59700
  skyblock:
    address: bat.hostify.cz:36830
    motd: Just another Bungee server
    restricted: false

V tomto příkladu není chybný samotný YML formát, ale program nebude schopen konfigurační soubor (konkrétně server lobby v sekci servers) správně přečíst, jelikož je hodnota lobby text guardian.hostify.cz:59700, přičemž lobby má být pouze sekce a tento text má být u pole address v sekci lobby, jak je správně nastaveno u ostatních serverů.

ping_passthrough: false
priorities:Shadowmc
proxy_protocol: false

V tomto příkladu není YML formát validní, jelikož mezi polem priorities a jeho hodnotou chybí mezera.

lobby:
  address: "localhost:25565"
  address: "localhost:25566"

V tomto příkladu není YML formát validní, jelikož obsahuje duplicitní klíče.

content: '&c&lHráči s nejvíce kill's'

V tomto příkladu není YML formát validní kvůli jedné úvozovce v textovém řetězci. To lze opravit buď použitím dvou jednoduchých uvozovek místo jedné (což se nazývá escapování): {#yaml-escape}

content: '&c&lHráči s nejvíce kill''s'

nebo změnou jednoduchých uvozovek za klasické:

content: "&c&lHráči s nejvíce kill's"

colors:
  red: "#ff0000"
   blue: "##0000ff"
  green: "#00ff00"

V tomto příkladu není YML validní kvůli špatnému odsazení blue. To musí být odsazeno (od kraje stejně daleko) stejně jako red a green.

spawn-limits:
		monsters: 70

Ačkoli nemusí být na první pohled žádná chyba vidět, YAML není validní, a to kvůli použití tabulátoru pro odsazení. Validní Y(A)ML nemůže pro odsazení používat tabulátory, ale pouze mezery!

boss-bar: <rainbow>&lPINATA: '%hit% HIT%S% LEFT

Zde není YML validní. V případě, kdy textový řetězec obsahuje speciální znaky, je dobré text zabalit do uvozovek (pozor však, pokud text již obsahuje uvozovku a na zabalení chcete použít stejný typ uvozovky viz zde).

JSON

JSON je další častý formát. I když JSON není formát určený pro konfigurační soubory (ačkoli jej někteří tak používají), může se stát, že budete potřebovat JSON soubor upravit manuálně (např. whitelist.json).

Obsah validního prázdného JSON souboru vypadá následovně: []. Prázdný soubor není validní JSON soubor!

JSON soubor může vypadat napříkald následovně:

{"dog": "woof", "cat": "meow", "list": [1, 2, 3, 4], "people": [{"name": "josh", "age": 22}, {"name": "andrea", "age": 23}]}

Jelikož rozsáhlejší JSON soubory můžou být hůře čitelné, může se hodit nástroj typu JSON Viewer/Editor.

Ostatní formáty

Existuje i řada dalších formátů, jako například properties, TOML či HOCON. Problém by to však být neměl, jelikož principy nastavení jsou napříč formáty stejné a lehce se líší pouze zápis, který si po chvíli osvojíte.

Formáty/formátování zpráv

V konfiguračních souborech můžou jít zprávy formátovat různými způsoby.

MiniMessage

MiniMessage je moderní standard, který drtivá většina aktualizovaných pluginů podporuje. Více se o něm dočtete zde: https://docs.advntr.dev/minimessage/format.html

Pro jednoduché zobrazení MiniMessage zpráv lze využít nástroj https://webui.advntr.dev/

Kódy barev

Ještě před tím, než vznikl formát MiniMessage, prakticky jedinou možností, jak zprávu obarvit, bylo pomocí barevných kódů, a to pomocí znaku & (případně u některých pluginů §) - &4&lTento text je tmavě červený a tlustý. &0Tato část je černá.

Konkrétní kódy barev naleznete zde: https://minecraft.fandom.com/wiki/Formatting_codes

Pozor! Pokud kombinujete více kódu, barva patří na první místo, tudíž správně je &4&l namísto &l&4. Pokud by bylo první ’&l“ (kód pro tučný text), text nebude tučný.

RGB/HEX a gradient

RGB/HEX barvy lze využít od verze 1.16. Hráči se starší verzí klienta (pomocí ViaVersion) HEX barvy nevidí, i když server běží na verzi, která HEX barvy podporuje.

Pro vytvoření gradient má formát MiniMessage podporu - https://docs.advntr.dev/minimessage/format.html#gradient

Pokud jej použít nemůžete, lze využít následující nástroj - https://www.birdflop.com/resources/rgb/

Nový řádek

Pokud server/plugin neumožňuje vytvoření více řádků pomocí listu, často lze použít symbol \n, tedy například

# spigot.yml
messages:
  restart: "Server is restarting\nTry reconnecting in a minute"

Nástroje

Validátory

Validátor je nástroj, který slouží k ověření validity konkrétního formátu. V případě, kdy formát validní není, validátor vypíše, na jakém řádku chyba nastala. Číslo tohoto řádku nemusí být přímo řádek, který problém způsobuje, nicméně pokud tomu tak není, pravděpodobně bude velice blízko něj.

YAML validátor najdete například na následujícím odkaze: https://jsonformatter.org/yaml-validator

Takových validátorů pro různé formáty existuje mnoho, ale u Y(A)ML osobně doporučuji tento konkrétní, jelikož u některých ostatních validátorů nemusí být chyby na první pohled vidět (např. duplicitní klíče).

Viewer/Editor

Viewer je nástroj, který slouží k přehlednějšímu zobrazení obsahu souboru. To se může hodit především u rozsáhlých a méně přehledných souborů (zejména JSON). Editor je nástroj, který umožňuje jednodušší úpravu takových souborů. Ačkoli je pro takový účel u Minecraft serverů většinou zbytečný, lze jej stále využít jako viewer.

Příkladem takových nástrojů je například tento YAML viewer a tento JSON viewer.

Formatter/Prettier/Beautify

Když v prohlížeči vyhledáte “<formát> formatter” (někdy nazýváno i jako prettier/beautify), narazíte na mnoho online nástrojů, které Vám text zformátují do čitelnější podoby, tedy např. z

{"dog": "woof", "cat": "meow", "list": [1, 2, 3, 4], "people": [{"name": "josh", "age": 22}, {"name": "andrea", "age": 23}]}

udělají

{
    "dog": "woof",
    "cat": "meow",
    "list": [
        1,
        2,
        3,
        4
    ],
    "people": [
        {
            "name": "josh",
            "age": 22
        },
        {
            "name": "andrea",
            "age": 23
        }
    ]
}

Converter

Pokud z nějakého důvodu potřebujete překonvertovat jeden formát na druhý, u nejčastěji používaných formátů nástroje pro takový účel naleznete (např. https://jsonformatter.org/yaml-to-json#Sample).

Tečková notace

Tečková notace v konfiguračních souborech označuje notaci, kde tečka značí přechod do “podsekce”, tedy například zápis entities.spawning.monster-spawn-max-light-level označuje

entities:
  spawning:
    monster-spawn-max-light-level: <hodnota>

Ostatní

Přípona souboru nutně nemusí odpovídat jeho formátu. Například Dynmap config je ve formátu YML, i když se konfigurační soubor jmenuje configuration.txt.

Terminologie

Termín “config” se používá jak pro označení souboru config.yml, tak i pro jakýkoli konfigurační soubor. Co je slovem “config” myšleno vždy záleží na kontextu.