pyengine-x 0.1.0__py3-none-any.whl

pyengine/figure.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+import math
+import pygame
+from typing import Literal, TYPE_CHECKING
+
+ShapeType = Literal['rect', 'circle', 'ellipse', 'line', 'polygon', 'sprite']
+
+# ――――――――――――――――――――――――― figure ―――――――――――――――――――――――――
+class Figure:
+    def __init__(
+        self,
+        screen: pygame.Surface,
+        shape: ShapeType,
+        color: tuple,
+        params: tuple,
+        width: int = 0,
+        images: dict[str, pygame.Surface] | None = None,
+        use_camera: bool = True,
+    ):
+        self.screen = screen
+        self.shape = shape
+        self.color = color
+        self.params: list = list(params)
+        self.width = width
+        self.images = images
+        self.last_contact_time: float = 0
+        self.use_camera: bool = use_camera
+        
+        # Анимации
+        self.current_anim: str | None = None
+        self.anim_frame: int = 0
+        self.anim_timer: float = 0.0
+        self.anim_finished: bool = False
+        
+        # x/y are always kept in sync with params[0]/[1] via set_pos
+        self.x: float = float(params[0])
+        self.y: float = float(params[1])
+        self.image_name: str | None = params[2] if shape == 'sprite' and len(params) >= 3 else None
+
+    # ――――――――――――――――――――――――― animations ―――――――――――――――――――――――――
+    def play(self, anim_name: str):
+        """
+        Запускает указанную анимацию, сбрасывая текущий кадр и таймер.
+        - anim_name (str): Имя анимации, зарегистрированной в engine.add_animation.
+        """
+        self.current_anim = anim_name
+        self.anim_frame = 0
+        self.anim_timer = 0.0
+        self.anim_finished = False
+
+    def _update_animation(self, animations: dict, dt: float):
+        """
+        Внутренний метод: обновляет кадр анимации на основе прошедшего времени.
+        Вызывается автоматически движком в главном цикле.
+        """
+        if self.current_anim and self.current_anim in animations:
+            if self.anim_finished:
+                return
+                
+            anim = animations[self.current_anim]
+            self.anim_timer += dt
+            frame_duration = 1.0 / anim['fps']
+            
+            if self.anim_timer >= frame_duration:
+                self.anim_timer -= frame_duration
+                
+                if self.anim_frame < len(anim['frames']) - 1:
+                    self.anim_frame += 1
+                    self.set_image(anim['frames'][self.anim_frame])
+                else:
+                    if anim.get('loop', True):
+                        self.anim_frame = 0
+                        self.set_image(anim['frames'][0])
+                    else:
+                        self.anim_finished = True
+
+    # ――――――――――――――――――――――――― position ―――――――――――――――――――――――――
+    def set_pos(self, x: float, y: float):
+        """
+        Устанавливает новые координаты фигуры, автоматически синхронизируя внутренние переменные и параметры отрисовки.
+        """
+        self.x = x
+        self.y = y
+        self.params[0] = x
+        self.params[1] = y
+        if self.shape == 'sprite':
+            self.params[2] = self.image_name
+
+    def move(self, dx: float, dy: float):
+        """
+        Смещает фигуру на заданное расстояние (dx, dy) по осям X и Y относительно её текущей позиции.
+        """
+        self.set_pos(self.x + dx, self.y + dy)
+
+    def clamp_to_screen(self):
+        """
+        Ограничивает позицию фигуры границами экрана, не позволяя ей визуально выйти за его пределы.
+        """
+        fx, fy, fw, fh = self.get_bounds()
+        sw, sh = self.screen.get_width(), self.screen.get_height()
+        nx, ny = self.x, self.y
+        if fx + fw > sw:
+            nx = self.x + (sw - (fx + fw))
+        elif fx < 0:
+            nx = self.x - fx
+        if fy + fh > sh:
+            ny = self.y + (sh - (fy + fh))
+        elif fy < 0:
+            ny = self.y - fy
+        self.set_pos(nx, ny)
+
+    # ――――――――――――――――――――――――― draw ―――――――――――――――――――――――――
+    def draw(self, screen: pygame.Surface, offset: tuple[float, float] = (0.0, 0.0)):
+        """
+        Отрисовывает фигуру на экране. Принимает опциональный параметр offset для учёта смещения камеры.
+        """
+        ox, oy = offset
+        p = self.params
+        draw_x = p[0] + ox
+        draw_y = p[1] + oy
+
+        if self.shape == 'rect':
+            pygame.draw.rect(screen, self.color, (draw_x, draw_y, p[2], p[3]), self.width)
+        elif self.shape == 'circle':
+            pygame.draw.circle(screen, self.color, (int(draw_x), int(draw_y)), int(p[2]), self.width)
+        elif self.shape == 'ellipse':
+            pygame.draw.ellipse(screen, self.color, (draw_x, draw_y, p[2], p[3]), self.width)
+        elif self.shape == 'line':
+            pygame.draw.line(screen, self.color, (draw_x, draw_y), (p[2] + ox, p[3] + oy), max(1, self.width))
+        elif self.shape == 'polygon':
+            shifted_pts = [(pt[0] + ox, pt[1] + oy) for pt in p[0]]
+            pygame.draw.polygon(screen, self.color, shifted_pts, self.width)
+        elif self.shape == 'sprite':
+            if self.images and self.image_name and self.image_name in self.images:
+                screen.blit(self.images[self.image_name], (int(draw_x), int(draw_y)))
+
+    def set_image(self, image_name: str):
+        """
+        Меняет изображение спрайта на другое из загруженного набора (работает только для фигур с shape='sprite').
+        """
+        if self.shape == 'sprite' and self.images and image_name in self.images:
+            self.image_name = image_name
+            self.params[2] = image_name
+
+    # ――――――――――――――――――――――――― geometry ―――――――――――――――――――――――――
+    @property
+    def radius(self) -> float:
+        """Возвращает радиус фигуры. Работает только для круга. Для остальных форм возвращает 0.0."""
+        return float(self.params[2]) if self.shape == 'circle' else 0.0
+
+    def get_center(self) -> tuple[float, float]:
+        """
+        Возвращает координаты (x, y) геометрического центра фигуры.
+        """
+        p = self.params
+        if self.shape == 'circle':
+            return (p[0], p[1])
+        if self.shape in ('rect', 'ellipse'):
+            return (p[0] + p[2] / 2, p[1] + p[3] / 2)
+        if self.shape == 'sprite' and self.images and self.image_name in self.images:
+            img = self.images[self.image_name]
+            return (p[0] + img.get_width() / 2, p[1] + img.get_height() / 2)
+        if self.shape == 'line':
+            return ((p[0] + p[2]) / 2, (p[1] + p[3]) / 2)
+        return (0.0, 0.0)
+
+    def get_bounds(self) -> tuple[float, float, float, float]:
+        """
+        Возвращает ограничивающий прямоугольник фигуры в формате (x, y, ширина, высота) для расчетов коллизий.
+        """
+        p = self.params
+        if self.shape in ('rect', 'ellipse'):
+            return (p[0], p[1], p[2], p[3])
+        if self.shape == 'circle':
+            r = p[2]
+            return (p[0] - r, p[1] - r, r * 2, r * 2)
+        if self.shape == 'sprite' and self.images and self.image_name in self.images:
+            img = self.images[self.image_name]
+            return (p[0], p[1], float(img.get_width()), float(img.get_height()))
+        if self.shape == 'line':
+            x1, y1, x2, y2 = p[0], p[1], p[2], p[3]
+            w = abs(x2 - x1) or 1.0
+            h = abs(y2 - y1) or 1.0
+            return (min(x1, x2), min(y1, y2), w, h)
+        if self.shape == 'polygon':
+            pts = p[0]
+            xs = [pt[0] for pt in pts]
+            ys = [pt[1] for pt in pts]
+            return (min(xs), min(ys), max(xs) - min(xs), max(ys) - min(ys))
+        return (0.0, 0.0, 0.0, 0.0)
+
+    # ――――――――――――――――――――――――― collision response ―――――――――――――――――――――――――
+    def push_out(self, other: Figure):
+        """
+        Выталкивает текущую фигуру из другой фигуры, если они пересеклись. Используется для физического разрешения коллизий.
+        """
+        if self.shape == 'circle' and other.shape == 'circle':
+            dx = self.x - other.x
+            dy = self.y - other.y
+            dist = math.hypot(dx, dy)
+            min_dist = self.radius + other.radius
+            if dist == 0:
+                self.set_pos(self.x + min_dist, self.y)
+                return
+            if dist < min_dist:
+                overlap = min_dist - dist
+                nx, ny = dx / dist, dy / dist
+                self.set_pos(self.x + nx * overlap, self.y + ny * overlap)
+            return
+            
+        x1, y1, w1, h1 = self.get_bounds()
+        x2, y2, w2, h2 = other.get_bounds()
+        if w1 == 0 or w2 == 0:
+            return
+            
+        ol = (x1 + w1) - x2
+        or_ = (x2 + w2) - x1
+        ot = (y1 + h1) - y2
+        ob = (y2 + h2) - y1
+        if ol <= 0 or or_ <= 0 or ot <= 0 or ob <= 0:
+            return
+            
+        m = min(ol, or_, ot, ob)
+        if m == ol:
+            self.set_pos(self.x - ol, self.y)
+        elif m == or_:
+            self.set_pos(self.x + or_, self.y)
+        elif m == ot:
+            self.set_pos(self.x, self.y - ot)
+        else:
+            self.set_pos(self.x, self.y + ob)

