Платформер на одном экране на JavaScript: ключ, дверь и состояние уровня

Коротко

Платформер на одном экране — уровень, где задача видна целиком: взять ключ, открыть дверь и дойти до выхода, как в 20 пещерах Manic Miner (1983). В коде на JavaScript уровень хранится строками текста, а при каждом запуске из них строится своя копия клеток и состояние — есть ли ключ, открыта ли дверь и статус «играем», «победа» или «погиб», поэтому рестарт после гибели — просто новая копия. Движение и столкновения считаются по осям отдельно, дверь твёрдая, пока стоит в сетке, а у шипов опасна только нижняя половина клетки.

Содержание

  1. Что такое платформер на одном экране
  2. Уровень из строк текста
  3. Шаблон и состояние: почему нужна копия
  4. Движение и столкновения по осям
  5. Ключ, дверь, шипы и выход
  6. Ядро на JavaScript и проверка в Node.js
  7. Обвязка для браузера: клавиши и canvas
  8. Практический сценарий: честный первый прыжок
  9. Когда вам это не подойдёт

Что такое платформер на одном экране

Платформер на одном экране — игра, где весь уровень помещается в экран без прокрутки, и задача видна с первой секунды. Классический пример — Manic Miner Мэтью Смита для ZX Spectrum (август 1983): в каждой из 20 пещер размером в один экран нужно собрать мигающие предметы, пока не кончился кислород, после чего начинает мигать портал, который ведёт в следующую пещеру. Враги ходят по заданным маршрутам с постоянной скоростью, а падение со слишком большой высоты убивает героя.

Для первой игры формат удобен тем, что не нужны камера и подгрузка уровня. Всё сводится к трём вещам: как описать уровень, как хранить его состояние и как проверить, что его можно пройти.

Уровень из строк текста

Уровень удобно хранить массивом строк одинаковой длины, где каждый символ — одна клетка 16 × 16 px. Наш уровень — 20 символов в ширину и 11 строк в высоту, то есть холст 320 × 176 px:

####################
#................#.#
#................#.#
#................#.#
#................#.#
#................#.#
#................#.#
#..........K.....#.#
#.........###....D.#
#.P....^.........DE#
####################
СимволКлеткаПоведение
#стенатвёрдая
.пустопроходимая
Pстарт герояпри загрузке становится пустой
Kключподбирается касанием
Dдверьтвёрдая, пока не открыта ключом
^шипыопасна нижняя половина клетки, 8 px
Eвыходкасание — победа

Задача уровня читается по карте: шип на полу, ключ над платформой, дверь в 2 клетки высотой перекрывает выход. Стена над дверью доходит до потолка, поэтому дверь не перепрыгнуть.

Шаблон и состояние: почему нужна копия

Шаблон уровня — неизменяемые строки, а всё, что меняется во время игры, живёт в отдельном объекте состояния. Функция createLevel превращает строки в массив клеток через split(''), то есть делает свою копию, и собирает рядом остальное состояние:

  • tiles — копия клеток, из которой убирают ключ и дверь;
  • player — координаты, скорость и признак «стоит на земле»;
  • hasKey и doorOpen — есть ли ключ и открыта ли дверь;
  • status — 'playing', 'won' или 'dead';
  • time и events — время попытки и журнал событий для проверки.

Рестарт после гибели — это вызов createLevel(level.rows): ключ возвращается, дверь снова закрыта, время — 0. Типичная ошибка — убирать ключ прямо из шаблона: тогда после первой гибели ключа на уровне больше нет, и пройти его нельзя. Тот же подход годится для контрольных точек, только вместо шаблона берут сохранённый снимок.

Движение и столкновения по осям

Герой двигается сначала по горизонтали, потом по вертикали, и после каждого сдвига выталкивается из твёрдых клеток. Так проще понять, во что он упёрся: при сдвиге по x — в стену сбоку, при сдвиге по y вниз — в пол, и тогда onGround = true, а вверх — в потолок.

