advanced example

README.md

@@ -2,7 +2,8 @@
 
 UE **5.7**, Windows / Linux. Biblioteka `ue_workshop` automatyzuje scenę,
 Sequencer, Movie Render Queue i składanie MP4. Nie wymaga kompilacji C++ ani pip.
-Pierwsze ćwiczenie korzysta wyłącznie z brył silnika. Blender jest opcjonalny.
+Plik do pokazu podstaw korzysta z własnego modelu z Blendera i obrotu kamery.
+Zadanie z animacjami korzysta z dołączonych postaci Mixamo i nie wymaga Blendera.
 
 Jeśli używasz wcześniejszej kopii projektu z C++ i edytor zgłasza
 `Target Upgrade Required`, zamknij UE i usuń pozostałości starej kompilacji:
@@ -23,19 +24,40 @@ automatyzacji edytora; nie służy tu do gameplayu.
 
 ## Pierwszy skrypt w edytorze
 
+Pliki do prowadzenia zajęć:
+
+- `exercises/basics.py` — prosty pokaz: `character_custom.blend`, podłoga, światła
+  i kamera robiąca pełne 360° w 8 sekund. Postać pozostaje nieruchoma.
+- `exercises/animation_starter.py` — punkt wyjścia dla studentów: jedna creature,
+  dwie animacje (`mutant_idle`, `mutant_swiping`) i 15 sekund na eksperymenty. Własną scenę walki
+  tworzą przez dodanie klipów, ruchu, drugiej postaci i zmian kamery.
+- `exercises/my_shot.py` — dotychczasowy rozbudowany plik z wyborem modelu.
+- `examples/mixamo_characters.py` — fighter i creature z pełnymi słownikami klipów;
+  zachowany układ sceny i dotychczasowe klipy, gotowe do własnej sceny walki.
+
+W nowych plikach render jest zakomentowany. Najpierw obejrzyj scenę w Sequencerze,
+potem odkomentuj `renderer.render(shot)`. Każdy plik tworzy własną nazwaną mapę.
+Przed edycją zrób kopię pliku; ponowne uruchomienie przebudowuje jego scenę.
+
+`REIMPORT = False` używa istniejących modeli i klipów w UE. Brakujące assety
+importowane są przy pierwszym uruchomieniu. `REIMPORT = True` wymusza ponowny
+import wszystkich wskazanych modeli i klipów, również eksport `.blend` z Blendera.
+Po odświeżeniu ustaw ponownie `False`. Zmiany plików nie są wykrywane automatycznie.
+
 Zapisz aktualną mapę. Wybierz **File → Execute Python Script** i wskaż
-`exercises/my_shot.py`. Możesz też wpisać w konsoli UE:
+`exercises/basics.py`. Możesz też wpisać w konsoli UE:
 
 ```text
-py "C:/sciezka/do/projektu/exercises/my_shot.py"
+py "C:/sciezka/do/projektu/exercises/basics.py"
 ```
 
-Powstanie prosta postać, podłoga, trzy światła, kamera i dwusekundowa animacja.
-Obejrzyj ją w Sequencerze. Zmień kolor, `head_scale`, kamerę albo klucze i uruchom
+Powstanie własna postać z Blendera, podłoga, trzy światła i ośmiosekundowy objazd kamerą.
+Obejrzyj go w Sequencerze. Zmień model, kolor podłogi, kamerę albo klucze i uruchom
 plik ponownie. Skrypt jest odczytywany ponownie z dysku.
 
-Ustaw `RENDER = True`, aby wyrenderować film. Domyślny preset `preview` to
-640×360, 24 FPS, 48 klatek. `final` to 1280×720 i więcej próbek.
+W `my_shot.py` ustaw `RENDER = True`, aby wyrenderować film. Preset `preview` to 640×360,
+a `final` to 1280×720 i więcej próbek. FPS i długość filmu pochodzą z `Sequence`.
+Ustawienia własnego renderera są na końcu ćwiczenia.
 Szybkie sprawdzenie obrazu: zamiast pełnego renderu użyj
 `renderer.render(shot, single_frame=24)`.
 
@@ -135,15 +157,17 @@ W `exercises/my_shot.py` wybierz `MODEL`:
 | Wartość | Postać |
 |---|---|
 | `"primitive"` | Dotychczasowa postać z brył, bez importu. |
-| `"robot"` | RobotPolice z dołączonego `DemoAssets`. |
-| `"pilot"` | Humanoid z `DemoAssets/pilot`. |
+| `"fighter"` | Wojowniczka z `source_assets/character/fighter`. Domyślna postać. |
+| `"creature"` | Stwór z `source_assets/character/creature`. |
 | `"file"` | Własny plik wskazany w `MODEL_FILE`. |
 
 Przykład własnego modelu:
 
 ```python
 MODEL = "file"
-MODEL_FILE = PROJECT / "source_assets/models/my_character.glb"
+MODEL_FILE = PROJECT / "source_assets/character/my_character.fbx"
+SKELETAL = True
+ANIMATION_FILE = None  # animacja zawarta w FBX; albo ścieżka do osobnego klipu FBX
 MODEL_HEIGHT = 200
 MODEL_ROTATION = (0, 0, 90)
 ```
