Отладочный оверлей на JavaScript: хитбоксы, FPS и журнал событий

Коротко

Отладочный оверлей — слой поверх игры, который показывает то, что игрок не видит: рамки столкновений, время кадра и последние игровые события. Для 2D-игры хватает четырёх частей: рамки хитбоксов с цветом по типу, счётчик FPS с худшим кадром, журнал событий на 8 строк со схлопыванием повторов и список наблюдаемых переменных. Оверлей включается одной клавишей, в выпуске выключен, а его логика проверяется без браузера.

Содержание

  1. Что показывает оверлей и чем он не является
  2. Хитбоксы: цвет по типу, пунктир для триггеров
  3. Счётчик кадров: среднее врёт, нужен худший кадр
  4. Журнал событий: 8 строк и схлопывание повторов
  5. Код на JavaScript и проверка в Node.js
  6. Практический сценарий: «враг иногда не получает урон»
  7. Когда вам это не подойдёт

Что показывает оверлей и чем он не является

Оверлей отвечает на вопрос «что игра думает прямо сейчас», а не «почему браузер тормозит». Он рисуется поверх кадра после всей игровой графики и показывает четыре вещи:

ЧастьЧто видноКакую ошибку ловит
Рамки хитбоксовпрямоугольники столкновений поверх спрайтоврамка меньше или сдвинута относительно картинки
Счётчик кадровсреднее, худший кадр, число долгих кадровподёргивания, которых не видно в среднем FPS
Журнал событийпоследние 8 событий с номером кадрасобытие не пришло, пришло дважды или не в том порядке
Наблюдение3–5 переменных: число объектов, скорость герояобъекты копятся, скорость не сбрасывается

Профилирование — другая задача: панель Performance записывает работу браузера и показывает, на что ушло время кадра. Как ею пользоваться, — в нашей статье про просадки FPS. Оверлей подсказывает, когда записывать профиль, но не заменяет его.

Хитбоксы: цвет по типу, пунктир для триггеров

Рамки рисуют контуром толщиной 1 пиксель, цвет зависит от типа объекта, а триггеры — пунктиром. Мы используем три цвета: зелёный для твёрдых тел, красный для зон урона, жёлтый пунктир для триггеров вроде контрольной точки или двери. Пунктир задаётся методом setLineDash: по MDN он принимает массив длин штрихов и промежутков, а пустой массив возвращает сплошную линию — его нужно вызвать после рисования, иначе пунктиром станет всё остальное.

Две детали, без которых рамки обманывают:

  • Координаты камеры. Рамку рисуют в тех же экранных координатах, что и спрайт: x - cam.x, y - cam.y. Если оверлей рисуется до сдвига камеры или после масштаба, рамки «плывут» относительно героя, и ошибку ищут не там.
  • Полпикселя. Линия толщиной 1 по целой координате ложится на границу двух пикселей и размывается на оба. Сдвиг на 0.5 после округления даёт чёткую линию; ширину и высоту уменьшаем на 1, чтобы рамка не вылезала за объект.

Рамки рисуют из тех же данных, что использует проверка столкновений, а не из размеров спрайта. Иначе оверлей покажет то, что вы думаете о хитбоксе, а не то, что видит физика. Как устроена сама проверка пересечения прямоугольников, — в статье про игровой цикл и AABB.

Счётчик кадров: среднее врёт, нужен худший кадр

Счётчик кадров должен показывать три числа: средний FPS, худший кадр в миллисекундах и число кадров длиннее бюджета. При 60 Гц бюджет кадра — 1000 / 60 ≈ 16,67 мс. Одно среднее не годится: в нашем прогоне 120 кадров, где 116 длятся 16,6 мс, а 4 — по 41,7 мс, среднее даёт 57 FPS. Игрок при этом видит 4 заметных рывка за 2 секунды.

Время кадра берут из аргумента колбэка requestAnimationFrame: по MDN это отметка времени в миллисекундах, общая для всех колбэков одного кадра. Разница между соседними отметками и есть длительность кадра. Хранить её удобно в кольцевом буфере на 120 значений — это 2 секунды при 60 Гц: память не растёт, а окно достаточно короткое, чтобы рывок не потерялся.

Ещё одна ловушка: по MDN браузеры ставят requestAnimationFrame на паузу на скрытой вкладке. Первый кадр после возвращения на вкладку покажет сотни или тысячи миллисекунд. Такой кадр стоит не записывать в буфер, а отметить в журнале событием tab:visible, иначе «худший кадр» будет врать до следующих 120 кадров.

Журнал событий: 8 строк и схлопывание повторов

Журнал хранит последние 8 событий с номером кадра, а одинаковые события подряд схлопывает в одну строку со счётчиком. Номер кадра важнее времени: по нему видно, что player:hit и enemy:dead пришли в одном кадре, а не в соседних. Схлопывание нужно, потому что события вроде «стоит на земле» приходят каждый кадр и за секунду вытесняют из журнала всё полезное.