Параметры героя — 12 × 14 px, бег 120 px/с, гравитация 1500 px/с², скорость прыжка 420 px/с. Высота прыжка считается по формуле:

h = v² / (2 · g) = 420² / (2 · 1500) = 58,8 px ≈ 3,67 клетки по 16 px

Значит, на платформу высотой 2 клетки (32 px) герой запрыгивает с запасом, а на 4 клетки (64 px) — нет. Шаг симуляции фиксированный — 1/60 с, поэтому одинаковый ввод всегда даёт одинаковый результат, и уровень можно проверять скриптом.

При первом прогоне мы нашли ошибку, которую стоит знать: клетки под героем искали по y + h − 1. За кадр гравитация опускает героя всего на 0,42 px, такая просадка в пол не попадала в проверку, и признак onGround включался через кадр — прыжок срабатывал только на каждом втором кадре. В коде ниже вычитается 0,001 px, и герой стоит на полу каждый кадр.

Ключ, дверь, шипы и выход

После движения игра проверяет, каких особых клеток касается герой, в фиксированном порядке:

  1. Ключ. Клетка K в копии становится пустой, hasKey = true.
  2. Дверь. Если ключ есть, проверяется рамка на 1 px шире героя: в дверь нельзя войти, потому что она твёрдая, а коснуться можно. Все клетки D становятся пустыми, ключ считается потраченным.
  3. Шипы. Гибель, только если низ героя ниже середины клетки шипов: задеть остриё краем не смертельно.
  4. Выход. Касание клетки E — статус 'won'.

После смены статуса step больше ничего не делает, и экран победы или гибели можно рисовать поверх застывшей сцены.

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

Ядро не знает про клавиши и canvas: оно получает действия left, right, jump и меняет состояние. Поэтому его можно проверить в Node.js сценариями ввода — «столько-то кадров держать вправо, потом прыжок».

// platformer.js — платформер на одном экране: ключ, дверь, выход
export const TILE = 16;
export const LEVEL_1 = [
  '####################',
  '#................#.#',
  '#................#.#',
  '#................#.#',
  '#................#.#',
  '#................#.#',
  '#................#.#',
  '#..........K.....#.#',
  '#.........###....D.#',
  '#.P....^.........DE#',
  '####################',
];
const G = 1500, RUN = 120, JUMP = 420, DT = 1 / 60;   // px/с², px/с, px/с, с
const PW = 12, PH = 14;                                // размер героя, px

// Состояние уровня строится заново из шаблона: шаблон не меняется никогда
export function createLevel(rows) {
  const tiles = rows.map(r => r.split(''));            // своя копия клеток
  let start = null;
  tiles.forEach((row, ty) => row.forEach((c, tx) => {
    if (c === 'P') { start = { x: tx * TILE + 2, y: ty * TILE + 2 }; row[tx] = '.'; }
  }));
  return {
    rows, tiles, start,
    player: { ...start, vx: 0, vy: 0, onGround: false },
    hasKey: false, doorOpen: false, status: 'playing', time: 0, events: [],
  };
}

const tileAt = (s, tx, ty) => (s.tiles[ty] && s.tiles[ty][tx]) || '#';
const solid = c => c === '#' || c === 'D';             // дверь твёрдая, пока стоит в сетке

function tilesUnder(x, y, w, h) {                       // клетки под прямоугольником
  const out = [];
  const E = 0.001;                                     // не «- 1»: иначе проседание < 1 px не видно
  for (let ty = Math.floor(y / TILE); ty <= Math.floor((y + h - E) / TILE); ty++)
    for (let tx = Math.floor(x / TILE); tx <= Math.floor((x + w - E) / TILE); tx++) out.push([tx, ty]);
  return out;
}

function moveAxis(s, axis, d) {                         // сдвиг по одной оси и упор в стены
  const p = s.player;
  p[axis] += d;
  for (const [tx, ty] of tilesUnder(p.x, p.y, PW, PH)) {
    if (!solid(tileAt(s, tx, ty))) continue;
    if (axis === 'x') p.x = d > 0 ? tx * TILE - PW : (tx + 1) * TILE;
    else {
      if (d > 0) { p.y = ty * TILE - PH; p.onGround = true; } else p.y = (ty + 1) * TILE;
      p.vy = 0;
    }
  }
}

