PythonInUnreal/docs/validation.md

# Weryfikacja v1 — 31 października 2026

Sprawdzone lokalnie: Windows, Unreal Engine 5.7, Blender 5.1.2 i FFmpeg.
Nie uruchamiano testów na Linuksie ani na Blenderze 4.x.

- Testy poza UE: 7 zaliczonych, w tym rzeczywiste kodowanie dwóch PNG do MP4,
  odczyt częściowo zapisanych komunikatów i raportowanie liczby klatek.
- Postęp headless: sprawdzone etapy od startu UE do jego zamknięcia,
  licznik zapisanych PNG i cichy zapis pełnych logów do pliku.
- Obiekt `Renderer`: własne 320×180, dwie próbki, rozgrzewka 0; sprawdzone
  właściwości MRQ i rzeczywiste wymiary PNG. Walidacja błędnych argumentów
  i nadpisywanie presetu. Launcher używa obiektu ze skryptu: sprawdzone 400×224.
- Dwukrotne wykonanie ćwiczenia w UE: bez dodatkowych aktorów, bindingów i Camera Cuts.
- Render MRQ w procesie edytora uruchomionym bez okna: 48 PNG oraz MP4, 24 FPS.
- `python exercises/my_shot_headless.py`: pełne ćwiczenie 1920×1080, 4 próbki,
  rozgrzewka 32, 48 PNG i MP4. UE zamknął się automatycznie; oba kody zakończenia 0.
- Podgląd pojedynczej klatki z terminala (`--single-frame 24`): zaliczony.
- Odroczone zamknięcie edytora po renderze: kod zakończenia UE i launchera 0.
- Zwykły `UnrealEditor.exe`: projekt otwiera się bez żądania aktualizacji targetu
  po usunięciu pozostałych receiptów i cache kompilacji UE 5.8.
- Wizualnie sprawdzony kadr, ekspozycja i wygenerowana postać.
- Pełny edytor z działającym UI Sequencera: otwarcie sekwencji, ticki UI,
  przebudowa sceny i dwa kolejne rendery po 48 klatek do MP4 w jednym procesie.
  Renderer startuje przez MoviePipelineQueueSubsystem po powrocie ze skryptu;
  Sequencer jest zamykany przed przebudową bindingów oraz rozpoczęciem PIE.
- Blender: eksport zapisanej kolekcji, trzy materiały, aktualizacja istniejącego
  StaticMesh pod tą samą ścieżką po zmianie geometrii.
- Zmiana koloru materiału oraz dodanie osadzonej tekstury: sprawdzone wartości
  parametrów UE, przypisanie tekstury i render do MP4.
- Import lokalnych RobotPolice i pilot z FBX, automatyczne dopasowanie wysokości
  do 200 cm i ustawienie podstawy na Z=0. Odtworzenie materiałów z tekstur PBR.
- Pełny `my_shot.py` z robotem: 48 klatek 1920×1080, MP4 i poprawne zamknięcie UE.
- GLB po włączeniu łączenia części modelu: zaliczony test eksportu/importu
  Blendera, aktualizacji materiałów i tekstury oraz renderu.
- `character_custom.blend`: dwukrotne wykonanie `my_shot.py`, dwa eksporty
  Blendera do GLB i aktualizacja tego samego assetu UE; podgląd renderu zaliczony.

Uruchamianie sprawdzeń jest opisane w README. Wyniki każdego renderu są zapisane
w jego `result.json`; logi UE znajdują się w `Saved/Logs`.
Skrypty integracyjne generują własne mapy i assety w `Workshop/Generated`.

## Postacie szkieletowe — 31 października 2026

- 13 testów poza UE: w tym zakresy klipów, wykrywanie nakładania, prędkość,
  wybór klipu i odrzucanie animacji z innym szkieletem.
- UE 5.7: import fighter i creature jako SkeletalMesh z materiałami i teksturami,
  własny szkielet każdej postaci oraz klipy idle, walk i attack z osobnych FBX.
- W klipach walk sprawdzone rzeczywiste zmiany rotacji kości między klatkami.
- Ponowny import tych samych assetów po restarcie UE oraz zapis zależności
  (szkielet, materiały, tekstury). FBX używa importera zgodnego z FbxImportUI;
  poprzednia wartość flagi Interchange jest przywracana po imporcie.
