# Live2D od A do Z: Wise One (ChatGPT + Cubism Editor PRO)

Kompletny proces: od jednego obrazka wygenerowanego w ChatGPT, przez warstwowy plik PSD,
po ruszającą się postać Live2D na stronie ariku.pl i w Lunecie. Pisany na żywo przy pierwszym
modelu — **Wise One v1** (postać od pasa w górę), październik 2026.

Poradnik ma dwie części:

- **Część I — dla początkujących.** Co to jest Live2D, jak wygląda cały proces i jak krok po kroku
  zriggować gotowy PSD w Cubism Editorze. Wystarczy, żeby zrobić pierwszy model.
- **Część II — dla zaawansowanych.** Wszystkie szczegóły: jak przygotować „Live2D-ready” PSD z obrazków
  z ChatGPT (ComfyUI See-through + skrypty Pythona), co daje wersja PRO, fizyka, animacje, eksport,
  osadzenie w przeglądarce i w Lunecie (Tauri), licencje, pułapki — i jak to faktycznie przebiegało u nas.

> **Program:** Live2D Cubism Editor 5.3 (PRO, trial 42 dni od 2026-10-17).
> **Plik wejściowy:** `C:\wise-one\wise-one-v1-3x.psd` (3072×4608 px).
> **Wynik:** `C:\wise-one\wise-one-v1.cmo3` (projekt) i `C:\wise-one\runtime\` (pliki dla strony).
> **Źródła pipeline'u:** repo Luneta, katalog `assets/design/live2d/` (README, `scripts/`, `workflows/`,
> `chatgpt/PROMPTY.md`). Zadania: Vikunja, projekt 15, epik 680.

---

# CZĘŚĆ I — DLA POCZĄTKUJĄCYCH

## 1. Co w ogóle robimy

Live2D to nie animacja 3D ani film. Bierzemy **płaski rysunek pocięty na warstwy** (oczy, usta, włosy,
ciało…) i każdą warstwę zamieniamy w gumową siatkę, którą da się wyginać. Potem uczymy program,
jak ma wyglądać postać przy różnych ustawieniach suwaków („głowa w lewo”, „oczy zamknięte”,
„usta otwarte”). Strona internetowa porusza tymi suwakami w czasie rzeczywistym — i postać „żyje”.

### Cały proces w 7 krokach

| # | Etap | Narzędzie | Kto / ile czasu u nas |
|---|---|---|---|
| 1 | **Obraz bazowy** postaci | ChatGPT (generowanie obrazów) | właściciel, kilka podejść |
| 2 | **Warianty** (zamknięte oczy, usta A/I/U/E/O, miny, części zasłonięte) | ChatGPT — edycje 1:1 obrazu bazowego | właściciel, ~20 edycji |
| 3 | **Pocięcie na warstwy** | ComfyUI + See-through + skrypty Pythona | automat na ariku-pc |
| 4 | **Plik PSD** gotowy pod Live2D | skrypt `build_psd.py` | automat |
| 5 | **Rigging** (siatki, deformery, parametry) | Live2D Cubism Editor | ręcznie — to jest serce pracy |
| 6 | **Eksport** dla przeglądarki | Cubism Editor → `.moc3` + `.model3.json` | kilka kliknięć |
| 7 | **Osadzenie** na stronie / w Lunecie | pixi.js + pixi-live2d-display | kod |

Jeśli dopiero zaczynasz — **etapy 1–4 możesz pominąć**, bo PSD Wise One jest już gotowy.
Zaczynasz od kroku 5 (sekcja 4 poniżej).

## 2. Słowniczek (5 pojęć, które trzeba znać)

| Pojęcie | Co to jest |
|---|---|
| **ArtMesh** | Jedna warstwa z PSD zamieniona w „gumową” siatkę trójkątów. Ruszając punktami siatki, wyginamy obrazek. |
| **Deformer** | Niewidzialny „uchwyt” na grupie ArtMeshy. *Warp* wygina jak siatka, *Rotation* obraca wokół punktu. Deformery można zagnieżdżać (głowa w ciele). |
| **Parametr** | Suwak, np. `ParamAngleX` = obrót głowy w lewo/prawo. Program na stronie steruje właśnie suwakami. |
| **Keyform (klucz)** | Zapamiętany kształt dla konkretnej wartości suwaka (np. głowa przy −30 i przy +30). Pomiędzy kluczami Cubism sam liczy płynne przejście. |
| **Clipping (maska)** | Warstwa widoczna tylko w obrysie innej warstwy — tęczówka nie wychodzi poza białko oka. |

**Złota zasada:** nazwy parametrów zostawiamy **standardowe** (`ParamAngleX`, `ParamEyeLOpen`…).
Dzięki temu mruganie, oddech, patrzenie za kursorem i ruch ust działają na stronie bez pisania kodu.

## 3. FREE czy PRO?

Cubism Editor ma wersję **FREE** (darmową, z limitami) i **PRO** (płatną, z 42-dniowym trialem).

- FREE wystarczy na mały model, ale ma limity liczby części, parametrów i rozmiaru tekstury —
  nasz PSD (dużo warstw, wariantów i tekstura 4096) w nie wchodzi. Aktualne limity sprawdź w oficjalnym
  porównaniu wersji na stronie Live2D.
- PRO daje m.in. **automatyczne generowanie mimiki głowy** (Automatic Generation of Facial Motion),
  szablony (Templates), większe tekstury i więcej elementów. Robimy na **trialu PRO** — trzeba zdążyć
  w 42 dni albo potem zostać z projektem otwieranym w trybie FREE (da się go oglądać, nie zawsze edytować).

> Plan na trial: tydzień 1 — rig twarzy i eksport, który działa na stronie. Reszta — szlify.

## 4. Pierwsze uruchomienie

1. Uruchom `C:\Program Files\Live2D Cubism 5.3\CubismEditor5.exe`.
2. Jeśli pojawi się okno o nowej wersji — kliknij **Cancel** (po japońsku *キャンセル*).
   **Nie klikaj „Open” (*開く*)** — to zamyka edytor i otwiera stronę pobierania. Wersja 5.3 wystarczy.
3. Interfejs jest już przełączony na angielski. (Gdyby nie był: ustawienia programu → język → English,
   potem restart edytora.)
4. Przy pierwszym uruchomieniu wybierz licencję **PRO (trial)**.

## 5. Co jest w naszym PSD

Warstwy (od góry do dołu), wszystkie w pełnym rozmiarze płótna 3072×4608:

| Grupa | Warstwy | Do czego |
|---|---|---|
| `~variants` (ukryta) | `~eyelid_closed_l/r`, `~eyes_left/right/up/down`, `~brow_surprised/angry/sad_l/r`, `~face_surprised/angry/sad/wink/blush`, `~mouth_A/I/U/E/O`, `~mouth_smile`, `~mouth_pout`, `~ears_flat_l/r` | **Wzorce** do kluczy: zamknięte oczy, miny, kształty ust. Nie są to stałe części postaci. |
| `front_hair` | `front_hair` | grzywka (jeden blok) |
| `ears` | `ears_l`, `ears_r` | uszy |
| `eyes` | `eyebrow_l/r`, `eyelash_l/r`, `irides_l/r`, `eyewhite_l/r` | brwi, rzęsy, tęczówki, białka |
| `head` | `mouth`, `nose`, `face`, `neckwear`, `head_bald` | twarz i „łysa” głowa pod włosami |
| `body` | `hand_l/r`, `sleeve_l/r`, `topwear`, `neck` | ciało |
| `back_hair` | `back_hair` | włosy z tyłu |

> Końcówki `_l` / `_r` to lewa / prawa strona **postaci** (nie nasza).
> Warstwy pod spodem (np. `head_bald`, skóra pod grzywką) są **dorysowane** — dzięki temu przy ruchu
> nie widać dziur.

## 6. Import PSD

1. Przeciągnij `wise-one-v1-3x.psd` do okna edytora (albo **File → Open** i wybierz PSD).
   Cubism utworzy nowy model, a każda warstwa stanie się ArtMeshem.
2. **Sprawdź paletę Parts** (lewa strona): czy jest grupa `~variants` z ukrytymi warstwami.
   Jeśli jej nie ma — zatrzymaj się, bez niej nie zrobimy mrugania ani min.
3. Od razu zapisz: **File → Save As** → `C:\wise-one\wise-one-v1.cmo3`.
   Od teraz **Ctrl+S po każdym etapie**.

> Nowy model ma już gotowy zestaw standardowych parametrów (paleta **Parameters** po prawej).
> Nie twórz ich od nowa — używaj tych, które są.

## 7. Siatki (Auto Mesh)

Siatka decyduje, jak gładko obrazek się wygina. Więcej punktów = ładniejszy ruch, ale wolniej.

1. Zaznacz wszystkie ArtMeshe (klik w obszar roboczy, **Ctrl+A**).
2. Uruchom **automatyczne generowanie siatki** (menu *Modeling → Mesh*, ikonka siatki na pasku).
   Ustawienie standardowe wystarczy dla ciała i włosów.
3. Dla **oczu, ust i brwi** powtórz z gęstszym ustawieniem (mniejszy rozstaw punktów) —
   te części ruszają się najbardziej i są małe.

## 8. Deformery (szkielet)

Układ, który chcemy dostać (od zewnątrz do środka):

```
Body (ruch ciała, ParamBodyAngleX/Y/Z)
 ├─ Breath (oddech, ParamBreath) ── topwear, sleeve_l/r, hand_l/r
 ├─ neck, back_hair
 └─ Head (obrót głowy, ParamAngleX/Y/Z) ── head, eyes, ears, front_hair
