v1.2.8

Author: bochkarnikov-victor

docs/game_loop.md

@@ -41,13 +41,57 @@ while True:
     s.update(fill_color=(10, 10, 20))
 ```
 
+Важно: если переключаете сцену прямо в `update`, завершайте метод сразу после `set_scene_by_name`, чтобы не запускать логику кадра дальше.
+
+```python
+def update(self, dt):
+    if s.input.was_pressed(pygame.K_RETURN):
+        s.set_scene_by_name("menu")
+        return
+```
+
 Перезапуск сцены:
 
 ```python
 s.restart_scene()          # текущая сцена
 s.restart_scene("main")    # по имени
 ```
 
+## Несколько активных сцен
+
+Можно держать активными несколько сцен одновременно (например, игра + UI).
+
+```python
+s.set_scene_by_name("game")
+s.activate_scene("hud")
+print(s.is_scene_active("hud"))
+
+for scene in s.get_active_scenes():
+    print(scene.name, scene.is_active)
+```
+
+Отключение сцены:
+
+```python
+s.deactivate_scene("hud")
+```
+
+### Порядок обновления и отрисовки
+
+У каждой сцены есть поле `order` (по умолчанию 0). Чем выше значение, тем позже сцена обновляется и рисуется.
+
+```python
+game_scene.order = 0
+hud_scene.order = 10
+s.activate_scene(hud_scene)
+```
+
+Или через менеджер:
+
+```python
+s.set_scene_order("hud", 10)
+```
+
 ## Таймеры в сценах
 
 ### Вариант 1: Через dt

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spritepro"
-version = "1.2.5"
+version = "1.2.8"
 authors = [
   { name="NeoXider", email="neoxider@gmail.com" },
 ]

spritePro/__init__.py

@@ -586,6 +586,41 @@ def set_scene_by_name(name: str, recreate: bool = False) -> None:
     _context.scene_manager.set_scene_by_name(name, _context, recreate=recreate)
 
 
+def activate_scene(scene_or_name: Scene | str) -> None:
+    """Активирует сцену, не отключая другие."""
+    _context.scene_manager.activate_scene(scene_or_name, _context)
+
+
+def deactivate_scene(scene_or_name: Scene | str) -> None:
+    """Деактивирует сцену."""
+    _context.scene_manager.deactivate_scene(scene_or_name)
+
+
+def set_active_scenes(scenes_or_names: list[Scene | str]) -> None:
+    """Устанавливает список активных сцен."""
+    _context.scene_manager.set_active_scenes(scenes_or_names, _context)
+
+
+def get_active_scenes() -> list[Scene]:
+    """Возвращает список активных сцен."""
+    return _context.scene_manager.get_active_scenes()
+
+
+def is_scene_active(scene_or_name: Scene | str) -> bool:
+    """Проверяет, активна ли сцена."""
+    return _context.scene_manager.is_scene_active(scene_or_name)
+
+
+def set_scene_order(scene_or_name: Scene | str, order: int) -> None:
+    """Устанавливает порядок отрисовки/обновления сцены."""
+    _context.scene_manager.set_scene_order(scene_or_name, order)
+
+
+def get_current_scene() -> Scene | None:
+    """Возвращает текущую сцену."""
+    return _context.scene_manager.current_scene
+
+
 def restart_scene(name: str | None = None) -> None:
     """Перезапускает сцену по имени или текущую сцену."""
     if name is None:

spritePro/audio/audio_manager.py

@@ -85,17 +85,16 @@ def load_sound(self, name: str, path: str) -> "Sound":
             >>> jump_sound = audio.load_sound("jump", "sounds/jump.mp3")
             >>> jump_sound.play()  # Можно сразу использовать!
         """
-        try:
-            cached = resource_cache.load_sound(path)
-            if cached is None:
-                cached = pygame.mixer.Sound(path)
-            self.sounds[name] = cached
-            return Sound(self, name)
-        except pygame.error as e:
+        cached = resource_cache.load_sound(path)
+        if cached is None:
             import spritePro
 
-            spritePro.debug_log_warning(f"Sound not loaded '{name}' from '{path}': {e}")
+            spritePro.debug_log_warning(
+                f"Sound not loaded '{name}' from '{path}': cache load returned None"
+            )
             return Sound(self, name)  # Возвращаем объект даже при ошибке
+        self.sounds[name] = cached
+        return Sound(self, name)
 
     def play_sound(self, name_or_path: str, volume: Optional[float] = None) -> None:
         """Воспроизвести звуковой эффект.
@@ -125,15 +124,18 @@ def play_sound(self, name_or_path: str, volume: Optional[float] = None) -> None:
             sound.set_volume(volume if volume is not None else self.sfx_volume)
             sound.play()
         else:
-            # Пытаемся загрузить и воспроизвести напрямую из файла
-            try:
-                sound = pygame.mixer.Sound(name_or_path)
-                sound.set_volume(volume if volume is not None else self.sfx_volume)
-                sound.play()
-            except pygame.error as e:
+            # Пытаемся загрузить и воспроизвести из кэша
+            sound = resource_cache.load_sound(name_or_path)
+            if sound is None:
                 import spritePro
 
-                spritePro.debug_log_warning(f"Sound not played '{name_or_path}': {e}")
+                spritePro.debug_log_warning(
+                    f"Sound not played '{name_or_path}': cache load returned None"
+                )
+                return
+            self.sounds[name_or_path] = sound
+            sound.set_volume(volume if volume is not None else self.sfx_volume)
+            sound.play()
 
     def play_music(
         self, path: str, loop: bool = True, volume: Optional[float] = None
@@ -158,7 +160,7 @@ def play_music(
             pygame.mixer.music.set_volume(music_vol)
             pygame.mixer.music.play(-1 if loop else 0)
             self.current_music = path
-        except pygame.error as e:
+        except Exception as e:
             import spritePro
 
             spritePro.debug_log_warning(f"Music not loaded '{path}': {e}")

spritePro/demoGames/input_events_demo.py

@@ -25,7 +25,7 @@ def main():
     s.events.connect("key_down", on_key_down)
     s.events.connect("quit", on_quit)
 
-    player = s.Sprite("", (60, 60), (400, 300), speed=260)
+    player = s.Sprite("", (60, 60), (400, 300), speed=5)
     player.set_color((120, 200, 255))
     player.angle = 0
 

spritePro/demoGames/particles_images_demo.py

@@ -18,12 +18,16 @@
     sys.path.insert(0, str(parent_dir))
 
 import spritePro as s
+from spritePro.resources import resource_cache
 from spritePro.particles import ParticleConfig, ParticleEmitter
 
 
 def load_image(name: str) -> pygame.Surface:
     sprites_dir = current_dir / "Sprites"
-    img = pygame.image.load(str(sprites_dir / name)).convert_alpha()
+    img = resource_cache.load_texture(str(sprites_dir / name))
+    if img is None:
+        img = pygame.Surface((16, 16), pygame.SRCALPHA)
+        img.fill((255, 255, 255, 255))
     return img
 
 

spritePro/demoGames/particles_stress_demo.py

@@ -0,0 +1,91 @@
+"""
+Particles Stress Demo - SpritePro
+
+Spawns 10k image particles every second and shows timings.
+"""
+
+import sys
+from pathlib import Path
+import time
+
+import pygame
+
+current_dir = Path(__file__).parent
+parent_dir = current_dir.parent.parent
+if str(parent_dir) not in sys.path:
+    sys.path.insert(0, str(parent_dir))
+
+import spritePro as s  # noqa: E402
+from spritePro.particles import ParticleConfig, ParticleEmitter  # noqa: E402
+from spritePro.readySprites import Text_fps  # noqa: E402
+from spritePro.resources import resource_cache  # noqa: E402
+
+
+TEXTURE_PATH = "spritePro/demoGames/Sprites/c.png"
+BURST_COUNT = 1_00
+BURST_INTERVAL = 0.1
+
+
+def _load_particle_image() -> pygame.Surface:
+    img = resource_cache.load_texture(TEXTURE_PATH)
+    if img is None:
+        img = pygame.Surface((24, 24), pygame.SRCALPHA)
+        img.fill((255, 255, 255, 255))
+    return img
+
+
+def main() -> None:
+    s.init()
+    screen = s.get_screen((900, 600), "Particles Stress Demo")
+    center = screen.get_rect().center
+
+    image = _load_particle_image()
+    cfg = ParticleConfig(
+        amount=BURST_COUNT,
+        lifetime_range=(1.5, 2.0),
+        speed_range=(40.0, 160.0),
+        fade_speed=220.0,
+        image=image,
+        image_scale_range=(0.05, 0.4),
+        angle_range=(0.0, 360.0),
+        spawn_circle_radius=30,
+    )
+    emitter = ParticleEmitter(cfg, use_pool=True, max_pool_size=BURST_COUNT * 2)
+
+    fps_counter = Text_fps(
+        pos=(10, 8), color=(255, 255, 0), prefix="FPS: ", precision=1
+    )
+    stats = s.TextSprite("", 20, (200, 220, 255), (450, 40))
+    _hint = s.TextSprite(
+        f"Spawn: {BURST_COUNT} particles every {BURST_INTERVAL:.1f}s",
+        18,
+        (180, 180, 180),
+        (450, 70),
+    )
+
+    total_emitted = 0
+    last_emit_ms = 0.0
+    last_emit_count = 0
+
+    def emit_burst() -> None:
+        nonlocal total_emitted, last_emit_ms, last_emit_count
+        start = time.perf_counter()
+        particles = emitter.emit(center)
+        last_emit_ms = (time.perf_counter() - start) * 1000.0
+        last_emit_count = len(particles)
+        total_emitted += last_emit_count
+        stats.set_text(
+            f"Burst: {last_emit_count} | Total: {total_emitted} | Emit: {last_emit_ms:.2f}ms"
+        )
+
+    stats.set_text("Waiting for burst...")
+    s.Timer(BURST_INTERVAL, callback=emit_burst, repeat=True, autostart=True)
+    emit_burst()
+
+    while True:
+        fps_counter.update_fps()
+        s.update(fill_color=(12, 12, 20))
+
+
+if __name__ == "__main__":
+    main()

spritePro/demoGames/ping_pong.py

@@ -318,16 +318,15 @@ def update_sprite_visibility():
 for bt in bts.values():
     bt.set_image(round_corners(bt.image, 50))
 
+bg_surface = spritePro.load_texture(path / "Sprites" / "bg.jpg")
+if bg_surface is None:
+    bg_surface = pygame.Surface(spritePro.WH)
+    bg_surface.fill((20, 20, 20))
+bg_scaled = pygame.transform.scale(bg_surface, spritePro.WH)
 BGS = {
-    STATE_MENU: pygame.transform.scale(
-        pygame.image.load(path / "Sprites" / "bg.jpg"), (spritePro.WH)
-    ),
-    STATE_SHOP: pygame.transform.scale(
-        pygame.image.load(path / "Sprites" / "bg.jpg"), (spritePro.WH)
-    ),
-    STATE_GAME: pygame.transform.scale(
-        pygame.image.load(path / "Sprites" / "bg.jpg"), (spritePro.WH)
-    ),
+    STATE_MENU: bg_scaled,
+    STATE_SHOP: bg_scaled,
+    STATE_GAME: bg_scaled,
 }