Sprinter-SDCC/applications/PoP/roomtest/tests-host/README.md

tests-host — модульные тесты движка roomtest

Прогоняются под ucsim_z80, обвязка общая — testkit/ (там же объяснение, почему под z80, а не хостовым gcc, и грабли).

make host-tests                                  # из корня, вместе с остальными
make -C applications/PoP/roomtest/tests-host     # только эти
make -C applications/PoP/roomtest/tests-host t_geom

Что покрыто

набор	модуль	что проверяет
t_geom	pop_geom.c	геометрия комнаты (x_bump, y_land, y_to_row) и PRNG оригинала
t_phys	pop_map.c + pop_kid.c + pop_ctrl.c	покадровые трассы физики Кида: стойка, бег, шаг с Shift, разворот, присед, прыжок вверх, падение с кромки, loose-плита, разбег-прыжок через провал
t_char	те же + pop_guard.c	физика над Char для РАЗНЫХ персонажей: кому достаётся урон (take_hp по charid), ветки land() (Кид −1 HP с двух рядов, страж гибнет, тень цела), падение и гард по X у слота Guard, check_guard_fallout, «окна Char не путают персонажей»

Главный тест в t_geom — geom_lcg_matches_reference. LCG оригинала (s = s*214013 + 2531011) написан в pop_geom.c на ассемблере по схеме Горнера ради обхода __mullong, и заявка «бит-в-бит как в SDLPoP» до появления теста держалась только на комментарии. Тест сверяет рукописный asm с наивной 32-битной формулой на 128 шагах — и по возвращаемому значению, и по обеим половинам сида.

t_phys: характеризация, а не проверка правильности

Набор существует ради страховки под рефакторинг. Эталоны сняты с текущего билда, то есть консервируют и текущие баги — правильность по-прежнему проверяется сверкой с SDLPoP/src/. Ценность в другом: ближайший крупный шаг (перенос физики с Kid. на Char., чтобы её мог переиспользовать страж) обязан быть поведение-сохраняющим, и «трасса до == трасса после» ловит ровно тот класс ошибок, который там возможен.

Поэтому эталон переснимается только осознанно, и в коммите должно быть написано, что и почему поменялось. Молча обновлённый эталон обесценивает весь набор.

Своё дело набор сделал: перенос физики на Char (GUARD-PHYS, 2026-08-07) прошёл при неизменных трассах — 1723 проверки без единого расхождения.

Грабли раскладки: DATA_LOC

Набор линкует уже полдвижка, и его код перевалил за --data-loc 0x8000. Линкер sdld это НЕ ошибка: хвост кода (_HOME, деления из libsdcc) он молча кладёт ПОВЕРХ _DATA, после чего тест ведёт себя как «зациклился» — хотя логика ни при чём. Час на поиск стоило именно это.

Поэтому: DATA_LOC в Makefile набора (сейчас 0x9000), а host-tests.mk перед каждым прогоном проверяет CODE_LOC + l__CODE <= DATA_LOC и падает с внятным сообщением. Упёрлись снова — поднять DATA_LOC (стек в crt0_ucsim начинается с 0xFEF0).

python3 record_golden.py          # переснять все трассы
python3 record_golden.py 7 9      # только сценарии 7 и 9

Трасса — по одной записи на кадр: frame, x, y, dir, col, row, action и смещение curr_seq от SEQTBL_BASE. Кадр гоняется ровно в том порядке, что и в главном цикле roomtest.c:

pop_ctrl_tick();   // ввод -> control(): смена последовательности
kid_tick();        // play_seq: следующий кадр
pop_phys_tick();   // падение/приземление/стена
pop_loose_tick();  // досчёт тряски и снятие провалившейся плиты

Покадровость здесь принципиальна: порт seg005/seg006 — конечный автомат, и ошибка почти всегда проявляется не в одной функции, а в расхождении траектории через несколько кадров. Плюс главный риск переноса на Char — не арифметика, а то, кто владеет окном Char внутри кадра; поймать это можно только прогоном полного кадра.

Проверка, что харнесс воспроизводит устройство: сценарий stand даёт frame=15, x=114, y=118, curr_seq=0x19A3 — те же значения, что читаются из _Kid в живом MAME.

Как это заработало под ucsim

Три шва, каждый закрыт без правок продуктового кода:

1. Таблицы анимации. pop_kid.c ходит по ним абсолютными адресами от KD_DATA_OFF (0x100) — там, куда на устройстве их приводит маппинг W0. В тесте kid_data.bin просто кладётся по 0x100 (gen_kid_blob.py), а gfx_w0_map заглушен. Следствие: код набора линкуется с --code-loc 0x1000 (CODE_LOC в Makefile), чтобы не налезть на блоб.
2. Окружение. stubs.c — libc/libbgi (графика, память, файлы), соседние модули (pop_bg/pop_trob/pop_level/pop_redraw) и состояние стража. Заглушки не пустые там, где это меняет смысл: файловое чтение реально отдаёт kid_data.bin (иначе pop_kid_data_load тихо сдаётся, kdat_ok остаётся нулём и play_seq не делает ничего — трасса выходит из одного застывшего кадра), клавиатура отвечает по набору «нажатых» скан-кодов (так под тест попадают read_input и read_user_control, а не только диспетчер), а обращения к соседям журналируются (tk_log) — можно проверять «плита отвалилась и попросила перерисовку», а не только координаты.
3. __banked. Модули физики помечены как банковые, SDCC генерирует на них трамплин ___sdcc_bcall_ehl, которому нужны set_bank/get_bank. В тесте память плоская — bank_stub.s отдаёт нулевой банк и пустое переключение, соблюдая контракт по регистрам.

Что харнесс НЕ покрывает и остаётся за MAME: отрисовка и окклюзия, реальные переключения банков, тайминги кадра, настоящая клавиатура.

Что нужно, чтобы двинуться дальше

• Доступ к странице уровня. pop_level.c ходит по абсолютным адресам ((uint8_t *)(LVL_DATA_OFF + …) после gfx_w0_map). Для pop_map это не потребовалось — карту комнаты в него ИНЪЕКТИРУЮТ через pop_map_set, — но набор на сам pop_level/pop_trob в это упрётся. Решение то же, что для kid_data: положить страницу по нужному адресу и поднять CODE_LOC.
• Сценарии из BUGS_CLOSED.md. У каждой закрытой записи есть симптом и ожидаемое поведение — готовый список регрессионных кейсов, который стоит переносить в t_phys по мере надобности.
• BUG-LOOSE-2 (гонка «уйти из комнаты раньше, чем долетит плита») — через мост MAME воспроизвести не удалось, а на уровне логики это несколько строк: заспавнить кусок, сменить комнату, тикать до приземления, проверить щебень.