```

### Szybka droga (PRO): automatyczna mimika

1. Zaznacz części głowy.
2. Uruchom **Automatic Generation of Facial Motion** (menu *Modeling*).
   Program sam tworzy deformery głowy i klucze dla `ParamAngleX/Y/Z`.
3. Poruszaj suwakami `ParamAngleX` i `ParamAngleY` — głowa ma się obracać bez dziur i rozjazdów.
4. Jeśli narzędzie nie rozpozna naszych warstw, robimy to ręcznie (niżej).

### Ręcznie

1. Zaznacz ArtMeshe głowy → **Create Rotation Deformer** → nazwij `Head`. Punkt obrotu ustaw na szyi.
2. Wybierz `ParamAngleZ`, kliknij **Add 3 keys** (−30 / 0 / +30), na skrajnych kluczach przekręć deformer.
3. Dla `ParamAngleX/Y` dodaj nad głową **Warp Deformer** i na skrajnych kluczach lekko „przesuń” twarz
   w stronę obrotu (bliższa strona szersza, dalsza węższa).
4. Tak samo deformer `Body` dla `ParamBodyAngleX` (zakres ±10 — ciało rusza się mniej niż głowa).

## 9. Parametry krok po kroku

Schemat zawsze ten sam: **zaznacz obiekt → wybierz parametr → Add 2 keys / Add 3 keys →
ustaw suwak na skraj → zmień kształt / przezroczystość**.

### Mruganie: `ParamEyeLOpen`, `ParamEyeROpen` (0 = zamknięte, 1 = otwarte)

- Przy **1**: widoczne `eyewhite`, `irides`, `eyelash`; `~eyelid_closed_l` niewidoczna.
- Przy **0**: `eyewhite`, `irides`, `eyelash` przezroczyste (opacity 0), `~eyelid_closed_l` widoczna.
- Najprostsza metoda dla pierwszego modelu to właśnie **podmiana przez przezroczystość**.
  Ładniejsza (Część II): przy 0 zgnieść rzęsy siatką w kreskę.
- Powtórz dla prawego oka z warstwami `_r`.

### Patrzenie: `ParamEyeBallX`, `ParamEyeBallY` (−1 … +1)

1. Najpierw maska: zaznacz `irides_l` → w **Inspectorze** w polu **Clipping** wpisz ID ArtMesha `eyewhite_l`.
   To samo dla `irides_r` ← `eyewhite_r`. Teraz tęczówka nie wyjdzie poza białko.
2. Dodaj 3 klucze i przesuń tęczówki o tyle pikseli (wyliczone z `wise-one-v1-3x-gaze.json`, już ×3):

| | w lewo (X=−1) | w prawo (X=+1) | w górę (Y=+1) | w dół (Y=−1) |
|---|---|---|---|---|
| lewe oko (`irides_l`) | ok. −49 px | ok. +53 px | ok. −39 px | ok. +50 px |
| prawe oko (`irides_r`) | ok. −57 px | ok. +44 px | ok. −47 px | ok. +42 px |

   (Wartości „w górę/w dół” to przesunięcie w pikselach obrazka — minus = w górę.)
   Warstwy `~eyes_left/right/up/down` pokazują, jak to ma wyglądać.

### Usta: `ParamMouthOpenY` i `ParamMouthForm`

- `ParamMouthOpenY` (0 = zamknięte, 1 = otwarte): przy 0 widoczne `mouth`, przy 1 — `~mouth_A`
  (albo `~mouth_O`). **To ten suwak porusza ustami, gdy postać „mówi”** (lip-sync).
- `ParamMouthForm` (−1 … +1): −1 = `~mouth_pout`, +1 = `~mouth_smile`.
  `~mouth_I`, `~mouth_E`, `~mouth_U` mogą posłużyć jako kształty pośrednie.

### Oddech: `ParamBreath` (0 … 1)

Na deformerze `Breath`: przy 1 lekko unieś ramiona i tors (kilka pikseli w górę). Mniej znaczy lepiej.

### Dodatki (gdy podstawy działają)

| Parametr | Warstwy | Jak |
|---|---|---|
| `ParamBrowLY/RY`, `ParamBrowLAngle/RAngle`, `ParamBrowLForm/RForm` | `eyebrow_*` ↔ `~brow_surprised/angry/sad_*` | wzorce jako skrajne klucze |
| `ParamCheek` | `~face_blush` | 0–1, sama przezroczystość |
| `ParamEarFlat` (**własny** parametr) | `ears_l/r` ↔ `~ears_flat_l/r` | przy 1 ukryj zwykłe uszy |
| `ParamHairFront`, `ParamHairBack` | `front_hair`, `back_hair` | pod fizykę (sekcja 10) |

## 10. Fizyka włosów (opcjonalnie)

1. Na `front_hair` i `back_hair` dodaj klucze dla `ParamHairFront` / `ParamHairBack`
   (włosy lekko wychylone w lewo przy −1 i w prawo przy +1).
2. Otwórz ustawienia fizyki (menu *Modeling → Physics*). Wejście: `ParamAngleX`, `ParamBodyAngleX`;
   wyjście: `ParamHairFront`, `ParamHairBack`. Sprawdź podglądem — włosy mają „dobiegać” za głową.
3. Uwaga: grzywka jest w v1 jednym kawałkiem, więc kołysze się cała naraz. Pasma rozdzielimy w v2.

## 11. Miny i animacje

- **Miny (`.exp3.json`)**: `surprised`, `angry`, `sad` (brwi + `~face_*`), `wink`, `blush`.
  Każda mina to zapis kilku suwaków naraz.
- **Animacje (`.motion3.json`)**: `Idle` — spokojny oddech i delikatny ruch głowy, odtwarzany w pętli.
  Robi się je w trybie **Animation** (przełącznik u góry okna) na osi czasu.

## 12. Eksport na stronę

1. Ustaw grupy specjalne (żeby strona wiedziała, czym mrugać i ruszać ustami):
   - **EyeBlink** = `ParamEyeLOpen`, `ParamEyeROpen`
   - **LipSync** = `ParamMouthOpenY`

   W 5.3 robi się to w ustawieniach *Eye Blink / Lip Sync* (menu *Modeling*). Jeśli nazwa jest inna,
   szukaj pozycji ze słowem „Eye Blink”.
2. **File → Export For Runtime → Export as moc3 file**:
   - rozmiar tekstury **4096** (dla Lunety wystarczy 2048),
   - zaznacz eksport fizyki i `model3.json`,
   - katalog: `C:\wise-one\runtime\`.
3. Miny i animacje eksportujemy osobno (z trybu Animation) do tego samego katalogu.
4. W katalogu powinny się znaleźć: `*.moc3`, `*.model3.json`, `*.physics3.json`, tekstury `*.png`,
   `*.exp3.json`, `*.motion3.json`.
5. Gotowe pliki odbiera ariku-pc (scp z `C:\wise-one\runtime\`) i wstawia na ariku.pl / do Lunety.

## 13. Najczęstsze problemy

| Objaw | Przyczyna | Co zrobić |
|---|---|---|
| Edytor zamknął się przy starcie | kliknięto „Open” w oknie aktualizacji | uruchom ponownie, wybierz **Cancel** |
| Brak grupy `~variants` | ukryte warstwy nie weszły przy imporcie | sprawdź import PSD, nie idź dalej |
| Tęczówka wychodzi poza oko | brak clippingu | `irides_*` → Inspector → Clipping = `eyewhite_*` |
| Dziury przy obrocie głowy | za mało siatki / za duży zakres | gęstsza siatka, mniejszy wychył kluczy |
| Na stronie postać nie mruga | brak grupy EyeBlink | sekcja 12.1 i ponowny eksport |
| Usta nie ruszają się przy mowie | brak grupy LipSync albo inna nazwa parametru | parametr musi się nazywać `ParamMouthOpenY` |

---

# CZĘŚĆ II — DLA ZAAWANSOWANYCH

## 14. Architektura pipeline'u i podział ról

Decyzja z 2026-10-17: każde narzędzie robi to, w czym jest najlepsze, a człowiek zatwierdza każdy etap.

| Co | Narzędzie | Dlaczego tak |
|---|---|---|
| Obraz bazowy i **edycje 1:1** (oczy, usta, brwi, uszy, części zasłonięte) | **ChatGPT** (generowanie/edycja obrazów), prompty w `chatgpt/PROMPTY.md` | najlepiej trzyma styl i pozę przy edycji; właściciel pobiera wyniki do `~/Downloads` |
| **Maski warstw i głębia** | **ComfyUI + See-through** (`scripts/comfy_run.py`, workflowy w `workflows/`) | rozkłada postać anime na semantyczne warstwy razem z częściami zasłoniętymi |
| **Piksele warstw, poprawki, złożenie, PSD** | skrypty Pythona (`scripts/`), venv `/mnt/nvme/ai/comfy-venv` | deterministyczne, powtarzalne, sprawdzalne liczbowo |
| **Rig** | Cubism Editor 5.3 PRO, ręcznie | siatek, deformerów, kluczy i fizyki nie da się sensownie zautomatyzować |
| **Runtime** | pixi.js 6 + pixi-live2d-display 0.4 + Cubism Core | stabilny, przetestowany stos dla Cubism 4/5 `.moc3` |

Pliki robocze leżą poza gitem (`/mnt/nvme/ai/wise-one/` na ariku-pc); `assets/design/` w Lunecie
również nie jest commitowany bez prośby właściciela.

### Bramki (G) — bez akceptu nie idziemy dalej

| Etap | Wynik | Bramka |
|---|---|---|
| **E1** baza | jedna postać, bez tekstu i tła, oczy w pełni otwarte, usta zamknięte | **zamrożona** — od teraz wszystkie edycje robimy od niej |
| **E2** edycje ChatGPT | ~20 wariantów 1:1 | każda edycja oceniona: sylwetka bez zmian? |
| **E3** See-through | warstwy na pełnym płótnie | kontaktówka warstw |
| **E4** czyszczenie | poprawione twarz, szyja, tors, rękawy, łysa głowa | `compose_check.py`: złożenie ≈ baza |
| **E5** ruch i mimika | warianty, tęczówki, powieki, brwi, usta, uszy, `gaze.json` | kontaktówka + podgląd |
| **E6** PSD | `wise-one-v1-3x.psd` 3072×4608 | import w Cubism, `~variants` obecna |
| **E7** rig | `.cmo3` + eksport runtime | test na stronie |

Do przeglądu każdej bramki: `contact_sheet.py` (kontaktówka warstw na szachownicy) + composite i `diff.png`.

## 15. ChatGPT — obraz bazowy i edycje

### Obraz bazowy (E1) — wymagania

- **Jedna** postać, frontalnie lub lekko 3/4, kadr od pasa w górę (v1), bez tekstu, logo i tła
  (jednolite tło, najlepiej jasne/neutralne — łatwiej wyciąć).
- **Oczy szeroko otwarte, usta zamknięte, neutralna mina.** To stan „0” wszystkich parametrów.
- Ręce **nie zasłaniają** twarzy ani tułowia; włosy nie przecinają oczu (grzywka może zakrywać brwi
  częściowo, ale wtedy brwi trzeba osobno dorysować).
- Czysty, kreskówkowy styl z wyraźnym konturem — See-through radzi sobie z nim najlepiej.
- Po akceptacji baza jest **zamrożona**. Każda późniejsza poprawka bazy unieważnia wszystkie edycje.

### Edycje 1:1 (E2) — reguła numer jeden

Każda edycja ma zmieniać **tylko jedną rzecz**. Szablon promptu, którego się trzymamy:

```
Edytuj załączony obraz. Zmień TYLKO: <co dokładnie>.
Kadr, poza, proporcje, styl, kolory, oświetlenie, tło i wszystkie pozostałe szczegóły
mają pozostać identyczne piksel w piksel. Nie przesuwaj, nie skaluj, nie poprawiaj niczego innego.
```

Lista edycji, które robiliśmy (pełne prompty: `chatgpt/PROMPTY.md` w repo Lunety):

| Grupa | Edycje | Po co |
|---|---|---|
| Oczy | zamknięte powieki (edit-01), spojrzenie w lewo / prawo / górę / dół | mruganie, zakresy `ParamEyeBall*`, `gaze.json` |
| Usta | A, I, U, E, O, uśmiech, „dzióbek” (pout) | lip-sync i `ParamMouthForm` |
| Brwi / twarz | zdziwienie, złość, smutek, mrugnięcie, rumieniec | miny `.exp3.json` |
| Uszy | uszy położone płasko | własny `ParamEarFlat` |
| **Części zasłonięte** | bez grzywki (skóra czoła), bez włosów (łysa głowa), sama kurtka, tors bez rąk (edit-14), bez dłoni | żeby przy ruchu pod spodem nie było dziur |

**Słaba edycja = odrzucić i powtórzyć mocniejszym promptem, nie łatać.** Typowe błędy ChatGPT:
lekko przesunięta lub przeskalowana postać, zmieniona fryzura, inna grubość konturu, „poprawione”
dłonie. Drobne przesunięcie skrypty wyrównają (ECC), ale zmienionej sylwetki — już nie.

Wskazówki:
- Wgrywaj **zawsze bazę**, nie poprzednią edycję — inaczej błędy się kumulują.
- Przy częściach zasłoniętych (bez grzywki, łysa głowa) dopisz, co ma się pojawić w miejscu
  usuniętej rzeczy („gładkie czoło w kolorze skóry”, „kształt czaszki”).
- Nazwy plików od razu porządkuj (`edit-01-eyes-closed.png` itd.) — skrypty biorą je po nazwie.

## 16. ComfyUI + See-through (E3)

See-through rozkłada pojedynczy obraz postaci anime na warstwy semantyczne (włosy przód/tył, oczy,
twarz, ubranie…) i szacuje głębię, **dorysowując części zasłonięte**.

- Uruchamiamy przez `scripts/comfy_run.py` z workflowem z `workflows/`.
- **Rozdzielczość 1024.** Przy 1280 VAE pada na XPU (Intel Arc) — nie próbuj wyżej, skalujemy później.
- Zasoby: szczyt RAM ~23 GB, VRAM ~10 GB, ~4,5 min na przebieg. **Nie odpalać przy uruchomionej grze.**
- Dwa przebiegi:
  1. **ciało** — cała baza,
  2. **głowa** — wycinek głowy (większe oczy/usta = dokładniejsze maski małych części).
- Składanie na wspólne płótno:
  `split_to_canvas.py --pixels base [--full-size WxH --offset x,y]` —
  **piksele widoczne bierzemy z bazy** (ostrzejsze, wierne), a z See-through tylko maski i części zasłonięte.

## 17. Czyszczenie warstw (E4)

| Skrypt | Co robi |
|---|---|
| `fix_face.py` | skóra twarzy/czoła z edycji „bez grzywki” — żeby pod grzywką była prawdziwa skóra |
| `fix_back_neck.py` | dorysowana tylna część szyi (widoczna przy obrocie głowy) |
| `topwear_from_edit.py` | tors/kurtka z edycji „sama kurtka” |
| `cut_arms_head.py` | rękawy, dłonie i łysa głowa wycięte z odpowiednich edycji |
| `defringe.py` | usuwa jasne/ciemne obwódki na krawędziach alfy (halo po wycinaniu) |
| `compose_check.py` | składa wszystkie warstwy i porównuje z bazą: **średnia różnica ma być mała**, `diff.png` do obejrzenia |

Mechanizm „edycja → warstwa”: edycja z ChatGPT jest wyrównywana do bazy algorytmem **ECC**
(OpenCV, dopasowanie afiniczne), potem liczona jest różnica i z niej powstaje maska nowej części.
Dlatego edycje muszą być 1:1 — ECC skoryguje przesunięcie o kilka pikseli, ale nie inną pozę.

## 18. Ruch i mimika (E5)

| Skrypt | Wynik |
|---|---|
| `diff_layers.py` | warianty (brwi, twarze, rumieniec) z edycji jako osobne warstwy `~...` |
| `eye_rig.py` | tęczówki oddzielone od białek, zamknięte powieki, brwi, **`gaze.json`** |
| `mouth_shapes.py` | `~mouth_A/I/U/E/O/smile/pout` |
| `ears_flat.py` | `~ears_flat_l/r` |

`gaze.json` zawiera środki tęczówek i przesunięcia (left/right/up/down) zmierzone z edycji „patrzy w…”.
Wartości są w **pikselach płótna 1024** — dla PSD 3x mnożymy ×3 (stąd tabela w sekcji 9).

## 19. Budowa PSD (E6) — wymagania „Live2D-ready”

`upscale_layers.py` (RealESRGAN ×3 na XPU) → `PSD_SRC=up3 build_psd.py OUT.psd`.

Wymagania, które skrypt spełnia, a które warto znać przy ręcznym PSD:

- **Każda część na osobnej warstwie**, każda warstwa w **pełnym rozmiarze płótna** (pozycje się nie rozjeżdżają).
- **Bez masek przycinających, efektów warstw i warstw dopasowania** — Cubism ich nie importuje
  (albo importuje źle). Wszystko zrasteryzowane, tryb mieszania Normal.
- RGB, 8 bit, przezroczyste tło.
- **Unikalne nazwy ASCII** warstw — stają się ID ArtMeshy.
- **Części zasłonięte dorysowane** (skóra pod grzywką, łysa głowa, tors pod rękami).
- Warianty w **ukrytej grupie `~variants`** — Cubism je importuje, ale nie pokazuje na starcie.
- Grupy i kolejność rysowania ustawione w `ORDER` w `build_psd.py`.
- Rozdzielczość: 1024 z See-through to za mało na teksturę 4096 → upscale ×3 do 3072×4608.

## 20. Rig dla zaawansowanych

### Siatki

- Auto Mesh na start, potem ręcznie: **gęściej oczy, usta, grzywka**, rzadziej duże płaskie powierzchnie.
- Punkty siatki kładź na **krawędziach kształtu i liniach zgięcia** (np. wzdłuż powieki) — wtedy
  deformacja nie „pływa”.
- **Glue** (sklejanie siatek) dla części, które muszą się stykać (szyja–twarz, rękaw–dłoń).

### Hierarchia deformerów

```
Body_Rotation (ParamBodyAngleZ)
 └─ Body_Warp (ParamBodyAngleX/Y)
     ├─ Breath_Warp (ParamBreath) ── topwear, sleeve_*, hand_*
     ├─ neck
     ├─ BackHair_Warp (ParamHairBack) ── back_hair
     └─ Head_Rotation (ParamAngleZ, pivot na szyi)
         └─ Face_Warp (ParamAngleX/Y)
             ├─ Eye_L_Warp / Eye_R_Warp ── eyewhite, irides, eyelash, ~eyelid_closed
             ├─ Brow_L / Brow_R ── eyebrow_*
             ├─ Mouth_Warp ── mouth, ~mouth_*
             ├─ ears_*
             └─ FrontHair_Warp (ParamHairFront) ── front_hair
