Skip to content

overview.md

Latest commit

 

History

History
210 lines (147 loc) · 10.3 KB

overview.md

File metadata and controls

210 lines (147 loc) · 10.3 KB

Overview (Обзор)

Краткий обзор возможностей библиотеки.

Общая идея

SpritePro — высокоуровневый фреймворк для 2D‑игр на Python (поверх Pygame). Многое уже сделано (отрисовка, камера, события, слои, звук, сохранения и т.д.), чтобы быстро собирать прототипы. Методы установки у Sprite, TextSprite, Button, Bar, Layout и др. возвращают self — удобно собирать цепочки: sprite.set_position(...).set_scale(1.5).set_color(...).

Layout (автолейауты)

Layout наследуется от Sprite и сам рисуется. Контейнером может быть другой спрайт, (x, y, w, h) или сам Layout (container=None).

Типы лейаутов

Тип Enum Поведение
Flex Row FLEX_ROW Элементы в ряд с автопереносом при нехватке ширины
Flex Column FLEX_COLUMN Элементы в колонку с автопереносом
Horizontal HORIZONTAL Ряд слева направо
Vertical VERTICAL Колонка сверху вниз
Grid GRID Сетка rows × cols
Circle CIRCLE Элементы по окружности (radius, start_angle, rotate_children)
Line LINE Элементы вдоль ломаной [(x,y), ...]

Параметры

  • gap, padding — отступы
  • align_main — START, CENTER, END, SPACE_BETWEEN, SPACE_AROUND, SPACE_EVENLY
  • align_cross — START, CENTER, END
  • use_local — координаты в локальной системе родителя (дети двигаются вместе с контейнером)
  • child_anchor — якорь позиционирования дочерних элементов

Удобные функции

from spritePro.layout import (
    layout_flex_row, layout_flex_column,
    layout_horizontal, layout_vertical,
    layout_grid, layout_circle, layout_line,
)

Они создают и применяют нужный Layout и возвращают его.

Демо

  • layout_demo.py — все 7 типов лейаутов
  • menu_shop_demo.py — меню и инвентарь на flex/grid

Подробнее: layout_ui.md

Физика

Модуль spritePro.physics построен на pymunk: мир тел (PhysicsWorld), динамические/статические/кинематические тела, гравитация, трение, отскок, коллизии. Формы коллайдеров задаются через PhysicsShape (AUTO, BOX, CIRCLE, LINE) или строки; поворот спрайта с физикой не синхронизируется (обновляется только позиция).

  • s.physics — прокси к глобальному миру. s.add_physics, s.add_static_physics, s.add_kinematic_physics, s.PhysicsConfig, s.PhysicsShape — создание тел; по умолчанию тело автоматически добавляется в мир (auto_add=True). Использование через s. гарантирует работу с тем же миром, что обновляется в s.update().
  • PhysicsConfig — mass, gravity, friction, bounce; опционально collision_category, collision_mask.
  • on_collision — колбэк при столкновении.
  • s.physics.set_bounds(rect) — границы экрана с отскоком. При загрузке сцены через spawn_scene типы физики и настройки (mass, friction, bounce, маски) из редактора применяются к глобальному миру. Тело из сцены: s.get_physics(sprite); донастройка в коде: body.set_bounce(0), body.velocity.x/y, см. physics_guide.md.

Демо: physics_demo.py, hoop_bounce_demo.py, ping_pong; сцена из редактора с физикой — demoGames/ в корне репозитория. Подробнее: physics_guide.md.

Builder (Fluent API)

s.sprite(path) и s.particles() — цепочки вызовов для создания спрайтов и эмиттеров частиц.

  • Спрайт: .position(), .scale(), .color(), .crop(), .border_radius(), .mask(), .build() — build() возвращает типизированный Sprite.
  • Частицы: .amount(), .lifetime(), .speed(), .gravity(), .position(), .auto_emit(), .build().

Демо: builder_demo.py. Подробнее: BUILDER_API.md.

Мультиплеер

TCP + JSON‑сообщения формата {"event": "...", "data": {...}}.

Компоненты

  • NetServer — TCP relay (пересылает сообщения всем клиентам)
  • NetClient — клиент с send() и poll()
  • s.run(..., multiplayer=True) — рекомендуемая единая точка входа для современных multiplayer-игр; s.networking.run() оставлен как low-level runner

