# RE2D World: устройство, проверки и ограничения

Актуализировано: 2026-10-09. Проверки SDK World и World Studio входят в полный прогон 116/116.
Этот документ описывает фактическое состояние; исторические Phase 0–5 не означают
готовность всего World. Замеры текущего пути описаны в `RE2D_WORLD_PERF.md`.

## Что реализовано теперь

Native `re2d_world.c/.h` принимает только специализированные примитивы:
стена = XY-отрезок + bottom/top; пол/потолок = прямоугольный регион + height.
В одном регионе допустимы несколько свободных вертикальных интервалов.
Перекрывающиеся свободные интервалы на пересекающихся XY отклоняются.
Построение транзакционное: ошибка не разрушает прежний мир.

BSP режет **только XY**. Исправлены оба направления пересечения и полнота обхода.
Теги исходных стен сохраняются; числовые индексы fragments локальны для сборки.
Вырожденный tail на лимите глубины полный, но не гарантирует точный painter order.
`blocked` пока линейно просматривает стены, без BSP broadphase.
Ray traversal проверяет весь tail и возвращает ближайшее попадание независимо
от его внутреннего порядка. Пол/потолок пока проверяется по списку spans.

Queries: support выбирает достижимый пол с headroom; blocked проверяет круг XY
× вертикальный интервал против стен; ray возвращает ближайшую стену/пол/потолок.
Ни World, ни renderer не владеют типами Player/Enemy/Weapon.

**Spatial description → projection → ordinary 2D representation**:
C синтезирует конечные RGBA и приватную CPU-глубину. Уже синтезированные
Re2DSprite покрываются внутри этого изображения. Затем возвращается обычный
sprite id и весь кадр отправляется существующим `engine.drawSprite` в 2D batch.
Новый World не подаёт треугольники в GPU mesh renderer.

Перспективная и ортографическая проекции используют те же примитивы. Наклон
поддерживается; pitch существующей native камеры ограничен примерно ±89°.
FPS/TPS задаются положением наблюдателя, отдельного scene graph нет.
Совместимые Re2DSprite pose/socket/attach/equip API сохранены. Поза вычисляется
непрерывно, не выбором billboard-направлений. API описан в
[highlevel/re2d.md](highlevel/re2d) и [internal/NATIVE.md](internal/NATIVE).

## Игровое демо

`./build/russiano2d --game demos/re2d_bsp_world`

Холл, лестничный коридор из восьми ступеней и две комнаты с перегородкой.
Холл и комнаты имеют одинаковые XY на двух высотах. Четыре Руси — обычные
Re2DSprite узлы со здоровьем. АК из существующего equipment JSON прикреплён
через handRight; muzzle socket используется для вспышки. Выстрел использует
world ray и игровую форму круг XY × высота. Урон 34, магазин 30, автоматический
огонь, задержка перезарядки и восстановление целей. Звук — имеющийся тестовый
эффект, а не специально записанный звук АК. Интерфейс — RmlUi.

WASD — движение, стрелки — взгляд, M — захват мыши, ЛКМ/Space — огонь,
R — перезарядка, F — восстановить цели, E — тестовый переход между этажами,
P — проекция, V — показать оружие, Esc — отпустить мышь.

## Ограничения и следующий безопасный этап

* Нет portals/PVS и автоматической топологии BSP cells. Authoring cells —
  прямоугольные регионы, не готовые BSP-листы. BSP применяется к traversal стен.
* Runtime не имеет текстурных world surfaces, произвольных многоугольных floors,
  непрерывных slopes или patches. SDK теперь генерирует лестницы и ступенчатую
  аппроксимацию slopes в обычные supports/стены — [SDK.md](SDK) §9.
* Support проверяет точку, blocked — статическую позицию, не sweep или весь
  footprint. Движение демо использует подшаги; нет прыжков/падения/общей физики
  сущностей или автоматического height-фильтра Box2D.
* Глубина Re2DSprite одна на изображение, alpha coverage ≥128. Тело и attached
  weapon упорядочиваются приближённо; точной глубины отдельных body samples нет.
  Полупрозрачность, tint/flip/blend/fog/poseBudget узла в World не применяются.
* Нет гарантии FPS, Web/WASM нового пути не собран. CPU-синтез проверен также на демо
  800×600, но не на больших сценах. Построение spans проверяет пары регионов.
* Данные экземпляров независимы, но камера legacy API общая и последовательно
  устанавливается перед синтезом. Viewmodel рисуется обычным экранным 2D sprite.

Следующий этап: world cells/порталы по XY с height-окнами, более полные формы
support/сweep, специализированные текстурные surfaces и экспорт глубины
Re2DSprite samples для точного compositor. Сохранять конечный обычный 2D кадр;
не добавлять универсальные meshes, OBJ-world или 3D physics/scene graph.

## Воспроизводимая проверка

```
cmake --build build -j6
build/tests/r2d_bsp_test
build/tests/r2d_re2d_world_test
build/_deps/quickjs-build/qjs tests/js/re2d_test.mjs
python3 tools/run_tests.py highlevel_re2d_bsp_world_test re2d_bsp_combat_test
```

C World проверяет три walkable spans с одинаковыми XY, headroom, высотные
столкновения/лучи, ступени, отклонение плохой сборки, обе проекции и RGBA/depth.
C BSP проверяет разрезание в обе стороны и полноту вырожденного обхода.
Агентский World-набор проверяет реальные пиксели перил/маскота/крепления,
проекции, native lifetime и отсутствие GPU world mesh. Игровой набор проверяет
попадания/смерть, препятствия, этажи, лестницу, магазин и восстановление целей.
Завершающая Debug-сборка прошла. Все 10 native test executables (включая
ASan/UBSan World/BSP) и 87 JS test files прошли. Агентские наборы: legacy
camera/room/world/billboards/native, Re2DSprite JSON/high-level, базовые
agent_protocol/highlevel_api/game и новые BSP World/combat — без пропусков.
Новые наборы: 29 и 16 проверок соответственно. Проверки doc_claims,
doc_coverage и `git diff --check` также прошли. Пиксели демо проверены визуально:
Руси виден в комнате, АК и socket-вспышка видны, RmlUi содержит счётчики.

## Исправление вида от первого лица

Демо больше не принуждает pixel-стиль или 320×180. World синтезируется по
размеру окна до native лимита 1024 на ось; модели используют anime. Руки из
частей Руси выбираются `.re2dVisibleParts`, АК направлен в глубину кадра и
остаётся attached через handRight. Захват мыши включён сразу, M переключает,
Esc отпускает. Проверяется реальный mouse delta и сохранение маски при reload.
Оптимизация CPU-синтеза, замеры и ограничения описаны в `RE2D_WORLD_PERF.md`;
гарантии FPS для произвольного мира нет.