```

- **Rotation** dla obrotów wokół punktu (`AngleZ`, `BodyAngleZ`), **Warp** dla „pseudo-3D” (`AngleX/Y`).
- Przy `ParamAngleX` + `ParamAngleY` naraz robi się **2D keyform (siatka 3×3 kluczy)**. Skrajne rogi
  (np. X=30, Y=30) często trzeba ręcznie poprawić — automat liczy je jako mieszankę, co daje „spłaszczenie”.
- Włosy z tyłu ruszają się **przeciwnie** do twarzy przy `AngleX` (paralaksa) — to daje wrażenie głębi.

### Ładniejsze mruganie

Zamiast samej przezroczystości: przy `EyeOpen=0` zgnieć siatkę rzęs w łuk zamkniętej powieki, białko
i tęczówkę przytnij (clipping) do obrysu oka — przy wartościach pośrednich oko zamyka się płynnie,
a nie „przenika”. Klucz pośredni 0.5 pomaga uniknąć „pustego” oka w połowie mrugnięcia.
Opcjonalnie `ParamEyeLSmile/RSmile` — oczy-łuki przy uśmiechu.

### Usta i lip-sync

- `ParamMouthOpenY` × `ParamMouthForm` to również siatka 2D (otwarcie × kształt). Minimum: 2×3 klucze.
- Kształty samogłosek (`~mouth_A/I/U/E/O`) można wpiąć jako klucze pośrednie albo — w PRO — użyć
  **Motion Sync** (lip-sync na podstawie samogłosek z dźwięku) zamiast samej głośności.

### Multiply / Screen color

ArtMesh może mieć kolor mnożony/ekranowy sterowany parametrem — tak robi się np. rumieniec bez osobnej
warstwy albo przyciemnienie postaci w Lunecie. Runtime (pixi-live2d-display 0.4) obsługuje to tylko
częściowo — testuj przed użyciem.

### Fizyka

- *Modeling → Physics* (ustawienia fizyki i scen). Grupa = wejścia (`ParamAngleX/Z`, `ParamBodyAngleX/Z`)
  → wahadło (długość, sztywność, opór) → wyjście (`ParamHairFront`, `ParamHairBack`, ew. ucho/kokarda).
- Dłuższe wahadło = wolniejszy, „cięższy” ruch. Grzywka: krótkie, sztywne; włosy z tyłu: dłuższe.
- Eksport fizyki → `*.physics3.json`.

### Template (PRO)

Gdy automatyczna mimika nie rozpoznaje warstw, można nałożyć **szablon** z gotowego modelu
(np. Hiyori z Cubism SDK Samples) — przenosi deformery i klucze, które potem dopasowujemy ręcznie.
Działa najlepiej, gdy podział warstw jest podobny do szablonu.

## 21. Animacje i miny

- **Tryb Animation** → nowa scena → oś czasu, klucze parametrów w czasie.
- `Idle` (pętla, 4–8 s): `ParamBreath` sinusoidalnie, delikatny `ParamAngleX/Z` (±3–5), od czasu do czasu
  `ParamEyeBall*`. Mruganie **nie** w animacji — robi je runtime (grupa EyeBlink).
- `Tap` (v2): reakcja na kliknięcie, np. znak pokoju.
- Miny: ustawiasz suwaki (brwi, `ParamCheek`, `~face_*`) i zapisujesz jako expression → `.exp3.json`.
- Eksport: *File → Export For Runtime* → motion3.json / exp3.json, do tego samego katalogu co model.
- W `model3.json` motions są w grupach (`Idle`, `TapBody`…) — nazwy grup to te, których używa kod.

## 22. Eksport — szczegóły

- **Atlas tekstur**: przy eksporcie Cubism składa ArtMeshe w atlas. 4096 dla strony; dla Lunety 2048
  (mniej VRAM, wystarczy przy mniejszym oknie). Sprawdź, czy nic nie zostało przeskalowane za mocno.
- `model3.json` musi zawierać `Groups`: `EyeBlink` = `ParamEyeLOpen`, `ParamEyeROpen`;
  `LipSync` = `ParamMouthOpenY`. Bez tego runtime nie mruga i nie rusza ustami.
- `HitAreas` (opcjonalnie) — obszary klikalne (`Head`, `Body`) do reakcji na dotyk.
- Projekt `.cmo3` trzymamy w `C:\wise-one\`, eksport w `C:\wise-one\runtime\` → scp na ariku-pc
  (`/mnt/nvme/ai/wise-one/e7-rig/runtime/`).

## 23. Runtime: strona i Luneta

Stos (wersje przypięte): **`pixi.js@6.5.10` + `pixi-live2d-display@0.4.0`** (Cubism 4/5 `.moc3`)
+ Cubism Core `live2dcubismcore.min.js`. pixi-live2d-display 0.4 wymaga PIXI **v6**, nie v7+.

```ts
// Core musi być załadowany przed importem (window.Live2DCubismCore).
await loadScript(coreUrl);            // <script src> z ariku.pl / asset protocol Tauri
import * as PIXI from 'pixi.js';
import { Live2DModel } from 'pixi-live2d-display/cubism4';
(window as any).PIXI = PIXI;           // pixi-live2d-display używa globalnego tickera

