more features

docs/cheatsheet.md

@@ -43,12 +43,19 @@ daje szerszy kadr. Zakres: `0 < fov < 180`. Domyślne `43.6` odpowiada obiektywo
 | Własna mapa | `scene = Scene("MyShot")` |
 | Kolor PBR (wartości liniowe 0–1) | `mat = materials.color("Red", (0.8, 0.02, 0.01), roughness=0.4)` |
 | Prosta postać | `actor = scene.character(material=mat, head_scale=1.3)` |
+| Kilka prostych postaci | `scene.character(material=mat, name="Bob", location=(200, 0, 0))` |
 | Bryła | `scene.primitive("Sphere", name="Ball", location=(0, 100, 50), material=mat)` |
+| Pochyła bryła | `scene.primitive("Cube", name="Ramp", scale=(2, 2, 0.2), rotation=(0, 30, 0))` |
+| Zmiana materiału, także modelu | `materials.assign(character, mat)` |
+| Powtarzana tekstura | `materials.texture_set("Floor", base_color="textures/floor.png", tiling=8)` |
 | Import statycznego modelu | `mesh = assets.import_model("C:/models/model.glb", name="MyModel")` |
 | Eksport + import Blendera | `mesh = blender.import_character("C:/models/character.blend")` |
 | Model na scenie | `actor = scene.mesh(mesh, name="Hero")` |
-| Import z dopasowaniem rozmiaru i pivotu | `actor = scene.model("source_assets/models/hero.glb", name="Hero", height=200)` |
+| Import z dopasowaniem rozmiaru i pivotu | `actor = scene.model("source_assets/models/hero.glb", name="Hero", height=200, location=(0, 100, 0))` |
 | Korekta osi modelu przed dopasowaniem | `actor = scene.model("hero.fbx", rotation=(0, 0, 90))` |
+| Niebo, słońce, światło otoczenia | `lighting.environment(scene)` |
+| Zachód słońca z mgłą | `lighting.environment(scene, sun_angle=5, sun_yaw=90, fog=0.02)` |
+| Noc | `lighting.environment(scene, sky=False, sun_intensity=0, ambient=0.3)` |
 | Światła studyjne | `lights = lighting.studio(scene)` |
 | Pojedyncze światło | `lighting.area(scene, location=(200, -200, 350), intensity=10000, color=(1, 0.5, 0.2))` |
 | Żarówka | `lamp = lighting.point(scene, location=(0, 0, 250), intensity=10000, color=(1, 0.5, 0.2))` |
@@ -58,6 +65,14 @@ daje szerszy kadr. Zakres: `0 < fov < 180`. Domyślne `43.6` odpowiada obiektywo
 | Zmiana kierunku | `camera.look_at(cam, (0, 0, 150))` |
 | Sekwencja | `shot = Sequence(scene, fps=24, frames=48)` |
 | Aktywna kamera | `shot.camera(cam)` |
+| Cięcie na drugą kamerę | `shot.camera(cam2, start=60)` albo `shot.camera(cam2, start=60, end=90)` |
+| Sekundy na klatki | `shot.seconds(2.5)` |
+| Następny klip po poprzednim | `shot.then(character, clip)` |
+| To samo z przejściem 10 klatek | `shot.then(character, clip, overlap=10)` |
+| Obrót względny | `shot.rotate(actor, start=0, end=24, offset=(0, 0, 90))` |
+| Odczyt rotacji | `shot.rotation(actor, frame=24)` |
+| Pojawienie się od klatki 60 | `shot.visible(actor, 60)` |
+| Zniknięcie od klatki 60 | `shot.visible(actor, 60, False)` |
 | Klucz pozycji | `shot.transform_key(actor, 0, location=(0, 0, 0))` |
 | Klucz rotacji | `shot.transform_key(actor, 47, rotation=(0, 0, 360))` |
 | Klucz skali | `shot.transform_key(actor, 24, scale=(1.2, 1.2, 1.2), interpolation="auto")` |
@@ -67,6 +82,7 @@ daje szerszy kadr. Zakres: `0 < fov < 180`. Domyślne `43.6` odpowiada obiektywo
 | Własny renderer | `renderer = Renderer(width=1920, height=1080, samples=8, warmup=32, mp4=True)` |
 | Preset z własnymi wartościami | `renderer = Renderer.from_preset("final", samples=8)` |
 | Render z własnymi ustawieniami | `renderer.render(shot)` |
+| Muzyka w MP4 (przycięta do długości filmu) | `Renderer(audio="source_assets/music.mp3")` |
 | Podgląd tym samym rendererem | `renderer.render(shot, single_frame=24)` |
 | PNG + MP4 | `render.start(shot, preset="preview")` |
 | Tylko PNG | `render.start(shot, mp4=False)` |
@@ -99,6 +115,10 @@ shot.animation(character)  # tylko gdy postac ma jedna dostepna animacje
 # shot.animation(character, "idle", start=48, end=120)  # automatyczny blend 12 klatek
 ```
 
+`shot.rotate` obraca aktora, ale `keep_end_position` dalej przesuwa go w kierunku
+sprzed obrotu. Po skręcie użyj klipu In Place i `shot.move` w nowym kierunku.
+Muzyka trafia tylko do MP4; Sequencer odtwarza film bez dźwięku.
+
 Krótsza animacja zapętla się w swojej sekcji. `transform_key` porusza całym aktorem
 równolegle z animacją kości. Do własnych tras wybieraj klipy In Place.
 Blender: kolekcja `Character`, siatki przypisane do jednego Armature, aktywna akcja

docs/validation.md

@@ -173,3 +173,15 @@ Nie sprawdzano retargetingu, Animation Blueprintów ani eksportu wielu akcji/NLA
   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.
+
+## Podstawowe operacje sceny
+
+- 86 testów poza UE: cięcia kamer, widoczność z dołączonymi aktorami, względna
+  rotacja, `then`, `seconds`, `materials.assign` oraz MP4 z dźwiękiem przyciętym do filmu.
+- `tools/smoke_basics.py` w UE: 48 klatek, trzy odcinki dwóch kamer, render MP4
+  ze ścieżką AAC. Wizualnie sprawdzono cięcia, pojawianie i znikanie obiektów,
+  czerwony materiał na fighterze, `tiling=8`, pochyłą bryłę i obrót postaci.
+- `lighting.environment` sprawdzone wizualnie: dzień, mgła, zachód, noc i `sky=False`.
+- Bez `lighting.environment` odsłonięte tło może być białe, np. przy samej żarówce.
+  Przy niebie na małej podłodze widać ciemny pas pod horyzontem; mgła go ukrywa.
+- `shot.visible` wyłącza też światło: sprawdzone na żarówce między dwiema klatkami.