spritepro 3.0.0

A high-level cross-platform 2D game framework for Python with desktop, web, and mobile workflows.

🎮 SpritePro

Создавайте 2D игры на Python быстро: мультиплатформенно для desktop, web и mobile

Мощный мультиплатформенный игровой фреймворк, который превращает создание 2D игр из сложной задачи в удовольствие.

---

🎨 Sprite Editor — визуальный редактор сцен

В SpritePro появился встроенный редактор спрайтов в стиле Unity: создавайте сцены визуально, расставляйте объекты мышью и сохраняйте в JSON для использования в игре.

Запуск через терминал

python -m spritePro.cli --editor

или коротко:

python -m spritePro.cli -e

Что делать в редакторе

1. Добавлять объекты — кнопки Rect, Circle, Ellipse для примитивов; Add или перетаскивание файлов для изображений.
2. Редактировать — инструменты Move (G), Rotate (R), Scale (T); перемещение, вращение, масштаб мышью.
3. Настраивать — Inspector справа: имя, позиция, размер, цвет, слой (Sorting Order).
4. Сохранять — Ctrl+S или кнопка Save; сцена сохраняется в JSON.
5. Загружать в игру — spawn_scene("scene.json", scene=...) и получение объектов по имени: rt.exact("player").Sprite(speed=5), rt.exact("button").to_button(...).

Подробнее: документация редактора.

---

SpritePro — высокоуровневая мультиплатформенная библиотека для 2D игр на Python: автоматическая отрисовка, камера, ввод, сцены, физика, UI, частицы, редактор уровней и мультиплеер. Базовый рантайм работает на pygame, для mobile есть запуск через Kivy host, а для web — отдельный build flow, так что одну и ту же игру можно разворачивать под desktop, web и mobile.

---

📑 Содержание

• ⚡ Почему SpritePro? · 🌟 Особенности
• 🚀 Быстрый старт — установка, первая игра, шаблон --create
• 📱 Mobile и Build — Kivy, Android, web, сборка библиотеки и билдов
• 💡 Примеры возможностей · 🎮 Что можно создать?
• 📖 Документация — главная карта и ссылки по разделам
• 🎬 Демо-игры · 📦 Что внутри?
• 🎯 Ключевые преимущества · 🆚 SpritePro vs pygame
• 🚀 Начните прямо сейчас! · 🤝 Сообщество · 📄 Лицензия

---

⚡ Почему SpritePro?

🚀 Вместо этого:

# С pygame нужно писать ВСЁ самому:
import pygame
pygame.init()
screen = pygame.display.set_mode((800, 600))
clock = pygame.time.Clock()
sprite = pygame.sprite.Sprite()
# ... 50+ строк кода для базовой игры ...

✨ С SpritePro:

import spritePro as s

class MainScene(s.Scene):
    def __init__(self):
        super().__init__()
        self.player = s.Sprite("player.png", (50, 50), s.WH_C, speed=5, scene=self)

    def update(self, dt):
        self.player.handle_keyboard_input()

s.run(scene=MainScene, size=(800, 600), title="My Awesome Game", fill_color=(20, 20, 30))

Это всё! Игра запускается через движок, без ручного цикла в каждом файле. 🎉

---

🌟 Что делает SpritePro особенным?

💎 Автоматизация всего, что раздражает

С чистым pygame	Со SpritePro
❌ Ручная отрисовка каждого спрайта	✅ Спрайты рисуются сами, один мир — один цикл
❌ Ручная камера и viewport	✅ Камера из коробки, слежение одной строкой
❌ Своя обработка клавиш и мыши	✅ InputState (was_pressed, оси), EventBus
❌ Ручные слои и порядок отрисовки	✅ sorting_order, группы, LayeredUpdates
❌ mixer.Sound и своя логика громкости	✅ AudioManager: load, play, музыка, громкость
❌ Парсинг JSON/файлов для сохранений	✅ PlayerPrefs: set_int/get_int, set_float, …
❌ Циклы и спрайты для частиц	✅ ParticleEmitter + ParticleConfig, emit()
❌ Свой движок или интеграция Box2D/pymunk	✅ Физика на pymunk: add_physics, типы тел, коллизии
❌ Ручная расстановка UI (x, y каждого элемента)	✅ Layout: flex, сетка, круг, линия; ScrollView
❌ Кодом расставлять объекты на уровне	✅ Редактор сцен (JSON), spawn_scene, объекты по имени
❌ Отдельный код под mobile-host	✅ Один и тот же runtime: s.run(..., platform="pygame") / s.run(..., platform="kivy")

