sprite-stacking to otwartoźródłowy skill dla agentów AI autorstwa Daniela White'a. Zamienia cztery widoki obiektu w pixel arcie (z góry, z boku, z przodu i z tyłu) w „sprite stack”: pasek płaskich warstw, które gra rysuje jedna na drugiej, udając obiekt 3D, który można obracać. Działa z Claude Code, Codex, Cursor, OpenCode, Gemini CLI i Pi. Repozytorium powstało 20 listopada 2026 r., a gdy sprawdzaliśmy je 21 listopada 2026 r., miało 187 gwiazdek. Licencja: MIT.

W tym poradniku wyjaśniamy, czym jest sprite stacking, co dodaje skill, jak go zainstalować, czego potrzebuje na wejściu i gdzie ma ograniczenia. Każde polecenie poniżej jest skopiowane z README repozytorium albo z pliku SKILL.md. Pliki przeczytaliśmy 21 listopada 2026 r., ale sami skilla nie uruchamialiśmy, więc opisane wyniki to to, co według dokumentacji powinno się stać.

Czym jest sprite stacking

Sprite stack to obiekt widziany z góry, pocięty na poziome warstwy, jak bochenek krojony od podłogi w górę. Gra rysuje warstwy od dołu do góry. Każdą obraca o ten sam kąt, spłaszcza w pionie zgodnie z nachyleniem kamery i podnosi o 1 piksel nad poprzednią. Efekt wygląda jak mały model wokselowy, który płynnie się obraca, ale to wciąż zwykłe rysowanie 2D: bez silnika 3D, bez siatek, a każdy kąt zostaje w ostrych pikselach.

README mówi wprost, że technika nie jest nowa: „Sprite stacking is a long-standing indie game technique, not invented here.” Skill dodaje do niej wycinanie z czterech widoków i cały workflow dla agenta.

Zwykle najbardziej męczące jest rysowanie warstw. Samochód z 30 warstw to 30 małych obrazków, które muszą do siebie pasować. Skill to omija: ty (albo twój agent) rysujesz cztery zwykłe widoki, a skrypt wycina z nich warstwy.

Co robi skill

README opisuje cztery kroki:

  1. Widoki: arkusz z widokiem z góry, z boku, z przodu i z tyłu, w rzucie prostokątnym, w jednym rzędzie.
  2. Wycinanie: woksel zostaje tylko tam, gdzie pokrywają go wszystkie cztery widoki.
  3. Warstwy: wycięta bryła jest cięta na pasek płaskich warstw, zaczynając od podłoża.
  4. Render: każda warstwa jest obracana, spłaszczana zgodnie z nachyleniem i podnoszona o 1 px.

W folderze skilla są:

  • SKILL.md – instrukcje, które czyta agent: jak przygotować dobry arkusz czterech widoków, lista kontrolna przed cięciem, flagi slicera, pętla renderowania i jej wartości, lista „gotowe, gdy” oraz tabela dawnych błędów z poprawkami.
  • scripts/views_to_slices.py – slicer. Usuwa tło, zdejmuje 1-pikselowe obrysy wokół widoków, sprowadza wszystko do jednej wspólnej palety, wycina warstwy i potrafi zapisać obraz kontrolny oraz samodzielną stronę z podglądem.
  • scripts/viewer.html – podgląd w przeglądarce, który otwiera się też samodzielnie i przyjmuje przeciągnięte paski warstw.
  • references/engines.md – krótkie przepisy dla Canvas i React w przeglądarce, Godot 4, Unity oraz Phasera, Pygame i innych.

Instalacja w Claude Code lub Codex

Jednolinijkowa instalacja z README korzysta z skills CLI, które wymaga Node 22.20 lub nowszego:

npx skills add danielwh2/sprite-stacking

To instaluje skill w bieżącym projekcie. Według README dodaj -g, żeby zainstalować go dla wszystkich projektów, oraz -a claude-code (albo codex, cursor itd.), żeby wybrać agenta.

