# russiano2d — справочник по JavaScript API

Полное описание объекта `globalThis.engine`, который движок публикует для игрового
кода. Все биндинги зарегистрированы в [`src/script.c`](../src/script.c) (функция
`r2d__make_engine`), свойства кадра обновляются в `r2d__refresh_engine_props`.

Игровой код — это ES-модули (QuickJS-ng, ES2023+). Точка входа по умолчанию —
[`game/main.js`](../game/main.js); движок вызывает у неё `onUpdate(dt)` и `onRender()`.

- [1. Точка входа и контракт кадра](#1-точка-входа-и-контракт-кадра)
- [2. Свойства кадра](#2-свойства-кадра)
- [3. Константы](#3-константы)
- [4. Базовые функции](#4-базовые-функции)
- [5. Ввод](#5-ввод)
- [6. Ресурсы и спрайты](#6-ресурсы-и-спрайты)
- [7. Отрисовка и батчинг](#7-отрисовка-и-батчинг)
- [8. Физика](#8-физика)
- [9. Игровой GUI (RmlUi)](#9-игровой-gui-rmlui)
- [10. Звук и музыка](#10-звук-и-музыка)
- [11. Система координат и DPI](#11-система-координат-и-dpi)
- [12. Полигоны видимости (2D-свет и тени)](#12-полигоны-видимости-2d-свет-и-тени)
- [13. 2D BSP-дерево](#13-2d-bsp-дерево)
- [14. Ограничения и лимиты](#14-ограничения-и-лимиты)
- [15. Ошибки и отладка](#15-ошибки-и-отладка)

---

## 1. Точка входа и контракт кадра

### 1.1. Экспорт из ES-модуля

Файл, указанный как точка входа (по умолчанию `game/main.js`), выполняется как
ES-модуль. Движок забирает из объекта модуля две необязательные функции:

```js
// game/main.js
export function onUpdate(dt) {
    // игровая логика; dt — секунды с прошлого кадра
}

export function onRender() {
    // наполнение батча и/или вызовы drawSprite/drawRect
}
```

`onUpdate(dt)` вызывается один раз за кадр **после** шагов физики, поэтому
`engine.getTransforms()` внутри `onUpdate` уже содержит свежие позиции.
`onRender()` вызывается сразу после `onUpdate`, перед началом кадра рендера
(см. [`src/main.c`](../src/main.c)). Обе функции могут отсутствовать — движок
просто ничего не вызовет.

### 1.2. Альтернатива: `engine.setUpdate` / `engine.setRender`

Если удобнее не использовать экспорт, можно зарегистрировать обработчики явно:

```js
// game/main.js
engine.setUpdate((dt) => {
    // ...
});

engine.setRender(() => {
    // ...
});
```

Обе формы равнозначны; если модуль и экспортирует `onUpdate`, и вызывает
`engine.setUpdate()`, победит экспорт (он разбирается после выполнения модуля).

### 1.3. Порядок одного кадра

| Шаг | Что происходит | Где в коде |
|---|---|---|
| 1 | События SDL, снимок ввода, тайминги (`dt`, `time`, `fps`) | `r2d_app_begin_frame` |
| 2 | Фиксированные шаги Box2D (`1/60`, до 5 подшагов) | `r2d_physics_step` |
| 3 | `onUpdate(dt)` | `r2d_script_call_update` |
| 4 | `onRender()` — наполнение батча | `r2d_script_call_render` |
| 5 | Заливка батча в GPU, render pass, RmlUi поверх сцены | `src/main.c` |

Физика считается **до** `onUpdate`, поэтому позиции тел в `getTransforms()`
актуальны на момент логики. Значения `engine.dt` и аргумент `dt` — одно и то же
число, но `dt` берётся из `engine.dt` до вызова, поэтому надёжнее использовать
аргумент.

### 1.4. Горячая перезагрузка

Любое сохранение `.js`-файла в каталоге точки входа (проверка раз в ~0.35 с)
пересоздаёт QuickJS-контекст и заново выполняет `game/main.js`. Окно, GPU-ресурсы
и физический мир при этом **сохраняются**: после перезагрузки мир остаётся таким,
каким был. Текстуры и спрайты тоже переживают перезагрузку (они живут в C),
поэтому повторный `loadTexture` вернёт тот же id.

Полный счётчик перезагрузок доступен как `engine.reloads`. Клавиша `F5` (в сборке
с ImGui) вызывает перезагрузку вручную.

> **Важно.** Между перезагрузками нельзя сохранять ссылки на JS-объекты или
> `Float32Array` из прошлого рантайма — старый контекст уничтожается целиком.
> Сохранять нужно только числовые id (тел, спрайтов, документов UI) и создавать
> JS-объекты заново в `onEnter`/при загрузке модуля.

### 1.5. Командная строка

Опции разбираются в `r2d__print_usage` ([`src/main.c`](../src/main.c)):

| Опция | Действие |
|---|---|
| `--game <каталог>` | Какую игру запускать; точка входа — `<каталог>/main.js` (по умолчанию `game`) |
| `--scene <имя>` | Сразу открыть указанную сцену; значение попадает в `engine.startScene` |
| `--screenshot <файл>` | Сохранить кадр из swapchain в PNG и продолжить работу |
| `--screenshot-at <сек>` | На какой секунде снимать кадр (по умолчанию `2.0`) |
| `--overlay` | Показать отладочный оверлей сразу; иначе он скрыт до `F1` |
| `--stats` | Печатать раз в секунду статистику кадра (FPS, спрайты, тела, звук) |
| `--seconds N` | Выйти автоматически через N секунд — для дымовых тестов |
| `--no-hot-reload` | Не следить за изменениями `.js` |
| `--help`, `-h` | Справка |

Базовый каталог (от него отсчитываются пути к ассетам) выбирается так:
переменная окружения `R2D_GAME_DIR` → текущий каталог, если в нём есть
`game/main.js` → каталог исполняемого файла.

```bash
./build/russiano2d --stats --seconds 4

./build/russiano2d --game demos --scene shooter_witch --screenshot /tmp/s.png --seconds 5

```

---

## 2. Свойства кадра

Эти свойства перезаписываются движком перед каждым `onUpdate` — читать их можно
только для чтения. Присваивание не имеет эффекта.

| Свойство | Тип | Значение |
|---|---|---|
| `engine.time` | `number` | Секунды с момента старта приложения |
| `engine.dt` | `number` | Длительность текущего кадра, секунды (ограничена сверху `0.25`) |
| `engine.fps` | `number` | Сглаженный FPS (`fps = fps*0.9 + inst*0.1`) |
| `engine.frame` | `number` | Номер кадра, счёт с 0 |
| `engine.width` | `number` | Ширина окна в логических точках (`app.width`) — система координат сцены |
| `engine.height` | `number` | Высота окна в логических точках (`app.height`) — система координат сцены |
| `engine.mouseX` | `number` | Курсор по X в логических точках окна |
| `engine.mouseY` | `number` | Курсор по Y в логических точках окна |
| `engine.wheel` | `number` | Накопленный за кадр `ev.wheel.y` (сбрасывается каждый кадр) |
| `engine.reloads` | `number` | Сколько раз скрипты перезагружались с запуска |

```js
export function onUpdate(dt) {
    if (engine.keyPressed(engine.scancode('Space'))) {
        engine.log('кадр', engine.frame, 'время', engine.time.toFixed(2));
    }
}
```

> Координаты сцены задаются в **логических точках** окна (`app.width` ×
> `app.height`, по умолчанию 1280×720, задаются в `r2d_app_init`). Хелперы
> `engine.width`/`engine.height` возвращают тот же **логический** размер —
> именно в этих координатах работают спрайты, треугольники и вся сцена.
> Физический размер буфера кадра (на HiDPI-экранах он больше) доступен
> отдельно как `engine.pixel_width`/`engine.pixel_height`; он нужен только
> для операций над самим изображением, например для снимка кадра.
> Подробнее — в разделе [11](#11-система-координат-и-dpi).

### `engine.startScene`

Свойство, а не функция: имя сцены, переданное флагом `--scene` при запуске
(см. [1.5](#15-командная-строка)), либо `null`, если флаг не задавали. Движок
выставляет его **до** выполнения модуля точки входа, поэтому читать можно прямо
в top-level коде — именно так делает [`demos/main.js`](../demos/main.js):

```js
// demos/main.js
scenes.switchTo(engine.startScene || 'launcher');
```

> Значение не меняется в течение сессии и переживает hot reload: рантайм
> пересоздаётся, но `--scene` остаётся тем же. Это удобно для дымовых
> прогонов — один и тот же бинарник открывает нужную сцену без правки кода.

---

## 3. Константы

| Константа | Значение | Смысл |
|---|---|---|
| `engine.STATIC` | `0` | Статичное тело: не двигается, не реагирует на силы |
| `engine.KINEMATIC` | `1` | Кинематическое тело: двигается скриптом, но не силами |
| `engine.DYNAMIC` | `2` | Динамическое тело: полная симуляция Box2D |
| `engine.WHITE` | `-1` | Белый цвет: `rgba(255,255,255,255)`, упакован как `0xFFFFFFFF` |

```js
const id = engine.createBody({ x: 100, y: 100, halfW: 16, halfH: 16, type: engine.DYNAMIC });
```

`engine.WHITE` — это знаковое 32-битное представление `0xFFFFFFFF`. При записи в
`Uint32Array` или при передаче в `drawSprite`/`drawRect` оно трактуется как
непрозрачный белый.

---

## 4. Базовые функции

### `engine.log(...args)`

Печатает аргументы в stdout через движок, с префиксом `[js]` и `[r2d]`.
Аргументы приводятся к строке и соединяются пробелом.

| Параметр | Тип | Описание |
|---|---|---|
| `...args` | `any` | Что угодно; каждый аргумент приводится к строке |

**Возвращает:** `undefined`.

```js
engine.log('игрок на', engine.mouseX.toFixed(0), 'px');
// [r2d] [js] игрок на 640 px
```

### `engine.rgba(r, g, b, a)`

Упаковывает цвет в 32-битное целое (little-endian RGBA: младший байт — красный).
Формат совпадает с `R2D_RGBA` из [`src/r2d.h`](../src/r2d.h).

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `r` | `number` | `255` | Красный, 0–255 |
| `g` | `number` | `255` | Зелёный, 0–255 |
| `b` | `number` | `255` | Синий, 0–255 |
| `a` | `number` | `255` | Альфа, 0–255 |

**Возвращает:** `number` — знаковое 32-битное число. При записи в `Uint32Array`
превращается в корректное беззнаковое `0xRRGGBBAA`-по-байтам значение.

```js
const red = engine.rgba(255, 0, 0, 255);   // → -16776961 (0xFFFF0000)
engine.drawRect(0, 0, 100, 100, red);
```

### `engine.quit()`

Запрашивает завершение приложения. Фактический выход произойдёт в конце
текущего кадра (`app.quit_requested = true`).

**Возвращает:** `undefined`.

```js
engine.ui.on(doc, 'btn-quit', 'click', () => engine.quit());
```

### `engine.scancode(name)`

Переводит человекочитаемое имя клавиши в `SDL_Scancode` через
`SDL_GetScancodeFromName`. Используйте это вместо «магических» чисел.

| Параметр | Тип | Описание |
|---|---|---|
| `name` | `string` | Имя клавиши так, как его понимает SDL |

**Возвращает:** `number` — код скана, либо `0` (`SDL_SCANCODE_UNKNOWN`), если имя
не распознано.

```js
const jump = engine.scancode('Space');
const left = engine.scancode('Left');
```

---

## 5. Ввод

Все функции ввода используют **физические** коды клавиш (`SDL_Scancode`), а не
символы раскладки. Поэтому `engine.scancode('W')` на русской раскладке всё равно
соответствует физической клавише W.

Состояние мыши — в логических точках, клавиши геймпада — в перечислении SDL.

### `engine.keyDown(scancode)`

`true`, пока клавиша удерживается.

```js
if (engine.keyDown(engine.scancode('D'))) { /* идти вправо весь кадр */ }
```

### `engine.keyPressed(scancode)`

`true` только в том кадре, когда клавиша была нажата (фронт). Подходит для
прыжка, переключения паузы, подтверждения в меню.

```js
if (engine.keyPressed(engine.scancode('Space'))) { /* прыжок */ }
```

### `engine.keyReleased(scancode)`

`true` только в кадре отпускания клавиши.

### `engine.mouseDown(button)`

`true`, пока кнопка мыши удерживается.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `button` | `number` | `1` | Номер кнопки SDL: `1` — ЛКМ, `2` — СКМ, `3` — ПКМ, дальше `4`/`5` — боковые |

### `engine.mousePressed(button)`

`true` в кадре нажатия кнопки мыши. Параметр `button` — тот же, по умолчанию `1`.

```js
if (engine.mousePressed(1)) {
    engine.log('клик в', engine.mouseX, engine.mouseY);
}
```

### `engine.padDown(button)`

`true`, пока удерживается кнопка геймпада. `button` — индекс `SDL_GamepadButton`
(`0` — A/юг, `1` — B/восток, `2` — X/запад, `3` — Y/север и т. д.). Геймпад
открывается автоматически при подключении (движок берёт первый).

### `engine.padAxis(axis)`

Значение оси геймпада. `axis` — индекс `SDL_GamepadAxis` (`0` — левый стик X,
`1` — левый стик Y, триггеры обычно `4`/`5`).

**Возвращает:** `number`: стики в диапазоне примерно `[-1, 1]`, триггеры `[0, 1]`.

```js
const ax = engine.padAxis(0);        // левый стик по X
const move = Math.abs(ax) > 0.2 ? ax * 300 : 0;
```

> Геймпад опрашивается только если он подключён; без геймпада `padDown` вернёт
> `false`, а `padAxis` — `0`.

### Таблица имён клавиш

Имена проверены через `SDL_GetScancodeFromName` (SDL3). Полный список — в
`SDL_scancode.h`; ниже самые ходовые. Имя не распознано → `scancode()` вернёт `0`.

| Имя для `engine.scancode(...)` | Клавиша |
|---|---|
| `"A"` … `"Z"` | Буквенные клавиши (по физическому расположению) |
| `"0"` … `"9"` | Цифровой ряд |
| `"Space"` | Пробел |
| `"Return"` | Enter (главный). Имя `"Enter"` **не** работает |
| `"Escape"` | Esc |
| `"Tab"`, `"Backspace"` | Tab, Backspace |
| `"Left"`, `"Right"`, `"Up"`, `"Down"` | Стрелки |
| `"Left Shift"`, `"Right Shift"` | Shift (пробел в имени обязателен) |
| `"Left Ctrl"`, `"Right Ctrl"` | Ctrl (именно `Ctrl`, не `Control`) |
| `"Left Alt"`, `"Right Alt"` | Alt |
| `"Left GUI"`, `"Right GUI"` | Cmd / Win |
| `"F1"` … `"F24"` | Функциональные клавиши |
| `"Insert"`, `"Delete"`, `"Home"`, `"End"`, `"PageUp"`, `"PageDown"` | Навигация |
| `"CapsLock"`, `"Numlock"`, `"PrintScreen"`, `"Pause"` | Служебные |
| `"Keypad 0"` … `"Keypad 9"`, `"Keypad ."`, `"Keypad Enter"`, `"Keypad +"`, `"Keypad -"` | Цифровой блок |
| `"-"`, `"="`, `","`, `"."`, `"/"`, `";"`, `"'"`, `"["`, `"]"`, `"\\"`, обратный апостроф | Пунктуация задаётся самим символом (не словом) |
| `"Mute"`, `"VolumeUp"`, `"VolumeDown"` | Мультимедиа |

```js
const keys = {
    jump: engine.scancode('Space'),
    left: [engine.scancode('A'), engine.scancode('Left')],
    back: engine.scancode('Escape'),
};
```

---

## 6. Ресурсы и спрайты

Пути к файлам (`loadTexture`, `ui.load`) разрешаются относительно `base_path`
движка: переменная окружения `R2D_GAME_DIR` → текущий каталог, если в нём есть
`game/main.js` → каталог исполняемого файла (см. `r2d__pick_base_path` в
[`src/app.c`](../src/app.c)). То есть `'assets/atlas.png'` — это путь от корня
проекта.

### `engine.loadTexture(path)`

Загружает изображение (PNG и другие форматы, которые понимает SDL_image) в
GPU-текстуру.

| Параметр | Тип | Описание |
|---|---|---|
| `path` | `string` | Путь к файлу относительно `base_path` |

**Возвращает:** `number` — id текстуры (`>= 0`) или `-1` при ошибке.

Повторный вызов с тем же путём возвращает тот же id — кэширование внутри
рендера. Текстуры переживают перезагрузку скриптов.

```js
const tex = engine.loadTexture('assets/atlas.png');
if (tex < 0) engine.log('атлас не найден');
```

### `engine.textureSize(texture)`

| Параметр | Тип | Описание |
|---|---|---|
| `texture` | `number` | id текстуры |

**Возвращает:** `number[]` — `[width, height]` в пикселях; `[0, 0]` для
несуществующего id.

```js
const [w, h] = engine.textureSize(tex);
```

### `engine.createSprite(texture, sx, sy, sw, sh)`

Регистрирует прямоугольник внутри текстуры (кадр атласа). UV-координаты
считаются один раз из размеров текстуры, поэтому при отрисовке достаточно id.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `texture` | `number` | — | id текстуры |
| `sx`, `sy` | `number` | `0` | Левый верхний угол кадра внутри текстуры |
| `sw`, `sh` | `number` | `0` | Размер кадра; если `<= 0`, берётся размер всей текстуры |

**Возвращает:** `number` — id спрайта (`>= 0`) или `-1` (неверная текстура,
нет памяти).

```js
const TILE = 32;
const slice = (i) => engine.createSprite(tex, i * TILE, 0, TILE, TILE);
const player = slice(0);
const brick  = slice(1);
```

---

## 7. Отрисовка и батчинг

Кадр отрисовки начинается с очистки внутреннего набора команд
(`r2d_render_begin_frame`), затем `onRender` может либо добавлять отдельные
элементы через `drawSprite`/`drawRect`, либо залить всё одним вызовом
`submitSprites`. Смешивать оба способа можно.

Все команды попадают в один батч и раскладываются в вершинный/индексный буферы
за один заход; количество draw call'ов равно числу смен текстуры в кадре.

### `engine.drawSprite(sprite, x, y, w, h, angle, color)`

Рисует спрайт с центром в точке `(x, y)`.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `sprite` | `number` | — | id спрайта |
| `x`, `y` | `number` | `0` | Центр спрайта, пиксели сцены |
| `w`, `h` | `number` | `0` | Размер; если `<= 0`, берётся исходный размер спрайта |
| `angle` | `number` | `0` | Поворот в радианах, по часовой стрелке (ось Y вниз) |
| `color` | `number` | `engine.WHITE` | Тонирование/альфа, упакованный RGBA |

**Возвращает:** `undefined`. Неверный id спрайта молча игнорируется.

```js
engine.drawSprite(playerSprite, 320, 200, 28, 40, 0, engine.WHITE);
```

### `engine.drawRect(x, y, w, h, color)`

Рисует залитый прямоугольник через внутреннюю текстуру 1×1. Удобно для фона,
отладочных рамок и простых фигур.

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `x`, `y` | `number` | `0` | Левый верхний угол |
| `w`, `h` | `number` | `0` | Размеры |
| `color` | `number` | `engine.WHITE` | Упакованный RGBA |

**Возвращает:** `undefined`.

```js
engine.drawRect(0, 0, 1280, 720, engine.rgba(20, 24, 34, 255));   // фон
```

### `engine.setClearColor(r, g, b, a)`

Задаёт цвет очистки кадра (фон, если сцена ничего не нарисовала).

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `r`, `g`, `b` | `number` | `0.09`, `0.10`, `0.13` | Компоненты 0.0–1.0 |
| `a` | `number` | `1.0` | Альфа 0.0–1.0 |

Обратите внимание: компоненты здесь — **float 0..1**, в отличие от `engine.rgba`,
где 0–255. Значения по умолчанию — тёмно-синий фон.

```js
engine.setClearColor(0.06, 0.08, 0.11, 1.0);
```

### `engine.submitSprites(transforms, colors, count, blend?)`

Главный путь отрисовки: одним вызовом отдаёт в C массив спрайтов на весь кадр.

| Параметр | Тип | Описание |
|---|---|---|
| `transforms` | `Float32Array` | Плоский массив троек-шестёрок, stride **6** |
| `colors` | `Uint32Array \| null` | Цвета по одному на спрайт; можно `null` |
| `count` | `number` (необязательно) | Сколько спрайтов рисовать |
| `blend` | `string` (необязательно) | Режим смешивания: `'alpha'` (по умолчанию), `'add'`, `'multiply'`, `'none'` |

**Возвращает:** `number` — сколько команд реально добавлено (может быть меньше
`count`, если спрайты невалидны).

Режим смешивания действует на весь вызов: один батч рисуется одним конвейером.
Если в кадре нужны разные режимы, разбейте спрайты на несколько вызовов —
именно так делает высокоуровневый `$.gfx` (см.
[HIGH_LEVEL_API.md](HIGH_LEVEL_API.md), раздел 7). Без четвёртого аргумента
поведение прежнее — обычное альфа-смешивание.

```js
engine.submitSprites(xf, col, n);              // альфа
engine.submitSprites(glow_xf, glow_col, gn, 'add');   // свечение складывается
```

#### Формат `transforms` (stride 6)

Массив — это последовательность записей по 6 чисел с плавающей точкой:

| Смещение | Поле | Смысл |
|---|---|---|
| `i*6 + 0` | `sprite` | id спрайта (целое, хранится как float) |
| `i*6 + 1` | `x` | центр по X, пиксели сцены |
| `i*6 + 2` | `y` | центр по Y, пиксели сцены |
| `i*6 + 3` | `w` | ширина |
| `i*6 + 4` | `h` | высота |
| `i*6 + 5` | `angle` | поворот в радианах |

```js
const MAX = 1000;
const xf  = new Float32Array(MAX * 6);   // sprite, x, y, w, h, angle
const col = new Uint32Array(MAX);        // упакованный RGBA

let n = 0;
function push(sprite, x, y, w, h, angle, color) {
    const o = n * 6;
    xf[o + 0] = sprite;
    xf[o + 1] = x;
    xf[o + 2] = y;
    xf[o + 3] = w;
    xf[o + 4] = h;
    xf[o + 5] = angle;
    col[n] = color;          // Uint32Array сам приведёт signed → unsigned
    n++;
}

// ... наполнение ...

engine.submitSprites(xf, col, n);
```

#### Формат `colors` (stride 1)

`Uint32Array` длиной не меньше `count`. Каждый элемент — упакованный RGBA, где
**младший байт — красный** (little-endian):

```
биты 0..7   — R
биты 8..15  — G
биты 16..23 — B
биты 24..31 — A
```

Именно такой формат возвращает `engine.rgba(r, g, b, a)` и константа
`engine.WHITE` (`0xFFFFFFFF`). Если `colors` не передан или равен `null`, все
спрайты рисуются белым. Если массив короче `count`, лишние спрайты не рисуются
вообще (см. правила вычисления `count` ниже).

#### Правила вычисления `count`

1. Базовое число спрайтов = `transforms.length / 6`.
2. Если передан третий аргумент `count` и он `>= 0` и меньше базового, берётся он.
3. Если `colors` короче получившегося `count`, `count` урезается до длины
   `colors` (чтобы не выйти за границу массива).

#### Почему это быстро

* **Один переход границы C ↔ JS на весь кадр.** Вызов JS-функции из C стоит
  дорого; при отрисовке «по спрайту» на 1000 объектов это 1000 переходов плюс
  1000 проверок аргументов. Здесь переход один.
* **Нет маршалинга объектов.** C не разбирает JS-объекты и строки: он получает
  указатель на буфер `Float32Array` через `JS_GetTypedArrayBuffer` и читает
  числа напрямую. Никаких аллокаций под каждый спрайт.
* **Данные уже в нужном виде.** JS пишет в типизированный массив, C читает его
  как `const float *` — формат совпадает байт в байт, копирования нет.
* **Батчинг по текстуре.** C раскладывает команды в один вершинный/индексный
  буфер и рисует по одному draw call'у на смену текстуры. На демо-уровне это
  порядка одной-двух тысяч спрайтов на пару draw call'ов.

Типичный каркас: массивы создаются **один раз** в `onEnter`, а в `onRender`
только заполняются и очищаются через счётчик `n`.

> Если передать в `colors` не `Uint32Array`, а массив другого типа, C всё равно
> прочитает его как 32-битные целые — это даст мусорные цвета. Используйте
> именно `Uint32Array` (и `Float32Array` для трансформов). Оба аргумента должны
> быть типизированными массивами — обычный `Array` вызовет исключение.

### `engine.submitTriangles(vertices, count)`

Рисует произвольные треугольники с цветом **на каждой вершине**. Это дополнение
к `submitSprites`: пакет спрайтов умеет только повёрнутые прямоугольники, а
произвольная фигура — полигон видимости, веер, заливка — нет. Треугольники
позволяют нарисовать любую такую фигуру и получить плавный градиент без
текстуры (цвет интерполируется между вершинами).

| Параметр | Тип | Описание |
|---|---|---|
| `vertices` | `Float32Array` | Плоский массив вершин, stride **6** |
| `count` | `number` (необязательно) | Число **вершин**; обязано быть кратно 3 |

**Возвращает:** `number` — сколько вершин реально принято, всегда кратно 3
(лишний хвост отброшен). `0`, если рантайм недоступен или массив короче одного
треугольника. Если аргумент не `Float32Array` — выбрасывается `TypeError`.

#### Формат `vertices` (stride 6)

| Смещение | Поле | Смысл |
|---|---|---|
| `i*6 + 0` | `x` | координата по X, пиксели **логического** экрана |
| `i*6 + 1` | `y` | координата по Y |
| `i*6 + 2` | `r` | красный, 0..255 (значения насыщаются) |
| `i*6 + 3` | `g` | зелёный, 0..255 |
| `i*6 + 4` | `b` | синий, 0..255 |
| `i*6 + 5` | `a` | альфа, 0..255 |

Каждые три вершины — один треугольник: `(0, 1, 2)`, `(3, 4, 5)`, … Координаты
заданы в той же системе, что у спрайтов, — в **логических точках** окна
(`engine.width` × `engine.height`, см. [11](#11-система-координат-и-dpi)), а не в
пикселях framebuffer. Цвет — на вершину, между вершинами интерполируется.

#### Правила вычисления `count`

1. Базовое число вершин = `vertices.length / 6`.
2. Если передан `count` и он меньше базового, берётся он.
3. `count` округляется вниз до кратного 3: неполный треугольник отбрасывается.
4. Если `count` не передан, берётся весь массив (с тем же округлением).

```js
// Веер из центра: (центр, v[i], v[i+1]) — годится для полигона видимости.
const tri = new Float32Array(64 * 3 * 6);
let v = 0;
function put(x, y, r, g, b, a) {
    const o = v * 6;
    tri[o + 0] = x; tri[o + 1] = y;
    tri[o + 2] = r; tri[o + 3] = g; tri[o + 4] = b; tri[o + 5] = a;
    v++;
}

// ... наполнение ...
engine.submitTriangles(tri, v);   // → число принятых вершин
```

#### Порядок и смешивание

* Треугольники уходят одним draw call с белой текстурой и обычным
  альфа-смешиванием — как спрайты.
* Они рисуются **поверх спрайтов того же кадра**, поэтому вызывать их нужно
  **после** `engine.submitSprites()`, когда батч спрайтов уже отдан.
* Смешивать с `drawSprite`/`drawRect`/`submitSprites` можно свободно: всё
  попадает в общий кадр отрисовки.

---

## 8. Физика

Мир Box2D целиком живёт в C. JS не считает коллизии: он создаёт тела по
числовому id и раз в кадр читает готовые трансформы.

### Масштаб: 32 пикселя = 1 метр

Координаты, размеры, скорости и гравитация задаются в **пикселях** и
**пикселях в секунду**. Внутри Box2D всё переводится в метры делением на
`R2D_PX_PER_M = 32` (см. [`src/physics.h`](../src/physics.h) и
[`src/physics.c`](../src/physics.c)). Углы и угловые скорости — без перевода:
радианы и радианы в секунду. Масса — килограммы.

Ось `y` направлена **вниз**, как на экране, поэтому «вниз» — это
положительная гравитация `+y`. При старте мир получает гравитацию
`(0, 2000)` px/s² (см. [`src/main.c`](../src/main.c)).

### `engine.createBody(opts)`

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

| Поле `opts` | Тип | По умолчанию | Описание |
|---|---|---|---|
| `x`, `y` | `number` | `0` | Центр тела, пиксели |
| `halfW`, `halfH` | `number` | `16`, `16` | Полуразмеры (половина ширины/высоты); `<= 0` → `16` |
| `angle` | `number` | `0` | Начальный поворот, радианы |
| `type` | `number` | `engine.STATIC` | `STATIC` / `KINEMATIC` / `DYNAMIC` |
| `density` | `number` | `1.0` | Плотность, кг/м² |
| `friction` | `number` | `0.3` | Трение |
| `restitution` | `number` | `0.0` | Упругость (0 — не отскакивает) |
| `fixedRotation` | `bool` | `false` | Запретить вращение (удобно игроку) |
| `shape` | `string` | `'box'` | `'box'` / `'circle'` / `'capsule'` / `'polygon'` |
| `radius` | `number` | `halfW` | Радиус круга и капсулы |
| `points` | `number[]` | — | Полигон: `[x0,y0,x1,y1,…]` в локальных пикселях, до 8 точек |
| `polyRadius` | `number` | `0` | Скругление полигона |
| `oneWay` | `bool` | `false` | Односторонняя платформа |
| `oneWayAngle` | `number` | `-π/2` | Куда смотрит лицевая сторона, радианы |
| `sensor` | `bool` | `false` | Зона: ловит контакты, но не отталкивает |
| `contacts` | `bool` | `false` | Присылать события контакта для этого тела |

**Возвращает:** `number` — id тела (`>= 0`) или `-1` при ошибке/лимите.

```js
const player = engine.createBody({
    x: 80, y: 400,
    halfW: 14, halfH: 20,
    type: engine.DYNAMIC,
    density: 1.0, friction: 0.02, restitution: 0.0,
    fixedRotation: true,
});

// Круг: катится честно, без «квадратных» углов.
const ball = engine.createBody({ x: 200, y: 100, shape: 'circle', radius: 12,
                                 type: engine.DYNAMIC, contacts: true });

// Капсула: не цепляется за стыки тайлов.
const hero = engine.createBody({ x: 100, y: 100, shape: 'capsule',
                                 halfH: 20, radius: 10, type: engine.DYNAMIC,
                                 fixedRotation: true });

// Полигон: силуэт произвольной формы (до 8 точек, локальные пиксели).
const rock = engine.createBody({ x: 300, y: 100, shape: 'polygon',
                                 points: [-20, -10, 20, -10, 25, 15, -25, 15],
                                 type: engine.DYNAMIC });

// Односторонняя платформа: сквозь неё проходят снизу.
const platform = engine.createBody({ x: 400, y: 300, halfW: 100, halfH: 8,
                                     type: engine.STATIC, oneWay: true });
```

> Коробка 32×32 px при плотности 1 весит примерно 1 кг. Тело-«игрок» 28×40 px
> весит около 1.1 кг. Импульсы и скорости подбирайте с учётом этого.

**Односторонние платформы.** `oneWay` работает через pre-solve-колбэк Box2D:
контакт разрешается, только если тело приближается с лицевой стороны
(по умолчанию — сверху, `oneWayAngle = -π/2`). Нормаль хранится в системе
тела, поэтому повёрнутая платформа работает правильно. Касательные контакты у
самой кромки отсекаются порогом 0.1 — иначе игрок цеплялся бы за угол,
пролетая снизу.

### `engine.contacts()`

События контакта за прошедший шаг физики. Собираются один раз в
`r2d_physics_step`, живут до следующего шага.

**Возвращает:** `object[]`, каждый элемент:

| Поле | Тип | Описание |
|---|---|---|
| `kind` | `string` | `'begin'` (начали касаться), `'end'` (перестали), `'hit'` (удар) |
| `a`, `b` | `number` | id тел; `-1`, если тело уже удалено |
| `nx`, `ny` | `number` | Нормаль от A к B |
| `x`, `y` | `number` | Точка контакта, пиксели |
| `speed` | `number` | Скорость сближения (только `'hit'`, иначе 0) |

```js
for (const c of engine.contacts()) {
    if (c.kind === 'begin') engine.log(`тело ${c.a} коснулось ${c.b} со скоростью ${c.speed}`);
}
```

События приходят только для форм, созданных с `contacts: true`. Высокоуровневое
API включает этот флаг динамическим телам автоматически и раздаёт события
узлам — см. [HIGH_LEVEL_API.md](HIGH_LEVEL_API.md).

### `engine.createJoint(opts)` / `engine.destroyJoint(id)`

Сустав между двумя телами.

| Поле `opts` | Тип | По умолчанию | Описание |
|---|---|---|---|
| `type` | `string` | `'revolute'` | `'revolute'` (шарнир), `'distance'` (стержень), `'weld'` (сварка) |
| `a`, `b` | `number` | — | id тел |
| `ax`, `ay` | `number` | `0` | Точка крепления на теле A, мировые пиксели |
| `bx`, `by` | `number` | `0` | Точка крепления на теле B |
| `collide` | `bool` | `false` | Могут ли соединённые тела сталкиваться |
| `length` | `number` | по факту | Длина для `distance`, пиксели |
| `limit` | `bool` | `false` | Включить ограничение |
| `lower`, `upper` | `number` | `0` | Границы: угол (рад) для шарнира, длина (пиксели) для стержня |
| `motor` | `bool` | `false` | Включить мотор |
| `motorSpeed` | `number` | `0` | Скорость мотора |
| `maxTorque` | `number` | `0` | Максимальный момент (или сила для стержня) |

**Возвращает:** `number` — id сустава (`>= 0`) или `-1`.

Дополнительно: `engine.jointAlive(id)`, `engine.jointCount()`. При удалении
тела связанные с ним суставы уничтожаются Box2D — `jointAlive` вернёт `false`.

```js
const hinge = engine.createJoint({ type: 'revolute', a: anchor, b: door,
                                   ax: 100, ay: 200, bx: 100, by: 200,
                                   limit: true, lower: 0, upper: Math.PI / 2 });
engine.destroyJoint(hinge);
```

### `engine.destroyBody(id)`

Удаляет тело. Безопасно вызывать с несуществующим id (ничего не произойдёт).
Слот id может быть переиспользован следующим `createBody`, поэтому после
удаления не обращайтесь к телу по старому id.

```js
engine.destroyBody(coin.body);
```

### `engine.bodyAlive(id)`

**Возвращает:** `boolean` — существует ли тело и валиден ли его id.

### `engine.getTransforms()`

**Возвращает:** `Float32Array` или `null` (если физика недоступна).

Это **zero-copy** представление памяти C: типизированный массив создан
`JS_NewArrayBuffer` поверх `physics->transforms`, общий размер —
`R2D_MAX_BODIES * 3` чисел (8192 × 3). Индексация:

```
x     = transforms[id * 3 + 0]
y     = transforms[id * 3 + 1]
angle = transforms[id * 3 + 2]   // радианы
```

```js
const t = engine.getTransforms();
const x = t[body * 3], y = t[body * 3 + 1], a = t[body * 3 + 2];
```

Особенности:

* **Это живой массив.** Данные обновляются C-кодом каждый шаг физики; читать их
  нужно после шага (в `onUpdate`/`onRender`), а не кэшировать значения.
* **Копировать не нужно.** Массив не занимает JS-памяти под данные — он смотрит
  прямо в структуру `R2DPhysics`. Копия (`slice`, `new Float32Array(t)`) только
  замедлит и «заморозит» данные.
* **Нельзя сохранять ссылку между перезагрузками скриптов.** После hot reload
  (или `F5`) рантайм QuickJS уничтожается, а вместе с ним — `ArrayBuffer`. Сразу
  после перезагрузки получите массив заново: `this.transforms = engine.getTransforms()`.
* Позиции удалённых тел в массиве «замирают» — перед использованием проверяйте
  `engine.bodyAlive(id)`.
* Индекс `id` привязан к телу; порядок в массиве не совпадает с порядком
  создания после переиспользования слотов.

### `engine.setVelocity(id, vx, vy)`

Задаёт линейную скорость, пиксели/с.

```js
engine.setVelocity(player, 300, 0);   // вправо
engine.setVelocity(player, 0, -640);  // прыжок вверх (Y вниз!)
```

### `engine.getVelocity(id)`

**Возвращает:** `number[]` — `[vx, vy]` в пикселях/с; `[0, 0]` для мёртвого тела.

```js
const [vx, vy] = engine.getVelocity(player);
```

### `engine.setAngularVelocity(id, w)` / `engine.getAngularVelocity(id)`

Угловая скорость в радианах/с. У тела с `fixedRotation: true` вращение
игнорируется.

### `engine.setPosition(id, x, y, angle)`

Телепортирует тело и мгновенно обновляет его запись в массиве трансформов
(та же функция, что используется при респауне).

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `id` | `number` | — | id тела |
| `x`, `y` | `number` | `0` | Новый центр, пиксели |
| `angle` | `number` | `0` | Новый поворот, радианы |

```js
engine.setPosition(player, spawnX, spawnY, 0);
engine.setVelocity(player, 0, 0);
```

### `engine.applyImpulse(id, ix, iy)`

Прикладывает линейный импульс к центру масс. Единицы — кг·(пиксель/с): C делит
значение на 32, чтобы получить импульс Box2D.

```js
engine.applyImpulse(crate, 0, -200);   // подбросить ящик
```

### `engine.setGravity(gx, gy)` / `engine.getGravity()`

Гравитация мира в пикселях/с².

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `gx` | `number` | `0` | Горизонтальная составляющая |
| `gy` | `number` | `-9.81` | Вертикальная; «вниз» — положительное значение |

> Значение по умолчанию `gy = -9.81` — это почти ноль в пиксельных единицах.
> Всегда передавайте оба аргумента явно. Начальная гравитация движка —
> `(0, 2000)`.

`engine.getGravity()` возвращает `number[]` — `[gx, gy]`.

```js
engine.setGravity(0, 1200);            // «лунная» гравитация, px/s²
const [gx, gy] = engine.getGravity();
```

### `engine.setAwake(id, awake)`

Будит (`true`) или усыпляет (`false`) тело. Спящее тело не считается физикой,
пока его не разбудит столкновение.

### `engine.bodyMass(id)`

**Возвращает:** `number` — масса в кг (`0` для невалидного id).

### `engine.bodyCount()`

**Возвращает:** `number` — сколько тел сейчас живо.

### Ограничения физики

* Максимум `R2D_MAX_BODIES = 8192` тел одновременно; при переполнении
  `createBody` вернёт `-1` и запишет ошибку в лог.
* Массив `getTransforms()` всегда длиной `8192 * 3`, независимо от числа тел.
* Шаг физики фиксированный: `1/60` с, до 5 подшагов на кадр. Долгий кадр не
  «взрывает» симуляцию: лишнее время отбрасывается.

---

## 9. Игровой GUI (RmlUi)

RmlUi рисует HTML/CSS-подобные документы (`.rml` + `.rcss`) поверх сцены, в тот
же GPU-проход. Разметка — это XML с элементами `div`, `span`, `p`, `h1`,
`button` и т. п.

### `engine.ui.load(path)`

Загружает документ. Созданный документ **скрыт** по умолчанию — после загрузки
нужно вызвать `engine.ui.show(doc)`.

| Параметр | Тип | Описание |
|---|---|---|
| `path` | `string` | Путь к `.rml` относительно `base_path` |

**Возвращает:** `number` — id документа (`>= 0`) или `-1`. Повторная загрузка
того же пути возвращает тот же id (кэш по пути), так что загружать документ один
раз в `onEnter` безопасно.

Максимум 64 документа одновременно.

```js
const menu = engine.ui.load('ui/menu.rml');
if (menu >= 0) engine.ui.show(menu);
```

### `engine.ui.show(doc)` / `engine.ui.hide(doc)`

Показывает/скрывает документ. Скрытый документ не рисуется и не получает ввод.

### `engine.ui.unload(doc)`

Выгружает документ, освобождая слот. Обращения к выгруженному id игнорируются.
Обычно достаточно `hide`; полноценно удалять документ нужно только если он больше
не понадобится.

### `engine.ui.visible(doc)`

**Возвращает:** `boolean` — виден ли документ. Удобно для реализации паузы и
переключения HUD.

### `engine.ui.setText(doc, elementId, text)`

Заменяет внутреннее содержимое элемента (`SetInnerRML`).

| Параметр | Тип | Описание |
|---|---|---|
| `doc` | `number` | id документа |
| `elementId` | `string` | Значение атрибута `id` элемента |
| `text` | `string` | Новый текст; парсится как RML-разметка |

Элемент ищется по `id`; если его нет — в лог уйдёт предупреждение, вызов
безопасен.

```js
engine.ui.setText(hud, 'score', String(score));
```

> Поскольку текст интерпретируется как разметка, при выводе пользовательских
> данных экранируйте `<`, `>` и `&` (например, заменяя их на `&lt;`, `&gt;`,