🎯 Всё, что нужно для игры - уже внутри:

• ✅ Автоматическая отрисовка - просто создайте спрайт, он сам отрисуется
• ✅ Умная камера - слежение за объектами одной строкой
• ✅ Простая физика - столкновения, гравитация, движение из коробки
• ✅ Система частиц - красивые эффекты за 3 строки кода
• ✅ UI компоненты - кнопки, переключатели, текст готовы к использованию
• ✅ Анимации и твининг - плавные переходы без головной боли
• ✅ Аудио менеджер - управление звуком и музыкой централизованно
• ✅ Система сохранений - PlayerPrefs как в Unity!
• ✅ Якоря позиционирования - размещайте объекты точно где нужно
• ✅ Автолейаут (Layout) - flex, сетка, круг, линия для автоматического размещения дочерних спрайтов (документация)
• ✅ ScrollView — скроллируемая область для контента (лейаут), колёсико и перетаскивание мышью, опциональная маска (клиппинг по viewport)
• ✅ Готовые сцены (readyScenes) — подключаемые сцены: ChatScene (мультиплеерный чат с историей, скроллом и маской) и ChatStyle для настройки оформления
• ✅ Мультиплеер — сетевые игры: TCP relay, контекст (send/poll/send_every), EventBus; быстрый старт через s.networking.run(). Готовое лобби (run(use_lobby=True)): один экран — имя, хост/клиент, порт, IP, список игроков; у хоста кнопки «В игру» и «Назад», у клиента — «Назад». По нажатию «В игру» игра запускается у обоих. Подробно: Networking — лобби. Мини-курс в папке multiplayer_course/ — 10 уроков от обмена сообщениями до готовой мини-игры.
• ✅ Mobile-рантайм — запуск через Kivy: s.run(..., platform="kivy"), встроенный host для touch-ввода и мобильных demo

---

🚀 Быстрый старт (30 секунд)

Установка

Способ 1: Установка через pip (рекомендуемый)

Это самый простой и быстрый способ начать работу со SpritePro.

pip install spritepro

Все зависимости, включая pygame, будут установлены автоматически.

Для мобильного host-режима:

pip install "spritepro[kivy]"

Обновление

Чтобы обновить SpritePro до последней версии, используйте команду:

pip install --upgrade spritepro

Способ 2: Для разработчиков (из исходного кода)

Этот способ подходит, если вы хотите внести свой вклад в разработку или использовать самую последнюю, еще не опубликованную версию.

1. Клонируйте репозиторий:

   git clone https://github.com/NeoXider/SpritePro.git
   

2. Перейдите в папку проекта:

   cd SpritePro
   

3. (Опционально) Установите в режиме редактирования:

   pip install -e .
   

   Это позволит вам изменять код библиотеки и сразу видеть изменения в своих проектах.

Ваша первая игра

import spritePro as s

class MainScene(s.Scene):
    def __init__(self):
        super().__init__()
        self.player = s.Sprite("", (50, 50), s.WH_C, speed=5, scene=self)

    def update(self, dt):
        self.player.handle_keyboard_input()

s.run(scene=MainScene, size=(800, 600), title="My Game", fill_color=(20, 20, 30))

Вот и всё! У вас уже есть игра с управлением, отрисовкой и игровым циклом. Для mobile достаточно сменить platform на "kivy". 🎮

Для файлов ассетов задавайте путь явно от текущего файла, а не от рабочей папки:

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.

⚡ Быстрый старт 2.0 (шаблон проекта)

python -m spritePro.cli --create

Создаст main.py в текущей папке и структуру assets/audio, assets/images, scenes. Шаблон теперь сразу современный:

• main.py запускает игру через s.run(...)
• scenes/main_scene.py — основная сцена, которая грузит scenes/main_level.json
• scenes/second_scene.py — вторая почти пустая сцена-заготовка, чтобы было удобно расширять проект
• scenes/main_level.json — стартовый уровень в формате Sprite Editor

То есть новый проект после --create уже показывает нормальную scene-based структуру, а не только один файл с ручным циклом.

Если хотите создать проект в отдельной папке, укажите путь:

python -m spritePro.cli --create MyGame

📱 Mobile и Build

Mobile игры

Теперь на SpritePro можно делать и мобильные 2D-игры. Идея простая:

s.run(scene=MainScene, platform="pygame")
s.run(scene=MainScene, platform="kivy")

То есть логика игры остаётся той же, меняется только host-платформа.

Полезные ссылки:

• Mobile guide — как устроен Kivy runtime и touch-ввод
• Hybrid Kivy UI guide — Kivy menu/layout + встроенная игровая область SpritePro
• Build guide — как собирать library, web и mobile build

Быстрый preview разных экранов через CLI:

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

Быстрая Android/APK-сборка через CLI:

python -m spritePro.cli --android .
python -m spritePro.cli --android . --android-mode release
python -m spritePro.cli --android . --android-mode spec

Что уже работает

• desktop runtime через pygame
• web build через pygbag
• mobile host через Kivy
• hybrid-режим: Kivy UI + встроенный SpritePro-виджет
• demo, которые можно запускать через --kivy

Отдельная инструкция по сборке

Подробный гайд вынесен в отдельный файл:

• docs/building.md

---

💡 Примеры "Вау!" возможностей

🎨 Создайте игру за минуту

import spritePro as s

class PlatformerScene(s.Scene):
    def __init__(self):
        super().__init__()
        self.player = s.Sprite("player.png", (50, 50), (100, 300), speed=5, scene=self)
        self.platforms = [
            s.Sprite("", (200, 20), (200, 400), scene=self),
            s.Sprite("", (200, 20), (500, 350), scene=self),
        ]
        self.emitter = s.ParticleEmitter(s.ParticleConfig(
            amount=10,
            speed_range=(50, 100),
            lifetime_range=(0.5, 1.0),
        ))

        self.player.set_collision_targets(self.platforms)
        s.set_camera_follow(self.player)

    def update(self, dt):
        self.player.handle_keyboard_input()
        if self.player.velocity.length() > 0:
            self.emitter.emit(self.player.rect.center)

s.run(scene=PlatformerScene, size=(800, 600), title="Platformer", fill_color=(135, 206, 235))

Результат: Полноценная платформер-игра с физикой, камерой и эффектами!

🎵 Звук и музыка - проще некуда

# Получаем готовый AudioManager
audio = s.audio_manager

# Вариант 1: Загружаем и сохраняем для многократного использования
jump_sound = audio.load_sound("jump", "sounds/jump.mp3")
jump_sound.play()  # Автоматически применяются настройки громкости!

# Вариант 2: Прямое воспроизведение по пути (без загрузки!)
audio.play_sound("sounds/jump.mp3")  # Автоматически загрузит и воспроизведет!
audio.play_sound("sounds/coin.wav", volume=0.8)  # С кастомной громкостью

# Вариант 3: В одну строку для быстрого воспроизведения
audio.load_sound("explosion", "sounds/explosion.mp3").play()

# Музыка
audio.play_music("music/background.mp3", volume=0.5)  # Сразу с нужной громкостью!
# Или установить громкость отдельно
audio.set_music_volume(0.5)  # 50% громкости

Никаких pygame.mixer.Sound(), никаких ручных настроек - всё работает!

🎯 UI за секунды

# Кнопка с автоматической анимацией
button = s.Button(
    "", (200, 50), (400, 300),
    "Начать игру",
    on_click=lambda: print("Игра началась!")
)

# Переключатель музыки
music_toggle = s.ToggleButton(
    "", (150, 40), (100, 50),
    text_on="Музыка: ВКЛ",
    text_off="Музыка: ВЫКЛ",
    on_toggle=lambda is_on: s.audio_manager.set_music_enabled(is_on)
)