- Sequencer: klipy w kolejnych zakresach, prędkość 0.75 i jednoczesne klucze
  transformacji rodzica. Render 48 klatek, 640×360, dla obu postaci.
- Blender 5.1.2: wczytanie fighter i chodzenia z nowych FBX wyeksportowanych
  przez UE, zmiana geometrii z zachowaniem wag, zapis `.blend`, eksport Armature
  i aktywnej akcji, import do UE i render 24 klatek, 640×360.
- Dołączone źródła są w FBX 6.1, nieobsługiwanym przez importer Blendera 5.1;
  bezpośredni import w UE działa. Test Blendera korzysta z eksportu UE do FBX 7.3.

Odtworzenie testu Blendera (po teście `smoke_skeletal.py`):

```text
blender --background --python-exit-code 1 --python tools/create_skeletal_fixture.py
python tools/run_workshop.py tools/smoke_skeletal_blender.py --render
```

Eksport szkieletowy obejmuje jedną postać i aktywną akcję w zakresie sceny.
Nie sprawdzano retargetingu, Animation Blueprintów ani eksportu wielu akcji/NLA.

## Pliki na zajęcia i pełne katalogi

- `tools/smoke_workshop_files.py`: w UE zaimportowano wszystkie 51 klipów fighter
  i 12 klipów creature; sprawdzono kompletność słowników i dodatnią długość klipów.
- `exercises/basics.py`: eksport własnego `.blend`, 192 klatki kamery na okręgu,
  stały promień, zgodne końce trasy i ciągły yaw obejmujący pełne 360°.
- `exercises/animation_starter.py`: jedna postać, dokładnie dwa klipy, 360 klatek.
- Wszystkie trzy sceny zostały zbudowane i zapisane w oddzielnych mapach.

## Blendowanie z Pythona

- 17 testów poza UE: dodatkowo poprawne nakładanie, wagi obu klipów, zachowanie
  wejścia i wyjścia środkowego klipu oraz odrzucanie trzech równoczesnych klipów.
- `tools/smoke_blending.py`: w UE 5.7 utworzono przejścia idle → attack → walk,
  po 12 klatek każde. Sprawdzone zapisane klucze Weight i wyrenderowana klatka 54,
  w środku pierwszego przejścia, równolegle z kluczami pozycji rodzica.
- Przejście korzysta z kanałów wag; chronione pola MovieSceneEasingSettings
  nie są modyfikowane. Modele i klipy są ponownie używane z `reimport=False`.

## Automatyczne wykrywanie bez aliasów

- 23 testy poza UE: dodatkowo pomijanie pliku modelu, nazwy z plików, wykrywanie
  kolizji nazw, automatyczny wybór wszystkich klipów, jawny wybór i puste `animations={}`.
- Sprawdzone przekazywanie `reimport=False`/`True` oraz użycie istniejącego modelu.
- `tools/smoke_workshop_files.py` zaliczony w UE: obie postacie wczytane bez
  argumentu `animations`, pełne 51 + 12 klipów i plik zadania z dwoma pełnymi nazwami.

## Automatyczny blend

- 26 testów poza UE: blend wynika ze wspólnego zakresu, także przy jednej klatce
  nakładania; stykające się klipy nie dostają fade. Sprawdzone łańcuchy trzech
  klipów oraz odrzucanie niejednoznacznych zakresów i dodawania w odwrotnej kolejności.
- Parametr `blend_in` usunięty z API i przykładów. Zakresy scen pozostają takie same.

## Katalog enumów i długości dostępnych offline

- 34 testy poza UE: statyczne enumy obejmują wszystkie pliki źródłowe, importują
  się bez `unreal`, udostępniają sekundy i przeliczenie klatek z FPS i prędkością.
- Sprawdzone zaokrąglanie czasu float32 bez dodawania zbędnej klatki, automatyczny
  koniec dla enuma, jawny koniec oraz odrzucenie sekcji dłuższej niż sekwencja.
- `tools/smoke_animation_catalog.py` w UE: porównane długości wszystkich 63 klipów
  z rzeczywistym `get_play_length()`, odtworzone enumy, w tym `speed=2`, oraz render
  klatki ze środka automatycznego przejścia. Katalog pochodzi z eksportu assetów UE.
- Po przypisaniu parametrów sekcji przywracany jest zakres podany w Pythonie,
  ponieważ edytor może przeskalować go przy zmianie prędkości.

## Automatyczne katalogi własnych modeli

