Návod jak si vytvořit vlastní plugin
Aktualizováno ke dni 4.9.2017 4:41
Obsah
- Úvod
Zvolení IDE aplikace
Seznámení se s SpigotAPI (BukkitAPI)
Vytvoření projektu
Vytvoření prvního pluginu
Implementace příkazů do pluginu
Implementace eventů do pluginu
Tipy a Triky
Úvod
V tomto návodě si ukážeme jaké editory jsou k dispozici, na které dávám já a proč.
Dále se zde seznámíme s používáním Bukkit API, vysvětlíme si co to je, k čemu to je dobré.
Postupně se prokopeme do části kde vytvoříme svůj vlastní plugin, který bude umět vykonat základní příkazy a odposlouchávat základní eventy.
Zvolení IDE aplikace
IDE je Integrated Development Environment. Pro nás to je jednoduše řečeno editor ale pozor. Mezi editorem a IDE je zásadní rozdíl, editor je taktéž poznámkový blok anebo Word.
Co tedy přesně IDE obnáší? Usnadňuje práci programátorům a to tak, že již má v sobě zabudovanou programovou logiku. Díky které dokáže rozeznat jestli kód je správně napsaný a kde je chyba.
To by bylo v krátkosti co to znamená, více si o tom můžete přečíst na Wikipedii pokud Vás to zajímá.
Hned ze začátku se nám nabízí spousty editorů, pokusím se tu vypsat takové ty známější, které lidé co znám používají.
Intellij Idea, Netbeans, Eclipse, Sublime
A však já pro tento návod jsem se rozhodl použít Intellij Idea, používám ho už dlouhou dobu a z těchto editorů mi sedl nejlépe.
A to hlavní je, že je zdarma!
Seznámení se s SpigotAPI (BukkitAPI)
Asi mě budete mít za blázna, ale řeknu Vám, že se budete učit BukkitAPI, nikoliv SpigotAPI.
Máme zde různý implementace serverů, z nynějších používaných je Spigot a ten je založený na CraftBukkit.
Popřípadě PaperSpigot který je založený na Spigotu.
Bukkit je tedy API, které umožňuje programátorům vytvořit pluginy pro CraftBukkit server.
API - Application Programming Interface, Lajsky řečeno: Jedná se o knihovnu z které čerpají všechny pluginy a potom server samotný.
Pomocí této knihovny se potom dokáže spojit s každým pluginem a dát ho dostavu načetlého anebo vlastně rovnou ho načíst.
Zapamatujte si: BukkitAPI nemůže být voláno z vedlejších vláken, pouze jen z hlavního!
Více o tom co je to CraftBukkit, Bukkit, Spigot, apod... najdete zde (Anglicky).
Nyní víme co je to Bukkit a proto se můžeme vrhnout na jeho poznání!
Vytvoření projektu
Po spuštění Intellij Idea, uvidíme následující tabulku:
Napravo tedy zvolíme 'Create New Project', kde poté v levé nabídce nalezneme Maven a klepneme na Next.
Nyní zde nalezneme nastavení Manevu, což je GroupId, ArtifactId a Version.
- Groupid
Označuje skupinu, která zadaný projekt vytváří.
Vždy se píše malými písmeny a odděluje tečky.
Dnešním zvykem je vždy první uvést organizaci skupiny (já udávám CZ jako, že jsem Czech a moje webovky končí .cz)
Jako druhé se pak uvádí jméno autora popř. název skupiny a jako třetí se dává název projektu.
ArtifactId
Označuje název projektu, již může obsahovat jakékoliv znaky. (Aspoň tedy doufám že může, nikdy nepoužívám jiné znaky než alfanumerické)
Version
Označuje verzi našeho projektu
Po klepnutí na Next uvidíme tabulku o názvu projektu a umístění projektu. To už je na Vás jak uznáte za vhodné, já jsem tedy nechal výchozí hodnoty a potvrdil klepnutím na Finish.
Nyní před sebou uvidíme nově vytvořený projekt, kde se nám automaticky otevře pom.xml projektu (ukazuje se jako název projektu, ne jako pom.xml) ale v souborech to je pom.xml.
Pokud se Vám něco takového neukázalo a nalevo nevidíte ani hierarchii s projektem, tak podržte levý ALT a zmáčkněte '1' ale tu u Esc.
Pokud-li teda ještě nemáme otevřený pom.xml tak ho otevřeme.
Nad </project> nyní přidáme tento kus kódu:
Čerpáno z SpigotMC.org
Takže tedy budeme mít toto:
Tento kód za nás stáhne všechny potřebné knihovny k vývoji Bukkit pluginu.
V levé hierarchii si otevřeme (název projektu) > src > main > java
Klepneme pravým na java složku a najedeme do 'New > Java Class'
Nyní třídu pojmenujeme tak, že začátek bude stejný jako naše GroupID, které jsme zadali při vytváření projektu a lze ho nalézt v pom.xml.
S tím rozdílem za konec přidáme tečku a přidáme název třídy. Název třídy vždy začíná velkým písmenem, neobsahuje mezery a pouze alfanumberické znaky.
Tedy v mém případě: cz.sionzee.joinleft.JoinLeftPlugin
Pokud-li jste udělal správně, uvidíte vlevo podobně hierarchii jako já.
Automaticky se Vám otevře Vámi vytvořená třída s Vašim názvem. V mém připadě to je JoinLeftPlugin.
Teď jste ve fázi, kdy projekt máte vytvořený a prostředí připravené k programování.
Abyste mohli pokračovat dále, musíte mít znalosti jazyka Java.
Vytvoření prvního pluginu
Nyní necháme naší třídu na implementovat abstraktní třídu JavaPlugin a přetížíme onEnable metodu.
Ze začátku pro nás budou podstatné pouze tři metody, které budeme přetěžovat:
- onLoad() - Metoda, která se zavolá, když je plugin načten PluginLoaderem.
onEnable() - Metoda, která se zavolá, když je plugin zapnut.
onDisable() - Metoda, která se zavolá, když je plugin vypnut.
Přidejme si tedy do onEnable nějaký debug,
System.out.println("Tohle se ukaze v konzoli, kdyz se server zapne a zrovna nacte tento plugin.");
BukkitPluginLoader potřebuje každý plugin nějak identifikovat, najít jeho EntryPoint (hlavní spouštěcí třídu)
Proto musíme ve složce 'src > main > resources' vytvořit soubor 'plugin.yml', který bude mít následující náležitosti:
- name
Název pluginu, který bude ukázán v /plugins /pl,
version
Verze pluginu
main
Entrypoint hlavní třídy, tzn. cesta k hlavní třídě a to v podobě: 'package.classname'
Pak jsou zde další věci jako Depend, SoftDepend, Website, Description, apod... Více zde (anglicky).
Já tam tedy budu mít
Nyní musíme nastavit export pluginu do balíčku .jar.
Klepneme na 'File > Project Structure' (anebo zkratkou CTRL+ALT+SHIFT+S)
Vybereme v Project Settings > Artifacts
Klepneme na PLUS úplně nahoře a vybereme JAR > Empty
Nahoře přejmenujeme z unnamed na název pluginu, který budou alfanumericky, bez háčku a čárek a mezer. Bude to název souboru který bude končit příponou .jar
V Output Layout napravo je Available Elements, uvidíme tam 'Váš název projektu' compile output.
Na tuto položku klepneme několikrát dokud se nepřesune do levé části.
Poté nahoře zaškrtneme 'Include in project build' a potvrdíme přes Apply a OK.
Nyní můžeme sestavit náš plugin a to tak, že nahoře v menu vybereme Build > Build Artifacts..., vybereme název našeho artifactu a klepneme na Build.
Nyní počkáme až se projekt sestaví (na spodní liště uprostřed uvídíme 'build') a kolečko které signalizuje načítání.
Jakmile to zmizí, můžeme se vydat do umístění projektu a tam najdeme složku 'out/artifacts/název artifactu/názevpluginu.jar'
TIP: Když klepnete na jakýkoliv soubor/složku pravým v hierarchii, tak tam máte možnost 'Show In Explorer', to Vás přesměruje o složku výš na složku na kterou jste to dali.
Tedy Vám to otevře umístění toho souboru.
Tento plugin teď můžete hodit do složky plugins a spustit server.
Měli byste vidět výpis, který jste zadali do onEnable().
No nebylo to jednoduché do začátku?
Nejlíp se to naučíte, když si otevřete nějaký open-source plugin a podíváte se jak to má dotyčná osoba udělané, z toho pochopíte nejvíce věcí.
Implementace příkazů do pluginu
Přetížíme metodu onCommand() a budeme odposlouchávat na zavolaný příkaz.
Pokud máte dobrou znalost angličtiny, dokážete vyvodit z toho obrázku, co k čemu slouží.
Pokud ne, tak v Bukkitu to pro Vás bude pruser, všechno tam je totiž pouze anglicky.
Na řádku 17 kontroluji jestli příkaz který byl zavolán je /prikaz a ne třeba /brumbal.
Na řádku 19 kontroluji jestli uživatel co zadává /prikaz má oprávnění JoinLeft.Commands.Prikaz a jestli ho nemá, tak řádek 23 ho o tom informuje.
Na řádku 20 posílám hráči co zadal /prikaz zprávu o tom že vykonal příkaz.
Na řádku 21 Tuto zprávu sděluji všem hráčům co jsou na serveru a v to zprávě zadávám jméno hráče co zadal /prikaz
Další parametry, který jsou zadány za příkazem např: /prikaz parametr1 parametr2 parametr3 parametrN
jsou uloženy v array 'args'. (args = {parametr1, parametr2, parametr3, parametrN})
Každý command musí být evidován v plugin.yml a to tak že tam musí být minimálně jeho jméno a description.
Implementace eventů do pluginu
Nyní si vytvoříme novou třídu (pravý klik na náš package > New > Java Class)
Pojmenujeme jí PlayerListener (třeba)
Tato třída bude implementovat Listener
a budou se do ní přidávat metody s event parametry, každá tato metoda musí obsahovat annotaci @EventHandler a jak již metodu pojmenujete je zcela na Vás.
Seznam těchto všech eventů naleznete zde (anglicky). (Bude jich tam dost chybět ale do začátku než se vyznáte v JavaDocs Vám to bude muset stačit)
Každá třída (cokoliv co implementuje ten Listener) musí být registrována v PluginManageru a k tomu potřebujeme přístup k naší hlavní třídě pluginu.
Proto tedy v onEnable můžeme napsat:
Bukkit.getPluginManager().registerEvents(new PlayerListener(), this);
A tím zaregistrujeme náš odposlouchávač na eventy, které jsme v té třídě určili. (PlayerJoinEvent, PlayerQuitEvent)
PlayerJoinEvent - Zavolá se když se připojí hráč.
PlayerQuitEvent - Zavolá se když se odpojí hráč.
Tipy a Triky
Dopíši v odpoledních hodinách.
Tento návod jsem psal poněkud v rychlosti a to z důvodu že jsem se nudil, dopisuji ho nyní v 4:40AM a až vstanu, určitě tady toho dost ještě upravím.
Stará verze tohoto návodu je zde:
Spoiler: zobrazit