Review PR #159 — Trainset spawning, various Lua scripting changes

Autor: @jakubg1 · base: master · 10 plików, +65/−38 · ostatnia aktualizacja 21.10 https://github.com/MaSzyna-EU07/maszyna/pull/159

Werdykt: Request changes — otwarte uwagi z rundy 21.10 nadal aktualne

Podsumowanie

api.spawn_trainset(trainset) w Lua — cały wpis trainset … endtrainset jak ze Startera.
state_serializer::insert_trainset_full().
Rejestracja źródeł dymu i świateł pojazdu przeniesiona z deserialize_node() do TDynamicObject::Init() (init_smoke_sources()), więc działa też dla pojazdów wstawianych w trakcie symulacji.
insert_trainset() dostaje parametr Velocity.

Warunek świateł w Init() ma już poprawne nawiasy (CategoryFlag == 1 && (front || rear)) — uwaga @jerrrrycho z 04.09 zaadresowana. ✔
Init() zwraca 0.0 (porażka, pojazd jest potem kasowany) tylko przed TurnOff(), czyli przed nową rejestracją dymu/świateł — więc brak wiszących wskaźników w Particles/Lights. ✔ Wyjątek: pojazd z Dim.L == 0 w .fiz przejdzie rejestrację, a potem zostanie usunięty jako „błąd”. Rzadkie, ale warto zabezpieczyć (rejestrować po sprawdzeniu długości albo wyrejestrować przy delete).

Pętla w insert_trainset_full() nie zatrzymuje się na endtrainset. Przykład @jerrrrycho: dwa składy w jednym stringu → oba wylądują na torze pierwszego. Do tego brak endtrainset nie daje błędu, a skład zostaje „w połowie”. Proponuję: czytać node aż do endtrainset; jeśli go nie ma — ErrorLog i usunąć już utworzone pojazdy (albo jasno udokumentować, że zostają).
lua_tostring() może zwrócić NULL (argument nie jest stringiem/liczbą) → std::string z nullptr = UB/crash. Zapowiedziany osobny PR dla wszystkich funkcji API jest OK, ale dla nowej funkcji to jedna linia: luaL_checkstring(L, 1).
Unikalne nazwy pojazdów. Ponowne wywołanie z tym samym wpisem tworzy duplikaty nazw (Vehicles.insert zwróci false, log „duplicate vehicle name”), a pojazd i tak zostaje w świecie. Dla API skryptowego, które z założenia będzie wołane wielokrotnie, warto automatyczny sufiks albo jawny błąd i odrzucenie.

Parametr Velocity w insert_trainset() — oba wywołania podają 0, a insert_trainset_full() go nie używa. Jeśli to przygotowanie pod przyszłość — lepiej dodać go w PR, który go użyje (YAGNI).
init_smoke_sources() const — metoda const, która rejestruje this w globalnym menedżerze cząsteczek. Kompiluje się (jest przeciążenie insert(…, TDynamicObject const*, …)), ale semantycznie to efekt uboczny; bez const będzie czytelniej.
Synchroniczne ładowanie (zamrożenie przy spawnie) — zaakceptowane w dyskusji; warto dopisać to w dokumentacji funkcji Lua.
Test dymu i świateł — @jakubg1 sam prosił o sprawdzenie, że dym i światła pojawiają się poprawnie. Proszę o potwierdzenie (np. zrzut parowozu z dymem i składu z oświetleniem czoła) zarówno dla scenerii wczytanej, jak i składu ze spawn_trainset.
Tytuł/opis: „various Lua scripting changes”, a dochodzi jedna funkcja — opis do zaktualizowania. Historia commitów jest pomieszana (autor sam to pisze), więc squash przy merge.
Formatowanie: mieszane tabulatory/spacje w DynObj.h i simulationstateserializer.cpp (if (!vehicle) + tab).