# Текст с якорем (автоматическое позиционирование!)
score_text = s.TextSprite(
    "Score: 0", 36, (255, 255, 255),
    (s.WH.x - 10, 10),
    anchor=s.Anchor.TOP_RIGHT  # Прижмется к правому краю!
)

Всё работает автоматически - наведение, клики, анимации!

⌨️ Ввод и события (как в Unity)

import pygame
import spritePro as s

class InputScene(s.Scene):
    def __init__(self):
        super().__init__()
        s.events.on("quit", self.on_quit)

    def on_quit(self, event):
        print("Quit")

    def update(self, dt):
        if s.input.was_pressed(pygame.K_SPACE):
            print("Space pressed")

s.run(scene=InputScene, size=(800, 600), title="Input")

Если нужен доступ к сырым событиям pygame — используйте s.pygame_events.

🧩 Сцены без пересоздания и перезапуск

import spritePro as s

class MainScene(s.Scene):
    def on_enter(self, context):
        pass

s.run(scene=MainScene, size=(800, 600), title="Scenes")

# Перезапуск сцены
s.restart_scene()         # текущая сцена
s.restart_scene("main")   # по имени

🎆 Частицы - это просто

# Создаем эффект взрыва
explosion = s.ParticleEmitter(s.ParticleConfig(
    amount=50,
    speed_range=(100, 300),
    angle_range=(0, 360),
    lifetime_range=(0.5, 1.5),
    gravity=s.Vector2(0, 200)
))

# Взрыв при клике
explosion.emit(mouse_pos)  # Всё! 50 частиц летят во все стороны!

3 строки кода = красивый эффект взрыва!

💾 Сохранения как в Unity

# Создаем PlayerPrefs
prefs = s.PlayerPrefs("save.json")

# Сохраняем что угодно
prefs.set_float("score", 1250.5)
prefs.set_int("level", 5)
prefs.set_string("player_name", "Hero")
prefs.set_vector2("player_pos", (400, 300))

# Загружаем
score = prefs.get_float("score", 0)
level = prefs.get_int("level", 1)
name = prefs.get_string("player_name", "Player")
pos = prefs.get_vector2("player_pos", (0, 0))

# Всё автоматически сохраняется в JSON!

Никаких ручных парсеров, никаких сложных форматов!

---

🎮 Что можно создать?

✅ Платформеры

• Автоматические столкновения
• Камера следует за игроком
• Готовые частицы для эффектов

✅ Аркады

• Система здоровья из коробки
• Таймеры для событий
• Готовые UI элементы

✅ RPG

• Система сохранений
• Инвентарь (через спрайты)
• Диалоги (через TextSprite)

✅ Пазлы

• Интерактивные элементы
• Анимации переходов
• Система состояний

✅ Tower Defense

• Пути для врагов (через move_towards)
• Система частиц для эффектов
• UI для интерфейса

✅ Мультиплеерные игры

• Встроенная сетевая подсистема (NetServer / NetClient, relay)
• Синхронизация позиций, состояний, событий (ready, start, счёт)
• Мини-курс в папке multiplayer_course/: уроки 1–10 с примерами, практикой и решениями

✅ Мобильные игры

• Запуск той же игры через platform="kivy"
• Экранные кнопки, touch-ввод, Kivy-host
• Основа для Android-сборок через Kivy/Buildozer

---

📊 Сравнение с альтернативами

Функция	pygame	arcade	SpritePro
Автоматическая отрисовка	❌	✅	✅
Готовая камера	❌	✅	✅
Физика (2D)	❌	✅	✅ pymunk, типы тел, коллизии
Layout (flex, сетка, круг)	❌	❌	✅
Редактор сцен (JSON)	❌	❌	✅
Мультиплеер (TCP, лобби)	❌	❌	✅
Система частиц	❌	❌	✅
AudioManager	❌	❌	✅
PlayerPrefs	❌	❌	✅
Якоря позиционирования	❌	❌	✅
Простота использования	⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐

SpritePro = pygame + физика, Layout, редактор сцен, мультиплеер и всё остальное для игры.

---

🎯 Ключевые преимущества

🚀 Скорость разработки

