v3.1.1

Author: NeoXider

CHANGELOG.md

@@ -5,6 +5,22 @@
 Формат основан на [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 и этот проект придерживается [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.1.1]
+
+### Added
+- **Project template paths** — `spritePro.cli --create` теперь создаёт `config.py` с готовыми путями `PROJECT_ROOT`, `ASSETS_DIR`, `AUDIO_DIR`, `IMAGES_DIR`, `SCENES_DIR` и `MAIN_LEVEL_PATH`, чтобы в новых проектах не нужно было каждый раз вручную собирать `Path(__file__).resolve()...`.
+- **Project template events file** — в шаблон добавлен `game_events.py` с базовым событием `game_started`, подпиской через `s.events.connect(...)`, отправкой через `s.events.get_event(...).send(...)` и логом через `s.debug_log_info(...)`.
+
+### Changed
+- **Project template structure** — шаблон `--create` по умолчанию создаёт `main.py`, `config.py`, `game_events.py`, `scenes/main_scene.py`, `scenes/second_scene.py` и `scenes/main_level.json`. Вторая сцена остаётся почти пустой заготовкой для меню, паузы, магазина или другого уровня.
+- **Multiplayer entrypoint** — рекомендации, demoGames и `multiplayer_course` обновлены под единый app-level запуск через `s.run(..., multiplayer=True)`, а `s.networking.run(...)` оставлен как low-level runner.
+- **Версия библиотеки** — релиз обновлён до `3.1.1`.
+
+### Fixed
+- **Editor runtime image sizing** — runtime-сцены, созданные в редакторе, снова корректно подхватывают размер image-объектов в embedded/Kivy-сценариях вместо fallback-белого прямоугольника.
+
+---
+
 ## [3.1.0]
 
 ### Added

DOCUMENTATION_INDEX.md

@@ -427,6 +427,7 @@
 ## 🔄 Обновления документации
 
 ### Последние обновления
+- **2026-03 (v3.1.1)**: Обновлены шаблон `spritePro.cli --create`, multiplayer docs и курс: в шаблон добавлены `config.py` с путями к проекту/ассетам, `game_events.py` с базовым событием через `EventBus`, а multiplayer-примеры переведены на единый запуск через `s.run(..., multiplayer=True)`. Обновлены [README.md](README.md), [docs/game_loop.md](docs/game_loop.md), [docs/networking.md](docs/networking.md), [multiplayer_course/README.md](multiplayer_course/README.md).
 - **2026-03 (v3.1.0)**: Добавлена документация по виртуальному разрешению `reference_size`: как запускать игру в маленьком окне, но держать `s.WH`, `s.WH_C`, UI, камеру и input в координатах большого логического экрана. Обновлены [README.md](README.md) и [docs/game_loop.md](docs/game_loop.md).
 - **2026-03 (v3.0.3)**: Обновлена mobile/Android-документация: добавлены рекомендации по preview на компактных окнах, описаны режимы ориентации `landscape`, `portrait`, `auto` для APK, уточнён workflow проверки layout на разных экранах. Обновлены [README.md](README.md), [docs/building.md](docs/building.md), [docs/mobile.md](docs/mobile.md).
 - **2026-03 (v3.0.2)**: Android/APK-документация уточнена по реально проверенному запуску после сборки: добавлены рекомендации по `adb logcat`, проверке ранних Python traceback и по явному включению свежего локального `spritePro` в проект игры, если тестируются непубликованные фиксы. Обновлены [README.md](README.md), [docs/building.md](docs/building.md), [docs/mobile.md](docs/mobile.md), [docs/kivy_hybrid.md](docs/kivy_hybrid.md).

README.md

@@ -142,7 +142,7 @@ s.run(
 - ✅ **Автолейаут (Layout)** - flex, сетка, круг, линия для автоматического размещения дочерних спрайтов ([документация](docs/layout.md))
 - ✅ **ScrollView** — скроллируемая область для контента (лейаут), колёсико и перетаскивание мышью, опциональная маска (клиппинг по viewport)
 - ✅ **Готовые сцены (readyScenes)** — подключаемые сцены: **ChatScene** (мультиплеерный чат с историей, скроллом и маской) и **ChatStyle** для настройки оформления
-- ✅ **Мультиплеер** — сетевые игры: TCP relay, контекст (send/poll/send_every), EventBus; быстрый старт через `s.networking.run()`. **Готовое лобби** (`run(use_lobby=True)`): один экран — имя, хост/клиент, порт, IP, список игроков; у хоста кнопки «В игру» и «Назад», у клиента — «Назад». По нажатию «В игру» игра запускается у обоих. Подробно: [Networking — лобби](docs/networking.md#подробная-инструкция-лобби-use_lobbytrue). Мини-курс в папке `multiplayer_course/` — 10 уроков от обмена сообщениями до готовой мини-игры.
+- ✅ **Мультиплеер** — сетевые игры: TCP relay, контекст (send/poll/send_every), EventBus; теперь можно запускать прямо через `s.run(..., multiplayer=True)` без отдельного `multiplayer_main`-runner, а `s.networking.run()` оставлен как low-level вариант. **Готовое лобби** (`s.run(..., multiplayer_use_lobby=True)`): один экран — имя, хост/клиент, порт, IP, список игроков; у хоста кнопки «В игру» и «Назад», у клиента — «Назад». По нажатию «В игру» игра запускается у обоих. Подробно: [Networking — лобби](docs/networking.md#подробная-инструкция-лобби-use_lobbytrue). Мини-курс в папке `multiplayer_course/` — 10 уроков от обмена сообщениями до готовой мини-игры.
 - ✅ **Mobile-рантайм** — запуск через `Kivy`: `s.run(..., platform="kivy")`, встроенный host для touch-ввода и мобильных demo
 
 ---
@@ -233,9 +233,13 @@ python -m spritePro.cli --create
 Шаблон теперь сразу современный:
 
 - `main.py` запускает игру через `s.run(...)`
-- `scenes/main_scene.py` — основная сцена, которая грузит `scenes/main_level.json`
+- `config.py` — общие настройки игры и готовые пути `PROJECT_ROOT`, `ASSETS_DIR`, `AUDIO_DIR`, `IMAGES_DIR`, `SCENES_DIR`, `GAME_DIR`, `DOMAIN_DIR`, `SERVICES_DIR`
+- `game_events.py` — базовый файл для `EventBus`: событие старта игры, подписка и лог
+- `scenes/main_scene.py` — основная сцена, которая грузит `config.MAIN_LEVEL_PATH`
 - `scenes/second_scene.py` — вторая почти пустая сцена-заготовка, чтобы было удобно расширять проект
 - `scenes/main_level.json` — стартовый уровень в формате Sprite Editor
+- `game/domain/game_state.py` — пример domain-модели
+- `game/services/game_service.py` — пример сервиса для игровой логики
 
 То есть новый проект после `--create` уже показывает нормальную scene-based структуру, а не только один файл с ручным циклом.
 

docs/OVERVIEW.md

@@ -87,7 +87,7 @@ TCP + JSON‑сообщения формата `{"event": "...", "data": {...}}`
 
 - **NetServer** — TCP relay (пересылает сообщения всем клиентам)
 - **NetClient** — клиент с `send()` и `poll()`
-- **s.networking.run()** — единая точка входа с разными режимами
+- **s.run(..., multiplayer=True)** — рекомендуемая единая точка входа для современных multiplayer-игр; `s.networking.run()` оставлен как low-level runner
 
 ### Режимы запуска
 

docs/game_loop.md

@@ -8,7 +8,23 @@
 python -m spritePro.cli --create MyGame
 ```
 
-Шаблон создаёт `main.py`, `scenes/main_scene.py`, `scenes/second_scene.py` и `scenes/main_level.json`.
+Шаблон создаёт:
+
+- `main.py`
+- `config.py`
+- `game_events.py`
+- `game/domain/game_state.py`
+- `game/services/game_service.py`
+- `scenes/main_scene.py`
+- `scenes/second_scene.py`
+- `scenes/main_level.json`
+
+В шаблоне уже есть:
+
+- две сцены: основная и почти пустая вторая сцена-заготовка
+- готовые пути к проекту, сценам, domain и services в `config.py`
+- базовый `EventBus`-файл с событием старта игры и логом через `s.debug_log_info(...)`
+- разделение структуры: `scenes/` для сцен, `game/domain/` для моделей, `game/services/` для игровой логики
 
 ```python
 import spritePro as s

docs/networking.md

@@ -42,7 +42,58 @@ TCP‑клиент, который отправляет сообщения и п
 - `poll(max_messages=100)` — забирает входящие сообщения.
 - `close()` — закрывает соединение.
 
-### s.networking.run(...)
+### Рекомендуемый запуск: `s.run(..., multiplayer=True)`
+
+Для новых игр удобнее использовать один вход через `s.run(...)`, а multiplayer
+включать флагом `multiplayer=True`.
+
+```python
+import spritePro as s
+
+
+class MultiplayerScene(s.Scene):
+    def __init__(self, net: s.NetClient, role: str):
+        super().__init__()
+        s.multiplayer.init_context(net, role)
+        self.ctx = s.multiplayer_ctx
+        self.me = s.Sprite("", (40, 40), (200, 300), scene=self)
+        self.me.set_color((220, 70, 70) if self.ctx.is_host else (70, 120, 220))
+
+    def update(self, dt):
+        pos = self.me.get_world_position()
+        self.ctx.send_every("pos", {"pos": list(pos)}, 1.0 / 60.0)
+
+
+if __name__ == "__main__":
+    s.run(
+        scene=MultiplayerScene,
+        size=(800, 600),
+        title="My Multiplayer",
+        fps=60,
+        fill_color=(20, 20, 25),
+        multiplayer=True,
+    )
+```
+
+Что это даёт:
+
+- один и тот же `s.run(...)` для singleplayer и multiplayer
+- `scene` и `setup` могут принимать `net` и `role`, если они нужны
+- те же terminal-аргументы `--quick`, `--server`, `--host_mode`, `--host`, `--port`, `--clients` работают без отдельного вызова `s.networking.run(...)`
+- `--kivy` и `--pygame` тоже можно передавать в тот же запуск
+
+Если нужен quick-режим на 3 окна прямо из кода:
+
+```python
+s.run(
+    scene=MultiplayerScene,
+    multiplayer=True,
+    multiplayer_clients=3,
+    multiplayer_client_spawn_delay=2,
+)
+```
+
+### Низкоуровневый запуск: `s.networking.run(...)`
 
 Утилита запуска для быстрого мультиплеера с автозапуском клиента/серверов.
 
@@ -60,7 +111,7 @@ s.networking.run(
 ```
 
 - **По умолчанию** (`use_lobby=False`): без аргументов запускается быстрый режим (два окна — хост и клиент). Удобно для разработки.
-- **С лобби** (`use_lobby=True`): одно окно. Сначала экран настройки: имя, выбор «Хост» / «Клиент», порт (и для клиента — IP). После подключения — список игроков (roster). У хоста: кнопки «Назад» и «В игру»; у клиента: кнопка «Назад». «Назад» отключает соединение и возвращает к настройке. По нажатию «В игру» вызывается ваша `multiplayer_main(net, role)`. Для готового приложения достаточно заменить вызов на `s.networking.run(use_lobby=True)`.
+- **С лобби** (`use_lobby=True`): одно окно. Сначала экран настройки: имя, выбор «Хост» / «Клиент», порт (и для клиента — IP). После подключения — список игроков (roster). У хоста: кнопки «Назад» и «В игру»; у клиента: кнопка «Назад». «Назад» отключает соединение и возвращает к настройке. По нажатию «В игру» вызывается ваша `multiplayer_main(net, role)`. Для нового кода удобнее использовать `s.run(..., multiplayer=True, multiplayer_use_lobby=True)`, а `s.networking.run(use_lobby=True)` оставить как low-level вариант.
 
 Важно: `run()` нужно вызывать из файла, а не из REPL.
 
@@ -152,9 +203,9 @@ while True:
     other.set_position(remote_pos)
 ```
 
-## Интеграция через s.networking.run()
+## Интеграция через `s.networking.run()`
 
-Создайте функцию входа и вызовите `run()`:
+Если нужен старый или более явный low-level flow, можно оставить отдельную entry-функцию:
 
 ```python
 import pygame
@@ -201,7 +252,11 @@ s.networking.run(entry="module:function")
 
 ```python
 if __name__ == "__main__":
-    s.networking.run(use_lobby=True)
+    s.run(
+        multiplayer=True,
+        multiplayer_entry=multiplayer_main,
+        multiplayer_use_lobby=True,
+    )
 ```
 
 Либо запустите демо с флагом:
@@ -241,7 +296,7 @@ s.get_screen((480, 540), "Лобби")
 run_multiplayer_lobby(lambda net, role: your_multiplayer_main(net, role))
 ```
 
-Если сама игра уже переведена на `s.run(...)`, обычно проще оставить это внутри `your_multiplayer_main(net, role)` и считать `run_multiplayer_lobby(...)` только экраном подключения.
+Если игра уже запускается через `s.run(...)`, то для нового кода обычно удобнее перейти на `s.run(..., multiplayer=True)` и использовать `s.networking.run(...)` только как низкоуровневый runner.
 
 - **Константа события:** `from spritePro.readyScenes import EVENT_START_GAME` — имя события `"start_game"` для согласования с своей логикой.
 
@@ -361,7 +416,7 @@ def multiplayer_main(net: s.NetClient, role: str):
     # ctx.send("ready", {...})
     # for msg in ctx.poll(): ...
 
-s.networking.run()
+s.run(multiplayer=True, multiplayer_entry=multiplayer_main)
 ```
 
 ### Кто такой «этот процесс» (наш компьютер)

docs/readySprites.md

@@ -22,7 +22,7 @@ Ready Sprites are pre-configured sprite classes that solve common game developme
 
 ```python
 # Через run() — одно окно с лобби, затем ваша игра
-s.networking.run(use_lobby=True)
+s.run(multiplayer=True, multiplayer_entry=your_multiplayer_main, multiplayer_use_lobby=True)
 ```
 
 ```python

multiplayer_course/10/example_routing.py

@@ -80,4 +80,4 @@ def multiplayer_main(net: s.NetClient, role: str) -> None:
 
 
 if __name__ == "__main__":
-    s.networking.run(entry="multiplayer_main")
+    s.run(multiplayer=True, multiplayer_entry=multiplayer_main)

multiplayer_course/10/lesson.md

@@ -18,7 +18,7 @@
 В EventBus и при прямой отправке через контекст можно разделять **куда** уходит сообщение.
 
 Этот урок остаётся low-level по смыслу: он про роутинг событий, а не про UI/сцены.
-Но сам пример ниже тоже можно удобно запускать через `s.networking.run(...)` и `s.run(...)`,
+Но сам пример ниже тоже можно удобно запускать через `s.run(..., multiplayer=True)` и `s.run(...)`,
 чтобы курс не расходился со стилем `SpritePro 3.x`.
 
 ### Варианты роутинга (EventBus: `route=...`)

multiplayer_course/10/practice_routing.py

@@ -62,4 +62,4 @@ def multiplayer_main(net: s.NetClient, role: str) -> None:
 
 
 if __name__ == "__main__":
-    s.networking.run(entry="multiplayer_main")
+    s.run(multiplayer=True, multiplayer_entry=multiplayer_main)