I knew you'd come (Ripley)

Krok 1: Let's start from the beginning

Zatiaľ ste vo svojom projekte pridávali aktérov do scény buď pomocou Inšpektora, respektíve ste písali jednoduché scenáre. Odkiaľ sa však vzala samotná scéna alebo Inšpektor? Prečo má okno spustenej aplikácie práve dané rozmery? V tomto kroku si ukážeme, ako vyskladať celú aplikáciu pekne od začiatku... od funkcie main, ktorá predstavuje vstupný bod Java aplikácií.

Metóda, ktorá môže byť nastavená ako tá, ktorá sa zavolá prvá po spustení aplikácie, musí mať v jazyku Java nasledovnú signatúru:

public static void main(String[] args) {

}

V súbore build.gradle.kts upravte hodnotu premennej mainClassName v bloku application na plné meno práve vytvorenej triedy Main, obsahujúcej statickú metódu main():

application {
    mainClassName = "sk.tuke.kpi.oop.game.Main"
}

K vytvoreniu aplikácie potrebujeme pripraviť minimálne 3 objekty - konfiguráciu okna, samotnú hru, a scénu, ktorú bude hra zobrazovať. Nasledujúci kód poskytuje ukážku implementácie so sprievodnými komentármi.

public static void main(String[] args) {
    // nastavenie okna hry: nazov okna a jeho rozmery
    WindowSetup windowSetup = new WindowSetup("Project Ellen", 800, 600);

    // vytvorenie instancie hernej aplikacie
    // pouzijeme implementaciu rozhrania `Game` triedou `GameApplication`
    Game game = new GameApplication(windowSetup, new LwjglBackend());  // v pripade Mac OS bude druhy parameter "new Lwjgl2Backend()"

    // vytvorenie sceny pre hru
    // pouzijeme implementaciu rozhrania `Scene` triedou `World`
    Scene scene = new World("world");

    // pridanie sceny do hry
    game.addScene(scene);

    // spustenie hry
    game.start();
}

V prvom rade, hru vieme korektne z kódu ukončiť volaním metódy stop() nad objektom typu Game, ku ktorému sa dostaneme zo scény pomocou metódy getGame().

Možností, ako reagovať na stlačenie klávesy, máme niekoľko:

• budeme neustále (napr. v rámci nejakej opakovanej akcie) kontrolovať, či bola stlačená požadovaná klávesa, pomocou metódy isKeyPressed(), alebo
• nastavíme tzv. callback v podobe lambdy odovzdanej metóde onKeyPressed(), ktorú zavolá knižnica vždy vtedy, keď dôjde k stlačeniu určitej klávesy.

Využijeme druhú možnosť pomocou callback-u. Keďže chceme ukončovať hru klávesou ESCAPE bez ohľadu na aktívnu scénu, použijeme Input objekt hry. Riešenie môže v metóde main() vyzerať nasledovne:

game.getInput().onKeyPressed(Input.Key.ESCAPE, () -> game.stop());

Alebo ekvivalentný zápis cez referenciu na bezparametrickú metódu:

game.getInput().onKeyPressed(Input.Key.ESCAPE, game::stop);

Triedu nazvite napríklad FirstSteps.

Tentoraz nebude trieda scenára dediť od triedy Scenario, ale bude priamo implementovať rozhranie SceneListener z knižnice. V triede prekryte metódu sceneInitialized() z rozhrania SceneListener - do tejto metódy budete čoskoro písať scenár. Časti scenára môžete tak ako predtým organizovať do samostatných metód.

V metóde main() triedy Main vytvorte inštanciu triedy scenára a pridajte ju pomocou metódy addListener() k vytvorenej scéne.

Ak ste postupovali správne, po spustení aplikácie prostredníctvom Gradle úlohy run (ten istý spôsob spustenia, aký ste používali doteraz) sa zobrazí prázdne okno s názvom, ktorý ste zadali v konštruktore WindowSetup.

Všimnite si, že okno Inšpektora sa už nezobrazí.

implementation("sk.tuke.kpi.gamelib:gamelib-inspector:$gamelibVersion")