const log = (s, what) => s.events.push(`${s.time.toFixed(2)} с: ${what}`);

export function step(s, input) {                        // input: { left, right, jump }
  if (s.status !== 'playing') return s;
  const p = s.player;
  s.time += DT;
  p.vx = ((input.right ? 1 : 0) - (input.left ? 1 : 0)) * RUN;
  if (input.jump && p.onGround) p.vy = -JUMP;
  p.vy += G * DT;
  p.onGround = false;
  moveAxis(s, 'x', p.vx * DT);
  moveAxis(s, 'y', p.vy * DT);

  // Ключ: подобрать и убрать из копии уровня
  for (const [tx, ty] of tilesUnder(p.x, p.y, PW, PH))
    if (tileAt(s, tx, ty) === 'K') { s.tiles[ty][tx] = '.'; s.hasKey = true; log(s, 'ключ подобран'); }
  // Дверь: открывается касанием, если ключ есть (проверяем рамку на 1 px шире героя)
  if (s.hasKey && !s.doorOpen)
    for (const [tx, ty] of tilesUnder(p.x - 1, p.y, PW + 2, PH))
      if (tileAt(s, tx, ty) === 'D') {
        s.tiles.forEach(row => row.forEach((c, i) => { if (c === 'D') row[i] = '.'; }));
        s.doorOpen = true; s.hasKey = false; log(s, 'дверь открыта');
        break;
      }
  // Шипы: опасна только нижняя половина клетки
  for (const [tx, ty] of tilesUnder(p.x, p.y, PW, PH))
    if (s.status === 'playing' && tileAt(s, tx, ty) === '^' && p.y + PH > ty * TILE + TILE / 2) { s.status = 'dead'; log(s, 'шипы'); }
  // Выход
  for (const [tx, ty] of tilesUnder(p.x, p.y, PW, PH))
    if (s.status === 'playing' && tileAt(s, tx, ty) === 'E') { s.status = 'won'; log(s, 'выход'); }
  return s;
}

// ---- проверка в Node.js ----
function run(s, script) {                               // script: [[кадры, input], ...]
  for (const [frames, input] of script) for (let i = 0; i < frames && s.status === 'playing'; i++) step(s, input);
  return s;
}
const R = { right: 1 }, RJ = { right: 1, jump: 1 };
console.log('высота прыжка:', (JUMP * JUMP / (2 * G)).toFixed(1), 'px =', (JUMP * JUMP / (2 * G) / TILE).toFixed(2), 'клетки');

let s = run(createLevel(LEVEL_1), [[120, R]]);                        // 1: вправо без прыжка
console.log('1) без прыжка:', s.status, '|', s.events.join('; '));
s = createLevel(s.rows);                                               // рестарт из шаблона
console.log('   рестарт: ключ на месте —', s.tiles[7][11] === 'K', '| время', s.time, '| герой', s.player.x, s.player.y);

s = run(createLevel(LEVEL_1), [[20, R], [1, RJ], [300, R]]);           // 2: только через шип
console.log('2) без ключа:', s.status, '| x =', s.player.x, '| дверь открыта —', s.doorOpen);

s = run(createLevel(LEVEL_1), [[20, R], [1, RJ], [34, R], [1, RJ], [300, R]]); // 3: полный проход
console.log('3) с ключом:', s.status, '|', s.events.join('; '));
console.log('   шаблон не тронут: ключ в LEVEL_1 —', LEVEL_1[7][11] === 'K', '| двери в LEVEL_1 —', LEVEL_1.join('').split('D').length - 1);

