Коротко
Отладочный оверлей — слой поверх игры, который показывает то, что игрок не видит: рамки столкновений, время кадра и последние игровые события. Для 2D-игры хватает четырёх частей: рамки хитбоксов с цветом по типу, счётчик FPS с худшим кадром, журнал событий на 8 строк со схлопыванием повторов и список наблюдаемых переменных. Оверлей включается одной клавишей, в выпуске выключен, а его логика проверяется без браузера.
Содержание
- Что показывает оверлей и чем он не является
- Хитбоксы: цвет по типу, пунктир для триггеров
- Счётчик кадров: среднее врёт, нужен худший кадр
- Журнал событий: 8 строк и схлопывание повторов
- Код на JavaScript и проверка в Node.js
- Практический сценарий: «враг иногда не получает урон»
- Когда вам это не подойдёт
Что показывает оверлей и чем он не является
Оверлей отвечает на вопрос «что игра думает прямо сейчас», а не «почему браузер тормозит». Он рисуется поверх кадра после всей игровой графики и показывает четыре вещи:
| Часть | Что видно | Какую ошибку ловит |
|---|---|---|
| Рамки хитбоксов | прямоугольники столкновений поверх спрайтов | рамка меньше или сдвинута относительно картинки |
| Счётчик кадров | среднее, худший кадр, число долгих кадров | подёргивания, которых не видно в среднем 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 от раскладки не зависит, поэтому оверлей включается при любой.
Практический сценарий: «враг иногда не получает урон»
Задача: игрок жалуется, что меч иногда проходит сквозь врага. Воспроизвести с первого раза не получается. Как оверлей сужает поиск:
- Включить рамки. Видно, что красная зона удара меча — 24×8 пикселей и появляется только на одном кадре анимации.
- Посмотреть журнал. При промахе в журнале есть
sword:swing, но нетenemy:hit; при попадании оба события стоят в одном кадре. - Проверить худший кадр. В момент промаха счётчик показывает кадр 41,7 мс: шаг физики за этот кадр сдвинул врага на 2,5 обычных шага, и зона удара его «перепрыгнула».
- Исправить. Держать зону удара 3 кадра вместо 1 или делать шаг физики фиксированным. Повторная проверка: при искусственном замедлении CPU промахов в журнале нет.
Без оверлея эта ошибка выглядит как «случайная», с ним — как связка «долгий кадр плюс зона удара на 1 кадр».
Когда вам это не подойдёт
Оверлей полезен в небольшой 2D-игре с одним холстом, но у подхода есть пределы:
- Ошибка в производительности, а не в логике. Оверлей покажет долгий кадр, но не скажет, что его занял сборщик мусора или отрисовка. Нужна запись в панели Performance.
- Сотни объектов на экране. Рамки превращаются в сплошную сетку; нужен фильтр по типу или по области вокруг курсора.
- Сетевая игра. Журнал одного клиента не покажет, что сервер принял событие в другом порядке; нужен журнал с обеих сторон и общая метка времени.
- Игра уже у игроков. Оверлей в выпуске раскрывает устройство уровня и тратит время кадра; для сбора ошибок у игроков нужны отчёты, а не рамки на экране.
Мы разрабатываем J2DRU — браузерный 2D игровой движок, где логика собирается из событий, условий и действий, а проект можно углублять на TypeScript. Движок в разработке и публично пока не открыт, заявку можно оставить на странице раннего доступа (подача заявки не гарантирует приглашение).
Источники (проверено: 10.11.2026): MDN — CanvasRenderingContext2D: setLineDash() (массив штрихов и промежутков, пустой массив — сплошная линия); MDN — Window: requestAnimationFrame() (отметка времени в миллисекундах, общая для колбэков одного кадра; пауза на скрытых вкладках); MDN — KeyboardEvent: code (физическая клавиша, не зависит от раскладки). Цвета, размеры буферов, учебный прогон и его вывод — наш ориентир и наш прогон в Node.js 24.
Читайте также:
- Как найти просадку FPS в браузерной 2D-игре: бюджет кадра, Chrome DevTools Performance, долгие задачи и сборка мусора
- Игровой цикл (Game Loop) и физика столкновений (AABB, хитбоксы и триггеры) простыми словами и на уровне профи
- Издатель и подписчик в игре: порядок доставки событий, отписка и утечки памяти