Писать в журнал удобно из того же места, где события рассылаются подписчикам. Если в игре есть шина событий, оверлей подписывается на неё как обычный слушатель — тогда журнал видит ровно то, что видят остальные системы, в том же порядке. Подробно о порядке событий и отписке — в статье про издателя и подписчика.

Код на JavaScript и проверка в Node.js

Оверлей разбит на независимые классы, а рисование рамок принимает контекст холста параметром, поэтому всё проверяется в Node.js с подставным контекстом:

// debug-overlay.js — отладочный оверлей: FPS, журнал событий, хитбоксы
export class FrameMeter {
  constructor(size = 120) { this.times = new Float64Array(size); this.n = 0; this.i = 0; }
  push(dtMs) { this.times[this.i] = dtMs; this.i = (this.i + 1) % this.times.length; this.n = Math.min(this.n + 1, this.times.length); }
  stats(budgetMs = 1000 / 60) {
    let sum = 0, worst = 0, slow = 0;
    for (let k = 0; k < this.n; k++) {
      const t = this.times[k]; sum += t; if (t > worst) worst = t; if (t > budgetMs) slow++;
    }
    const avg = this.n ? sum / this.n : 0;
    return { fps: avg ? Math.round(1000 / avg) : 0, avgMs: +avg.toFixed(2), worstMs: +worst.toFixed(2), slow };
  }
}

export class EventLog {
  constructor(size = 8) { this.items = []; this.size = size; this.dropped = 0; }
  add(frame, text) {
    const last = this.items[this.items.length - 1];
    if (last && last.text === text) { last.count++; last.frame = frame; return; } // схлопываем повторы
    this.items.push({ frame, text, count: 1 });
    if (this.items.length > this.size) { this.items.shift(); this.dropped++; }
  }
  lines() { return this.items.map(e => `#${e.frame} ${e.text}` + (e.count > 1 ? ` ×${e.count}` : '')); }
}

export const COLORS = { solid: '#00e676', trigger: '#ffd600', hurt: '#ff1744' };

export function drawHitboxes(ctx, objects, cam) {
  ctx.save();
  ctx.lineWidth = 1;
  for (const o of objects) {
    ctx.strokeStyle = COLORS[o.kind] ?? '#ffffff';
    ctx.setLineDash(o.kind === 'trigger' ? [4, 2] : []); // триггер — пунктиром
    // +0.5, чтобы линия толщиной 1 пиксель не размывалась на два
    ctx.strokeRect(Math.round(o.x - cam.x) + 0.5, Math.round(o.y - cam.y) + 0.5, o.w - 1, o.h - 1);
  }
  ctx.setLineDash([]);
  ctx.restore();
}

export class DebugOverlay {
  constructor() { this.on = false; this.meter = new FrameMeter(); this.log = new EventLog(); this.watch = new Map(); }
  key(code) { if (code === 'Backquote') this.on = !this.on; } // KeyboardEvent.code, не зависит от раскладки
  frame(dtMs) { this.meter.push(dtMs); }
  set(name, value) { this.watch.set(name, value); }
  text() {
    const s = this.meter.stats();
    return [`FPS ${s.fps} | ср ${s.avgMs} мс | худший ${s.worstMs} мс | долгих ${s.slow}`,
      ...[...this.watch].map(([k, v]) => `${k}: ${v}`), ...this.log.lines()];
  }
}

// ---- прогон в Node.js без браузера ----
const dbg = new DebugOverlay();
dbg.key('Backquote');
for (let f = 1; f <= 120; f++) {
  dbg.frame(f % 30 === 0 ? 41.7 : 16.6);           // каждый 30-й кадр долгий
  if (f % 40 === 0) dbg.log.add(f, 'coin:picked');
  if (f >= 100 && f <= 104) dbg.log.add(f, 'player:hit');
  if (f === 118) dbg.log.add(f, 'level:checkpoint');
}
dbg.set('objects', 37); dbg.set('player.vy', (2.4).toFixed(1));
console.log(dbg.text().join('\n'));

const calls = [];
const ctx = new Proxy({}, { get: (_, p) => (...a) => calls.push(`${String(p)}(${a.map(x => JSON.stringify(x)).join(',')})`), set: (_, p, v) => (calls.push(`${String(p)}=${v}`), true) });
drawHitboxes(ctx, [{ kind: 'solid', x: 100, y: 200, w: 16, h: 24 }, { kind: 'trigger', x: 140.6, y: 196, w: 32, h: 32 }], { x: 80, y: 120 });
console.log(calls.filter(c => c.startsWith('strokeRect') || c.startsWith('setLineDash')).join('\n'));

