🎮 Гра "3 в ряд" (STM32 Hardware Engine)

📌 Опис проєкту

Мікроконтролерна реалізація логічної гри Match-3 для плати STM32F0. Уся логіка гри, математика, анімація гравітації та збереження прогресу виконуються безпосередньо на апаратному рівні (MCU), а зв'язок з комп'ютером відбувається через бінарний UART-протокол.

---

💻 Вимоги до системи

PC Client

Параметр	Значення
ОС	Windows 10 / Windows 11 (64-bit)
Python	3.11+ (рекомендовано 3.12)
Залежності	pygame-ce latest, pyserial 3.5+

Hardware (MCU)

Параметр	Значення
Плата	STM32F0Discovery
МК	STM32F051R8 (ARM Cortex-M0)
IDE	STM32CubeIDE
Компілятор	GCC for ARM Embedded (arm-none-eabi)

---

⚙️ Архітектура

┌─────────────────────┐        UART 38400        ┌──────────────────────┐
│   PC Client         │  ◄──────────────────────►  │   STM32F051R8        │
│   (Python/pygame)   │      Бінарний протокол    │   (Ігровий рушій)    │
│                     │         6 байт/пакет      │                      │
│  - Графіка          │                           │  - Логіка Match-3    │
│  - Введення         │                           │  - Гравітація        │
│  - Лідерборд UI     │                           │  - Flash NVM         │
│  - UART клієнт      │                           │  - Лідерборд         │
└─────────────────────┘                           └──────────────────────┘

Принцип: MCU — єдине джерело правди. Всі збіги, гравітація, deadlock-перевірка виконуються на платі. Клієнт лише відображає стан.

---

🧩 Механіка гри

• Поле: 8×8 клітинок, 6 кольорів
• Мінімальний збіг: 3 кульки в ряд (горизонталь або вертикаль)
• Кінець гри: автоматично при відсутності можливих ходів (Deadlock)

Нарахування балів

Збіг	Бали
3 кульки	30 (базовий)
4 кульки	60 (бонус ×2)
5+ кульок	100 (супер-бонус)

Генерація поля

При старті автоматичне утворення ліній заборонено. Перевірка при генерації: $$A_{xy(1)} = A_{xy(2)} = x \Rightarrow \text{обрати інший колір}$$

---

💾 Flash NVM (Збереження)

Адреса збережень: 0x0800FC00 · Адреса лідерборду: 0x0800F800

Ігрові слоти

• 3 незалежні слоти (0, 1, 2) в межах однієї сторінки Flash (1 КБ)
• Кожен слот містить: magic number, score (uint32_t), ім'я (15 символів), стан поля (64 байти)

Wear Leveling (лідерборд)

Для мінімізації стирань Flash реалізовано wear leveling: нові записи пишуться в наступну вільну комірку без стирання сторінки. Стирання відбувається лише коли всі 9 комірок заповнені (~90 000 оновлень).

---

📡 UART Протокол

Формат: 38400 baud, 8N1 · Пакет: 6 байт фіксованої довжини · Таймаут: 10 мс

Структура пакету

Byte 0	Byte 1	Byte 2	Byte 3	Byte 4	Byte 5
CMD	ADDR_H	ADDR_L	DATA_H	DATA_L	CRC-8

CRC-8: Поліном 0x07, Init 0x00. При невалідному CRC MCU ігнорує пакет.

Таблиця команд

HEX	Команда	Напрямок	Опис
0x10	NEW GAME	PC→MCU	Нова гра. Відповідь: AA + дамп поля пакетами 0x16
0x11	SWAP	PC→MCU	Хід: байти 1-4 = r1, c1, r2, c2. Відповідь: AA=успіх, EE=помилка, DD=deadlock
0x12	FINISH	PC→MCU	Завершити гру, записати у лідерборд. Відповідь: AA=топ-5, BB=не потрапив
0x14	GET CELL	PC→MCU	Колір клітинки r,c. Відповідь: Byte3=колір
0x15	GET SCORE	PC→MCU	Поточний рахунок. Відповідь: score як uint32_t у байтах 1-4
0x16	UPDATE CELL	MCU→PC	Асинхронне оновлення клітинки під час анімації
0x20	SET NAME	PC→MCU	Ім'я чанками по 3 символи. ADDR_H=чанк (0-5)
0x30	SAVE GAME	PC→MCU	Зберегти у слот. ADDR_H=слот (0-2)
0x31	LOAD GAME	PC→MCU	Завантажити слот. Відповідь: AA + ім'я (0x32) + score (0x15) + поле (0x16)
0x32	GET NAME	MCU→PC	Ім'я з Flash чанками по 3 символи (+ 0x33-0x36)
0x40	GET LEADERS	PC→MCU	Топ-5. Відповідь: імена (0x41,0x43,0x44,0x45) + score (0x42) × 5

---

🏆 Лідерборд

• Топ-5 гравців зберігається у Flash MCU — незалежно від ПК
• При підключенні клієнт автоматично завантажує актуальні рекорди
• При виході: MCU виконує Update_Leaderboard() → Flash Erase → Write (~20 мс)
• Максимальний score: 16 777 215 (3 байти у пакеті 0x42)
• Максимальна довжина імені: 15 символів ASCII

---

🖥 Запуск клієнта

Встановлення

pip install pygame-ce pyserial

Запуск

python match3_final.py

1. Кнопками < / > виберіть COM-порт ([BOARD DETECTED] = правильний)
2. Натисніть CONNECT
3. Клієнт автоматично завантажить лідерборд з Flash MCU
4. Введіть ім'я та оберіть NEW GAME або завантажте збережену гру

⚠️ При запуску .exe — якщо Windows показує «Захист SmartScreen», натисніть Додаткові відомості → Все одно виконати

---

🚀 Прошивка MCU

1. Відкрийте STM32CubeIDE, імпортуйте папку проєкту
2. Переконайтесь що підключені модулі: main.c (UART), game.c (логіка), save.c (Flash)
3. Build: натисніть молоток або make -j16 all → 0 errors
4. Підключіть плату через ST-LINK USB → Run (зелений трикутник)

⚠️ При першому старті після оновлення прошивки Leaderboard_Deduplicate() автоматично очистить некоректні записи з Flash

---

🔧 Відомі обмеження

Обмеження	Значення
Максимальний score	16 777 215
Максимальна довжина імені	15 символів ASCII
Підтримувані ОС клієнта	Windows 10 / 11
Baudrate	38400 (фіксований)
Слотів збереження	3
Позицій у лідерборді	5

---

📜 Ліцензія

MIT License — вільне використання з посиланням на автора.

---

Розроблено як навчальний проєкт · STM32F051R8 + Python/pygame