Scene scene = new InspectableScene(new World("world"), List.of("sk.tuke.kpi"));
game.addScene(scene);

Krok 2: Ripley is back!

Postava základného hráča, ktorú ste doteraz mali k dispozícii, sa už v novej scéne nezobrazuje. Namiesto neho si však vytvoríte vlastnú hlavnú postavu hry: Ripleyovú. A postupne ju budete učiť.

V triede vytvorte bezparametrický konštruktor, v ktorom:

• zavolajte konštruktor rodiča a odovzdajte mu meno aktéra ako argument: Ellen.
• nastavte animáciu s názvom player a režimom prehrávania LOOP_PINGPONG.

Vloženie do scény realizujte pomocou metódy addActor(Actor actor, int x, int y), ktorou môžete priamo definovať aj pozíciu, kde bude Ripleyová umiestnená. Pohľad na zobrazenú scénu bude vycentrovaný na pozíciu [0, 0] (kým to nenastavíme inak), takže toto miesto sa bude nachádzať v strede okna.

V prípade správnej implementácie sa vám po spustení hry zobrazí prázdny svet, v ktorom sa objaví Ripleyová na definovanej pozícii.

Krok 3: First Steps with Ellen Ripley

Aktuálne vie Ripleyová iba nervózne prešľapovať na mieste. To sa však veľmi skoro zmení.

Definujte 4 smery: NORTH, EAST, SOUTH a WEST.

V enumeračnom type Direction pridajte privátne a finálne celočíselné členské premenné dx a dy, ktoré budú reprezentovať zmeny polohy v osiach x a y, potrebné pre pohyb v danom smere. Premenné inicializujte v konštruktore Direction(int dx, int dy) a pridajte im get metódy.

Movable bude rozširovať rozhranie Actor a bude obsahovať tieto metódy:

• int getSpeed() pre získanie rýchlosti pohybu aktéra.
• void startedMoving(Direction direction) ako listener pre udalosť začatia pohybu v smere direction.
• void stoppedMoving() ako listener pre udalosť zastavenia pohybu.

Metódam startedMoving() a stoppedMoving() pridajte v rámci rozhrania prázdnu default implementáciu, aby ich nebolo nutné implementovať v každom Movable aktérovi, ak to daný aktér nebude vyžadovať.

Default implementácia metódy stoppedMoving() v rozhraní bude vyzerať takto:

default void stoppedMoving() {}

Nastavte Ripleyovej rýchlosť napríklad na hodnotu 2. V metóde startedMoving() otočte animáciu v smere pohybu a spustite ju. V metóde stoppedMoving animáciu pozastavte.

Pri implementácií použite priamo rozhranie Action z balíka knižnice sk.tuke.kpi.gamelib.actions. Akcia bude mať vlastný typový parameter viazaný na typ Movable, keďže chceme zabezpečiť, aby túto akciu bolo možné použiť len v spojitosti s aktérmi, ktorí sa môžu pohybovať (implementujú Movable).

Jej konštruktor bude mať parametre určujúce smer pohybu a trvanie pohybu v sekundách.

public Move(Direction direction, float duration) {
    // implementacia konstruktora akcie
}

Pridajte aj preťažený konštruktor len s jedným parametrom typu Direction. V tomto prípade budeme čas pohybu považovať za nulový, čo bude znamenať pohyb aktéra len o jeden krok, bez ďalšieho opakovania.

Význam jednotlivých metód je nasledovný:

• getActor() a setActor() slúžia ako getter a setter pre aktéra, ktorý vykonáva danú akciu. Scéna zavolá metódu setActor() pri naplánovaní akcie a tak aktéra nastaví.
• isDone() slúži ako getter pre overenie stavu dokončenia akcie. Po inicializovaní akcie by táto metóda mala vrátiť false, aby metóda execute() bola aspoň raz zavolaná. Keďže akcia Move bude môcť nejaký čas trvať, táto metóda by mala vrátiť true až keď uplynie určený čas. Zmenu stavu dokončenia akcie budete riešiť v ďalšej úlohe.
• reset() metóda obnoví stav akcie (s výnimkou nastaveného aktéra) do pôvodného stavu ako po vytvorení akcie.

