# Animation Builder - poradnik nietechniczny Ten poradnik jest bez polskich znakow, bo w niektorych prostych viewerach ogonki potrafia sie rozwalic. ## Po co jest Animation Builder Animation Builder sluzy do tego, zeby z kilku klatek grafiki zrobic animacje i zapisac ja jako gotowy wpis w: ```text data/assets/sprite-mapping.json ``` Dzieki temu nie trzeba recznie pisac JSON-a. Mozesz robic animacje dla: ```text - postaci gracza - NPC - maszyn - serwerow - monitorow - lamp - drzwi - innych obiektow stojacych ``` ## Najwazniejszy flow Jesli ktos przed chwila wgral Ci nowe pliki na serwer, robisz tak: ```text 1. Wrzuc pliki assetow do assets/vendor/... 2. Wejdz w Admin -> Animation Builder. 3. Kliknij: Odswiez assets/vendor. 4. Wybierz nowy obrazek z listy. 5. Ustaw rozmiar klatki. 6. Kliknij klatki animacji po kolei. 7. Nazwij animacje. 8. Kliknij: Zapisz animacje w projekcie. 9. Kliknij: Zapisz do sprite-mapping.json. 10. Kliknij: Odswiez po zapisie. 11. Otworz Map Builder. 12. Wybierz nowy spriteId i dodaj go do mapy. ``` To jest cala droga od nowego pliku w assets/vendor do dzialajacej animacji na mapie. ## Krok 1 - wrzucenie nowych plikow Nowe grafiki wrzucasz na serwer do: ```text assets/vendor/ ``` Przyklady: ```text assets/vendor/limezu/modern-office/ assets/vendor/limezu/modern-interiors/ assets/vendor/custom/my-machines/ assets/vendor/custom/my-characters/ ``` Nie wrzucaj ich do paczki release, jesli sa platne. Paczka aplikacji ma tylko odwolania do assetow, a nie pelne platne pliki. ## Krok 2 - odswiez assets/vendor Po wgraniu plikow kliknij w Animation Builderze: ```text Odswiez assets/vendor ``` To przebuduje plik: ```text data/assets/vendor-index.json ``` Ten plik mowi aplikacji, jakie obrazki istnieja w assets/vendor. Jesli nie klikniesz odswiezenia, nowy plik moze nie pojawic sie na liscie. ## Krok 3 - wybierz obrazek Wybierz z listy obrazek / tileset. Jesli nie widzisz swojego pliku: ```text - sprawdz czy jest w assets/vendor - kliknij Odswiez assets/vendor - odswiez strone w przegladarce - sprawdz czy plik ma format png, jpg, jpeg albo webp ``` ## Krok 4 - ustaw rozmiar klatki Rozmiar klatki mowi, jak duzy jest jeden obrazek animacji. Typowe wartosci: ```text 16 x 16 - male kafelki, drzwi, male obiekty 32 x 32 - wieksze obiekty, maszyny, meble 48 x 48 - postacie RPG Maker / NPC 64 x 64 - duze obiekty albo wieksze postacie ``` Jesli siatka nie pasuje do grafiki, zmien szerokosc i wysokosc klatki. ## Krok 5 - kliknij klatki animacji Klikasz klatki na obrazku po kolei. Przyklad maszyny: ```text klatka 1 - maszyna normalna klatka 2 - maszyna z lampka klatka 3 - maszyna z inna lampka ``` Klikasz: ```text 0,4 -> 1,4 -> 2,4 ``` Animacja bedzie leciala w tej kolejnosci. Prawy klik usuwa ostatnia klatke. ## Krok 6 - nazwa animacji Dobra nazwa animacji jest krotka i jasna. Dla maszyn: ```text idle running warning broken offline ``` Dla drzwi: ```text closed opening open locked ``` Dla postaci: ```text idleDown idleUp idleLeft idleRight walkDown walkUp walkLeft walkRight ``` Nie uzywaj nazw typu: ```text test nowe animacja2 final_final ``` Za tydzien nikt nie bedzie wiedzial, co to bylo. ## Krok 7 - zapisz animacje w projekcie Po kliknieciu klatek kliknij: ```text Zapisz animacje w projekcie ``` To zapisuje wybrane klatki pod aktualna nazwa animacji w builderze. Jesli robisz postac, musisz zapisac osobno: ```text walkDown walkLeft walkRight walkUp idleDown idleLeft idleRight idleUp ``` Jesli robisz maszyne, czesto wystarczy: ```text running ``` ## Krok 8 - dopasuj offsety Offsety przesuwaja grafike wzgledem kratki mapy. ```text offsetX - przesuwa grafike w lewo albo prawo offsetY - przesuwa grafike w gore albo dol destW - szerokosc wyswietlania na mapie destH - wysokosc wyswietlania na mapie ``` Proste zasady: ```text Postac stoi za wysoko -> zmien offsetY. Postac stoi za bardzo w lewo -> zmien offsetX. Postac jest za duza -> zmniejsz destW i destH. Postac jest za mala -> zwieksz destW i destH. Maszyna nachodzi na sciane -> zmniejsz destH albo popraw offsetY. ``` ## Krok 9 - zapisz do sprite-mapping.json Kliknij: ```text Zapisz do sprite-mapping.json ``` Backend zrobi kopie zapasowa obecnego pliku w: ```text data/assets/backups/ ``` Potem doda albo zaktualizuje wybrany spriteId. Jesli spriteId juz istnieje, zaznacz: ```text Nadpisz, jesli spriteId juz istnieje ``` Nie zaznaczaj tego przypadkiem, jesli nie chcesz zmieniac starej animacji. ## Krok 10 - odswiez po zapisie Po zapisie kliknij: ```text Odswiez po zapisie ``` To laduje aktualny sprite-mapping.json do narzedzia. Potem nowy spriteId powinien byc dostepny w Map Builderze i Animation Preview. ## Krok 11 - uzyj animacji w Map Builderze Otworz: ```text Admin -> Map Builder ``` Dodaj obiekt albo NPC i wybierz nowy spriteId. Przyklad: ```text spriteId: machine_press_animated animation: running ``` Dla NPC wybierasz spriteId postaci. Jesli NPC sam chodzi, silnik moze dobierac walkDown / walkLeft / walkRight / walkUp. ## Krok 12 - maszyna animowana Przyklad maszyny: ```text spriteId: machine_line_animated animacja: running ``` Na mapie obiekt moze miec: ```json { "id": "OBJ_LINE_A", "type": "machine", "spriteId": "machine_line_animated", "animation": "running" } ``` Jesli pozniej chcesz zrobic awarie, mozesz miec stan: ```text running -> warning -> broken ``` ## Krok 13 - drzwi animowane Drzwi maja dwie rzeczy: ```text 1. wyglad / animacja 2. logika przejscia / blokowania ruchu ``` Animation Builder robi tylko grafike. Przyklad animacji drzwi: ```text closed opening open locked ``` Potem w Interaction & Animation Editor ustawiasz: ```text closed -> animacja closed, blokuje ruch locked -> animacja closed, blokuje ruch open -> animacja open, nie blokuje ruchu ``` ## Krok 14 - postac z kierunkami Dla postaci najlepiej robic animacje: ```text idleDown idleUp idleLeft idleRight walkDown walkUp walkLeft walkRight ``` Silnik wybiera animacje na podstawie kierunku ruchu. Jesli nie masz wszystkich kierunkow, zostaw przynajmniej: ```text idleDown walkDown ``` Postac bedzie mniej ladna, ale nie powinna sie wysypac. ## Krok 15 - test po zapisie Po zapisaniu: ```text 1. Otworz Animation Preview. 2. Wybierz spriteId. 3. Wybierz animacje. 4. Sprawdz czy klatki ida w dobrej kolejnosc. 5. Otworz Map Builder. 6. Dodaj obiekt z tym spriteId. 7. Otworz gre i sprawdz na mapie. ``` ## Najczestsze problemy ### Nie widze nowego pliku ```text - kliknij Odswiez assets/vendor - sprawdz folder assets/vendor - sprawdz rozszerzenie pliku - odswiez strone ``` ### Siatka nie pasuje ```text - zmien frameWidth - zmien frameHeight - sprawdz czy obrazek ma rowne klatki ``` ### Animacja skacze ```text - klatki sa w zlej kolejnosc - klatki maja rozne pozycje w obrazku - popraw offsetX / offsetY ``` ### Obiekt jest za duzy ```text - zmniejsz destW - zmniejsz destH ``` ### Zapis nie dziala ```text - sprawdz czy jestes zalogowany jako admin - sprawdz uprawnienia pliku data/assets/sprite-mapping.json - sprawdz czy serwer moze tworzyc katalog data/assets/backups ``` ## Zasada bezpieczenstwa Przed wiekszymi zmianami skopiuj plik: ```text data/assets/sprite-mapping.json ``` Backend robi backup automatycznie, ale kopia reczna przed duzymi zmianami tez jest dobrym pomyslem. --- ## v1.5.0 - sprawdzanie po zapisie w Asset Library Po zapisaniu animacji nie koncz pracy od razu. Zrob tak: ```text 1. Kliknij Zapisz do sprite-mapping.json. 2. Kliknij Odswiez po zapisie. 3. Otworz Asset Library. 4. Wyszukaj nowy spriteId. 5. Sprawdz, czy nie ma czerwonego bledu. 6. Dopiero potem uzyj spriteId w Map Builderze. ``` Jesli Asset Library pokazuje `ANIMATION_MISSING`, to obiekt na mapie chce uzyc animacji, ktorej ten sprite nie ma. Jesli pokazuje `SPRITE_MISSING`, to mapa wskazuje spriteId, ktorego nie ma w mappingu. Jesli pokazuje `UNUSED_SPRITE`, to nie musi byc problem. To znaczy tylko, ze sprite jest gotowy, ale nie zostal jeszcze uzyty na mapie. --- # Dodatek v1.5.4 - klatki wieksze niz jedna kratka Niektore assety maja animacje, w ktorych jedna klatka zajmuje wiecej niz jedna kratke. Przyklad: postac 2x2, wysoka postac 2x3 albo maszyna 4x2. W Animation Builderze ustaw: ```text Bazowa kratka W/H - rozmiar malej kratki assetu, zwykle 16x16. Klatka ma kratek W/H - ile takich kratek ma cala klatka animacji. ``` Przyklady: ```text Postac 2x2: - bazowa kratka 16x16 - klatka 2x2 - anchor bottom-center - footprint 1x1 Maszyna 4x2: - bazowa kratka 16x16 - klatka 4x2 - anchor top-left - footprint 4x2 Drzwi wysokie 1x2: - bazowa kratka 16x16 - klatka 1x2 - anchor bottom-center albo top-left - footprint 1x1 ``` Pelny opis: `docs/MULTITILE_ANIMATION_FRAMES_NON_TECH_GUIDE.md`.