v3.0.0

Author: NeoXider

README.md

@@ -148,7 +148,7 @@ pip install spritepro
 Для мобильного host-режима:
 
 ```bash
-pip install kivy
+pip install "spritepro[kivy]"
 ```
 
 #### Обновление
@@ -195,6 +195,19 @@ s.run(scene=MainScene, size=(800, 600), title="My Game", fill_color=(20, 20, 30)
 
 **Вот и всё!** У вас уже есть игра с управлением, отрисовкой и игровым циклом. Для mobile достаточно сменить `platform` на `"kivy"`. 🎮
 
+Для файлов ассетов задавайте путь явно от текущего файла, а не от рабочей папки:
+
+```python
+from pathlib import Path
+
+ASSETS_DIR = Path(__file__).resolve().parent / "assets" / "images"
+
+def asset_path(name: str) -> str:
+    return str((ASSETS_DIR / name).resolve())
+```
+
+Такой способ одинаково корректно работает и в `pygame`, и в `kivy`. Подробности: [docs/mobile.md](docs/mobile.md).
+
 ### ⚡ Быстрый старт 2.0 (шаблон проекта)
 
 ```bash
@@ -235,6 +248,14 @@ s.run(scene=MainScene, platform="kivy")
 - [Hybrid Kivy UI guide](docs/kivy_hybrid.md) — Kivy menu/layout + встроенная игровая область SpritePro
 - [Build guide](docs/building.md) — как собирать library, web и mobile build
 
+Быстрый preview разных экранов через CLI:
+
+```bash
+python -m spritePro.cli --preview main.py --platform kivy --screen phone-portrait
+python -m spritePro.cli --preview main.py --platform kivy --screen tablet-landscape
+python -m spritePro.cli --list-screen-presets
+```
+
 ### Что уже работает
 
 - desktop runtime через `pygame`

docs/building.md

@@ -185,10 +185,10 @@ s.run(scene=MainScene, platform="kivy")
 
 ### Локальная проверка mobile-режима на ПК
 
-Установите `Kivy`:
+Установите mobile-зависимости:
 
 ```bash
-pip install kivy
+pip install "spritepro[kivy]"
 ```
 
 Запустите игру:
@@ -204,6 +204,72 @@ python -m spritePro.demoGames.mobile_orb_collector_demo --kivy
 python -m spritePro.demoGames.builder_demo --kivy
 ```
 
+Если вы работаете из исходников SpritePro, а не из опубликованного пакета:
+
+```bash
+pip install -e ".[kivy]"
+```
+
+### Тестирование на разных экранах до Android build
+
+Перед реальной сборкой полезно прогнать одну и ту же игру на нескольких размерах окна в desktop-preview через `platform="kivy"`.
+
+Самый быстрый способ теперь через CLI:
+
+```bash
+python -m spritePro.cli --preview main.py --platform kivy --screen phone-portrait
+python -m spritePro.cli --preview main.py --platform kivy --screen phone-tall
+python -m spritePro.cli --preview main.py --platform kivy --screen phone-landscape
+python -m spritePro.cli --preview main.py --platform kivy --screen tablet-landscape
+python -m spritePro.cli --preview main.py --platform pygame --size 412x915
+python -m spritePro.cli --list-screen-presets
+```
+
+Команда `--preview`:
+
+- принимает путь к `main.py` или к папке проекта
+- временно подменяет размер окна
+- для scene-based игр на `s.run(...)` может быстро переключать `pygame` / `kivy`
+- помогает быстро увидеть расхождения layout до Android build
+
+Пример:
+
+```python
+import spritePro as s
+
+
+class MainScene(s.Scene):
+    def __init__(self):
+        super().__init__()
+        self.player = s.Sprite("", (96, 96), s.WH_C, scene=self)
+        self.player.set_rect_shape((96, 96), (90, 210, 255), border_radius=24)
+
+
+s.run(
+    scene=MainScene,
+    size=(360, 640),
+    title="Phone Portrait Preview",
+    fill_color=(20, 20, 30),
+    platform="kivy",
+)
+```
+
+Что стоит проверить хотя бы в нескольких профилях:
+
+- `size=(360, 640)` — компактный phone portrait
+- `size=(412, 915)` — современный высокий phone portrait
+- `size=(640, 360)` — compact landscape
+- `size=(1280, 720)` — tablet / desktop-preview landscape
+
+На что смотреть:
+
+- не уезжает ли UI за края
+- хватает ли размеров hitbox и кнопок под touch
+- корректно ли выглядят `screen_space`-элементы
+- не завязана ли логика на один фиксированный `s.WH`
+- одинаково ли ведут себя `pygame` и `kivy`
+- помните, что в `Kivy` при resize `s.WH` и `s.WH_C` обновляются, но уже созданные объекты не relayout'ятся автоматически
+
 ### Android: рекомендуемый путь
 
 Для Android-сборки обычно используется `Buildozer`.
@@ -212,6 +278,7 @@ python -m spritePro.demoGames.builder_demo --kivy
 
 - `Buildozer` официально удобнее всего запускать на Linux
 - на Windows обычно используют `WSL` или отдельную Linux-машину
+- собирать проект лучше внутри Linux filesystem/WSL home, а не из Windows-диска
 - на Android нужно заранее продумать ассеты, ориентацию экрана и touch-управление
 
 ### Минимальный сценарий сборки Android
@@ -247,6 +314,8 @@ s.run(
 
 ### Buildozer
 
+`Buildozer` ставится и запускается внутри Linux/WSL-окружения.
+
 Установка:
 
 ```bash
@@ -271,6 +340,11 @@ orientation = landscape
 fullscreen = 1
 ```
 
+Если вы тестируете не опубликованный `spritepro`, а локально модифицированную версию, заранее проверьте, как именно библиотека попадёт в Android build:
+
+- либо используйте опубликованный пакет `spritepro`
+- либо собирайте/подключайте свою локальную версию отдельно и проверяйте это до финальной сборки
+
 Если игра использует сеть по Wi-Fi:
 
 ```ini

docs/kivy_hybrid.md

@@ -233,6 +233,13 @@ HybridApp().run()
 
 Это именно то поведение, которое нужно для embedded-игры.
 
+Важно понимать нюанс resize:
+
+- при изменении размера `game_widget` значения `s.WH` и `s.WH_C` тоже обновляются
+- но уже созданные объекты не перепозиционируются автоматически
+- если вы один раз поставили спрайт в `__init__` через `s.WH_C`, он не "переедет" сам после следующего resize
+- для truly adaptive layout пересчитывайте позиции/размеры от текущих `s.WH` и `s.WH_C`
+
 ---
 
 ## Что лучше использовать

docs/mobile.md

@@ -23,6 +23,20 @@ s.run(scene=MyScene, platform="kivy")
 - `spritePro.update_embedded(...)` — один кадр без `pygame.display.update()`
 - `spritePro.mobile.run_kivy_app(...)` — низкоуровневый запуск, если нужна ручная настройка host-приложения
 
+## Установка mobile-зависимостей
+
+Если вы ставите библиотеку из `pip`:
+
+```bash
+pip install "spritepro[kivy]"
+```
+
+Если вы работаете из исходников:
+
+```bash
+pip install -e ".[kivy]"
+```
+
 ## Full-screen по умолчанию
 
 Сейчас режим по умолчанию для `Kivy` остаётся простым:
@@ -131,6 +145,122 @@ if left.rect.collidepoint(s.input.mouse_pos) and s.input.is_mouse_pressed(1):
 
 Это работает и мышью на desktop, и касанием внутри `Kivy`.
 
+## Пути к ассетам: делайте явно через `Path(__file__)`
+
+Если игра должна одинаково работать в `pygame` и `kivy`, не полагайтесь на текущую рабочую папку и не пишите пути вроде `"spritePro\\demoGames\\Sprites\\hero.png"` или `"assets/player.png"` как "магическую" строку без привязки к файлу.
+
+Правильный и явный вариант:
+
+```python
+from pathlib import Path
+import spritePro as s
+
+
+ASSETS_DIR = Path(__file__).resolve().parent / "assets" / "images"
+
+
+def asset_path(name: str) -> str:
+    return str((ASSETS_DIR / name).resolve())
+
+
+class MyScene(s.Scene):
+    def __init__(self):
+        super().__init__()
+        self.player = s.Sprite(
+            asset_path("player.png"),
+            (96, 96),
+            s.WH_C,
+            scene=self,
+        )
+```
+
+Почему именно так:
+
+- путь считается от текущего `.py` файла, а не от папки, из которой вы запустили Python
+- один и тот же код стабильно работает в `pygame`, `kivy` и в будущей упаковке проекта
+- это особенно важно для mobile/hybrid-сценариев, где host-приложение может запускать игру не из той директории, на которую вы рассчитывали
+
+Рекомендуемое правило:
+
+- для изображений, звуков, JSON-сцен и шрифтов используйте `Path(__file__).resolve()`
+- передавайте в `SpritePro` уже нормализованный путь через `str(...)`
+
+## Как тестировать на разных экранах
+
+До сборки на телефон полезно прогнать игру на нескольких размерах окна прямо на ПК.
+
+Самый быстрый путь теперь через CLI:
+
+```bash
+python -m spritePro.cli --preview main.py --platform kivy --screen phone-portrait
+python -m spritePro.cli --preview main.py --platform kivy --screen phone-tall
+python -m spritePro.cli --preview main.py --platform kivy --screen tablet-landscape
+python -m spritePro.cli --preview main.py --platform pygame --size 412x915
+python -m spritePro.cli --list-screen-presets
+```
+
+Что делает `--preview`:
+
+- запускает указанный `main.py` или папку проекта с `main.py`
+- временно подменяет размер окна
+- может быстро переключать `pygame` / `kivy` для игр на `s.run(...)`
+- добавляет в title подпись вида `[kivy 360x640]`, чтобы не путать окна
+
+Важно:
+
+- переключение платформы через CLI рассчитано на современные игры, которые запускаются через `s.run(...)`
+- если проект использует старый ручной цикл с `s.get_screen(...)`, override размера сработает, но автоматическое переключение на `kivy` через CLI не гарантируется
+
+Что происходит при resize в `Kivy`:
+
+- `s.WH` и `s.WH_C` обновляются под новый размер окна/виджета
+- но уже созданные спрайты, панели и текст не перестраиваются автоматически только потому, что когда-то были созданы через `s.WH` или `s.WH_C`
+- если нужен настоящий adaptive layout, пересчитывайте позиции и размеры от текущих `s.WH` / `s.WH_C` после resize
+
+Минимальный пример:
+
+```python
+import spritePro as s
+
+
+class MainScene(s.Scene):
+    def __init__(self):
+        super().__init__()
+        self.player = s.Sprite("", (96, 96), s.WH_C, scene=self)
+        self.player.set_rect_shape((96, 96), (90, 210, 255), border_radius=24)
+
+
+s.run(
+    scene=MainScene,
+    size=(360, 640),
+    title="Mobile Preview",
+    fill_color=(20, 20, 30),
+    platform="kivy",
+)
+```
+
+Полезные размеры для быстрой проверки:
+
+- `size=(360, 640)` — маленький portrait
+- `size=(412, 915)` — высокий portrait
+- `size=(640, 360)` — compact landscape
+- `size=(1280, 720)` — большой landscape / tablet preview
+
+Практика:
+
+- сначала прогоните игру в `platform="pygame"`
+- потом те же размеры прогоните в `platform="kivy"`
+- сравните layout, размер кнопок, позиционирование и touch-friendly UI
+
+Что проверять:
+
+- опирается ли UI на `s.WH` и `s.WH_C` корректно
+- не обрезаются ли панели, текст и кнопки
+- удобны ли hitbox для пальца
+- не выглядят ли ассеты слишком мелкими или слишком крупными
+- нормально ли игра переживает portrait/landscape-сценарии
+- не осталось ли объектов, которые были один раз выставлены в `__init__` от старого `s.WH_C` и больше не обновляются
+
 ## Готовое демо
 
 ```bash

pyproject.toml

@@ -34,6 +34,7 @@ dependencies = [
 
 [project.optional-dependencies]
 web = ["pygbag>=0.9.0"]
+kivy = ["kivy"]
 
 [project.urls]
 Homepage = "https://github.com/NeoXider/SpritePro"

spritePro/__init__.py

@@ -22,6 +22,7 @@
 Документация: см. docs/ в корне репозитория и DOCUMENTATION_INDEX.md.
 """
 
+import os
 from typing import Callable, List
 
 import pygame
@@ -1022,6 +1023,47 @@ def init():
     _context.init_pygame()
 
 
+def _parse_size_override(raw_value: str | None) -> tuple[int, int] | None:
+    if not raw_value:
+        return None
+    normalized = raw_value.lower().replace(" ", "")
+    separator = "x" if "x" in normalized else ","
+    if separator not in normalized:
+        return None
+    try:
+        width_str, height_str = normalized.split(separator, 1)
+        width = max(1, int(width_str))
+        height = max(1, int(height_str))
+    except ValueError:
+        return None
+    return width, height
+
+
+def _resolve_screen_options(
+    size: tuple[int, int],
+    title: str,
+) -> tuple[tuple[int, int], str]:
+    size_override = _parse_size_override(os.environ.get("SPRITEPRO_WINDOW_SIZE"))
+    if size_override is not None:
+        size = size_override
+    title_suffix = os.environ.get("SPRITEPRO_TITLE_SUFFIX", "").strip()
+    if title_suffix:
+        title = f"{title} {title_suffix}"
+    return size, title
+
+
+def _resolve_run_options(
+    size: tuple[int, int],
+    title: str,
+    platform: str,
+) -> tuple[tuple[int, int], str, str]:
+    size, title = _resolve_screen_options(size, title)
+    platform_override = os.environ.get("SPRITEPRO_PLATFORM")
+    if platform_override:
+        platform = platform_override
+    return size, title, platform
+
+
 def get_screen(
     size: tuple[int, int] = (800, 600), title: str = "Игра", icon: str = None
 ) -> pygame.Surface:
@@ -1037,6 +1079,7 @@ def get_screen(
     Returns:
         pygame.Surface: Поверхность экрана игры.
     """
+    size, title = _resolve_screen_options(size, title)
     result = _context.get_screen(size=size, title=title, icon=icon)
     _sync_globals()
     return result
@@ -1102,6 +1145,7 @@ def run(
         fill_color: Цвет очистки кадра.
         platform: "pygame" или "kivy".
     """
+    size, title, platform = _resolve_run_options(size, title, platform)
     platform_normalized = platform.lower().strip()
     if platform_normalized in {"pygame", "desktop"}:
         get_screen(size=size, title=title, icon=icon)