# Русские имена API (`$.ru`)

Движок русский, документация русская — а писать игру приходилось латиницей.
`$.ru` добавляет **второй полноценный набор имён**: русские теги, атрибуты,
методы узлов и пространства имён. Латиница остаётся основным набором, русский —
надстройкой: код можно писать вперемешку, оба варианта ссылаются на одни и те же
объекты и функции.

```js
$.ready(() => {
    $.мир.gravity(0, 0).bounds(0, 0, 800, 600);

    $('<свет>', { 'радиус': 280, 'яркость': 1, 'цвет': '#ffd9a0', 'тени': true })
        .в(200, 300).смешать('add').конус(70).добавитьВ($.мир);

    $('<игрок>', { id: 'герой' }).в(100, 300).скорость(220)
        .управление('wasd')
        .на('смерть', () => $.сцена.load('конец'))
        .добавитьВ($.мир);

    $('игрок').цвет('#ffd9a0');          // селектор тоже по-русски
});
```

## 1. Как это устроено

| Слой | Механизм | Что важно |
|---|---|---|
| Теги | `$.aliasTag('свет', 'light')` | Узел создаётся с **каноническим** тегом: отрисовка, селекторы, префабы и снимок для агента видят обычный `<light>`. Русское имя живёт только на входе |
| Селекторы | Перевод слов словарём до `query()` | Переводятся только известные слова: `#герой`, `.босс` и атрибуты остаются как есть |
| Атрибуты | `translateAttrs({ 'радиус': 200 })` | Переводятся **до** создания узла: подсистемы знают только латинские ключи |
| Методы узлов | Псевдоним на ту же функцию (`Wrapper.prototype['в'] = Wrapper.prototype.at`) | Не копия, а ссылка: поведение и исправления общие, своих багов у псевдонима быть не может |
| Пространства имён | Ссылки: `$.мир === $.world` | Это тот же объект, а не обёртка |

## 2. Теги

| Русский | Канонический | Русский | Канонический |
|---|---|---|---|
| `<игрок>` | `player` | `<свет>` | `light` |
| `<враг>` | `enemy` | `<светплощадка>` | `lightarea` |
| `<нпс>` | `npc` | `<туман>` | `fog` |
| `<предмет>` | `pickup` | `<частицы>` | `particles` |
| `<пуля>` | `bullet` | `<тайлмап>` | `tilemap` |
| `<спрайт>` | `sprite` | `<слой>` | `layer` |
| `<прямоугольник>` | `rect` | `<зона>` | `trigger` |
| `<круг>` | `circle` | `<область>` | `area` |
| `<текст>` | `text` | `<стена>` | `wall` |

Интерфейс: `<панель>` (`ui.panel`), `<надпись>` (`ui.label`), `<кнопка>`
(`ui.button`), `<полоса>` (`ui.bar`), `<картинка>` (`ui.image`), `<строка>`
(`ui.row`), `<колонка>` (`ui.col`), `<сетка>` (`ui.grid`), `<прокрутка>`
(`ui.scroll`), `<флажок>` (`ui.checkbox`), `<ползунок>` (`ui.slider`),
`<поле>` (`ui.input`), `<список>` (`ui.list`), `<диалог>` (`ui.dialog`).

## 3. Атрибуты конструктора

| Русский | Латинский | Русский | Латинский |
|---|---|---|---|
| `радиус` | `radius` | `тени` | `shadows` |
| `яркость` | `intensity` | `конус` | `cone` |
| `цвет` | `color` | `мерцание` | `flicker` |
| `скорость` | `speed` | `препятствия` | `occluders` |
| `здоровье` | `hp` | `плотность` | `density` |
| `прозрачность` | `alpha` | `полосы` | `layers` |
| `затухание`, `светимость` | `falloff` | `источник` | `src` |
| `текст` | `text` | `размер` | `tile` |

Если заданы оба ключа, побеждает тот, что написан позже в литерале: русский
переводится в латинский и затирает прежний.

## 4. Методы узлов

`в`→`at`, `размер`→`size`, `ширина`/`высота`, `цвет`→`color`,
`прозрачность`→`alpha`, `скорость`→`speed`, `поворот`→`rotate`, `угол`→`angle`,
`позиция`→`pos`, `видимый`/`показать`/`скрыть`, `текст`, `радиус`, `яркость`,
`тени`→`shadows`, `конус`→`cone`, `мерцание`→`flicker`,
`препятствия`→`occluders`, `добавить`→`append`, `добавитьВ`→`appendTo`,
`удалить`→`remove`, `каждый`→`each`, `на`→`on`, `снять`→`off`,
`испустить`→`emit`, `класс`/`убратьКласс`/`естьКласс`, `здоровье`, `урон`,
`лечить`, `убить`, `жив`, `смотретьНа`→`lookAt`, `идтиК`→`moveTo`, `прыжок`,
`управление`→`controls`, `столкновение`→`collision`, `игратьЗвук`→`playSound`,
`кадр`/`кадры`, `тень`→`shadow` (тень-копия спрайта), `контур`→`outline`,
`слой`, `глубина`, `данные`, `смешать`→`blend`, `анимация`→`animate`,
`остановитьАнимацию`→`stopAnim`.

Полный список — таблица `RU_METHODS` в `src/highlevel/ru.js`; она же
экспортируется наружу, её проверяет `tests/js/ru_test.mjs`.

## 5. Пространства имён

`$.мир`→`world`, `$.камера`→`camera`, `$.время`→`time`, `$.ввод`→`input`,
`$.сцена`→`scene`, `$.звук`→`sound`, `$.графика`→`gfx`, `$.интерфейс`→`ui`,
`$.навигация`→`nav`, `$.частицы`→`particles`, `$.анимация`→`anim`,
`$.отладка`→`debug`, `$.сеть`→`http`, `$.пул`→`pool`, `$.сохранение`→`store`,
`$.переводы`→`tr`, `$.слои`→`layers`, `$.триггеры`→`triggers`,
`$.префаб`→`prefab`, `$.твин`→`tween`, `$.пачка`→`batch` (пачка спавна и
удаления, см. `docs/HIGH_LEVEL_API.md`).

## 6. Свои псевдонимы

```js
$.aliasTag('камень', 'wall');        // $('<камень>') и $('камень') заработают
```

Метод-псевдоним добавляется обычным `def`-ом — см.
[_CONTRACT.md](https://github.com/Nikide/russiano2d/blob/main/docs/highlevel/_CONTRACT.md) §5 (там же список занятых имён).

## 7. Ограничения

* Псевдонимы методов — **ссылки** на существующие функции: свой набор из
  русского модуля не вырастет, он только называет уже существующее.
* Русский тег в префабах и сценах сериализуется каноническим — при чтении
  данных разницы нет, но в сохранённом виде вы увидите `player`, а не `игрок`.
* Если подсистемы нет (сборка без неё), её псевдоним пропускается с одной
  записью в журнал: игра не падает из-за имени.
* Смешивать наборы в одном файле можно, но читаемость страдает — выберите
  один для проекта.

## 8. Тесты

| Что | Файл | Запуск |
|---|---|---|
| Таблицы, перевод атрибутов, иммутабельность | `tests/js/ru_test.mjs` | `build/_deps/quickjs-build/qjs tests/js/ru_test.mjs` |
| Русская сцена целиком: теги, селекторы, методы, пространства имён | `tests/agent/highlevel_ru_test.py`, фикстура `tests/fixtures/ru/` | `python3 tests/agent/highlevel_ru_test.py` (после сборки) |