Gravity Shift

English secondary version is available in the project as a draft/reference translation. See the English draft at README_EN.md. The project itself is Ukrainian and all current documentation remains in Ukrainian as the primary language.

Космічний платформер про пошук себе, гравітацію, простір і неочевидні правила світу.

Лінійний платформер Gravity Shift

Це гра про подорожі та головоломки у забутих світах.

Ти — гравець, набутий унікальних сил. Подорожуєш по світах в надії на роз'яснення. Чому ти тут? З чого ти складаєшся? Хто тебе створив? Де правда взагалі?

---

╰┈─┈─┈─┈─┈─┈─┈─┈─┈─┈─┈─┈─╯

🪐 Що є у грі

Гра насичена багатьма фішками та функціями, з яких створено її всесвіт.

Дрібні деталі, такі як розгін та зупинка, плавність камери, математична текстуризація простору, дають лише найменшу краплю в деталях, які тільки можуть бути у цій грі.

👤 Гравець

Невідома речовина. В залежності від неї вирішуються його фішки.

Має гравітаційні властивості, міняє гравітацію при доторку до свого матеріалу іншої полярності — це є портали.

Здатен скорочуватися при падінні, обходячи гравітацію.

Має систему ривків (спринту), що допомагає долати великі відстані або зупиняти падіння, якщо це потрібно.

🌌 Світи

Унікальні простори з фокусом на можливості та зручність розробки.

Кожен світ має власний main.py, objects.json, Resources (музика, картинки, звуки) та особистий файл-згруповувач (усе має міститися у ньому).

Всі авторські деталі можна додати у main.

✨ Оформлення

Стиль класичного Pygame з додаваннями класичної космічної тематики, із урахуванням продуманості опцій та підтримкою власних витворів (модинг).

У грі будуть інфо-панелі, що розбиті на категорії:

• Користувача
• Розробника
• Підказки
• Регулювання
• Розмова (у майбутньому)

Завжди унікальні текстурки реалізовані математикою. Лише головні об'єкти уваги задіяні як зображення.

---

⚙️ Залежності та встановлення пакетів

Структура файлу

___________________________
├───────Gravy Shift───────┤
├── core_v#/               
│   ├── __init__.py        
│   ├── classes.py         
│   ├── lighting.py        
│   └── save.json          
│                          
├── 1_world/               
│   ├── Resources/         
│   │   ├── Music/...      
│   │   ├── Picture/...    
│   │   └── Sounds/...     
│   ├── main.py            
│   └── objects.json       
│                          
├── 2_world/  (якщо є)     
│   ├── Resources/         
│   │   ├── Music/...      
│   │   ├── Picture/...    
│   │   └── Sounds/...     
│   ├── main.py            
│   └── objects.json       
│                          
├── docs                   
│   ├── LICENSE            
│   ├── notes.txt          
│   ├── README_EN.md       
│   ├── README.md          
│   └── requirements.txt   
│                          
├── START_HERE.py          
└─────────────────────────┘

Переконайтеся, що структура файлу належна.

Пакети, які потрібні

Перед запуском необхідно встановити додаткові Python-пакети.

Потрібні бібліотеки:

• python
• pygame
• colorama
• moderngl
• numpy

Для комфорту рекомендовано використовувати pip і файл requirements.txt:

cd docs
pip install -r requirements.txt

Системні вимоги

• Windows 10/11 або сумісна ОС.
• Python (ver 3.8+, ver printed game 3.13.7 also 3.13.14).
• Оновлені драйвери відеокарти з підтримкою OpenGL (для moderngl).
• Аудіо може працювати через стандартні звукові драйвери Windows.

Почати гру можна завдяки START_HERE.py (головне меню та навігація) або ручним методом виклику потрібного main.py файлу.

---

🧩 Як працює код і гнучкість

Архітектура

Правила та фактура гри знаходиться в папці core_v#/classes.py (основні класи гравця, об'єктів, сцени), lighting.py (освітлення) та save.json (збереження).

Логіка конкретного світу розміщується в кожному власному модулі світу, наприклад MARS_world/, і має свій main.py та objects.json.

Модель взаємодії

Через START_HERE.py можна завантажувати main.py світу, почавши гру.

У коді main.py підключається список об'єктів з objects.json і активуються потрібні модулі з classes.py — вони дають готову логіку існуючих об'єктів, камери та текстур.

Гнучкість

Система задумана модульно: додати новий світ — створити папку з main.py, objects.json і Resources/ (музика, картинки, звуки). Рушій автоматично підхопить стандартні файли за конвенцією. Та намалює нову планету у головному меню, готову до запуску.

Комфорт

Код наповнений нотатками та історією по будові. У місцях інтерему будуть роз'яснення дії рядків. Для більшості головних класів та функцій створені заголовки.

---

🧭 Для тих, хто хоче зробити свій мод