Ожидаемый вывод (проверено в Node.js 24.22.1, 10.11.2026):

FPS 57 | ср 17.44 мс | худший 41.7 мс | долгих 4
objects: 37
player.vy: 2.4
#80 coin:picked ×2
#104 player:hit ×5
#118 level:checkpoint
#120 coin:picked
setLineDash([])
strokeRect(20.5,80.5,15,23)
setLineDash([4,2])
strokeRect(61.5,76.5,31,31)
setLineDash([])

Первая строка показывает разницу между средним и худшим кадром: 57 FPS выглядят прилично, а 4 кадра по 41,7 мс — нет. Строка player:hit ×5 — пять попаданий в пяти кадрах подряд, что почти всегда означает пропущенную неуязвимость после удара. Последние строки — команды холсту: триггер нарисован пунктиром [4,2], а координаты со сдвигом камеры и на полпикселя.

В браузере остаётся подключить три вещи: вызвать dbg.key(e.code) в обработчике keydown, dbg.frame(t - last) в начале кадра и, если dbg.on, нарисовать рамки и dbg.text() построчно через fillText после всей игровой графики. Клавиша Backquote — слева от 1, в русской раскладке она печатает «ё»; event.code по MDN от раскладки не зависит, поэтому оверлей включается при любой.

Практический сценарий: «враг иногда не получает урон»

Задача: игрок жалуется, что меч иногда проходит сквозь врага. Воспроизвести с первого раза не получается. Как оверлей сужает поиск:

  1. Включить рамки. Видно, что красная зона удара меча — 24×8 пикселей и появляется только на одном кадре анимации.
  2. Посмотреть журнал. При промахе в журнале есть sword:swing, но нет enemy:hit; при попадании оба события стоят в одном кадре.
  3. Проверить худший кадр. В момент промаха счётчик показывает кадр 41,7 мс: шаг физики за этот кадр сдвинул врага на 2,5 обычных шага, и зона удара его «перепрыгнула».
  4. Исправить. Держать зону удара 3 кадра вместо 1 или делать шаг физики фиксированным. Повторная проверка: при искусственном замедлении CPU промахов в журнале нет.

Без оверлея эта ошибка выглядит как «случайная», с ним — как связка «долгий кадр плюс зона удара на 1 кадр».

Когда вам это не подойдёт

Оверлей полезен в небольшой 2D-игре с одним холстом, но у подхода есть пределы:

  • Ошибка в производительности, а не в логике. Оверлей покажет долгий кадр, но не скажет, что его занял сборщик мусора или отрисовка. Нужна запись в панели Performance.
  • Сотни объектов на экране. Рамки превращаются в сплошную сетку; нужен фильтр по типу или по области вокруг курсора.
  • Сетевая игра. Журнал одного клиента не покажет, что сервер принял событие в другом порядке; нужен журнал с обеих сторон и общая метка времени.
  • Игра уже у игроков. Оверлей в выпуске раскрывает устройство уровня и тратит время кадра; для сбора ошибок у игроков нужны отчёты, а не рамки на экране.

Мы разрабатываем J2DRU — браузерный 2D игровой движок, где логика собирается из событий, условий и действий, а проект можно углублять на TypeScript. Движок в разработке и публично пока не открыт, заявку можно оставить на странице раннего доступа (подача заявки не гарантирует приглашение).

Источники (проверено: 10.11.2026): MDN — CanvasRenderingContext2D: setLineDash() (массив штрихов и промежутков, пустой массив — сплошная линия); MDN — Window: requestAnimationFrame() (отметка времени в миллисекундах, общая для колбэков одного кадра; пауза на скрытых вкладках); MDN — KeyboardEvent: code (физическая клавиша, не зависит от раскладки). Цвета, размеры буферов, учебный прогон и его вывод — наш ориентир и наш прогон в Node.js 24.

Читайте также:

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

Чем отладочный оверлей отличается от панели Performance в DevTools?

Оверлей показывает состояние игры прямо во время игры: где рамки столкновений, какое событие только что произошло, сколько объектов на сцене. Панель Performance записывает отрезок работы браузера и помогает найти причину просадки кадра. Оверлей говорит, что что-то не так, профайлер — почему.

Почему средний FPS в оверлее не показывает подёргивания?

Один долгий кадр в 40 мс среди 119 обычных почти не меняет среднее: в нашем прогоне 4 долгих кадра из 120 дали 57 кадров в секунду в среднем. Поэтому рядом со средним нужно выводить худший кадр и число кадров длиннее бюджета.

Какой клавишей включать оверлей?

Клавишей, которую игра не использует и браузер не перехватывает, и проверять её по event.code. Мы берём Backquote — клавишу слева от 1, в русской раскладке это «ё»: event.code от раскладки не зависит.

Нужно ли убирать оверлей из выпуска игры?

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