• Создайте прототип игры за минуты, а не часы
• Меньше кода = меньше багов
• Больше времени на геймплей, меньше на инфраструктуру

🎨 Красота из коробки

• Автоматические анимации кнопок
• Плавные переходы (tweening)
• Готовые эффекты частиц
• Цветовые эффекты

🛠️ Мощность и гибкость

• Полный доступ к pygame под капотом
• Расширяемая архитектура
• Можно использовать как pygame, так и высокоуровневые функции

📚 Отличная документация

• Подробные примеры для каждого компонента
• Демо-игры с исходным кодом
• Понятные API

---

🎬 Демо-игры

Все с открытым исходным кодом. Полный список — DOCUMENTATION_INDEX.md → Демо.

Демо	Описание
Ping Pong	Игра с меню, звуком, физикой
Physics Demo	Гравитация, отскок, платформы, статика/кинематика
Mobile Orb Collector	Mobile-first demo: экранные кнопки, touch, Kivy
Kivy Hybrid Demo	Kivy UI + встроенная игровая область SpritePro
demoGames/	Сцена из редактора: level.json, spawn_scene, get_physics, платформер. python demoGames/main.py
Fireworks	Частицы
Tween	Плавные анимации
Мультиплеер	local_multiplayer_demo, курс multiplayer_course

Запуск из корня репозитория: python -m spritePro.demoGames.physics_demo или python demoGames/main.py.

---

📦 Что внутри?

🎮 Основные компоненты

• Sprite — базовый класс с движением и визуальными эффектами
• Button, ToggleButton — кнопки и переключатели с анимациями
• TextSprite — текст с якорями
• Bar — полосы прогресса (HP, опыт)

⚙️ Физика

• pymunk — мир тел, типы DYNAMIC/STATIC/KINEMATIC, формы (PhysicsShape), гравитация, коллизии. Тело из сцены: s.get_physics(sprite). docs/physics.md

📐 Layout и UI

• Layout — автолейаут: flex, сетка, круг, линия; контейнер — спрайт или rect. docs/layout.md
• ScrollView — скроллируемая область (колёсико, перетаскивание)
• Slider, TextInput, Pages — слайдеры, поля ввода, страницы

🎨 Игровые системы

• Animation — анимации по кадрам
• Tween — плавные переходы; Fluent API: sprite.DoMove(...).SetEase(...). docs/tween.md
• Timer, Health — таймеры и здоровье
• ParticleEmitter — частицы (конфиг, emit)

🌐 Мультиплеер

• NetServer / NetClient, relay, контекст (send, poll, send_every)
• Лобби — экран с именем, хост/клиент, порт, «В игру». docs/networking.md
• Курс: multiplayer_course/ — 10 уроков

📱 Mobile и build

• Kivy host — запуск game loop внутри mobile-оболочки
• run(platform="kivy") / run_kivy(...) — full-screen режим по умолчанию
• run_kivy_hybrid(...) / create_kivy_widget(...) — Kivy UI вокруг встроенной игровой области
• Подробно: docs/mobile.md, docs/kivy_hybrid.md, docs/building.md

🛠️ Утилиты

• AudioManager — звук и музыка
• PlayerPrefs — сохранения в JSON
• Camera — камера и слежение за объектом
• Builder — fluent API для спрайтов и частиц

🎨 Редактор сцен

• Sprite Editor — сцены в стиле Unity: Move/Rotate/Scale, Hierarchy, Inspector, JSON
• В игре: spawn_scene("level.json", ...), объекты по имени, физика из сцены. docs/sprite_editor.md
• Запуск: python -m spritePro.cli --editor или -e

---

📖 Документация

Главная карта — DOCUMENTATION_INDEX.md: всё по полочкам (старт, основы, физика, редактор, UI, демо, порядок изучения).

