v3.3.0

Author: NeoXider

CHANGELOG.md

@@ -5,6 +5,17 @@
 Формат основан на [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 и этот проект придерживается [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.3.0]
+
+### Added
+- ✨ **Мобильный ввод: экранная клавиатура для TextInput** — в Kivy‑режиме SpritePro автоматически запрашивает системную софт‑клавиатуру, когда любое поле `s.TextInput` становится активным. События `on_key_down` и `on_textinput` из Kivy транслируются в `pygame.KEYDOWN` и `pygame.TEXTINPUT`, поэтому `TextInput` обрабатывает ввод на Android так же, как на desktop.
+
+### Changed
+- 🔧 **Kivy mobile host** — `_KivySpriteProWidget` отслеживает активные `s.TextInput` и открывает/закрывает экранную клавиатуру через `Window.request_keyboard(...)`. Закрытие клавиатуры происходит автоматически при деактивации всех полей ввода (по Enter или при тапе вне поля).
+- 🔧 **Версия библиотеки** — релиз обновлён до `3.3.0`.
+
+---
+
 ## [3.2.0]
 
 ### Added
@@ -647,6 +658,13 @@
 
 ## Планы на будущие версии
 
+## [Unreleased]
+
+- ✨ Улучшенное Kivy-лобби (`use_lobby=True`, `platform="kivy"`) с поддержкой мобильного режима и удобным десктопным тестированием.
+- ✨ Автозапуск нескольких Kivy-процессов с лобби при `multiplayer_clients>1` — каждый процесс = отдельный игрок, для локального теста мультиплеера.
+- 🎨 Перевод лобби на flex-лейауты SpritePro (`layout_flex_column` / `layout_flex_row`) для аккуратного расположения полей, кнопок и статуса.
+- 📚 Обновления документации по `use_lobby=True`, Kivy-режиму и демо `three_clients_move_demo`.
+
 ### v1.1.0 - Система инвентаря
 - Полноценная система управления предметами
 - Drag & Drop интерфейс

docs/networking.md

@@ -42,6 +42,33 @@ TCP‑клиент, который отправляет сообщения и п
 - `poll(max_messages=100)` — забирает входящие сообщения.
 - `close()` — закрывает соединение.
 
+### Системные события
+
+При использовании `MultiplayerContext` (рекомендуется), хост автоматически получает события о подключении/отключении клиентов через `ctx.poll()`:
+
+- `client_connected` — новый клиент подключился
+  - `data.client_id` — ID клиента (0, 1, 2...)
+  - `data.peer` — адрес клиента (например, "127.0.0.1:54321")
+- `client_disconnected` — клиент отключился
+  - `data.client_id` — ID клиента
+
+```python
+class MyScene(s.Scene):
+    def __init__(self, net, role):
+        super().__init__()
+        s.multiplayer.init_context(net, role)
+        self.ctx = s.multiplayer_ctx
+
+    def update(self, dt):
+        for msg in self.ctx.poll():
+            if msg.get("event") == "client_connected":
+                client_id = msg["data"]["client_id"]
+                print(f"Подключился клиент: {client_id}")
+            elif msg.get("event") == "client_disconnected":
+                client_id = msg["data"]["client_id"]
+                print(f"Отключился клиент: {client_id}")
+```
+
 ### Рекомендуемый запуск: `s.run(..., multiplayer=True)`
 
 Для новых игр удобнее использовать один вход через `s.run(...)`, а multiplayer
@@ -265,7 +292,7 @@ if __name__ == "__main__":
 python spritePro/demoGames/local_multiplayer_demo.py --lobby
 ```
 
-### Сценарий для игрока
+### Сценарий для игрока (desktop / pygame)
 
 1. **Один экземпляр (хост)**  
    - Открыть приложение.  
@@ -283,17 +310,34 @@ python spritePro/demoGames/local_multiplayer_demo.py --lobby
    - Хост нажимает **«В игру»**.  
    - У **обоих** игроков закрывается лобби и запускается игра (`multiplayer_main(net, role)`).
 
+### Сценарий для игрока (mobile / Kivy)
+
+- Запуск через `s.run(..., platform="kivy", multiplayer=True, multiplayer_use_lobby=True)` или Kivy-билд.
+- Окно лобби и сама игра работают внутри одного Kivy-приложения (SpritePro рендерится в Kivy-виджет).
+- Каждый процесс/билд даёт **одного** игрока; для локальных тестов мультиплеера используйте несколько устройств/эмуляторов (по одному клиенту на процесс) **или автоспавн процессов по `clients` (см. ниже)**.
+
+Если указать `multiplayer_clients=1`, такой запуск можно рассматривать как «build‑режим» (один экземпляр клиента, без автоспавна дополнительных окон).
+
 ### Для разработчика
 
 - **События лобби:** хост рассылает `start_game` при нажатии «В игру»; клиент при получении `start_game` тоже переходит в игру. Кнопка «Назад» закрывает соединение и возвращает к экрану настройки.
-- **Очистка UI:** лобби реализовано как `MultiplayerLobbyScene(s.Scene)`. При выходе из лобби вызывается `on_exit()`: все спрайты лобби (кнопки, поля ввода, текст, в том числе дочерние `text_sprite`) снимаются с регистрации, в игре не остаётся элементов лобби.
+- **Очистка UI:** лобби реализовано как `MultiplayerLobbyScene(s.Scene)` и обновляется через `update()`. При выходе из лобби вызывается `on_exit()`: все спрайты лобби (кнопки, поля ввода, текст, в том числе дочерние `text_sprite`) снимаются с регистрации, в игре не остаётся элементов лобби.
 - **Использование без run():** можно вызвать лобби вручную после `get_screen()` и передать колбэк перехода в игру:
 
 ```python
 from spritePro.readyScenes import run_multiplayer_lobby
 
+# pygame / desktop
 s.get_screen((480, 540), "Лобби")
 run_multiplayer_lobby(lambda net, role: your_multiplayer_main(net, role))
+
+# Kivy / mobile
+run_multiplayer_lobby(
+    lambda net, role: your_multiplayer_main(net, role),
+    window_size=(480, 540),
+    title="Лобби",
+    platform="kivy",
+)
 ```
 
 Если игра уже запускается через `s.run(...)`, то для нового кода обычно удобнее перейти на `s.run(..., multiplayer=True)` и использовать `s.networking.run(...)` только как низкоуровневый runner.
@@ -302,7 +346,10 @@ run_multiplayer_lobby(lambda net, role: your_multiplayer_main(net, role))
 
 ## Режимы запуска run()
 
-- **use_lobby=True** (в коде) — одно окно с лобби: настройка (имя, хост/клиент, порт, IP), подключение, roster; у хоста кнопки «Назад» и «В игру», у клиента «Назад». Не используется при запуске через `--quick` / env (тогда роль уже задана).
+- **use_lobby=True** (в коде)  
+  - desktop / pygame: одно окно с лобби: настройка (имя, хост/клиент, порт, IP), подключение, roster; у хоста кнопки «Назад» и «В игру», у клиента «Назад».  
+  - mobile / Kivy: одно окно с лобби внутри Kivy-приложения; `size` из `s.run(...)` переиспользуется для окна лобби.
+  - если `platform="kivy"` и `multiplayer_clients>1`, SpritePro поднимает несколько процессов Kivy с лобби (по одному игроку на процесс) — удобно для локального теста мультиплеера на ПК.
 - `--server` — только сервер.
 - `--host_mode` — сервер + клиент в одном процессе.
 - `--quick` — быстрый запуск (хост + второй клиент).

docs/readySprites.md

@@ -21,16 +21,40 @@ Ready Sprites are pre-configured sprite classes that solve common game developme
 **Использование:**
 
 ```python
-# Через run() — одно окно с лобби, затем ваша игра
-s.run(multiplayer=True, multiplayer_entry=your_multiplayer_main, multiplayer_use_lobby=True)
+# Через run() — одно окно с лобби, затем ваша игра (desktop / pygame)
+s.run(
+    multiplayer=True,
+    multiplayer_entry=your_multiplayer_main,
+    multiplayer_use_lobby=True,
+)
+
+# Мобильный / Kivy-вариант
+s.run(
+    multiplayer=True,
+    multiplayer_entry=your_multiplayer_main,
+    multiplayer_use_lobby=True,
+    platform="kivy",
+    # multiplayer_clients > 1 на ПК с Kivy поднимет несколько процессов с лобби
+    # (каждое окно — отдельный игрок, удобно для локального теста).
+    multiplayer_clients=1,
+)
 ```
 
 ```python
-# Вручную: после get_screen() вызвать лобби с колбэком
+# Вручную: после get_screen() или через Kivy вызвать лобби с колбэком
 from spritePro.readyScenes import run_multiplayer_lobby
 
+# pygame / desktop
 s.get_screen((480, 540), "Лобби")
 run_multiplayer_lobby(lambda net, role: your_multiplayer_main(net, role))
+
+# Kivy / mobile
+run_multiplayer_lobby(
+    lambda net, role: your_multiplayer_main(net, role),
+    window_size=(480, 540),
+    title="Лобби",
+    platform="kivy",
+)
 ```
 
 **Экспорт:** `run_multiplayer_lobby`, `MultiplayerLobbyScene`, `EVENT_START_GAME` из `spritePro.readyScenes`. Подробнее: [Networking — лобби](networking.md#подробная-инструкция-лобби-use_lobbytrue).

pyproject.toml

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

spritePro/__init__.py

@@ -24,7 +24,7 @@
 
 from __future__ import annotations
 
-__version__ = "3.2.4"
+__version__ = "3.3.0"
 
 import inspect
 import os
@@ -1329,6 +1329,17 @@ def _wrapped_setup():
                 def _wrapped_scene():
                     return _resolve_scene_value(scene, net, role)
 
+                # Если мы уже внутри Kivy-приложения (лобби / mobile),
+                # не запускаем run() повторно, а просто выполняем bootstrap
+                # в существующем контексте.
+                if os.environ.get("SPRITEPRO_IN_KIVY_APP") == "1":
+                    _run_bootstrap(
+                        _wrapped_setup if setup is not None else None,
+                        _wrapped_scene if scene is not None else None,
+                    )
+                    _emit_resize_event(force=True)
+                    return
+
                 run(
                     _wrapped_setup if setup is not None else None,
                     scene=_wrapped_scene if scene is not None else None,
@@ -1360,6 +1371,12 @@ def _wrapped_scene():
             setattr(main_module, _RUN_MULTIPLAYER_ENTRY, entry_callable)
 
         os.environ["SPRITEPRO_PLATFORM"] = platform
+        # Передаём размер окна в лобби через env, чтобы Kivy/pygame-лобби
+        # могли совпадать по size с основной игрой.
+        try:
+            os.environ["SPRITEPRO_LOBBY_SIZE"] = f"{int(size[0])},{int(size[1])}"
+        except Exception:
+            pass
         _networking.run(
             argv=filtered_multiplayer_argv,
             entry=entry_name,

spritePro/demoGames/three_clients_move_demo.py

@@ -51,7 +51,10 @@ def _color_for_id(client_id: int) -> tuple[int, int, int]:
 class ThreeClientsMoveScene(s.Scene):
     def __init__(self, net: s.NetClient, role: str) -> None:
         super().__init__()
-        s.multiplayer.init_context(net, role)
+        # Если контекст уже инициализирован (например, через лобби), переиспользуем его,
+        # иначе инициализируем заново для quick/terminal-режима.
+        if s.multiplayer_ctx is None:
+            s.multiplayer.init_context(net, role)
         self.ctx = s.multiplayer_ctx
         self.hint = s.TextSprite(
             "WASD — move | IDs above players", 20, (200, 200, 200), (450, 30), scene=self
@@ -152,6 +155,7 @@ def main(default_platform: str = "kivy") -> None:
         multiplayer_argv=sys.argv[1:],
         multiplayer_clients=3,
         multiplayer_client_spawn_delay=2,
+        multiplayer_use_lobby= True
     )
 
 

spritePro/mobile.py

@@ -86,6 +86,7 @@ def __init__(
                 self._active_touch_id: str | None = None
                 self._last_touch_pos: tuple[int, int] | None = None
                 self._bootstrap_wait_frames = 0
+                self._keyboard = None
                 self._fatal_error: str | None = None
 
                 with self.canvas:
@@ -261,6 +262,114 @@ def on_touch_up(self, touch):
                 self._last_touch_pos = None
                 return True
 
+            def _map_kivy_key_to_pygame(self, keycode, modifiers) -> tuple[int, int]:
+                key_value, key_name = keycode
+                name = (key_name or "").lower()
+                mapping = {
+                    "enter": pygame.K_RETURN,
+                    "return": pygame.K_RETURN,
+                    "kp_enter": pygame.K_RETURN,
+                    "backspace": pygame.K_BACKSPACE,
+                    "escape": pygame.K_ESCAPE,
+                    "esc": pygame.K_ESCAPE,
+                    "space": pygame.K_SPACE,
+                    "spacebar": pygame.K_SPACE,
+                }
+                if name in mapping:
+                    pg_key = mapping[name]
+                elif len(name) == 1:
+                    attr_name = f"K_{name}"
+                    pg_key = getattr(pygame, attr_name, key_value)
+                else:
+                    pg_key = key_value
+
+                mod = 0
+                if "shift" in modifiers:
+                    mod |= pygame.KMOD_SHIFT
+                if "ctrl" in modifiers or "control" in modifiers:
+                    mod |= pygame.KMOD_CTRL
+                if "alt" in modifiers:
+                    mod |= pygame.KMOD_ALT
+                if "meta" in modifiers or "cmd" in modifiers or "super" in modifiers:
+                    mod |= pygame.KMOD_META
+                return pg_key, mod
+
+            def _open_soft_keyboard(self) -> None:
+                if self._keyboard is not None:
+                    return
+                try:
+                    from kivy.core.window import Window
+                except Exception:
+                    return
+                keyboard = Window.request_keyboard(self._on_keyboard_closed, self)
+                if keyboard is None:
+                    return
+                self._keyboard = keyboard
+                try:
+                    self._keyboard.bind(
+                        on_key_down=self._on_key_down,
+                        on_textinput=self._on_textinput,
+                    )
+                except Exception:
+                    self._keyboard = None
+
+            def _close_soft_keyboard(self) -> None:
+                kb = self._keyboard
+                if kb is None:
+                    return
+                try:
+                    kb.unbind(on_key_down=self._on_key_down, on_textinput=self._on_textinput)
+                except Exception:
+                    pass
+                try:
+                    kb.release()
+                except Exception:
+                    pass
+                self._keyboard = None
+
+            def _on_keyboard_closed(self, *_args) -> None:
+                self._keyboard = None
+
+            def _on_key_down(self, keyboard, keycode, text, modifiers):
+                pg_key, pg_mod = self._map_kivy_key_to_pygame(keycode, modifiers or [])
+                event = pygame.event.Event(
+                    pygame.KEYDOWN,
+                    {
+                        "key": pg_key,
+                        "mod": pg_mod,
+                        "unicode": text or "",
+                    },
+                )
+                self._event_queue.append(event)
+                return True
+
+            def _on_textinput(self, keyboard, text: str):
+                if not text:
+                    return False
+                event = pygame.event.Event(
+                    pygame.TEXTINPUT,
+                    {
+                        "text": text,
+                    },
+                )
+                self._event_queue.append(event)
+                return True
+
+            def _sync_soft_keyboard_state(self) -> None:
+                try:
+                    active_inputs = [
+                        ti
+                        for ti in s.get_sprites_by_class(s.TextInput, active_only=True)
+                        if getattr(ti, "is_active", False)
+                    ]
+                except Exception:
+                    active_inputs = []
+
+                if active_inputs and self._keyboard is None:
+                    self._open_soft_keyboard()
+                elif not active_inputs and self._keyboard is not None:
+                    self._close_soft_keyboard()
+
             def _tick(self, _dt: float) -> None:
                 if self._surface is None:
                     self._on_resize()
@@ -293,6 +402,8 @@ def _tick(self, _dt: float) -> None:
                     self._draw_fatal_error()
                     return
 
+                self._sync_soft_keyboard_state()
+
                 self._present_surface()
 
         return _KivySpriteProWidget, App