УРОК 2 ІЗ 48
Робоче середовище і запуск прикладів
Робоче середовище і запуск прикладів
Передумови: будова браузерної гри, уміння працювати з файлами й terminal. Результат: ти запускаєш приклад через HTTP, знаходиш його модуль у DevTools і розумієш роль Node, npm та Vite.
Де виконується код
У нашій грі є два середовища. Browser виконує gameplay і надає window, document, canvas, input і browser storage. Node запускає інструменти розробки: dev server, compiler і bundler. Під час відкриття статичної гри користувачеві не потрібний Node на пристрої.
Самостійний діагностичний приклад:
console.log(typeof document);
У browser Console ти побачиш "object"; у Node — "undefined". document.querySelector у browser module має сенс, у звичайному Node процесі DOM немає. Тому запуск node main.js не є універсальним способом запуску browser game.
Dev server доставляє файли. Він не виконує рух гравця замість браузера. Production build готує ресурси для hosting; це окрема стадія, яку поглибимо в уроці 45.
Інструменти
Потрібні редактор коду, terminal і browser з DevTools. Node/npm потрібні для Vite та бібліотек пізніше. Перший Canvas проєкт можна запустити без npm через простий локальний HTTP server.
Зафіксований baseline курсу:
| Інструмент | Версія | Роль |
|---|---|---|
| Node | 24.21.0 LTS як рекомендована exact version | Виконання інструментів |
| Vite | 8.3.4 | Dev server і production build |
| TypeScript | 7.0.2 | Статична перевірка пізніше |
| PixiJS | 8.22.0 | Другий проєкт |
| Phaser | 4.2.1 | Великий проєкт |
Версії та первинні джерела: manifest. Vite8.3.4 задає Node engines ^20.19.0 || >=22.12.0; локальний Node24.14.0 також відповідає цьому діапазону. Вимога engines і вибір рекомендованої LTS версії мають різний зміст. Vite package у tag 8.3.4
Перевір доступні інструменти:
node --version
npm --version
python3 --version
Це незалежні команди. Відсутність Python не блокує курс: використай Vite. Відсутність Node не блокує перший HTTP запуск, якщо Python уже є. Рекомендовані exact versions потрібні для відтворюваності tooling, а не для пояснення game rules.
Чому відкриваємо через HTTP
Пряме відкриття HTML із файлової системи дає file:// URL. Модулі та requests у цьому режимі мають інші origin/security умови, ніж сайт. Щоб курс від початку працював у моделі майбутнього випуску, використовуємо локальний HTTP.
ES module підключається через <script type="module">. Import paths у browser — URL відносно модуля, а не довільний пошук файлів у всьому диску. ./main.js і ../model.js задають конкретні розташування. Без bundler bare import на кшталт 'pixi.js' потребує іншого механізму resolution. MDN JavaScript modules
Корінь HTTP сервера визначає, які URL доступні. Якщо сервер запущений із кореня курсу, шлях до прикладу починається /examples/00-first-scene/. Якщо з папки самого прикладу — він буде /. Розташування terminal і URL пов'язані; це часта причина 404.
Запускаємо перший приклад
Повні файли лежать у examples/00-first-scene. Із кореня курсу виконай:
python3 -m http.server 8765 --bind 127.0.0.1
Відкрий http://127.0.0.1:8765/examples/00-first-scene/. Server залишається працювати в terminal; Ctrl+C зупинить його. Якщо порт уже зайнятий, обери інший, наприклад 8766, і зміни його в URL. Browser cache і server process — різні речі: оновлення сторінки не перезапускає сам server.
На сторінці є арена, квадрат і дві кнопки. Початковий x=80. «Крок праворуч» змінює x на 40, після чого малюється новий кадр. «Скинути стан» повертає x=80. Тут поки що немає animation loop, тому кожну зміну легко простежити.
Структура прикладу:
index.html canvas, buttons, status і script module
main.js model state, input callbacks, render
style.css вигляд звичайної сторінки
package.json необов'язковий запуск через Vite
README.md інструкції й очікуваний результат
HTML задає елементи. CSS оформлює оболонку. JS змінює дані й малює. Таке розділення не заважає створити складнішу архітектуру пізніше: тепер видно, яку відповідальність ми переноситимемо в окремі модулі.
Простежуємо натискання
Фрагмент із реального main.js:
document.querySelector('#step').addEventListener('click', () => {
state.markerX = Math.min(state.markerX + 40, canvas.width - state.markerSize);
render();
});
Кнопка генерує event. Callback читає попередню координату, додає 40, обмежує її максимальною 640 - 24 = 616, записує значення в state і викликає render. Якщо x=600, наступний результат 616, а не 640: правий край маркера 616+24=640 залишається в арені.
Фрагмент render:
context.clearRect(0, 0, canvas.width, canvas.height);
context.fillStyle = '#101a2d';
context.fillRect(0, 0, canvas.width, canvas.height);
context.fillStyle = '#72efc6';
context.fillRect(state.markerX, state.markerY, state.markerSize, state.markerSize);
Очистили попередній кадр, намалювали фон, потім маркер. Порядок команд визначає порядок зображень. Властивість fillStyle є станом context; вона використовується наступними командами. Детальний Canvas state і координати — в уроці 09.
DevTools як інструмент спостереження
Відкрий DevTools через menu браузера. У Console перевір, що помилок немає. У Network після reload знайди index.html, main.js і style.css: успішний HTTP response та правильний content допомагають відокремити delivery issue від bug у коді.
У Sources відкрий main.js, постав breakpoint на присвоєнні state.markerX, натисни кнопку. Browser зупиниться перед виконанням рядка. Подивися старий state; виконай step over і побачиш новий x. Цей сценарій значно корисніший за здогад «щось не так із canvas». Поглиблення налагодження — в уроці 08.
DOM status показує координату окремо від картинки. Це простий приклад спостережуваності: можна перевірити модель навіть тоді, коли помилка малювання приховує об'єкт.
Коли потрібний Vite
Для bare package imports, зручного development workflow і build використаємо Vite. У папці examples/00-first-scene вже є package.json з exact vite: "8.3.4". Альтернативний запуск:
cd examples/00-first-scene
npm install
npm run dev
Відкрий адресу, яку надрукує Vite. Не вгадуй порт: він може змінитися, якщо інший process уже займає типовий.
package.json описує прямі залежності й scripts. Exact version фіксує цей пакет. Перший npm install створює package-lock.json, який фіксує також транзитивне дерево. Коли lockfile вже є та відповідає manifest, npm ci відтворює встановлення. Не запускай npm ci у папці без lockfile і не підмінюй його вигаданим JSON.
Зібрати й локально подивитися production assets:
npm run build
npm run preview
Dev server і preview мають різне призначення: preview показує результат build. Сам build не означає публікацію на hosting. Vite Guide
У майбутньому TS project додамо окремий tsc --noEmit: Vite transpilation не виконує type checking. Наявність .ts файла не гарантує runtime validation для JSON. Vite TypeScript features
Типові несправності
| Симптом | Як розділити причини | Виправлення |
|---|---|---|
404 на main.js | Network показує wrong URL | Звірити root сервера, шлях і регістр імен |
Cannot use import... | Script запущений як classic script | type="module" у HTML |
document is not defined | Browser code виконується в Node | Відкрити сторінку через HTTP |
| Server не стартує | Terminal повідомляє occupied port | Обрати вільний port і змінити URL |
npm ci завершується помилкою | Lockfile відсутній/неузгоджений | Спершу потрібен реальний install із manifest |
| Видно старий результат | Перевірити Sources/Network після reload | Переконатися, що редагуєш файл активного URL |
Практика й відповіді
- Постав breakpoint і зафіксуй x перед/після двох кліків. Очікування: 80→120→160. Поясни, чому render не змінює x.
- Зміни крок 40 на 75. Яким буде x після восьми кліків? Обмеження лишається 616. Розрахунок:80+8×75=680, clamp дає 616. Частина кліків на межі вже не змінює координату.
- Запусти HTTP server із папки прикладу. Який URL потрібний?
http://127.0.0.1:8765/, бо index лежить у root цього server. Старий/examples/...тепер дублює шлях і дасть 404. - Чим direct pin відрізняється від lockfile? Pin задає версію прямої залежності; lockfile фіксує resolved дерево для встановлення. Обидва потрібні для npm-проєкту.
Готовність: ти запускаєш приклад, зупиняєш server, знаходиш source і можеш відрізнити HTTP помилку від помилки стану. Наступний урок — проєктування гри.
Від читання — до результату.
Зміни код і запусти в браузері. Це відкрите демо: запуск коду не завершує урок автоматично.
Завантажуємо вправи…
ЗНАННЯ СТАЮТЬ НАВИЧКОЮ ЧЕРЕЗ ПРАКТИКУ
Готовий закріпити результат?
Прочитай матеріал і виконай завдання з уроку. Після цього відзнач свій маленький успіх.
Увійти, щоб пройти тести й зберегти прогрес