v1.3.3

Author: bochkarnikov-victor

CHANGELOG.md

@@ -8,11 +8,21 @@
 ## [Unreleased]
 
 ### Планируется
-- Система инвентаря
 - Продвинутые UI компоненты
-- Система частиц
 - Мобильная поддержка
 
+## [1.3.3]
+
+### Added
+- **docs/networking.md**: раздел «Лучшие практики» — примитивы JSON (что можно отправлять), позиция списком `list(pos)` и приём через `data.get("pos", ...)`, значения по умолчанию, троттлинг.
+- **docs/networking.md**: таблица полей контекста, «Кто такой этот процесс», «Отображаемое имя», «Как отличить своего игрока от чужих».
+
+### Changed
+- **Позиция по сети**: во всех примерах и курсе — отправка `{"pos": list(pos)}`, приём `remote_pos[:] = data.get("pos", ...)`; убраны лишние `float()` и поля `x`/`y`.
+- **Лобби (урок 4)**: при отправке `join` добавляем себя в `players` локально (`players.add(name)`), чтобы хост и все клиенты видели полный список (реле не отдаёт сообщение отправителю).
+- **Демо и курс**: упрощена обработка `sender_id` (без лишних try/except и int()), компактное получение `other_id = data.get("sender_id")` где уместно.
+- Версия библиотеки 1.3.3 (патч).
+
 ## [1.3.2]
 
 ### Added

docs/networking.md

@@ -213,6 +213,53 @@ python your_game.py --server --tick_rate 20
 - `run()` не работает в интерактивной консоли — нужен файл.
 - Если `poll()` не вызывается, сообщения копятся в очереди.
 
+## Лучшие практики
+
+### Что можно отправлять по сети (примитивы JSON)
+
+Сообщения сериализуются в **JSON**. В `data` можно передавать только то, что умеет JSON:
+
+- **Числа** — `int`, `float`
+- **Строки** — `str`
+- **Списки и словари** — вложенные структуры из перечисленного
+- **Булевы** — `True` / `False`
+- **Пусто** — `None` (в JSON будет `null`)
+
+Объекты вроде `Vector2`, спрайтов, классов — **нельзя** отправлять как есть. Конвертируйте в примитивы: позиция → `list(pos)` или `[pos.x, pos.y]`, состояние → `dict` с полями. На приёме вы получаете уже числа/списки/словари — приводить к `float()` не нужно.
+
+### Позиция удалённого игрока: один список, обновление на месте
+
+Один список на удалённую позицию и обновление через срез — не пересоздаём объект и не теряем ссылку для `set_position()`. Позицию удобно отправлять списком: на приёме одно присваивание. `get_world_position()` возвращает `Vector2`; он итерируем, поэтому подойдёт `list(pos)`:
+
+```python
+# Отправка: pos — Vector2 из get_world_position(), list(pos) → [x, y]
+ctx.send_every("pos", {"pos": list(pos)}, 0.05)
+
+# Приём: один буфер, обновляем на месте
+remote_pos = [x0, y0]
+for msg in ctx.poll():
+    if msg.get("event") == "pos":
+        data = msg.get("data", {})
+        remote_pos[:] = data.get("pos", [0, 0])
+other.set_position(remote_pos)
+```
+
+По умолчанию при отсутствии ключа можно подставить предыдущее значение: `data.get("pos", remote_pos)` — тогда при пропуске пакета позиция не дёрнется. Вариант с полями `{"x": pos.x, "y": pos.y}` тоже допустим; на приёме тогда `remote_pos[:] = [data.get("x", 0), data.get("y", 0)]`.
+
+### Данные из JSON — уже нужные типы
+
+После `json.loads` поля приходят как числа, строки, списки, словари. Приводить к `float()` или `int()` вручную не нужно — используйте значения как есть: `data.get("x", 0)`, `data.get("sender_id")`.
+
+### Значения по умолчанию при разборе payload
+
+- `data.get("key", default)` — если ключа нет или событие пришло без поля, подставится `default`. Для позиции удобны `0` или текущее значение (`remote_pos[0]`).
+- Для вложенных структур: `data.get("scores", self.scores)` — не перезаписываем локальное состояние, если в сообщении пусто.
+- Если вы сами всегда отправляете полный payload (например, `pos` с `x`, `y`, `sender_id`), на приёме можно не проверять на `None` — присваивайте `other_id = data.get("sender_id")` и при отображении обработайте `other_id is None` (например, показать «?»).
+
+### Троттлинг позиции
+
+Используйте `ctx.send_every("pos", {"pos": list(pos)}, interval)` вместо `ctx.send("pos", ...)` в каждом кадре — так вы ограничите частоту отправки (например, 20 раз/сек при `interval=0.05`) и снизите нагрузку на сеть.
+
 ## Debug‑режим мультиплеера (консоль)
 
 Включите вывод отправки/получения сообщений:
