# Postacie, kierunki ruchu i animowane obiekty — poradnik nietechniczny Ten dokument jest dla osoby, która ma gotowe grafiki i chce je wykorzystać w grze: postać patrzy w dół, w lewo, w prawo, w górę; podczas chodzenia zmienia klatki; drzwi mogą mieć klatki `closed`, `opening`, `open`. ## 1. Najważniejsze pojęcia **Sprite** to grafika obiektu albo postaci. Może być statyczny, czyli jedna klatka, albo animowany, czyli kilka klatek. **Tileset / spritesheet** to duża grafika PNG, na której jest dużo małych obrazków. Asset Picker pomaga wybrać współrzędne z tej dużej grafiki. **Klatka animacji** to pojedynczy obrazek w animacji. Na przykład postać idąca w dół może mieć 3 klatki: lewa noga, środek, prawa noga. **Kierunek** mówi, którą animację wybrać: `walkDown`, `walkLeft`, `walkRight`, `walkUp`. ## 2. Jak gra wybiera animację postaci Silnik w v1.3.0 potrafi wybrać animację gracza na podstawie kierunku ruchu. Kiedy gracz idzie: - w dół: gra szuka `walkDown`, - w lewo: gra szuka `walkLeft`, - w prawo: gra szuka `walkRight`, - w górę: gra szuka `walkUp`. Kiedy gracz stoi: - patrzy w dół: gra szuka `idleDown`, - jeżeli nie ma `idleDown`, bierze statyczny sprite. Jeżeli animacji nie ma, nic się nie wybucha. Gra rysuje statyczną grafikę tak jak wcześniej. ## 3. Najprostszy układ postaci Najwygodniejszy układ spritesheeta postaci: ```text wiersz 0: chodzenie w dół wiersz 1: chodzenie w lewo wiersz 2: chodzenie w prawo wiersz 3: chodzenie w górę ``` Przykład, jeśli klatka ma 48x48 px: ```text kolumna 0 kolumna 1 kolumna 2 [ dół 1 ] [ dół 2 ] [ dół 3 ] [ lewo1 ] [ lewo2 ] [ lewo3 ] [ praw1 ] [ praw2 ] [ praw3 ] [ góra1 ] [ góra2 ] [ góra3 ] ``` ## 4. Jak dodać animowaną postać Otwierasz: ```text admin/tools/asset-picker.html ``` albo: ```text admin/tools/animation-preview.html ``` Wybierasz plik PNG z postaciami i sprawdzasz, ile pikseli ma jedna klatka. W wielu paczkach RPG Maker to będzie 48x48. Do `data/assets/sprite-mapping.json` dodajesz sprite w takim stylu: ```json { "sprites": { "player_office_worker_01": { "tilesetId": "modern_interiors_characters", "frameWidth": 48, "frameHeight": 48, "frameDurationMs": 140, "offsetX": -4, "offsetY": -18, "destW": 40, "destH": 40, "animations": { "idleDown": [ { "tileX": 1, "tileY": 0 } ], "walkDown": [ { "tileX": 0, "tileY": 0 }, { "tileX": 1, "tileY": 0 }, { "tileX": 2, "tileY": 0 } ], "walkLeft": [ { "tileX": 0, "tileY": 1 }, { "tileX": 1, "tileY": 1 }, { "tileX": 2, "tileY": 1 } ], "walkRight": [ { "tileX": 0, "tileY": 2 }, { "tileX": 1, "tileY": 2 }, { "tileX": 2, "tileY": 2 } ], "walkUp": [ { "tileX": 0, "tileY": 3 }, { "tileX": 1, "tileY": 3 }, { "tileX": 2, "tileY": 3 } ] } } } } ``` ## 5. Co oznaczają pola ```text tilesetId z którego dużego PNG bierzemy postać frameWidth szerokość jednej klatki, np. 48 frameHeight wysokość jednej klatki, np. 48 frameDurationMs szybkość animacji; 120–180 zwykle jest OK offsetX przesunięcie w poziomie offsetY przesunięcie w pionie destW / destH jak duża ma być postać w grze animations lista animacji ``` Najczęstsza korekta to `offsetY`. Jeśli postać wygląda, jakby stała za nisko albo za wysoko, popraw `offsetY`. ## 6. Jak ustawić animowaną postać jako gracza W scenariuszu albo mapie możesz wskazać sprite gracza: ```json { "playerSpriteId": "player_office_worker_01" } ``` Jeżeli pole jest w mapie, dotyczy tej mapy. Jeżeli jest w scenariuszu, dotyczy scenariusza. Praktyczna zasada: dla różnych scenariuszy lepiej ustawiać `playerSpriteId` w scenariuszu. ## 7. Jak dodać animowanego NPC NPC może mieć statyczny sprite albo animowany sprite. W mapie przy obiekcie ustawiasz: ```json { "id": "NPC_IT_ADMIN", "type": "npc", "label": "IT Admin", "spriteId": "npc_it_admin_animated" } ``` Jeżeli sprite ma animację `idleDown`, gra może ją wykorzystać jako spokojną animację stania. Na razie NPC nie chodzą samodzielnie, więc nie potrzebują `walkLeft` itd., ale można je dodać na przyszłość. ## 8. Animowane drzwi Drzwi mogą być zwykłym tile albo obiektem. Jeżeli mają być animowane i/lub zamykane/otwierane warunkiem, rób je jako **obiekt**. Przykładowy sprite drzwi: ```json { "sprites": { "door_server_room_animated": { "tilesetId": "office_room_builder", "frameWidth": 16, "frameHeight": 16, "frameDurationMs": 120, "animations": { "closed": [ { "tileX": 4, "tileY": 11 } ], "opening": [ { "tileX": 4, "tileY": 11 }, { "tileX": 5, "tileY": 11 }, { "tileX": 6, "tileY": 11 } ], "open": [ { "tileX": 6, "tileY": 11 } ] } } } } ``` W mapie obiekt drzwi: ```json { "id": "OBJ_SERVER_ROOM_DOOR", "label": "Drzwi do serwerowni", "type": "door", "x": 12, "y": 5, "spriteId": "door_server_room_animated", "state": "closed", "blocksMovement": true, "interactionTile": { "x": 12, "y": 6 }, "animationsByState": { "closed": "closed", "opening": "opening", "open": "open", "locked": "closed" } } ``` ## 9. Drzwi otwierane po akcji Flow: ```text 1. Drzwi są closed albo locked. 2. Gracz wykonuje akcję, np. u IT Admina. 3. Akcja daje dostęp albo zmienia stan drzwi. 4. Gracz klika drzwi. 5. Akcja drzwi zmienia stan na open. 6. Drzwi przestają blokować ruch. ``` W Scenario Editorze ustawiasz akcję przy drzwiach: ```text Akcja: Otwórz drzwi Wymaganie: wykonano ACT_GET_SERVER_ROOM_ACCESS Efekt: OBJECT_STATE_CHANGED -> OBJ_SERVER_ROOM_DOOR -> open ``` W wersji v1.3.0 silnik potrafi dobrać grafikę/animację do stanu obiektu przez `animationsByState`. Sama fizyczna zmiana blokowania drzwi nadal musi być pilnowana w logice stanu/efektów. Jeśli drzwi mają naprawdę zacząć przepuszczać po otwarciu, w kolejnej wersji warto dodać automatyczne przeliczanie kolizji po zmianie stanu obiektu. ## 10. Jak testować animacje Wejdź do: ```text admin/tools/animation-preview.html ``` Tam możesz: - wybrać `spriteId`, - wybrać animację, - zobaczyć, czy klatki lecą poprawnie. Jeżeli postać „skacze”, popraw `offsetX`, `offsetY`, `destW`, `destH`. Jeżeli animacja pokazuje złe obrazki, najpewniej złe są `tileX` i `tileY`. ## 11. Zasady dla nietechnicznej osoby 1. Najpierw znajdź w PNG pierwszy obrazek animacji. 2. Sprawdź, jak duża jest jedna klatka: 16x16, 32x32, 48x48. 3. Ustal wiersze: dół, lewo, prawo, góra. 4. Dodaj sprite mapping. 5. Sprawdź w Animation Preview. 6. Dopiero potem użyj go w mapie/scenariuszu. Nie zaczynaj od przepisywania 200 klatek. Najpierw zrób jedną postać i jedne drzwi. Jak działa, kopiujesz schemat. --- # v1.3.2 - chodzace NPC i animacje obiektow stojacych Od v1.3.2 silnik wspiera dwa dodatkowe przypadki: 1. NPC, ktorzy sami chodza po mapie. 2. Obiekty stojace, ktore animuja sie w miejscu, np. maszyny, serwery, monitory, lampy. ## Chodzacy NPC NPC moze miec pole `autoMove`. Przyklad patrolu: ```json "autoMove": { "enabled": true, "mode": "patrol", "speedMs": 850, "pingPong": true, "autoInteractionTile": true, "path": [ { "x": 7, "y": 6 }, { "x": 10, "y": 6 }, { "x": 10, "y": 9 }, { "x": 7, "y": 9 } ] } ``` Przyklad losowego krecenia sie w okolicy: ```json "autoMove": { "enabled": true, "mode": "wander", "radius": 4, "speedMs": 1000, "autoInteractionTile": true } ``` Dla chodzacego NPC najlepiej nie ustawiac stalego `interactionTile`. Ustaw `autoInteractionTile: true`, wtedy gra sama liczy kratki obok aktualnej pozycji NPC. ## Animowana maszyna albo monitor Obiekt stojacy moze miec `animation`. ```json { "id": "OBJ_LINE_A", "type": "machine", "spriteId": "machine_line_animated", "animation": "running", "blocksMovement": true } ``` W sprite-mapping ten sprite powinien miec `animations.running` z kilkoma klatkami. Jesli maszyna ma stan `warning`, mozesz zrobic osobna animacje `warning` i przelaczac ja efektem `setObjectState`. Pelny opis nietechniczny jest w: ```text NPC_AND_STATIC_ANIMATION_NON_TECH_GUIDE.md ``` --- # v1.4.0 - tworzenie animacji bez recznego JSON-a Od v1.4.0 animacje najlepiej tworzyc w: ```text /admin/tools/animation-builder.html ``` Najprostszy flow: ```text 1. Wgraj nowe pliki do assets/vendor. 2. Kliknij Odswiez assets/vendor. 3. Wybierz obrazek. 4. Ustaw rozmiar klatki. 5. Kliknij klatki animacji. 6. Nazwij animacje, np. walkDown albo running. 7. Zapisz do sprite-mapping.json. 8. Kliknij Odswiez po zapisie. 9. Uzyj spriteId w Map Builderze. ``` Dla postaci uzywaj nazw: ```text idleDown, idleUp, idleLeft, idleRight walkDown, walkUp, walkLeft, walkRight ``` Dla maszyn i obiektow stojacych: ```text idle, running, warning, broken, offline ``` Dla drzwi: ```text closed, opening, open, locked ``` Szczegolowy poradnik jest tutaj: ```text docs/ANIMATION_BUILDER_NON_TECH_GUIDE.md ``` --- # v1.5.4 - multitile animation frames The animation format now supports frames larger than one base tile. New sprite fields: ```json { "baseTileWidth": 16, "baseTileHeight": 16, "frameTileW": 2, "frameTileH": 3, "frameWidth": 32, "frameHeight": 48, "anchor": "bottom-center", "footprint": { "w": 1, "h": 1 } } ``` Use this for character sheets where one character frame uses a rectangle such as 2x2 or 2x3 tiles. Machines can use a larger footprint, for example 4x2.