# roomtest — правила подпроекта

Живой прототип порта PoP: комната 1 уровня 1 (композиция тайлов в рантайме)
+ Kid (анимация seqtbl, управление, коллизия, падение, зацеп, fore-окклюзия,
проваливающиеся полы).  Действуют правила корневого `CLAUDE.md` и
`applications/PoP/CLAUDE.md`.

**Главное правило (из `../CLAUDE.md`): `../SDLPoP/src/` — источник истины.**
Перед реализацией ЛЮБОЙ функции и по ЛЮБОМУ вопросу «как в оригинале» —
СНАЧАЛА прочитай соответствующий код SDLPoP и портируй по нему; не пиши
по памяти и не угадывай константы/порядок слоёв.  Расхождение с SDLPoP =
по умолчанию баг у нас.

**Что в работе сейчас — `TASKS.md`** (доска задач: приоритеты, критерии
готовности).  Баги — `bug_list.md` (только ОТКРЫТЫЕ) и `bug_closed.md`
(закрытые + разбор корней: перед заведением нового бага грепни там по
симптому).  План следующих уровней — `../docs/levels_plan.md`.

## Сборка и запуск

```
make            # собрать roomtest.exe (упаковав ассеты через toolchain/)
make run        # exe + EXTRA_DATA на дискету + запуск MAME (см. корневой док)
make -C tests-host   # модульные тесты движка под ucsim_z80 (секунды, без MAME)
```

Логику, которую можно проверить без железа, покрывать в `tests-host/`
(обвязка — `testkit/`, там же почему прогон именно под z80).  MAME остаётся
для отрисовки, банков, таймингов и клавиатуры.

`MEMORY=small`, `--gfx 256`.  Ассеты (`pop_env0..4.atl`, `pop_wall.atl`,
`pop_fore.atl`, `kid0..27.atl`, `kid.pal`) генерируются python-скриптами
`../toolchain/` — Makefile дёргает их сам при изменении.  Данные комнаты —
`room1_data.h` (fg=foretable code, bg=backtable modifier); данные анимации
Kid — `kid_data.h` (генерится `pop_extract_kid_data.py`).

## Проверка в MAME

Только через `toolchain/mame_interactive.py` или MCP-мост `mame-z80`
(см. memory `mame_autotest`, `mame_mcp_bridge`, `mame_hdd_test_disk`).
Эталон комнаты — `../toolchain/1.1-2.png`.  Пересобрал HDD-образ → MAME
ОБЯЗАН полный рестарт (`mame_hdd_rebuild_restart`).

Отладочные тумблеры в живой сессии (`roomtest.c`): **SPACE** — вкл/выкл
дабл-буфер (в однобуфере видно баги рисования без мерцания-через-кадр);
**1** — заморозить кадр, **2** — продолжить (разбор позы/окклюзии);
**ESC** — выход.  Читы (`pop_cheat.h`): **K** — убить стража, **I** —
бессмертие, **S** — выдать меч, **Shift+L** — следующий уровень,
**+/−** — обход комнат (`ROOMNAV`).  Уровень грузится по номеру
(`pop_level_load_num`), на диске лежат все 15.

## Модули

| Файл | Роль (порт SDLPoP) |
|------|--------------------|
| `roomtest.c` | Главный цикл: дабл-буфер (2 страницы + флип на vsync), tick→draw порядок слоёв. |
| `pop_bg.c/.h` | Отрисовка фона композицией тайлов (`seg008` draw_tile/wall_pattern), fore-окклюзия поверх Kid (`seg003` redraw_at_char), loose-полы (shake/bake/mob, `seg007/008`). |
| `pop_kid.c/.h` | Анимация/движение Kid: интерпретатор seqtbl `play_seq` + frame_table (`seg006`). |
| `pop_ctrl.c/.h` | Управление: диспетчер `control()` (`seg005`) + ввод `read_user_control` (`seg006`) поверх `<kbd_raw.h>`. |
| `pop_map.c/.h` | Коллизия с картой + физика падения/приземления/стены + loose-полы (`seg005/006/007`). |

## Порядок слоёв в кадре (важно для окклюзии)

`roomtest.c` каждый тик рисует в СКРЫТУЮ страницу: `kid_heal` (стереть
прошлый кадр) → `kid_tick` → `pop_phys_tick` → `pop_loose_tick` (loose СЛОЙ
ФОНА — ДО Kid, чтобы Kid был поверх плиты) → `kid_draw` → `pop_fore_over_kid`
(передние грани тайлов поверх Kid) → `pop_room_clip_borders` (чистка бортов,
гейт по флагу — только в кадрах падения) → флип на vsync.

**Дабл-буфер:** у каждой страницы своя видео-ОЗУ и теневая ОЗУ-копия; heal
берёт чистый фон из копии ТОЙ страницы, в которую рисуем.  Любой динамический
элемент (Kid, loose-плита, падающий кусок) обязан чистить свой прошлый кадр
на КАЖДОЙ из двух страниц — иначе остаток виден через кадр как **мерцание**.
Это типовой источник багов «остаётся кусочек» (см. memory
`pop_fall_debug_baseline`).

## Ключевые memory

`pop_kid_plan`, `pop_hang_state`, `pop_fore_layer`, `pop_fall_debug_baseline`,
`accel_vertical_copy`, `kbd_raw_fifo_drain`, `pop_check_sdlpop_first`.
