Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
296 lines (222 loc) · 9.34 KB

GETTING_STARTED.md

File metadata and controls

296 lines (222 loc) · 9.34 KB

🚀 Getting Started — SpritePro v3.5.0

Быстрый старт для новичков: установка, первая игра, базовые концепции

1️⃣ Установка (2 минуты)

Способ 1: Через pip (рекомендуемый)

pip install spritepro

Для mobile/Kivy-режима:

pip install "spritepro[kivy]"

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

git clone https://github.com/NeoXider/SpritePro.git
cd SpritePro
pip install -e .

2️⃣ Первая игра за 5 минут

Создайте файл my_game.py:

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):
        # Обработка ввода (WASD/стрелки)
        self.player.handle_keyboard_input()

# Запуск игры
s.run(scene=MainScene, size=(800, 600), title="Моя первая игра")

Запустите:

python my_game.py

Готово! У вас есть окно, сцена, игровой цикл и управление. 🎮

3️⃣ Шаблон проекта (CLI)

Для быстрого старта с правильной структурой:

python -m spritePro.cli --create

Или в отдельную папку:

python -m spritePro.cli --create MyGame

Что создаст:

  • main.py — точка входа
  • config.py — настройки и пути к ассетам
  • game_events.py — базовые события через EventBus
  • scenes/main_scene.py — главная сцена
  • scenes/second_scene.py — вторая сцена (заготовка)
  • scenes/main_level.json — стартовый уровень из редактора
  • assets/audio/, assets/images/ — папки для ассетов

4️⃣ Базовые концепции

Сцена (Scene)

Сцена — изолированный игровой мир с собственным циклом обновления. Каждая сцена имеет:

  • __init__() — инициализация объектов
  • update(dt) — вызывается каждый кадр
  • on_enter(context) — вызывается при входе в сцену
  • on_exit() — вызывается при выходе из сцены

Переключение между сценами:

s.restart_scene()           # Перезапуск текущей сцены
s.set_scene_by_name("menu") # Переключение на сцену "menu"

Спрайт (Sprite)

Спрайт — базовый визуальный объект. Основные возможности:

  • Позиционирование: set_position(x, y)
  • Трансформации: set_scale(), set_rotation(), set_color()
  • Движение: handle_keyboard_input(), move_towards()
  • Коллизии: collides_with(), collide_mask()

Создание спрайта:

# Пустой прямоугольник
sprite = s.Sprite("", (100, 100), (50, 30), scene=scene)

# С изображением
sprite = s.Sprite("player.png", (100, 100), (50, 30), scene=scene)

# С физикой
s.add_physics(sprite, shape=s.PhysicsShape.BOX)

Игровой цикл

SpritePro автоматически управляет игровым циклом:

  • update(dt) — вызывается ~60 раз в секунду (dt = delta time в секундах)
  • draw(screen) — отрисовка спрайтов
  • Обработка событий (keyboard, mouse)

Ваш код:

def update(self, dt):
    # Логика игры (вызывается каждый кадр)
    self.player.handle_keyboard_input()
    
    if s.input.was_pressed(s.pygame.K_SPACE):
        print("Прыжок!")

5️⃣ 5-минутный туториал

Шаг 1: Создаём игрока

class MainScene(s.Scene):
    def __init__(self):
        super().__init__()
        # Игрок в центре экрана, размер 50x30, скорость 5
        self.player = s.Sprite("", (50, 50), s.WH_C, speed=5, scene=self)

Шаг 2: Добавляем управление

def update(self, dt):
    # WASD / стрелки
    self.player.handle_keyboard_input()

Шаг 3: Добавляем камеру

def __init__(self):
    super().__init__()
    self.player = s.Sprite("", (50, 50), s.WH_C, speed=5, scene=self)
    
    # Камера следит за игроком
    s.set_camera_follow(self.player)

Шаг 4: Добавляем платформы

def __init__(self):
    super().__init__()
    self.player = s.Sprite("", (50, 50), s.WH_C, speed=5, scene=self)
    
    # Платформы (статическая физика)
    self.platform1 = s.Sprite("", (200, 20), (200, 400), scene=self)
    self.platform2 = s.Sprite("", (200, 20), (500, 350), scene=self)
    
    # Добавляем физику
    s.add_static_physics(self.platform1)
    s.add_static_physics(self.platform2)
    
    # Камера следит за игроком
    s.set_camera_follow(self.player)

Шаг 5: Запускаем!

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

Полный код:

import spritePro as s

class PlatformerScene(s.Scene):
    def __init__(self):
        super().__init__()
        self.player = s.Sprite("", (50, 50), s.WH_C, speed=5, scene=self)
        
        # Платформы
        self.platforms = [
            s.Sprite("", (200, 20), (200, 400), scene=self),
            s.Sprite("", (200, 20), (500, 350), scene=self),
        ]
        
        # Физика платформ
        for p in self.platforms:
            s.add_static_physics(p)
        
        # Камера
        s.set_camera_follow(self.player)

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

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

6️⃣ Полезные команды

Запуск демо-игр

# Физика
python -m spritePro.demoGames.physics_demo

# Твины (анимации)
python -m spritePro.demoGames.fluent_tween_demo

# Лейауты
python -m spritePro.demoGames.layout_demo

# Мультиплеер
python -m spritePro.demoGames.local_multiplayer_demo --quick

Mobile preview

# Preview разных экранов
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 build

# Сборка APK
python -m spritePro.cli --android .
python -m spritePro.cli --android . --android-mode release
python -m spritePro.cli --android . --android-orientation portrait

7️⃣ Следующие шаги

Изучите документацию

  1. API Reference — полный справочник всех классов и функций
  2. Physics Guide — физика pymunk + редактор сцен
  3. UI & Layouts — UI компоненты и автолейауты
  4. Animation & Tweens — анимации и плавные переходы
  5. Полный индекс — все статьи одним списком

Практикуйтесь

  • Изучите код демо-игр в spritePro/demoGames/
  • Попробуйте изменить параметры в туториале
  • Создайте свой проект через python -m spritePro.cli --create

Сообщество

🎯 Частые вопросы

Q: Как загрузить изображение?
A: s.Sprite("path/to/image.png", ...) или через Builder: s.sprite("image.png").build()

Q: Как добавить физику?
A: s.add_physics(sprite, shape=s.PhysicsShape.BOX) для динамического тела
s.add_static_physics(sprite) для статической (стена/пол)

Q: Как сделать анимацию?
A: Используйте твины: sprite.DoMove((100, 200)).SetDuration(1.0).Start()

Q: Как сохранить данные?
A: prefs = s.PlayerPrefs("save.json") → prefs.set_int("score", 100)

Q: Как запустить mobile-версию?
A: s.run(scene=MainScene, platform="kivy")

🎮 Готовы к следующему шагу?
Перейдите к API Reference или изучите демо-игры!