Режимы запуска

  • --server — только сервер
  • --host_mode — сервер + клиент в одном процессе
  • --quick — хост + клиенты в разных окнах
  • --host, --port, --clients, --net_debug

MultiplayerContext (s.multiplayer_ctx)

После s.multiplayer.init_context(net, role) доступны:

  • ctx.send(event, data) — отправка
  • ctx.poll() — очередь входящих сообщений
  • ctx.send_every(event, data, interval) — троттлинг (например, для позиций)
  • ctx.client_id, ctx.role, ctx.is_host
  • ctx.state — общий словарь состояния
  • ctx.seed, ctx.random — детерминированный рандом для сетевых игр

Пример синхронизации позиции

class MultiplayerScene(s.Scene):
    def __init__(self, net, role):
        super().__init__()
        s.multiplayer.init_context(net, role)
        self.ctx = s.multiplayer_ctx
        self.me = s.Sprite("", (50, 50), (200, 300), scene=self)
        self.other = s.Sprite("", (50, 50), (600, 300), scene=self)
        self.remote_pos = [600.0, 300.0]

    def update(self, dt):
        pos = self.me.get_world_position()
        self.ctx.send_every("pos", {"pos": list(pos)}, 0.016)
        for msg in self.ctx.poll():
            if msg.get("event") == "pos":
                self.remote_pos[:] = msg.get("data", {}).get("pos", [0, 0])
        self.other.set_position(self.remote_pos)

Курс по мультиплееру

В multiplayer_course/ — 11 уроков: обмен сообщениями → синхронизация → лобби → меню → результаты → финальная сборка → продвинутые темы и декораторы.

Подробнее: networking_guide.md

Другие подсистемы

Спрайты и UI

  • Sprite — базовый спрайт (позиция, физика, столкновения по rect и по маске: collides_with, collide_mask)
  • Button, ToggleButton
  • TextSprite — текст с якорями
  • Bar — полосы прогресса (HP, опыт)
  • DraggableSprite, MouseInteractor

Анимация и эффекты

  • Animation — покадровая анимация
  • Tween — плавные переходы (position, scale, color, alpha и др.)
  • Fluent Tween API (на Sprite): DoMove, DoScale, DoRotateBy, DoColor, DoFadeOut/In, SetEase, SetDelay, OnComplete, SetLoops, SetYoyo, Kill — демо fluent_tween_demo.py
  • ParticleEmitter — частицы (шаблоны: sparks, smoke, fire, snow и др.)

Игровая логика

  • Timer — таймеры
  • Health — здоровье
  • Scenes — сцены (меню, игра, пауза)
  • PlayerPrefs — сохранение/загрузка в JSON

Утилиты

  • AudioManager — звук и музыка
  • Camera — слежение за целью, shake
  • InputState — ввод в стиле Unity
  • EventBus — подписка на события
  • Anchor — якоря позиционирования (как в Unity)
  • Debug overlay — сетка, логи, FPS

Полезные пути

Что Где
Layout docs/ui/layout_ui.md
Tween, Fluent API docs/core/tween_system.md, docs/core/tween_presets.md
Networking networking_guide.md
Курс мультиплеера multiplayer_course/README.md
Демо Layout spritePro/demoGames/layout_demo.py
Демо Fluent Tween spritePro/demoGames/fluent_tween_demo.py
Демо меню/инвентарь spritePro/demoGames/menu_shop_demo.py
Демо мультиплеер spritePro/demoGames/local_multiplayer_demo.py
Демо физики spritePro/demoGames/physics_demo.py
Демо Builder spritePro/demoGames/builder_demo.py
Демо обруч/отскок spritePro/demoGames/hoop_bounce_demo.py
Крестики-нолики multiplayer_course/tictactoe_example/

Запуск демо

# Layout
python spritePro/demoGames/layout_demo.py

# Fluent Tween API
python spritePro/demoGames/fluent_tween_demo.py

# Меню/магазин
python spritePro/demoGames/menu_shop_demo.py

# Мультиплеер (хост + клиенты)
python spritePro/demoGames/local_multiplayer_demo.py --quick --host 127.0.0.1 --port 5050

# Крестики-нолики
python multiplayer_course/tictactoe_example/example_tictactoe_multiplayer.py --quick