V rámci metódy execute() implementujte nasledovné:

• V prípade, že je metóda volaná prvýkrát, zavolajte metódu startedMoving() na aktérovi vykonávajúcom akciu.
• Aktualizujte pozíciu aktéra vzhľadom na smer pohybu a jeho rýchlosť (získate ju metódou getSpeed()).
• Ak celkový čas behu akcie prekročí, alebo sa rovná času definovanému pri vytváraní inštancie akcie, ukončite akciu. To znamená, že od toho momentu musí metóda isDone() vrátiť hodnotu true. Nezabudnite zavolať metódu stoppedMoving() na pohybujúcom sa aktérovi, aby ten mohol patrične zareagovať.

Pri správnej implementácii by sa Ripleyová mala posunúť v definovanom smere počas definovanej doby, pričom jej animácia by sa mala prehrávať len pri pohybe.

Krok 4: Mission Controller

Ripleyová sa už teda vie pohybovať, zatiaľ ale len podľa vopred pripraveného scenára. To však zoči-voči nepriateľom nebude postačovať - potrebujeme niečo flexibilnejšie. V tomto kroku si ukážeme, ako navigovať Ripleyovú v reálnom čase pomocou klávesnice.

Trieda MovableController nech implementuje rozhranie KeyboardListener z hernej knižnice. Toto rozhranie obsahuje metódy, ktoré v štýle návrhového vzoru observer slúžia ako listener funkcie, volané knižnicou pri zmene stlačených kláves na klávesnici. Implementáciou týchto metód teda vieme na stláčané (a uvoľnené) klávesy reagovať.

V triede vytvorte konštruktor, ktorý vo svojom parametri akceptuje referenciu na Movable aktéra, ktorého pohyb bude ovládať.

Typ členskej premennej bude Map<Input.Key, Direction> - teda zobrazenie, kde kľúčom bude klávesa a hodnotou smer pohybu. Použitím metódy get(), ktorá akceptuje kľúč (Input.Key), tak získame príslušnú hodnotu (Direction).

Zobrazenie však musí byť "naplnené" kombináciami klávesa-smer. Túto inicializáciu viete vykonať buď pomocou metódy put() nad objektom zobrazenia, alebo pomocou factory metódy Map.ofEntries(), ktorej odovzdáte 4 parametre vytvorené volaním funkcie Map.entry() s dvojicami hodnôt klávesy a smeru pohybu:

private Map<Input.Key, Direction> keyDirectionMap = Map.ofEntries(
    Map.entry(Input.Key.UP, Direction.NORTH),
    // dalsie zaznamy zobrazenia prekladu ...
);

V tejto členskej premennej budete udržiavať referenciu na posledne vytvorenú akciu Move, aby ste ju vedeli zrušiť v prípade, že sa smer pohybu aktéra zmení.

Nezabudnite, že pre ukončenie akcie je potrebné zmeniť jej stav vrátený metódou isDone() na true a keďže pracujeme s Movable aktérom, je potrebné zavolať jeho metódu stoppedMoving()!

V metóde skontrolujte, či stlačená klávesa je jedna zo štyroch smerových kláves. Ak áno, naplánujte pohyb ovládaného aktéra v zodpovedajúcom smere na maximálny možný čas. Nezabudnite si uložiť referenciu na vytvorenú akciu.

Postup pri tejto metóde bude analogický: skontrolujte, či sa jedná o klávesu, ktorá nás zaujíma a ak áno, zastavte prebiehajúci pohyb (ak nejaký prebieha).

Registrácia listenera vstupu sa realizuje metódu registerListener() na objekte Input, ktorý zo scény získate metódou getInput().

Krok 5: Repository

Zdrojový kód nahrajte aj v prípade, ak ste nestihli dokončiť všetky úlohy. Rozpracované časti, ktoré by mohli spôsobiť kompilačné chyby, odporúčame zakomentovať.