Druga opcja to skopiowanie folderu skills/sprite-stacking z repozytorium do folderu skilli twojego agenta:

Agent Folder
Claude Code ~/.claude/skills/
Codex, Cursor, OpenCode, Gemini CLI, Pi ~/.agents/skills/

Slicer to skrypt w Pythonie, więc potrzebujesz też Pythona 3 z Pillow i NumPy. Polecenie z README:

pip install pillow numpy

Jak z niego korzystać: o co prosić agenta

Nie wywołujesz skilla po nazwie. Po instalacji po prostu poproś o to, czego chcesz, a agent sam po niego sięgnie. Przykłady z README:

  • „Zrób obracany samochód w pixel arcie.”
  • „Zrób sprite stack z tego arkusza 4 widoków i daj mi obrotówkę.”
  • „Dodaj do mojej gry w Godot pseudo-3D drzewo w pixel arcie.”

SKILL.md każe agentowi wybrać ścieżkę zależnie od tego, co dostanie:

  • Pasek warstw PNG albo eksport warstw z MagicaVoxel: od razu przechodzi do renderowania.
  • Arkusz czterech widoków: sprawdza arkusz, potem go wycina.
  • Tylko prompt albo pomysł: najpierw tworzy arkusz czterech widoków, potem wycina i renderuje.

Jeśli nie masz arkusza, agent użyje narzędzia do generowania obrazów, jeśli je ma, z promptem rozpisanym w SKILL.md. Jeśli nie ma, sam narysuje cztery widoki jako pixel art w krótkim skrypcie Pythona. README ujmuje to prosto: „No image generator? The agent draws the views itself in a short Python script.”