@@ -161,16 +185,89 @@ dopasowaniem wysokości. Pivot animacji znajduje się na środku podstawy.
 
 Dla pojedynczego atlasu FBX/OBJ można dołączyć mapy `NazwaModelu_BC.png`,
 `_N`, `_R`, `_M`, `_E` (również JPG/JPEG). Biblioteka odtworzy z nich jeden
-materiał dla wszystkich slotów. Robot i pilot korzystają z tej konwencji.
+materiał dla wszystkich slotów w statycznym przepływie `scene.model(...)`.
 Bez pliku `_BC` pozostają materiały zaimportowane przez UE. W GLB zachowywany
 jest osobny materiał dla każdego slotu.
 
-Po zmianie postaci reszta skryptu działa tak samo: klucze `location`, `rotation`
-i `scale` animują cały model. W przykładzie jest też opcjonalny podskok.
-Modele z rigami są w tej wersji importowane jako statyczna geometria:
-animacje kości, chodzenie z Mixamo i retargeting nie są jeszcze obsługiwane.
+Dla `fighter` i `creature` użyj nazwy pliku bez rozszerzenia, ze spacjami zamienionymi
+na podkreślenia: np. `great_sword_walk` lub `mutant_swiping`. Dostępny jest
+[pełny katalog animacji](docs/animations.md): 51 klipów fighter i 12 klipów creature.
+`scene.skeletal_model(...)` samo znajduje wszystkie pliki FBX w folderze postaci
+poza modelem. Nie wymaga `animations` ani ręcznych aliasów. Import tworzy SkeletalMesh, szkielet,
+materiały i wszystkie klipy. Sequencer odtwarza
+animację kości przez 120 klatek (5 s); krótszy klip zapętla się w swojej sekcji.
+Klucze `location`, `rotation` i `scale` mogą dodatkowo poruszać całym modelem.
+Przykład dwóch postaci z różnymi klipami: `examples/mixamo_characters.py`.
+
+```python
+character = scene.skeletal_model(
+    PROJECT / "source_assets/character/creature/Maw J Laygo.fbx",
+    name="Creature", height=200, location=(150, 0, 0),
+)
+shot.animation(character, "mutant_walking")
+```
+
+`shot.animation(character, "mutant_walking", start=0, end=48, speed=0.8)` odtwarza klip
+w zakresie `[0, 48)` z prędkością 80%. Następny klip może zacząć się w klatce 48.
+Nakładające się klipy tej samej postaci automatycznie tworzą płynne przejście
+przez cały wspólny zakres. Helper ustawia narastanie wagi nowego klipu
+i zanikanie poprzedniego; nie trzeba podawać dodatkowego parametru:
+
+```python
+shot.animation(character, "mutant_idle", start=0, end=60)
+shot.animation(character, "mutant_walking", start=48, end=120)
+```
+
+Przy 24 FPS przejście na klatkach 48–60 trwa 0,5 sekundy. Dodawaj klipy w kolejności
+odtwarzania; naraz mogą mieszać się dwie animacje tej samej postaci.
+Klipy stykające się końcami przechodzą bez blendu. Nie trzeba ponownie importować animacji.
+Przy kolejnych przejściach środkowy klip zachowa zarówno wejście, jak i wyjście.
+Pełne zawieranie jednego klipu w drugim oraz identyczne zakresy są odrzucane.
+`shot.animation(character)`
+wybiera jedyny klip zawarty w modelu. Każda postać zachowuje swój szkielet;
+automatyczny retargeting między różnymi postaciami nie jest wykonywany.
+
+W Mixamo pobierz FBX **With Skin**, aby mieć model, szkielet i animację w jednym
+pliku. Kolejne klipy pobieraj dla tej samej wybranej postaci; mogą być **Without Skin**.
+Umieść je obok pliku modelu — są wykrywane automatycznie, pod nazwami plików.
+Opcjonalne `animations={"mutant_idle": path1, "mutant_walking": path2}` ogranicza
+wybór do konkretnych klipów. Puste `animations={}` pomija animacje z folderu
+i pozostawia tylko klipy zawarte w pliku modelu.
+Jeśli samodzielnie animujesz trasę przez `transform_key`, wybierz **In Place**,
+gdy jest dostępne, aby animacja kości nie dodawała własnego przesuwania.
+
+Importy szkieletowe trafiają do `Content/Workshop/Generated/Skeletal`.
+Przy `REIMPORT=True` aktualizowane są te same assety. Pivot jest na środku podstawy
+pozy referencyjnej; podczas animacji obrys i pozycja stóp mogą się zmieniać.
+Dla statycznego GLB, FBX, OBJ lub `.blend` ustaw `MODEL="file"`, `SKELETAL=False`.
+Dotychczasowe `scene.model(...)` zachowuje statyczny przepływ importu.
 Wybrany model działa zarówno w edytorze, jak i przez `my_shot_headless.py`.
 