const app = new PIXI.Application({ view: canvas, backgroundAlpha: 0, autoStart: true, resolution: devicePixelRatio });
app.ticker.maxFPS = 30;                // tanio
const model = await Live2DModel.from('/live2d/wise-one/wise-one.model3.json');
app.stage.addChild(model);
```

| Efekt | Jak |
|---|---|
| Mruganie, oddech | automatycznie, gdy `model3.json` ma grupę `EyeBlink` i parametr `ParamBreath` |
| Śledzenie kursora | `model.focus(x, y)` na `pointermove` (`ParamAngleX/Y`, `ParamEyeBallX/Y`) |
| Idle | `model.motion('Idle')` |
| Mina | `model.expression('surprised')` |
| Lip-sync | `AnalyserNode` → RMS co klatkę → `coreModel.setParameterValueById('ParamMouthOpenY', v)` w `beforeModelUpdate` |
| Pauza | `document.visibilitychange` → `app.ticker.stop()/start()` |

**Luneta (Tauri):** komponent `src/components/Live2DView.tsx`; model i Core z katalogu danych
(`convertFileSrc` / asset protocol) — dopisać zakres w `tauri.conf.json` (`assetProtocol.scope`) i CSP
(`script-src` dla Core). Brak Core lub modelu → statyczny obraz (splash), bez błędu. Nakładka nad grą
tylko informacyjna — kliknięcia przechodzą do gry. Animacja tylko przy widocznym oknie, FPS ograniczony
(ENGINEERING-RULES §36).

**ariku.pl:** model i Core jako pliki statyczne; ta sama inicjalizacja, `autoInteract` tylko na hover,
`prefers-reduced-motion` → bez Idle.

**Test:** najpierw darmowy model przykładowy (Hiyori z Cubism SDK Samples), potem Wise One:
renderuje się, śledzi kursor, mruga, przy ukrytym oknie FPS = 0.

## 24. Licencje — ważne

- **Cubism Core** (`live2dcubismcore.min.js`) jest zamknięty (licencja Live2D Proprietary Software).
  **Nigdy** do publicznego repo — Luneta jest na MIT. Ładujemy go z ariku.pl albo z dysku użytkownika.
- Cubism SDK for Web (Framework) ma własną licencję; przy publikacji komercyjnej powyżej progu
  przychodów Live2D wymaga umowy — sprawdź aktualne warunki przed wydaniem.
- Edytor: trial PRO 42 dni; plików `.cmo3` zapisanych w PRO nie da się w pełni edytować w FREE, jeśli
  przekraczają limity FREE.
- Obrazy z ChatGPT — zgodnie z warunkami OpenAI; postać jest nasza.

## 25. Jak to przebiegało u nas (dziennik Wise One v1)

| Kiedy | Gdzie | Co |
|---|---|---|
| przed 2026-10-17 | ChatGPT | obraz bazowy Wise One (E1) zamrożony; ~20 edycji 1:1 (oczy, usta, brwi, miny, uszy, części zasłonięte) |
| | ariku-pc (Linux, Intel Arc/XPU) | See-through w ComfyUI (ciało + głowa, 1024), czyszczenie, mimika, `gaze.json`, upscale ×3, `wise-one-v1-3x.psd` |
| | | wnioski: 1280 w See-through pada w VAE na XPU; edycja „tors bez rąk” (edit-14) wyszła słabo; grzywka została jednym blokiem |
| 2026-10-17 | felix-pc (Windows) | instalacja Cubism Editor 5.3, aktywacja triala PRO; UI po japońsku → przełączone na English (restart) |
| 2026-10-17 | felix-pc | okno „nowa wersja” — kliknięcie *開く* zamknęło edytor; od tej pory zawsze **Cancel** |
| 2026-10-17 | felix-pc | próba riggingu przez asystenta (computer use) — okno Javy wymagało osobnej zgody; decyzja: **rig robi właściciel sam**, asystent pisze poradnik |
| 2026-10-17 | wiki | ten poradnik |

Co warto zrobić inaczej od początku (lekcje):
1. **Zaplanować warstwy przed bazą** — np. grzywka na 3–5 pasm już w obrazie bazowym, ręce opuszczone.
2. **Robić edycje części zasłoniętych od razu**, a nie dopiero przy czyszczeniu.
3. **Testować runtime na Hiyori**, zanim rig Wise One będzie gotowy — błędy integracji wychodzą wcześniej.
4. **Trial PRO odpalać dopiero, gdy PSD jest gotowy** — 42 dni szybko mijają.

## 26. Znane braki v1 i plan v2

- Grzywka i boczne włosy to jeden blok — fizyka „sztywniejsza”. **v2:** pasma osobno.
- Postać tylko od pasa w górę. **v2:** pełna postać.
- Tors bez rąk (pod rękawami) słabej jakości — nie podnosić rąk za wysoko. **v2:** lepsza edycja.
- Brak animacji `Tap`. **v2:** znak pokoju po kliknięciu.

## 27. Checklista końcowa

- [ ] PSD zaimportowany, `~variants` obecna
- [ ] siatki (gęściej oczy/usta/grzywka)
- [ ] `ParamAngleX/Y/Z`, `ParamBodyAngleX`, `ParamBreath`
- [ ] `ParamEyeLOpen/ROpen`, `ParamEyeBallX/Y` (clipping tęczówek)
- [ ] `ParamMouthOpenY`, `ParamMouthForm`
- [ ] (opcja) brwi, `ParamCheek`, `ParamEarFlat`, fizyka włosów
- [ ] miny `.exp3.json`, animacja `Idle`
- [ ] grupy EyeBlink / LipSync
- [ ] eksport do `C:\wise-one\runtime\`, test na Hiyori → test Wise One
- [ ] Cubism Core poza publicznym repo