Розробка браузерних ігор
Розмір тексту: 16

УРОК 2 ІЗ 48

Робоче середовище і запуск прикладів

20 хв читання та практикиТвій наступний крок

Робоче середовище і запуск прикладів

Передумови: будова браузерної гри, уміння працювати з файлами й 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 курсу:

ІнструментВерсіяРоль
Node24.21.0 LTS як рекомендована exact versionВиконання інструментів
Vite8.3.4Dev server і production build
TypeScript7.0.2Статична перевірка пізніше
PixiJS8.22.0Другий проєкт
Phaser4.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.jsNetwork показує wrong URLЗвірити root сервера, шлях і регістр імен
Cannot use import...Script запущений як classic scripttype="module" у HTML
document is not definedBrowser code виконується в NodeВідкрити сторінку через HTTP
Server не стартуєTerminal повідомляє occupied portОбрати вільний port і змінити URL
npm ci завершується помилкоюLockfile відсутній/неузгодженийСпершу потрібен реальний install із manifest
Видно старий результатПеревірити Sources/Network після reloadПереконатися, що редагуєш файл активного URL

Практика й відповіді

  1. Постав breakpoint і зафіксуй x перед/після двох кліків. Очікування: 80→120→160. Поясни, чому render не змінює x.
  2. Зміни крок 40 на 75. Яким буде x після восьми кліків? Обмеження лишається 616. Розрахунок:80+8×75=680, clamp дає 616. Частина кліків на межі вже не змінює координату.
  3. Запусти HTTP server із папки прикладу. Який URL потрібний? http://127.0.0.1:8765/, бо index лежить у root цього server. Старий /examples/... тепер дублює шлях і дасть 404.
  4. Чим direct pin відрізняється від lockfile? Pin задає версію прямої залежності; lockfile фіксує resolved дерево для встановлення. Обидва потрібні для npm-проєкту.

Готовність: ти запускаєш приклад, зупиняєш server, знаходиш source і можеш відрізнити HTTP помилку від помилки стану. Наступний урок — проєктування гри.

СПРОБУЙ ВЛАСНОРУЧ

Від читання — до результату.

Зміни код і запусти в браузері. Це відкрите демо: запуск коду не завершує урок автоматично.

Завантажуємо вправи…

ЗНАННЯ СТАЮТЬ НАВИЧКОЮ ЧЕРЕЗ ПРАКТИКУ

Готовий закріпити результат?

Прочитай матеріал і виконай завдання з уроку. Після цього відзнач свій маленький успіх.

Увійти, щоб пройти тести й зберегти прогрес