+### Mixamo → Blender → Unreal
+
+Zaimportuj do Blendera FBX ze szkieletem i animacją. Zmieniaj geometrię, zachowując
+Armature, wagi wierzchołków i modyfikator Armature. Siatki umieść w kolekcji
+`Character`; muszą być przypisane do jednego Armature. Wybierz aktywną akcję
+i ustaw zakres klatek sceny obejmujący animację. Zapisz `.blend`, a w ćwiczeniu ustaw:
+
+```python
+MODEL = "file"
+MODEL_FILE = PROJECT / "source_assets/character/my_animated_character.blend"
+SKELETAL = True
+ANIMATION_FILE = None
+```
+
+Python uruchomi Blendera w tle, wyeksportuje siatki, szkielet i aktywną animację
+do FBX, a następnie zaimportuje je w UE. Eksport obejmuje aktywną akcję w zakresie
+sceny; nie eksportuje osobnych akcji i pasków NLA jako wielu klipów. Materiały FBX
+przenoszą podstawowe kolory i obsługiwane tekstury. Proceduralne materiały wypal
+do tekstur; statyczne modele z pełniejszym PBR nadal eksportuj do GLB.
+
+Blender potrzebuje binarnego FBX 7.1 lub nowszego. Dołączone fighter i creature
+są w starym FBX 6.1: UE importuje je bezpośrednio, ale Blender 5.1 ich nie otworzy.
+Do edycji w Blenderze pobierz współczesny wariant FBX albo wyeksportuj SkeletalMesh
+i animację z UE do nowego FBX.
+
 ## Blender → UE → film
 
 Własną kopię wybierzesz też bezpośrednio w `my_shot.py`:
@@ -178,9 +275,10 @@ Własną kopię wybierzesz też bezpośrednio w `my_shot.py`:
 ```python
 MODEL = "file"
 MODEL_FILE = PROJECT / "source_assets/character/character_custom.blend"
+SKELETAL = False  # ten przykład to statyczne siatki bez Armature
 ```
 
-Zapisz zmiany w Blenderze i ponownie uruchom ćwiczenie. Za każdym razem plik
+Zapisz zmiany w Blenderze i uruchom ćwiczenie z `REIMPORT=True`. Plik
 jest eksportowany w tle i aktualizuje ten sam asset `CustomCharacter` w UE.
 Nie trzeba ręcznie usuwać poprzedniego modelu. Eksport obejmuje kolekcję `Character`.
 Na Windows biblioteka wykrywa też standardowe instalacje w `Blender Foundation`,
@@ -212,13 +310,16 @@ Tekstury PNG/JPEG są wyciągane z GLB i aktualizowane w wydzielonym katalogu
 `WorkshopTextures`. Parametry PBR synchronizujemy jawnie, ponieważ standardowy
 reimport siatki w UE zachowuje wcześniejsze materiały. Zmiany w tych importowanych
 materiałach wykonuj w Blenderze; skrypt nadpisuje wspierane parametry ich źródłem.
-Dowolne grafy proceduralne, rig, animacje szkieletowe, włosy i shader skóry nie
-wchodzą w zakres v1. Materiały proceduralne należy wypalić do tekstur.
+Dowolne grafy proceduralne, włosy i shader skóry nie są przenoszone w tym przepływie.
+Materiały proceduralne należy wypalić do tekstur. Modele z Armature obsługuje
+`scene.skeletal_model(...)`, opisane wyżej.
 
 ## Układ i zasady
 
 - `Content/Python/ue_workshop/` — biblioteka, automatycznie dostępna w Pythonie UE.
-- `exercises/my_shot.py` — jedyny wymagany plik uczestnika; zrób kopię przed edycją.
+- `exercises/basics.py` — pokaz podstaw na własnym modelu z Blendera.
+- `exercises/animation_starter.py` — plik startowy zadania z dwiema animacjami.
+- `exercises/my_shot.py` — rozbudowany wariant z wyborem postaci.
 - `examples/` — dodatkowa kamera i Blender; ćwiczenie startowe jest też rozwiązaniem bazowym.
 - `tools/` — launcher, eksport/generator Blendera i testy integracyjne.
 - `docs/` — ściąga API i scenariusz spotkania.
@@ -241,6 +342,8 @@ python -m unittest discover -s tests -v
 python tools/run_workshop.py tools/smoke_scene.py
 python tools/run_workshop.py tools/smoke_blender.py
 python tools/run_workshop.py tools/smoke_renderer.py
+python tools/run_workshop.py tools/smoke_skeletal.py --render
+python tools/run_workshop.py tools/smoke_workshop_files.py
 ```
 
 Pierwszy test integracyjny wykonuje ćwiczenie dwa razy, sprawdza duplikaty,