@@ -247,17 +294,49 @@ def multiplayer_main(net: s.NetClient, role: str):
 s.networking.run()
 ```
 
-Контекст хранит:
-
-- `client_id` (0 для хоста, для клиентов назначается сервером по порядку);
-- `role` и `is_host`:
-  - `role="host"` — процесс, который поднимает сервер (host‑режим), `is_host=True`,
-  - `role="client"` — обычный клиент,
-  - `role="server"` — сервер без клиента (в этом режиме контекст не создаётся).
-  Значение роли задаётся `run()` через параметры запуска (`--host_mode`, `--quick`, `--server`).
-- `state` для глобальных значений;
-- `seed` и `random` для детерминированного случайного генератора;
-- методы `send()`, `poll()`, `send_every()`.
+### Кто такой «этот процесс» (наш компьютер)
+
+Код `multiplayer_main` выполняется **в одном из процессов** — в том же окне, что открылось при запуске. Этот процесс и есть «наш компьютер»: мы не «получаем» его с сервера, мы в нём уже находимся. Чтобы понять, хост мы или клиент и какой у нас номер, используйте поля контекста после `init_context()`.
+
+### Поля контекста и возможные значения
+
+| Поле / метод | За что отвечает | Возможные значения |
+|--------------|-----------------|--------------------|
+| `ctx.client_id` | Числовой ID этого участника. Уникален в сессии. | `0` — хост; `1`, `2`, … — клиенты (назначаются сервером по порядку подключения). |
+| `ctx.role` | Роль процесса в сети. | `"host"` — процесс с поднятым сервером (одно окно); `"client"` — обычный клиент; `"server"` — только сервер без игры (контекст не создаётся). |
+| `ctx.is_host` | Является ли этот процесс хостом. | `True` — мы хост, `False` — мы клиент. Удобно для ветвления логики («если хост — рассылаю roster»). |
+| `ctx.state` | Произвольный словарь для глобального состояния. | Любой dict, общий на весь процесс. |
+| `ctx.seed` / `ctx.random` | Детерминированный рандом для мультиплеера. | См. раздел «Детерминированный рандом». |
+| `ctx.send(event, data)` | Отправка сообщения в сеть. | — |
+| `ctx.poll()` | Получение входящих сообщений. | Список dict с полями `event`, `data`. |
+| `ctx.send_every(event, data, interval)` | Отправка не чаще чем раз в `interval` секунд. | — |
+
+Роль задаётся при запуске: `run()` передаёт в `multiplayer_main` аргумент `role` в зависимости от режима (`--host_mode`, `--quick`, `--server`). Контекст только отражает уже выбранную роль.
+
+### Отображаемое имя участника (name)
+
+В примерах часто встречается переменная вроде `name = "host" if ctx.is_host else f"client_{client_index + 1}"`. Это **не** «получение сервера» и не данные с сети: это **локально выбранное отображаемое имя** для этого процесса (чтобы в лобби показывать «host», «client_1», «client_2»). Номер клиента для имени можно взять из `os.environ.get("SPRITEPRO_NET_INDEX", "0")` (индекс окна клиента) или строить логику по `ctx.client_id` (0 у хоста, 1 и выше у клиентов). Сервер имён не выдаёт — имя задаётся в коде под текущую роль и ID.
+
+### Как отличить своего игрока от чужих (цвет, камера)
+
+«Наш» экземпляр игры — это **этот процесс**: мы не получаем его по сети, мы в нём. В этом процессе один спрайт обновляется от **локального ввода** (клавиатура, мышь) и его позиция **отправляется** в сеть — это «я». Остальные спрайты обновляются из `ctx.poll()` — это «другие». Цвет задаём в коде: свой — один (например синий), чужие — другой (красный).
+
+```python
+ctx = s.multiplayer_ctx
+me = s.Sprite("", (40, 40), (200, 300))    # двигаем мы, шлём позицию в сеть
+other = s.Sprite("", (40, 40), (600, 300)) # позицию получаем из ctx.poll()
+
+# В этом процессе «я» всегда один и тот же — тот, кого мы контролируем.
+MY_COLOR = (70, 120, 220)    # синий
+OTHER_COLOR = (220, 70, 70)  # красный
+me.set_color(MY_COLOR)
+other.set_color(OTHER_COLOR)
+
+# В игровом цикле: движение me от s.input, отправка ctx.send("pos", ...);
+# other.set_position(...) из данных, пришедших в ctx.poll().
+```
+
+У каждого участника в своём окне «я» синий, «другие» красные — так и задумано: в своём экземпляре игры свой персонаж выделен. Для нескольких чужих игроков храните словарь `others[client_id]` и задайте им один цвет «чужой» или разные по `client_id`.
 
 ### Детерминированный рандом
 

multiplayer_course/2/example_sync_positions.py

@@ -39,16 +39,13 @@ def multiplayer_main(net: s.NetClient, role: str) -> None:
         me.set_position(pos)
 
         # Отправляем pos не чаще чем раз в 0.2 сек — меньше нагрузки на сеть.
-        ctx.send_every("pos", {"x": pos.x, "y": pos.y}, 0.2)
+        ctx.send_every("pos", {"pos": list(pos)}, 0.2)
 
         # Читаем входящие сообщения; при pos обновляем remote_pos и двигаем other.
         for m in ctx.poll():
             if m.get("event") == "pos":
                 d = m.get("data", {})
-                remote_pos[:] = [
-                    float(d.get("x", remote_pos[0])),
-                    float(d.get("y", remote_pos[1])),
-                ]
+                remote_pos[:] = d.get("pos", [0, 0])
         other.set_position(remote_pos)
 
 

multiplayer_course/2/practice_sync_positions.py

@@ -43,13 +43,13 @@ def multiplayer_main(net: s.NetClient, role: str) -> None:
         me.set_position(pos)
 
         # Отправка позиции с лимитом.
-        # TODO: используйте ctx.send_every("pos", {"x": pos.x, "y": pos.y}, 0.05).
+        # TODO: используйте ctx.send_every("pos", {"pos": list(pos)}, 0.05).
         pass
 
         # Прием сетевых сообщений.
         for msg in ctx.poll():
             if msg.get("event") == "pos":
-                # TODO: прочитайте координаты и обновите remote_pos.
+                # TODO: прочитайте координаты из data и обновите remote_pos (например remote_pos[:] = data.get("pos", [0, 0])).
                 pass
 
         # Применяем позицию удаленного игрока.

multiplayer_course/2/solution_sync_positions.py

@@ -39,16 +39,13 @@ def multiplayer_main(net: s.NetClient, role: str) -> None:
         me.set_position(pos)
 
         # Отправка позиции 20 раз/сек.
-        ctx.send_every("pos", {"x": pos.x, "y": pos.y}, 0.05)
+        ctx.send_every("pos", {"pos": list(pos)}, 0.05)
 
         # Прием позиции удаленного игрока.
         for msg in ctx.poll():
             if msg.get("event") == "pos":
                 d = msg.get("data", {})
-                remote_pos[:] = [
-                    float(d.get("x", remote_pos[0])),
-                    float(d.get("y", remote_pos[1])),
-                ]
+                remote_pos[:] = d.get("pos", [0, 0])
 
         # Применяем удаленную позицию.
         other.set_position(remote_pos)

multiplayer_course/4/example_lobby.py

@@ -4,44 +4,60 @@
 и рассылает roster; все обновляют отображаемый список игроков.
 """
 
+import os
+
 import spritePro as s
 
 
 def multiplayer_main(net: s.NetClient, role: str) -> None:
-    s.get_screen((800, 600), "Lesson 4 - Lobby")
+    client_index = int(os.environ.get("SPRITEPRO_NET_INDEX", "0"))
+    window_tag = "HOST" if role == "host" else f"CLIENT {client_index + 1}"
+    s.get_screen((800, 600), f"Lesson 4 - Lobby [{window_tag}]")
     ctx = s.multiplayer.init_context(net, role)
 
-    # Имя по роли; players — множество имён (у хоста), roster — итоговый список для отображения.
-    name = "host" if ctx.is_host else "client"
+    # Отображаемое имя этого участника (не «получение сервера»).
+    # «Это наш компьютер» = этот процесс; кто мы — задаётся ctx.is_host и ctx.client_id.
+    # Имя задаём сами, чтобы в roster были видны host, client_1, client_2.
+    name = "host" if ctx.is_host else f"client_{client_index + 1}"
     players = set()
     roster = []
     joined = False
 
     title = s.TextSprite("Lobby", 34, (240, 240, 240), (20, 20), anchor=s.Anchor.TOP_LEFT)
+    me_text = s.TextSprite("", 20, (170, 220, 255), (20, 58), anchor=s.Anchor.TOP_LEFT)
     roster_text = s.TextSprite("", 24, (240, 240, 240), (20, 80), anchor=s.Anchor.TOP_LEFT)
     hint = s.TextSprite(
-        "Ожидание игроков...", 20, (180, 180, 180), (20, 520), anchor=s.Anchor.TOP_LEFT
+        "Host + 2 clients: client_2 появляется через 6 сек.",
+        20,
+        (180, 180, 180),
+        (20, 520),
+        anchor=s.Anchor.TOP_LEFT,
     )
 
     while True:
         s.update(fill_color=(18, 18, 24))
+        me_text.set_text(
+            f"Я: {name} | role={ctx.role} | id={ctx.client_id} | window={window_tag}"
+        )
 
-        # Один раз при входе шлём join, чтобы все (и хост) знали о нас.
+        # Один раз при входе шлём join. Реле не отдаёт сообщение обратно отправителю,
+        # поэтому добавляем себя в players локально — иначе хост не увидит себя в roster.
         if not joined:
             joined = True
             ctx.send("join", {"name": name})
+            players.add(name)
 
         for msg in ctx.poll():
             event = msg.get("event")
             data = msg.get("data", {})
             if event == "join":
-                # Хост добавляет имя и рассылает обновлённый roster.
                 player_name = data.get("name")
-                if player_name:
-                    players.add(player_name)
-                    if ctx.is_host:
-                        roster = sorted(players)
-                        ctx.send("roster", {"players": roster})
+                if not player_name:
+                    continue
+                players.add(player_name)
+                if ctx.is_host:
+                    roster = sorted(players)
+                    ctx.send("roster", {"players": roster})
             elif event == "roster":
                 # Все клиенты (и хост при получении своего же roster) обновляют список.
                 roster = list(data.get("players", []))
@@ -50,5 +66,5 @@ def multiplayer_main(net: s.NetClient, role: str) -> None:
 
 
 if __name__ == "__main__":
-    # Запуск примера.
-    s.networking.run()
+    # clients=3 => host + client_1 через 3 сек + client_2 через 6 сек.
+    s.networking.run(clients=3, client_spawn_delay=3, net_debug=True)