Раздел	Куда смотреть
Старт	Установка, Первая игра, Шаблон проекта
Обзор	docs/OVERVIEW.md — Layout, физика, Builder, мультиплеер кратко
Физика	docs/physics.md — pymunk, типы тел, PhysicsShape, сцена из редактора; docs/physics_issues.md — нюансы
Редактор сцен	docs/sprite_editor.md — редактор, spawn_scene, get_physics из сцены
Демо	DOCUMENTATION_INDEX.md → Демо; сцена из редактора: demoGames/
Сеть	docs/networking.md; курс: multiplayer_course/
Mobile	docs/mobile.md — Kivy runtime, touch, mobile demo
Hybrid Kivy UI	docs/kivy_hybrid.md — меню/кнопки Kivy + встроенная игра SpritePro
Build	docs/building.md — library wheel/sdist, web, Android, packaging
Вся документация	docs/README.md — навигация по docs

---

🎯 Примеры использования

Игра с меню, звуком и сохранениями

import spritePro as s

class MainScene(s.Scene):
    def __init__(self):
        super().__init__()

        audio = s.audio_manager
        audio.load_sound("click", "sounds/click.mp3")
        self.click_sound = audio.get_sound("click")
        audio.play_music("music/bg.mp3")

        self.prefs = s.PlayerPrefs("save.json")
        self.high_score = self.prefs.get_int("high_score", 0)
        self.score = 0

        self.start_button = s.Button(
            "", (200, 50), s.WH_C, "Начать игру",
            on_click=lambda: self.click_sound.play(),
            scene=self,
        )
        self.player = s.Sprite("player.png", (50, 50), (100, 300), speed=5, scene=self)
        s.set_camera_follow(self.player)

    def update(self, dt):
        self.player.handle_keyboard_input()
        if self.score > self.high_score:
            self.prefs.set_int("high_score", self.score)

s.run(scene=MainScene, size=(800, 600), title="My Game", fill_color=(20, 20, 30))

Всё работает вместе из коробки!

---

🆚 SpritePro vs Обычный pygame

❌ С pygame нужно писать:

# 100+ строк для базовой игры
import pygame
pygame.init()
screen = pygame.display.set_mode((800, 600))
clock = pygame.time.Clock()
sprites = pygame.sprite.Group()
# ... обработка событий ...
# ... ручная отрисовка ...
# ... ручное управление камерой ...
# ... ручная система слоев ...
# ... и так далее ...

✅ С SpritePro:

import spritePro as s

class MainScene(s.Scene):
    def __init__(self):
        super().__init__()
        self.player = s.Sprite("player.png", (50, 50), s.WH_C, speed=5, scene=self)

    def update(self, dt):
        self.player.handle_keyboard_input()

s.run(scene=MainScene, size=(800, 600), title="Game")

В 10 раз меньше кода! 🚀

---

🎁 Бонусы

✨ Автоматические фичи

• Автоматическая отрисовка - создали спрайт? Он уже рисуется!
• Автоматическое обновление - Tween, Animation, Timer обновляются сами
• Автоматическая камера - слежение за объектами одной строкой
• Автоматические столкновения - физика из коробки

🎨 Готовые эффекты

• Пульсация, мерцание, волны для кнопок
• Плавные переходы (easing)
• Система частиц
• Цветовые эффекты

🛠️ Удобные утилиты

• Якоря позиционирования (как в Unity!)
• PlayerPrefs (как в Unity!)
• AudioManager (централизованное управление звуком)
• Готовые компоненты (Bar, TextSprite, Button)

---

🚀 Начните прямо сейчас!

pip install spritepro

Затем — Ваша первая игра выше или шаблон: python -m spritePro.cli --create.

---

📊 Статистика

• ⚡ В 10 раз меньше кода чем с чистым pygame
• 🚀 В 5 раз быстрее разработка прототипов
• 🎯 100% готовых компонентов для типичных задач
• 📚 Полная документация с примерами
• 🎮 30+ демо-игр с исходным кодом

---

🤝 Сообщество

• 💬 Вопросы? Откройте Issue
• 🐛 Нашли баг? Сообщите
• 💡 Есть идея? Предложите
• ⭐ Понравилось? Поставьте звезду!

---

📄 Лицензия

Открытый исходный код. Используйте свободно в своих проектах!

---

🎮 Начните создавать игры уже сегодня!

SpritePro - это не просто библиотека. Это ваш путь от идеи к игре!

📖 Документация • 🎮 Демо-игры • 💬 Вопросы

Создано с ❤️ для разработчиков игр