W istniejącej grze SKILL.md każe agentowi najpierw przeczytać twój renderer (silnik, skalę pikseli, sposób rysowania i sortowania sprite'ów) i dopasować do niego stack, nigdy nie dodając drugiego canvasa ani drugiego potoku renderowania.

Czego potrzebuje na wejściu

Arkusz czterech widoków ma ścisłe zasady i większość złych wyników bierze się z ich łamania. Z SKILL.md:

  • Jeden rząd w kolejności TOP, SIDE, FRONT, BACK, na jednolitym białym tle, z wyraźnymi odstępami między widokami.
  • TOP patrzy prosto w dół, a przód obiektu jest skierowany w dół. W SIDE przód jest skierowany w lewo.
  • Ściśle rzut prostokątny: bez perspektywy, bez pochylenia, bez widoku 3/4.
  • Ta sama skala we wszystkich czterech widokach: długość TOP równa długości SIDE, szerokość TOP równa szerokości FRONT i BACK, wysokość SIDE równa wysokości FRONT i BACK.
  • Płaskie wypełnienia kolorem i ostre obrysy. Miękkie, „aerografowe” krawędzie i cienkie 1-pikselowe linie wewnętrzne rozmazują się, gdy warstwy się obracają, a skill radzi narysować je od nowa, zamiast ratować.

Podaje też trzy poziomy rozmiaru:

  • Chunky retro: 15–20 warstw, około 25×48 px, wyświetlane w skali 8–10×.
  • Detailed hi-bit: 26–44 warstwy, od 36×72 do 46×107 px, wystarczy na kratki wentylacyjne, logo i felgi ze szprychami.
  • Showcase / wideo 1080p: 36–56 warstw, od 30×30 do 148×148 px, wyświetlane w skali 4–6×.

Samodzielne uruchomienie slicera

Zwykle slicer uruchamia agent, ale możesz to zrobić sam z katalogu głównego repozytorium poleceniem z README:

python3 skills/sprite-stacking/scripts/views_to_slices.py views.png slices.png \
  --slices 36 --preview check.png --html viewer.html

views.png to twój arkusz czterech widoków, a slices.png to zapisany pasek warstw. Flagi wymienione w README:

  • --slices N: liczba warstw. 15–20 dla stylu chunky, 32–48 dla szczegółowego.
  • --order reading: wymusza kolejność TOP, SIDE, FRONT, BACK. Domyślnie skrypt dopasowuje widoki po proporcjach.
  • --round: wieże, balony i donice wycina okrągłe zamiast kwadratowych.
  • --side-nose right: gdy widok SIDE jest skierowany w prawo.
  • --colours N: rozmiar wspólnej palety; 0 zachowuje wszystkie kolory.
  • --normals path.png: zapisuje dodatkowo pasujący pasek warstw z mapą normalnych.
  • --emissive path.png: zapisuje dodatkowo automatycznie wykrytą maskę świecenia (reflektory, okna, neony).

SKILL.md wymienia jeszcze kilka, m.in. --top-nose (podaj down dla wszystkiego, co nie jest pojazdem), --shade, --bg-tol i --dark-thresh.

check.png pokazuje cztery wyodrębnione widoki, cztery kąty obrotu i widok rozłożony. Skill każe agentowi obejrzeć go, zanim napisze jakikolwiek kod gry.

Podgląd

--html zapisuje samodzielną stronę. Według README ma obrotówkę, tryb Scene z proceduralnymi rekwizytami, skan warstw, widok rozłożony i tryb Play, w którym można jeździć klawiszami WASD lub strzałkami. Do tego porę dnia, przeciągane słońce z cieniami, deszcz i śnieg oraz przycisk eksportu, który wypieka arkusz sprite'ów PNG w 16 kierunkach. To ostatnie przydaje się, jeśli twój silnik chce po prostu zwykłych sprite'ów kierunkowych.

Jak wstawić to do gry

Pętla renderowania wszędzie jest taka sama: dla każdej warstwy od podłoża w górę obróć ją wokół środka, przeskaluj oś y o wartość spłaszczenia, podnieś o jej indeks razy odstęp, przyciągnij do pełnych pikseli i rysuj z filtrowaniem najbliższego sąsiada. SKILL.md podaje wartości domyślne: odstęp 1.0 i spłaszczenie 0.75 dla pochylonej kamery z góry (1.0 to widok prosto w dół). references/engines.md ma gotową funkcję dla Canvas 2D i skrypt Node2D dla Godot 4, a także uwagi dla Unity (jeden SpriteRenderer na warstwę, filtr Point) oraz dla Phasera i Pygame.

Dwie wskazówki ze skilla mają znaczenie dla wydajności i wyglądu. Sortuj całe stacki według punktu styku z podłożem i nigdy nie przeplataj warstw dwóch obiektów. A statyczne stacki wypiekaj do zwykłych sprite'ów przy ładowaniu gry: skill zauważa, że 200 drzew po 30 warstw to 6000 wywołań rysowania na klatkę.

Ograniczenia

Pochodzą z listy kontrolnej skilla i jego tabeli dawnych błędów:

  • Ukryte wnęki się wypełniają. Wycinanie zostawia tylko to, co pokrywają wszystkie cztery sylwetki, więc paka pick-upa albo pusty łuk, których żaden widok nie pokazuje, wychodzą pełne. Nawisy, przez które w widoku z boku widać prześwit, np. uniesione tylne skrzydło, zostają. Wnęki trzeba poprawić ręcznie po wycięciu.
  • Okrągłe części wychodzą kwadratowe, chyba że widok z góry ma piksel-artowe koło albo podasz --round, gdy okrągła część jest węższa od podstawy.
  • Części o szerokości 1 px migają, gdy stack się obraca. Słupki, liny i anteny muszą mieć co najmniej 2 px szerokości; slicer wypisuje ostrzeżenie.
  • Wystające elementy zamieniają się w półki. Coś wystającego ze ściany, np. skrzynka na kwiaty albo szyld, wycina półkę wzdłuż całej ściany. Małe elementy maluj płasko.
  • Zamknięte prześwity wychodzą pełne. Tło całkowicie zamknięte wewnątrz widoku (między nogami, płetwami czy linami) jest traktowane jak część obiektu. Każda szczelina musi sięgać krawędzi swojego widoku.
  • Obiekty poza środkiem się chwieją. Stack obraca się wokół środka swojego prostokąta ograniczającego, więc wyśrodkuj obiekt w widokach.
  • Tylko pixel art. Technika i slicer są zrobione dla małych sprite'ów z płaskim cieniowaniem. To nie jest sposób na prawdziwy model 3D do gry w three.js czy Unity 3D.

Licencja

Repozytorium jest na licencji MIT (copyright 2026 Daniel White), co widać na GitHubie i w pliku LICENSE. Możesz go używać, zmieniać i dołączać do komercyjnych projektów, pod warunkiem że zachowasz informację o prawach autorskich i licencji razem z kopiami kodu. README nie mówi nic o licencji sprite'ów, które nim zrobisz.

FAQ

Czym jest sprite stacking?

To sposób na udawanie 3D w grze 2D. Obiekt jest zapisany jako pasek płaskich warstw widzianych z góry, a gra rysuje je od dołu do góry, każdą obróconą o ten sam kąt i podniesioną o 1 piksel. Wygląda to jak mały obracający się model wokselowy, a jednocześnie pozostaje ostrym pixel artem.

Czy skill sprite-stacking jest darmowy?

Tak. Jest open source na licencji MIT. Potrzebujesz tylko Pythona 3 z Pillow i NumPy oraz Node 22.20 lub nowszego, jeśli instalujesz przez npx skills. Subskrypcja albo koszty API twojego agenta AI to osobna sprawa.

Czy działa z Claude Code i Codex?

Tak. Oba są wymienione w README. Zainstaluj go poleceniem npx skills add danielwh2/sprite-stacking (z -a claude-code albo -a codex, żeby wybrać agenta) albo skopiuj skills/sprite-stacking do ~/.claude/skills/ dla Claude Code lub do ~/.agents/skills/ dla Codex.

Czy potrzebuję generatora obrazów?

Nie. Jeśli twój agent go ma, skill daje mu prompt do arkusza czterech widoków. Jeśli nie, agent sam narysuje widoki w krótkim skrypcie Pythona. Możesz też dać mu narysowany przez siebie arkusz, pasek warstw albo eksport warstw z MagicaVoxel.

Czy mogę użyć wyniku w Godot, Unity albo Phaserze?

Tak. references/engines.md zawiera skrypt dla Godot 4, uwagi dla Unity, funkcję Canvas 2D dla przeglądarki i Reacta oraz ogólną pętlę dla Phasera i Pygame. Podgląd potrafi też wyeksportować arkusz sprite'ów PNG w 16 kierunkach dla silników, które chcą zwykłych sprite'ów.

Dlaczego części mojego sprite'a wychodzą pełne albo kwadratowe?

Slicer zostawia woksel tylko tam, gdzie pokrywają go wszystkie cztery widoki. Wnęki ukryte przed każdym widokiem się wypełniają, okrągłe części potrzebują koła w widoku z góry albo flagi --round, a prześwity całkowicie zamknięte w widoku wychodzą pełne. Poprawki znajdziesz w sekcji „Ograniczenia” wyżej.

Powiązane poradniki

Źródła

Sprawdzone 21 listopada 2026 r.: README danielwh2/sprite-stacking, SKILL.md, references/engines.md, LICENSE oraz dane repozytorium na GitHubie (utworzone 20 listopada 2026 r.; 187 gwiazdek 21 listopada 2026 r.).

Zrobiłeś grę z samochodami albo rekwizytami w technice sprite stacking? Zgłoś ją do VibeGamer.