Створіть папку NAME_world/ (обов'язково залиште у назві _world для авторозпізнання) поруч з іншими світами і додайте:

• main.py — точка входу і логіка рівня (в ньому додайте всі свої нові фішки та правила та активовуйте ігровий цикл);
• objects.json — опис усіх об'єктів (позиції, типи, властивості);
• Resources/ → Music/, Picture/, Sounds/ — медіафайли для рівня.

Інтерфейс зі core_v#

У main.py підключайте потрібні класи напряму, наприклад:

from core_v1.classes import Player, Platform, TunnelPortal, JumpPad, Campfire, Finish

Правила і події

Визначайте власні правила у main.py (наприклад, нестандартну гравітацію, режими переміщення) і обробляйте їх у своєму коді замість зміни ядра.

Збереження

Для збереження стану використовуйте save_full_progress() та standart_progress() або робіть власні виклики до save.json відповідно до конвенції про формат.

Фішки для розробників

• DEV_MODE: у ядро вбудовано режим розробника для покращення досвіду, аналітика та інші корисні фішки.
  • Під час розробки увімкніть DEV_MODE, щоб:
    • бачити позиції сутностей в реальному часі;
    • перевіряти різні змінні (вимикаючи або перемикаючи);
    • використовувати мишу для розмітки та видобовування об'єктів;
    • мати привілеї у грі (між керуванням та зором).
• JSON-система завантаження рівнів: завантаження через objects.json дає зручну, декларативну модель рівнів — легко версіонувати та редагувати контент зовнішніми інструментами. А автонумерація за index дасть не загубитися у кількості.
• ModernGL та GLSL (SDF-based): якщо ModernGL і власні GLSL шейдери інтегровані в ядро, використовуйте їх для розвантаження рендерингу й візуальних ефектів — це підвищує продуктивність і дає доступ до сучасних графічних технік. (Розділяючи обов'язки між CPU та GPU)

---

⚡ Для чутливих до оптимізації

Мій комп'ютер також не один з потужних, тому мій код з самого початку мав фокус на якість. Ось що вже зроблено і можна ще підкреслити:

• Розмір ігрового вікна прямо впливає на кількість видимого простору та кількість обрахунків процесору;
• У файлі lighting.py рядок self.downscale впливає на пропорційну обрахунок пікселів (4 рази для 1600x900 = 400x225, це 1 440 000 проти 90 000 пікселів!);
• Плашки інфо-панелей вимальовуються тільки коли з'являються і коли є нові відомості (ніяких 60 разів на секунду, тільки накладання);
• DEV_MODE додає допоміжні елементи і діагностику, але також збільшує витрати — для звичайної гри тримайте його вимкненим.

Поради для користувачів, які хочуть полегшити гру без зміни механіки

• Зменшіть роздільність вікна або запустіть гру в меншому вікні;
• Вимкність інфо-панелі (F9), якщо вам потрібна суха гра без відомостей;
• Тримайте вимкненим режим розробника та інші налаштування для відладки (ці панелі оновлюються періодично);
• Використовуйте простіші моди з меншою кількістю активних об'єктів і логіки;
• А для самих модерів, намагайтеся уникати надлишкової кількості об'єктів у світі. Де можна обійтися одним або менше.
• Якщо потрібно зробити старт швидшим на вашому ПК, можна попередньо скомпілювати Python-код у байткод (.pyc-кеш). Це не є exe-збіркою і не дає приросту в FPS, але може зменшити час ініціалізації на повторних запусків:

python -m compileall -f core_v1 MARS_world START_HERE.py

Це корисно як підготовка до повторного старту в тому ж середовищі, а не як перемикання гри у формат настільного виконуваного файлу.

(Недописаний пункт)

Для створення об'єктів, що на поверхні та під тінню, використовуйте "indoor": true у словнику platforms, щоб штучно прибрати засвіт від сонця.

(Тут буде ще більше пунктів)

---

📝 Авторське та користувальницьке право (Коротко)

Авторство та захист

Цей проект, його ядро (core_v#/) та вся базова архітектура розроблені та захищені авторськими правами:

• Автор гри: Moorzik Kin / Ніколаєць Богдан

Правила використання коду

Виконання коду гравцем — це використання, дозволене у межах однієї інсталяції гри.

Користувач:

• ✓ Може запускати гру та грати у неї;
• ✓ Може досліджувати код для навчання;
• ✗ Не може напряму копіювати фрагменти коду й виставляти проект як власний;
• ✗ Не може розповсюджувати модифіковане ядро як окремий продукт.

Авторство модів та розширень

Користувач матиме авторство на модифікації, що створює особисто. Він може змінювати та розширювати тільки:

• main.py (логіка та правила власного світу);
• objects.json (конфігурація об'єктів);
• Resources/ (музика, картинки, звуки власного світу);
• Персональний файл-згруповувач (папка розташування вище переліченого).

Поширення модів

Моди можуть бути поширені окремо як доповнення до Gravity Shift, за умови:

• вказання авторства модифікації;
• збереження оригінальної гри Gravity Shift окремим продуктом;
• відсутності розповсюдження ядра core_v#/ чи базового коду як частини моду.

Моди самі по собі можуть не запускатися без оригінальної гри. Це нормально для доповнень — вони мають працювати разом із Gravity Shift, але не бути повноцінною самостійною грою.

Детальніше про авторство, обмеження ядра, права користувача та правила модингу описано в окремому юридично-описовому документі LICENSE. Там зафіксовано, що оригінальний рушій і базова логіка гри залишаються під авторським контролем, а власний _world контент може розвиватися як авторська модифікація.

---

M.