---
title: "Отладочный оверлей на JavaScript: хитбоксы, FPS и журнал событий"
description: "Как сделать отладочный оверлей для браузерной 2D-игры: рамки хитбоксов на canvas с цветом по типу и пунктиром для триггеров, счётчик FPS с худшим кадром за 2 секунды, журнал событий на 8 строк со схлопыванием повторов и наблюдение за переменными. Включение клавишей по event.code, код проверен в Node.js 24."
slug: otladochnyj-overlej-na-javascript-hitboksy-fps-i-zhurnal-sobytij
date: 2026-11-10
updated: 2026-11-10
scheduled_at: "2026-11-10T19:00:00+03:00"
rubric: praktika-i-uroki
tags: ["otladka", "javascript", "canvas", "brauzernye-igry", "razrabotchikam"]
reading_time: 12
draft: false
summary: "Отладочный оверлей — слой поверх игры, который показывает то, что игрок не видит: рамки столкновений, время кадра и последние игровые события. Для 2D-игры хватает четырёх частей: рамки хитбоксов с цветом по типу, счётчик FPS с худшим кадром за последние 120 кадров, журнал событий на 8 строк со схлопыванием повторов и список наблюдаемых переменных. Оверлей включается одной клавишей и в выпуске выключен, а его логика проверяется без браузера."
---

## Коротко

Отладочный оверлей — слой поверх игры, который показывает то, что игрок не видит: рамки столкновений, время кадра и последние игровые события. Для 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 с подставным контекстом:

```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):

```text
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. Движок в разработке и публично пока не открыт, заявку можно оставить на [странице раннего доступа](/early-access?utm_source=blog&utm_medium=article&utm_campaign=otladochnyj-overlej-na-javascript-hitboksy-fps-i-zhurnal-sobytij) (подача заявки не гарантирует приглашение).

**Источники (проверено: 10.11.2026):** [MDN — CanvasRenderingContext2D: setLineDash()](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/setLineDash) (массив штрихов и промежутков, пустой массив — сплошная линия); [MDN — Window: requestAnimationFrame()](https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame) (отметка времени в миллисекундах, общая для колбэков одного кадра; пауза на скрытых вкладках); [MDN — KeyboardEvent: code](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/code) (физическая клавиша, не зависит от раскладки). Цвета, размеры буферов, учебный прогон и его вывод — наш ориентир и наш прогон в Node.js 24.

**Читайте также:**
- [Как найти просадку FPS в браузерной 2D-игре: бюджет кадра, Chrome DevTools Performance, долгие задачи и сборка мусора](/blog/prosadki-fps-v-brauzernoj-igre-chrome-devtools-performance)
- [Игровой цикл (Game Loop) и физика столкновений (AABB, хитбоксы и триггеры) простыми словами и на уровне профи](/blog/igrovoj-cikl-i-fizika-stolknovenij-aabb)
- [Издатель и подписчик в игре: порядок доставки событий, отписка и утечки памяти](/blog/izdatel-i-podpischik-v-igre-poryadok-sobytij-otpiska-i-utechki)