- 41 testów poza UE: generowanie nowej klasy, metadane bez `unreal`, zachowanie
  innych modeli, aktualizacja podzbioru, usuniętych klipów i niezmienionych danych.
- Sprawdzone odrzucanie kolizji nazw i nieprawidłowych czasów bez naruszenia pliku
  oraz dodanie nowej klasy do już załadowanego modułu.
- `tools/smoke_automatic_catalog.py` zaliczony w UE: pierwszy import pod nazwą
  StudentCatalogSmoke, automatyczny zapis dwóch klipów, odczyt wygenerowanego enuma
  i użycie go do animacji z automatycznym końcem. Katalog testowy zapisano w build.
- Zwykły hook odświeżył także pełne katalogi Fighter i Creature z istniejących assetów.

## keep_end_position

- 45 testów poza UE: dodatkowo pozioma interpolacja ruchu, sumowanie pętli,
  włączenie przeniesienia do Transform i ponowne użycie jednej kopii klipu.
- `tools/smoke_keep_end_position.py` zaliczony w UE: slash_2 od klatki 57 przy
  30 FPS, wejście slash_3 w klatce 161. Zapisane rzeczywiste klucze rodzica;
  po klatce 163 aktor zachowuje około 354 cm przesunięcia dla modelu wysokości 200 cm.
- Sprawdzone ciągłe położenie bioder przy przejściu, brak podwojenia przesunięcia,
  niezmieniona źródłowa animacja, ponowne wykonanie i render klatki po ataku.
- Przenoszony jest poziomy ruch pierwszej kości szkieletu (Hips w tym modelu).
  Pionowe ruchy i obroty kości zostają w klipie; kopie są w wygenerowanym folderze RootMotion.

## Odczyt pozycji i ruch względny

- 49 testów poza UE: odczyt istniejących kanałów pozycji, pozycja startowa bez
  ścieżki, dodanie względnego offsetu oraz walidacja bez tworzenia częściowych kluczy.
- `tools/smoke_relative_move.py` zaliczony w UE: creature wysokości 300 cm,
  start `(0, -850, 0)`, MUTANT_RUN z keep_end_position, swiping i walking.
- Pozycja w klatce 80 odczytana z natywnych krzywych Sequencera. Ruch 80–120
  zwiększył Y dokładnie o 50 cm, zachował punkt początkowy i pozycję po klatce 120.
  Sprawdzono też interpolowaną pozycję w środku ruchu.

## Cofanie i zastępowanie trasy

- 53 testy poza UE: odwrócone odtwarzanie, cofanie ruchu po nierównomiernej krzywej,
  sumowanie pętli do tyłu, usuwanie kluczy wewnątrz move i przesuwanie późniejszych.
- `tools/smoke_reverse_walk.py` zaliczony w UE: run → swiping → walking z reverse,
  naturalny ruch wstecz oraz zastąpienie trasy cofnięciem o 200 cm.
- Sprawdzone pozycje początkowa, środkowa i końcowa, brak wewnętrznych kluczy
  z poprzedniej trasy i zachowanie względnego ruchu późniejszego klucza.

## Zachowanie końcowej pozy

- 55 testów poza UE: natywne Keep State, zamrożony odcinek końcowej pozy oraz
  skracanie tego odcinka, gdy pojawi się następny klip tej samej postaci.
- `tools/smoke_keep_end_pose.py`: śmierć mutanta od klatki 0 przy 30 FPS, render
  klatki 299 po zakończeniu klipu. Wizualnie sprawdzono, że mutant leży na ziemi.
- Samo Keep State dawało w takim renderze pozę referencyjną; dodatkowy odcinek
  z prędkością 0 i przesunięciem czasu do końca klipu utrzymuje właściwą pozę.

## Rodzaje świateł i klucze światła

- 60 testów poza UE: klucze koloru i jasności, ponowne użycie tracków oraz
  odrzucanie błędnych argumentów bez tworzenia tracka.
- `tools/smoke_lights.py` w UE: point, spot i sun w jednej scenie, render klatek
  0, 24 i 47. Wizualnie sprawdzono zmianę koloru reflektora z czerwonego na niebieski
  oraz wzrost jasności reflektora i żarówki.
- Domyślne `intensity=500` słońca dobrano do stałej ekspozycji `camera.create`;
  przy `intensity=1` słońce nie było widoczne na renderze.