const ok = [];                                                         // окно прыжка через шип
for (let a = 0; a <= 40; a++) {
  const t = run(createLevel(LEVEL_1), [[a, R], [1, RJ], [60, R]]);
  if (t.status !== 'dead') ok.push(a);
}
console.log('окно прыжка через шип: кадры', ok[0] + '–' + ok[ok.length - 1], '=', ok.length, 'кадров ≈', Math.round(ok.length * DT * 1000), 'мс');

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

высота прыжка: 58.8 px = 3.67 клетки
1) без прыжка: dead | 0.57 с: шипы
   рестарт: ключ на месте — true | время 0 | герой 34 146
2) без ключа: playing | x = 260 | дверь открыта — false
3) с ключом: won | 1.30 с: ключ подобран; 1.95 с: дверь открыта; 2.10 с: выход
   шаблон не тронут: ключ в LEVEL_1 — true | двери в LEVEL_1 — 2
окно прыжка через шип: кадры 15–32 = 18 кадров ≈ 300 мс

Что показывают три сценария:

  • Без прыжка герой бежит вправо и через 0,57 с попадает на шип: статус dead. После рестарта ключ снова на месте, время — 0, герой — в точке старта (34, 146).
  • Только через шип. Один прыжок на 21-м кадре переносит героя через шип, но без ключа он упирается в закрытую дверь: x = 260 — это левая граница двери (272 px) минус ширина героя (12 px), статус остаётся playing.
  • С ключом. Второй прыжок после ещё 34 кадров бега приводит на платформу: ключ подобран на 1,30 с, дверь открыта касанием на 1,95 с, выход — на 2,10 с. Шаблон LEVEL_1 при этом не тронут: в нём по-прежнему ключ и 2 клетки двери.

Последняя строка — замер, который полезен при проектировании уровня. Прыжок после любого числа кадров бега от старта с 15 по 32 не заканчивается на шипе: окно 18 кадров при 60 кадрах в секунду — около 300 мс.

Обвязка для браузера: клавиши и canvas

Обвязка читает клавиши по KeyboardEvent.code, крутит ядро с фиксированным шагом 1/60 с и рисует клетки прямоугольниками. Для браузера блок проверки в конце platformer.js можно удалить или вынести в отдельный файл.

// main.js — обвязка для браузера: клавиши, фиксированный шаг и canvas 320 × 176
import { TILE, LEVEL_1, createLevel, step } from './platformer.js';

const canvas = document.querySelector('canvas');
const ctx = canvas.getContext('2d');
canvas.width = LEVEL_1[0].length * TILE;
canvas.height = LEVEL_1.length * TILE;

const held = new Set();
addEventListener('keydown', e => held.add(e.code));
addEventListener('keyup', e => held.delete(e.code));
const input = () => ({
  left: held.has('ArrowLeft') || held.has('KeyA'),
  right: held.has('ArrowRight') || held.has('KeyD'),
  jump: held.has('Space') || held.has('ArrowUp') || held.has('KeyW'),
});

const COLORS = { '#': '#555', D: '#a0522d', K: '#ffd700', E: '#3c3', '^': '#e33' };
let level = createLevel(LEVEL_1), acc = 0, last = performance.now();

function frame(now) {
  acc += Math.min(now - last, 250) / 1000; last = now;
  while (acc >= 1 / 60) { step(level, input()); acc -= 1 / 60; }
  if (level.status === 'dead' && held.has('KeyR')) level = createLevel(level.rows);  // рестарт

  ctx.fillStyle = '#111'; ctx.fillRect(0, 0, canvas.width, canvas.height);
  level.tiles.forEach((row, ty) => row.forEach((c, tx) => {
    if (!COLORS[c]) return;
    ctx.fillStyle = COLORS[c];
    if (c === '^') ctx.fillRect(tx * TILE, ty * TILE + TILE / 2, TILE, TILE / 2);       // опасная половина
    else ctx.fillRect(tx * TILE, ty * TILE, TILE, TILE);
  }));
  ctx.fillStyle = '#fff'; ctx.fillRect(level.player.x, level.player.y, 12, 14);
  ctx.fillText(level.hasKey ? 'ключ: есть' : 'ключ: нет', 20, 12);
  if (level.status !== 'playing') ctx.fillText(level.status === 'won' ? 'Выход!' : 'Шипы. R — заново', 120, 12);
  requestAnimationFrame(frame);
}
requestAnimationFrame(frame);