pyengine/scene.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+import pygame
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .engine import PyEngine
+
+
+# ――――――――――――――――――――――――― scene base ―――――――――――――――――――――――――
+
+
+class Scene:
+    def __init__(self, engine: PyEngine):
+        self.engine = engine
+        self.screen = engine.screen
+        self.width = engine.width
+        self.height = engine.height
+
+    # ――――――――――――――――――――――――― lifecycle ―――――――――――――――――――――――――
+
+    def on_enter(self, **kwargs):
+        """
+        Вызывается при активации (входе) в сцену. Используется для инициализации объектов, загрузки ресурсов и настройки начального состояния.
+        """
+        pass
+
+    def on_exit(self):
+        """
+        Вызывается при выходе из сцены. Используется для очистки ресурсов, сохранения состояния или остановки музыки.
+        """
+        pass
+
+    # ――――――――――――――――――――――――― per-frame ―――――――――――――――――――――――――
+
+    def events(self, event: pygame.event.Event):
+        """
+        Обрабатывает события pygame (нажатия клавиш, движения мыши и т.д.) для текущей активной сцены.
+        """
+        pass
+
+    def update(self):
+        """
+        Обновляет внутреннюю логику сцены (физика, ИИ, состояния объектов) перед каждым кадром отрисовки.
+        """
+        pass
+
+    def draw(self):
+        """
+        Отрисовывает все визуальные элементы текущей сцены на экран.
+        """
+        pass

