Sprinter-SDCC/applications/PoP/docs/impl_diff.md

Осознанные расхождения с SDLPoP

Правило подпроекта (../CLAUDE.md): расхождение нашей реализации с SDLPoP/src/ — по умолчанию баг у нас. Этот файл — список исключений: мест, где мы сознательно сделали иначе, потому что платформа/ABI/бюджет кадра требуют другого, а НАБЛЮДАЕМОЕ поведение обязано совпадать.

Формат записи: что делает оригинал → что делаем мы → почему → чем платим и что проверять при регрессе. Если запись перестала быть верной (портировали дословно, отказались от обхода) — удалять, а не оставлять «для истории»: история в git.

---

D-1. История флагов перекрытия у бокового шва: сдвиг вместо тега комнаты

Файлы: roomtest/pop_map.c (pop_coll_shift, pop_coll_invalidate, check_collisions), roomtest/roomtest.c (enter_room_side). Связанный баг: BUG-GATE-PASS-1 (roomtest/bug_closed.md). Дата: 2026-08-09.

Как в оригинале

check_collisions (seg004:0004) вместе с get_row_collision_data (seg004:0185) держит 10 слотов флагов перекрытия и рядом — параллельный массив номера комнаты:

row_coll_flags_ptr[tile_col] = curr_flags;   /* tile_col — колонка ВНУТРИ разрешённой комнаты (0..9) */
row_coll_room_ptr [tile_col] = curr_room;    /* и номер этой комнаты */
...
for (short column = 9; column >= 0; --column) {
    if (curr_row_coll_room[column] >= 0 &&
        prev_coll_room[column] == curr_row_coll_room[column]) {
        if ((prev_coll_flags[column] & 0x0F) == 0 &&
            (curr_row_coll_flags[column] & 0x0F) != 0)
            bump_col_left_of_wall = column;
        ...

Ключ слота — пара (колонка в своей комнате, номер комнаты). Решётка комнаты 8 и до перехода 8→6, и после лежит в слоте 9 с room = 8: история переживает смену комнаты, переход флага 0→1 виден, bumped() срабатывает. Комнату оригинал резолвит на лету через find_room_of_tile (seg006:005D), никакого кэша всех комнат у него нет.

Что делаем мы

Индекс — колонка ОТРИСОВАННОЙ комнаты, диапазон −2…11 (14 слотов, COLL_C0/COLL_N/COLL_IDX), номер комнаты рядом не хранится. При смене комнаты тот же физический тайл менял бы слот на ±10, поэтому раньше история просто выбрасывалась (pop_coll_invalidate → prev = 3 = «уже перекрывал» → бампа нет). Именно это и был BUG-GATE-PASS-1.

Теперь при боковом переходе история не выбрасывается, а перенумеровывается: pop_coll_shift(∓10) сдвигает coll_curr, coll_above, coll_below на 10 слотов и заполняет освободившиеся тройками. enter_room_side зовёт её сразу после pop_map_set_edges.

Корректность держится на том, что check_leave двигает Char.x ровно на ∓140 = 10 тайлов по 14 px, и координата грани (pop_x_bump[col + …]) сдвигается на те же 140 вместе с габаритом Кида, — сами флаги инвариантны, меняется только номер слота. Сдвигаются curr/above/below, а не prev: prev на следующем кадре всё равно перезапишет move_coll_to_prev, выбирая источник как раз из этих трёх.

Переходы вверх/вниз и все прочие входы в комнату (старт уровня, респавн, чит-навигация) остаются на полной инвалидации: там колонки не сдвигаются, но тайлы под ними принадлежат другой комнате — история действительно недействительна.

Почему не дословно (вариант A)

Дословный порт — 10 слотов + параллельный массив номера комнаты, индекс по колонке разрешённой комнаты, бамп только при совпадении номеров; тогда pop_coll_invalidate не нужен вовсе, история сама «не совпадает» там, где колонка сменила комнату.

Не взяли по одной причине: десяти слотов нам не хватит. Оригинал перебирает узкое окно вокруг Кида (от col(char_x_left_coll) − 1 до col(char_x_right_coll) + 2), поэтому коллизии слотов у него практически не случаются. Мы намеренно считаем все четырнадцать колонок сразу (FIX_COLL_FLAGS из SDLPoP — чтобы не оставалось протухших ячеек), а при таком переборе колонки −2/−1 и 8/9 сядут в одни и те же слоты 8/9. То есть вариант A тянет за собой ещё и сужение окна перебора — то есть отказ от FIX_COLL_FLAGS, — и это заметно рискованнее точечного сдвига.

Чем платим

• Расхождение структур: если в будущем понадобится знать, из какой комнаты пришёл тайл конкретного слота, этого у нас нет — придётся идти в вариант A.
• Сдвиг работает только для чисто горизонтальных переходов на ровно 10 колонок. Любая будущая диагональ/иная ширина комнаты его сломает молча.
• coll_last_row: pop_coll_invalidate прячет прошлый ряд, чтобы pop_coll_shift мог отменить инвалидацию. Порядок вызовов в enter_room_side (сначала pop_map_set_edges, потом pop_coll_shift) стал значимым.

Что проверять при регрессе

Это сердце коллизии, вокруг которого разбирался BUG-SEAM-PINGPONG. После любой правки здесь — прогон швов:

1. Уровень 1, комнаты 6 ↔ 8, закрытая решётка, обе стороны.
2. Оба режима подхода: мелким шагом (упереться) и с разбега (не пройти насквозь).
3. Проверить, что пинг-понг у шва не вернулся (экран не перескакивает туда-сюда на кадре бампа о ворота).
4. make -C roomtest/tests-host — наборы t_wall/t_char ходят по этой же геометрии.