Подключите main.js к странице с одним элементом canvas как модуль. Ограничение прошедшего времени 250 мс нужно, чтобы после переключения вкладки игра просчитала разом не больше 15 кадров, а не сотни. Синтаксис обвязки проверен командой node --check; страницу с модулями открывают через локальный сервер, как советует руководство MDN по модулям JavaScript.

Практический сценарий: честный первый прыжок

Задача: собрать первый уровень так, чтобы новичок прошёл его с 3 попыток, а шип учил прыгать, а не наказывал. Входные условия — уровень из примера, холст 320 × 176 px, физика из кода выше. Шаги:

  1. Замер окна. Прогнать цикл из последней части проверки для шипа и записать окно прыжка: у нас 18 кадров ≈ 300 мс.
  2. Порог. Для первого препятствия — наш ориентир не меньше 15 кадров (250 мс). Если окно меньше, сделать шип уже, отодвинуть его от старта или снизить платформу.
  3. Проходимость. Добавить в проверку сценарий полного прохода и запускать его после каждой правки карты: статус должен быть won.
  4. Люди. Дать уровень трём людям, не видевшим игру, и записать, с какой попытки каждый дошёл до выхода.

Проверяемый итог — скрипт полного прохода возвращает won, окно прыжка не меньше 15 кадров, и хотя бы двое из трёх проходят уровень не больше чем с 3 попыток. Как это выглядит на практике: в первом варианте нашей карты шипов было 2 подряд, а платформа стояла на клетку выше, и прыжок, который проходит шипы и сразу берёт ключ, удавался только в окне 6 кадров (100 мс) — для первого уровня слишком мало. В итоговой карте шип один, платформа ниже, а задача разделена на два прыжка: через шип с окном 18 кадров и на платформу отдельно, перед которым можно остановиться.

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

Платформер на одном экране и такая простая физика подходят не всегда:

  • Большой мир. Если уровень шире экрана, нужны камера, координаты мира и экрана и подгрузка частей карты — это отдельная задача.
  • Наклонные поверхности. Сетка из квадратных клеток и выталкивание по осям не дают склонов; для них нужна другая проверка столкновений.
  • Отзывчивый прыжок. Здесь нет времени койота, буфера прыжка и прыжка разной высоты; без них управление жёстче, чем в современных платформерах.
  • Много врагов со своим поведением. Когда у героя и врагов много состояний — бег, прыжок, удар, оглушение, — флаги в одном объекте лучше заменить конечным автоматом.

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

Источники (проверено: ноябрь 2026, 11.11.2026): Wikipedia — Manic Miner (Мэтью Смит, ZX Spectrum, август 1983; 20 пещер размером в один экран; мигающие предметы, кислород, портал в следующую пещеру; враги по заданным маршрутам с постоянной скоростью; гибель от падения с высоты); MDN — KeyboardEvent: code property (физическая клавиша независимо от раскладки); MDN — JavaScript modules (import и export, запуск примеров через локальный сервер). Размеры клеток и героя, параметры физики, окно прыжка и порог 15 кадров — наш расчёт и ориентир; код и вывод — наш прогон в Node.js 24.

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

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

Как хранить уровень платформера в JavaScript?

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

Почему ключ не появляется после рестарта уровня?

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

Как сделать дверь, которая открывается ключом?

Пока ключа нет, дверь — твёрдая клетка, как стена. Когда герой с ключом касается двери (проверка рамкой на 1 px шире героя), клетки двери заменяются пустыми, а ключ считается потраченным.

Почему герой прыгает через раз?

Частая причина — проверка клеток под героем с вычитанием 1 px: проседание меньше пикселя не замечается, и признак «стоит на земле» включается через кадр. В нашем коде вместо этого вычитается 0,001 px.