pyengine/sound.py

@@ -0,0 +1,102 @@
+import pygame
+
+
+# ――――――――――――――――――――――――― sound mixin ―――――――――――――――――――――――――
+
+
+class Sound:
+    def __init__(self):
+        self.sounds: dict[str, pygame.mixer.Sound] = {}
+        self.playing_sounds: dict[str, pygame.mixer.Sound] = {}
+
+    # ――――――――――――――――――――――――― sfx ―――――――――――――――――――――――――
+
+    def load_sound(self, name: str, path: str):
+        """
+        Загружает звуковой эффект (sfx) из файла и сохраняет его в памяти под указанным именем.
+        """
+        self.sounds[name] = pygame.mixer.Sound(path)
+
+    def play_sound(self, name: str, loop: bool = False):
+        """
+        Воспроизводит загруженный звуковой эффект. Если loop=True, зацикливает его воспроизведение.
+        """
+        if name not in self.sounds:
+            print(f"sound '{name}' not found")
+            return
+        sound = self.sounds[name]
+        sound.play(loops=-1 if loop else 0)
+        self.playing_sounds[name] = sound
+
+    def stop_sound(self, name: str):
+        """
+        Останавливает воспроизведение указанного звукового эффекта.
+        """
+        if name in self.playing_sounds:
+            self.playing_sounds[name].stop()
+            del self.playing_sounds[name]
+
+    def set_sound_volume(self, name: str, volume: float):
+        """
+        Устанавливает громкость для конкретного звукового эффекта (значение от 0.0 до 1.0).
+        """
+        if name in self.sounds:
+            self.sounds[name].set_volume(volume)
+
+    # ――――――――――――――――――――――――― music ―――――――――――――――――――――――――
+
+    def load_music(self, path: str):
+        """
+        Загружает фоновую музыкальную композицию из файла (поддерживается только один трек одновременно).
+        """
+        pygame.mixer.music.load(path)
+
+    def play_music(self, loop: bool = False):
+        """
+        Начинает воспроизведение загруженной фоновой музыки. Если loop=True, зацикливает её.
+        """
+        pygame.mixer.music.play(loops=-1 if loop else 0)
+
+    def stop_music(self):
+        """
+        Полностью останавливает воспроизведение фоновой музыки.
+        """
+        pygame.mixer.music.stop()
+
+    def pause_music(self):
+        """
+        Приостанавливает воспроизведение музыки (можно продолжить позже через resume_music).
+        """
+        pygame.mixer.music.pause()
+
+    def resume_music(self):
+        """
+        Продолжает воспроизведение музыки с момента паузы.
+        """
+        pygame.mixer.music.unpause()
+
+    def set_music_volume(self, volume: float):
+        """
+        Устанавливает громкость фоновой музыки (значение от 0.0 до 1.0).
+        """
+        pygame.mixer.music.set_volume(volume)
+
+    def fade_in_music(self, seconds: float = 2.0, loop: bool = False):
+        """
+        Запускает воспроизведение музыки с плавным нарастанием громкости за указанное время (в секундах).
+        """
+        pygame.mixer.music.play(loops=-1 if loop else 0, fade_ms=int(seconds * 1000))
+
+    def fade_out_music(self, seconds: float = 2.0):
+        """
+        Плавно затухает и останавливает музыку за указанное время (в секундах).
+        """
+        pygame.mixer.music.fadeout(int(seconds * 1000))
+
+    def set_all_volume(self, volume: float):
+        """
+        Устанавливает заданную громкость одновременно для всех загруженных звуков и фоновой музыки.
+        """
+        for s in self.sounds.values():
+            s.set_volume(volume)
+        pygame.mixer.music.set_volume(volume)

pyengine/tilemap.py

@@ -0,0 +1,224 @@
+from __future__ import annotations
+import pygame
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from .engine import PyEngine
+
+# ――――――――――――――――――――――――― tile ―――――――――――――――――――――――――
+class Tile:
+    """Один тип тайла (плитки)"""
+    def __init__(
+        self, 
+        tile_id: int, 
+        color: tuple | None = None, 
+        image_name: str | None = None,
+        solid: bool = False,
+        exceptions: list[str] | None = None
+    ):
+        """
+        :tile_id: уникальный ID тайла
+        :color: цвет тайла (используется, если нет image_name)
+        :image_name: имя изображения из engine.images (приоритетнее цвета)
+        :solid: если True, фигуры не смогут проходить сквозь этот тайл
+        :exceptions: список названий фигур, которые МОГУТ проходить сквозь этот тайл
+        """
+        self.id = tile_id
+        self.color = color if color else (100, 100, 100)
+        self.image_name = image_name
+        self.solid = solid
+        self.exceptions = exceptions if exceptions else []
+
+# ――――――――――――――――――――――――― tileset ―――――――――――――――――――――――――
+class TileSet:
+    """Набор тайлов с общим размером"""
+    def __init__(self, tile_width: int = 32, tile_height: int = 32):
+        """
+        :tile_width: ширина одного тайла в пикселях
+        :tile_height: высота одного тайла в пикселях
+        """
+        self.tile_width = tile_width
+        self.tile_height = tile_height
+        self.tiles: dict[int, Tile] = {}
+
+    def add_tile(self, tile: Tile):
+        """Добавляет тайл в набор. Если тайл с таким ID уже существует, он будет перезаписан."""
+        self.tiles[tile.id] = tile
+
+# ――――――――――――――――――――――――― tilelayer ―――――――――――――――――――――――――
+class TileLayer:
+    """Один слой тайлов"""
+    def __init__(self, width: int, height: int, default_tile: int = 0):
+        """
+        :width: ширина слоя в тайлах
+        :height: высота слоя в тайлах
+        :default_tile: ID тайла по умолчанию (используется при создании и удалении)
+        """
+        self.width = width
+        self.height = height
+        self.default_tile = default_tile
+        self.data: list[list[int]] = [[default_tile for _ in range(width)] for _ in range(height)]
+
+    def set_tile(self, x: int, y: int, tile_id: int):
+        """
+        Устанавливает тайл с указанным ID в позицию (x, y).
+        Если координаты выходят за границы слоя, метод ничего не делает.
+        """
+        if 0 <= x < self.width and 0 <= y < self.height:
+            self.data[y][x] = tile_id
+
+    def get_tile(self, x: int, y: int) -> int:
+        """
+        Возвращает ID тайла в позиции (x, y).
+        Если координаты выходят за границы слоя, возвращает 0.
+        """
+        if 0 <= x < self.width and 0 <= y < self.height:
+            return self.data[y][x]
+        return 0
+    
+    def remove_tile(self, x: int, y: int):
+        """
+        Удаляет тайл из позиции (x, y), делая ячейку пустой (ID=0).
+        Пустые тайлы не отрисовываются, что позволяет видеть слои под ними.
+        Если координаты выходят за границы слоя, метод ничего не делает.
+        """
+        if 0 <= x < self.width and 0 <= y < self.height:
+            self.data[y][x] = self.default_tile
+
+# ――――――――――――――――――――――――― tilemap ―――――――――――――――――――――――――
+class TileMap:
+    """Двумерная карта тайлов с поддержкой нескольких слоев"""
+    def __init__(self, engine: PyEngine, tileset: TileSet, width: int, height: int):
+        """
+        :engine: экземпляр PyEngine
+        :tileset: набор тайлов (TileSet)
+        :width: ширина карты в тайлах
+        :height: высота карты в тайлах
+        """
+        self.engine = engine
+        self.tileset = tileset
+        self.width = width
+        self.height = height
+        
+        self.layers: list[TileLayer] = []
+        self.collision_layer_index: int = 0
+        
+        # Кеш отрендеренных слоев для ускорения отрисовки
+        self._layer_cache: dict[int, pygame.Surface | None] = {}
+
+    def add_layer(self, default_tile: int = 0) -> int:
+        """
+        Добавляет новый слой тайлов в карту.
+        Возвращает индекс созданного слоя (начинается с 0).
+        """
+        layer = TileLayer(self.width, self.height, default_tile)
+        self.layers.append(layer)
+        return len(self.layers) - 1
+
+    def set_tile(self, x: int, y: int, tile_id: int, layer_index: int = 0):
+        """
+        Устанавливает тайл с указанным ID в позицию (x, y) на заданном слое.
+        Если layer_index не указан, используется слой 0.
+        """
+        if 0 <= layer_index < len(self.layers):
+            self.layers[layer_index].set_tile(x, y, tile_id)
+            self._layer_cache[layer_index] = None  # Сбрасываем кеш
+
+    def get_tile(self, x: int, y: int, layer_index: int = 0) -> int:
+        """
+        Возвращает ID тайла в позиции (x, y) на заданном слое.
+        Если layer_index не указан, используется слой 0.
+        Если координаты или индекс слоя некорректны, возвращает 0.
+        """
+        if 0 <= layer_index < len(self.layers):
+            return self.layers[layer_index].get_tile(x, y)
+        return 0
+
+    def remove_tile(self, x: int, y: int, layer_index: int = 0):
+        """
+        Удаляет тайл из позиции (x, y) на заданном слое, делая ячейку пустой.
+        Пустые тайлы не отрисовываются, позволяя видеть нижние слои.
+        Если layer_index не указан, используется слой 0.
+        """
+        if 0 <= layer_index < len(self.layers):
+            self.layers[layer_index].remove_tile(x, y)
+            self._layer_cache[layer_index] = None  # Сбрасываем кеш
+
+    def is_solid(self, x: int, y: int, figure_name: str | None = None) -> bool:
+        """
+        Проверяет, является ли тайл в позиции (x, y) непроходимым.
+        Проверка выполняется только на слое collision_layer_index.
+        Если figure_name указан и находится в списке exceptions тайла, возвращается False.
+        """
+        if self.collision_layer_index >= len(self.layers):
+            return False
+        tile_id = self.get_tile(x, y, self.collision_layer_index)
+        tile = self.tileset.tiles.get(tile_id)
+        if tile is None or not tile.solid:
+            return False
+        if figure_name and figure_name in tile.exceptions:
+            return False
+        return True
+
+    def _render_layer(self, layer_index: int) -> pygame.Surface:
+        """Рендерит весь слой в отдельную Surface (используется для кеширования)."""
+        layer = self.layers[layer_index]
+        surf = pygame.Surface(
+            (self.width * self.tileset.tile_width, self.height * self.tileset.tile_height), 
+            pygame.SRCALPHA
+        )
+        tw, th = self.tileset.tile_width, self.tileset.tile_height
+        
+        for y in range(self.height):
+            for x in range(self.width):
+                tile_id = layer.data[y][x]
+                if tile_id == 0: continue
+                
+                tile = self.tileset.tiles.get(tile_id)
+                if not tile: continue
+                
+                px, py = x * tw, y * th
+                if tile.image_name and tile.image_name in self.engine.images:
+                    surf.blit(self.engine.images[tile.image_name], (px, py))
+                else:
+                    pygame.draw.rect(surf, tile.color, (px, py, tw, th))
+        return surf
+
+    def draw(self):
+        """
+        Отрисовывает все слои карты на экран с учётом смещения камеры.
+        Слои рисуются по порядку их добавления (от 0 до последнего).
+        Оптимизировано: использует кеш, если слой не менялся.
+        """
+        ox, oy = self.engine.camera_offset
+        
+        for i in range(len(self.layers)):
+            if self._layer_cache.get(i) is None:
+                self._layer_cache[i] = self._render_layer(i)
+            
+            self.engine.screen.blit(self._layer_cache[i], (int(ox), int(oy)))
+
+    # ――――――――――――――――――――――――― utils ―――――――――――――――――――――――――
+    def cell_to_pixel(self, col: int, row: int) -> tuple[int, int]:
+        """
+        Преобразует координаты ячейки (col, row) в пиксельные координаты (x, y).
+        """
+        return (col * self.tileset.tile_width, row * self.tileset.tile_height)
+
+    def pixel_to_cell(self, x: float, y: float) -> tuple[int, int]:
+        """
+        Преобразует пиксельные координаты (x, y) в координаты ячейки (col, row).
+        Использует целочисленное деление, корректно работает с отрицательными координатами.
+        """
+        return (int(x // self.tileset.tile_width), int(y // self.tileset.tile_height))
+
+    def load_from_lines(self, lines: list[str], legend: dict[str, int], layer_index: int = 0):
+        """
+        Загружает карту из списка строк (текстовый уровень).
+        - lines (list[str]): Список строк, где каждый символ представляет тайл.
+        - legend (dict[str, int]): Словарь соответствия символа и ID тайла (например, {'#': 1, '.': 0}).
+        - layer_index (int): Индекс слоя для записи данных.
+        """
+        for row, line in enumerate(lines):
+            for col, char in enumerate(line):
+                if char in legend:
+                    self.set_tile(col, row, legend[char], layer_index)