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/BUGS_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), поэтому коллизии слотов у него практически не случаются. Мы держим четырнадцать колонок (−2…11) — при узком окне это не мешает, а вот в десять слотов колонки −2/−1 и 8/9 сядут поверх 8/9.

Окно перебора с 2026-08-09 у нас такое же, как в оригинале (было: все четырнадцать колонок каждый кадр). Признак годности слота при этом не массив номеров комнат, как у оригинала, а ГРАНИЦЫ окна — четыре байта, которые move_coll_to_prev переносит в prev вместе с флагами; сравнение идёт по пересечению двух окон. Очистки массивов нет вовсе, то есть это дешевле оригинала, а смысл тот же (у него слот вне окна помечен row_coll_room = −1 и в цикл бампа не попадает). check_chomped_flags тоже ограничен окном — иначе протухшие слоты дали бы фантомный перемол.

Чем платим

• Расхождение структур: если в будущем понадобится знать, из какой комнаты пришёл тайл конкретного слота, этого у нас нет — придётся идти в вариант A.
• Границы окна надо переносить везде, где переносятся флаги: pop_coll_shift двигает и их, move_coll_to_prev снимает их в prev. Забыть один из переносов = молча потерять или, наоборот, разрешить лишний бамп.
• Сдвиг работает только для чисто горизонтальных переходов на ровно 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 ходят по этой же геометрии.

---

D-2. Кнопка в шве: перерисовываем, хотя оригинал не перерисовывает

Что делает оригинал

Тайл-«трансформер» (кнопка, ворота, пика) перерисовывается только если он в ОТРИСОВАННОЙ комнате: redraw_11h → redraw_tile_height → get_trob_pos_in_drawn_room (seg007:0258), а та для trob.room != drawn_room возвращает 30 — заведомо несуществующий tilepos, то есть «не рисовать». Исключение сделано ровно одно — факелы (animate_torch, seg007:03CF, ветка trob.room == room_L && tilepos % 10 == 9).

Кнопка соседа слева при этом ВЛИЯЕТ на картинку: get_tile_to_draw (seg008:253) подменяет нажатый tiles_15_opener на tiles_1_floor, а load_leftroom (seg008:360) кладёт результат в leftroom_[row], откуда он приходит в draw_tile как tile_left. У пола правая грань есть, у кнопки нет — значит в оригинале нажатие кнопки, видимой через левый шов, меняет картинку только при следующей ПОЛНОЙ отрисовке комнаты.

Что делаем мы

Перерисовываем шов сразу: seam_row_sig (roomtest.c) подмешивает в сигнатуру ряда бит «кнопка нажата» (pop_doorlink2(mod) & 0x1F > 1) для тайлов 0x0F/0x06, и change-driven редрой pop_room_redraw_seam_left срабатывает на нём так же, как на openness ворот.

Почему

Голый порт давал видимый залип (SEAM-BUTTON-STALE, roomtest/BUGS_CLOSED.md): кнопка (1,9) комнаты 11 — она же (1,−1) комнаты 24 — оставалась нарисованной в том состоянии, в каком была на входе в комнату, хотя связь срабатывала. Сигнатура шва следила только за room_modif, а у кнопки modif — это ИНДЕКС LINKLOC, константа уровня: нажатие живёт в doorlinks2 и в сигнатуру не приходило никогда. Добавить кнопку в сигнатуру — те же три сравнения на кадр, что уже делались для ворот; воспроизводить артефакт оригинала смысла нет.

Чем платим

• Резидент +200 Б (_CODE 24 739 → 24 939), куча W2 1795 → 1595 Б. Если станет тесно — seam_row_sig переносится в банк 7 к pop_room_redraw_seam_left, ценой одного трамплина на кадр.
• Сигнатура ряда стала разнотипной: для кнопки это булев бит, для остальных тайлов — modif. Значения между собой не сравниваются (сравнивается только ряд сам с собой), но при добавлении нового типа тайла в шов про это надо помнить.

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

Уровень 5, кнопка нижних ворот комнаты 24 (она же (1,9) комнаты 11), оба направления: нажать её из комнаты 11 и войти в 24; и наоборот — войти в 24 поверху и наступить на неё, стоя в шве. Картинка кнопки обязана совпадать со статусом ворот в обоих случаях.

---

Перо (медленное падение) ловит ТОЛЬКО Кида

Оригинал (fall_accel, seg006:057C): is_feather_fall — глобальный флаг, и медленное падение достаётся ЛЮБОМУ персонажу, который окажется в Char, пока эффект жив. То есть страж, сошедший с уступа в те же секунды, парит вместе с Кидом, хотя зелье пил не он. SDLPoP считает это багом и чинит опцией fix_feather_fall_affects_guards.

Мы берём поведение С ФИКСОМ: pop_feather проверяется вместе с Char.charid == CHARID_0_KID — и в fall_accel (pop_map.c), и в опкоде JMP_IF_FEATHER интерпретатора seqtbl (pop_kid.c), чтобы физика и анимация не разъехались.

Чем платим. Сцена, где страж падает при живом пере, будет выглядеть иначе, чем в DOS-оригинале (у нас он падает нормально, там — парит). На уровне 7, единственном с этим зельем, такой сцены нет: зелье в комнате 1, стражи — в других комнатах.

Что проверять при регрессе. Уровень 7: выпить зелье в комнате 1, тут же столкнуть стража в провал — он обязан падать БЫСТРО, а Кид рядом — медленно.

---

Синее зелье («−HP») не ставит свою вспышку

Оригинал (proc_get_object, seg006:1892): ветка case 5 только глушит звуки, играет sound_13_kid_hurt и ставит hitp_delta. Экран краснеет не здесь, а общим механизмом «Кид ранен» (flash_if_hurt, seg003:0AFC).

Мы раньше ставили в этой ветке ещё и pop_flash_* (красную вспышку на 2 кадра) — то есть красили экран дважды: своей вспышкой и кадром урона. Приведено к оригиналу: ветка правит только hitp_delta, краснеет pop_kid_hurt.

Что проверять при регрессе. Уровень 2, комната 13, зелье (1,3): выпить — HP убавляется на единицу, экран краснеет РОВНО один раз (без двойного строба).

---

Переворот (зелье инверсии) применяется НА ГРАНИЦЕ КАДРА, а не мгновенно

Оригинал (toggle_upside, seg000:15E9): upside_down = ~upside_down и need_redraw_because_flipped = 1 — флаг переключается прямо в момент глотка, то есть в середине кадра. Оригиналу это ничего не стоит: он ВСЕГДА рисует в offscreen неперевёрнутым, а зеркалит только при выводе на экран (flip_screen вокруг copy_screen_rect, seg000:939/946). Внутренние координаты у него от переворота не зависят вообще.

Мы offscreen-буфера не имеем (две видеостраницы + теневая ОЗУ-копия на каждую), поэтому рисуем зеркально сразу — переворот «зашит» в координаты каждого слоя. Из-за этого момент переключения важен: зелье выпивается из play_seq, то есть в СЕРЕДИНЕ кадра, и остаток кадра рисовался бы уже зеркально поверх ещё неперевёрнутого фона. Хуже всего пламя факела — оно ЗАПЕКАЕТСЯ в ОЗУ-копию (pop_torch_draw, у него нет heal: каждый следующий кадр непрозрачно накрывает предыдущий). Кадр пламени, положенный в зеркальную позицию на старом фоне, оставался там навсегда — по комнате рассыпались лишние языки огня.

Поэтому у нас два флага: pop_upside_want (пишут зелье, смерть Кида, чит U) и pop_upside (читают все слои отрисовки). Переключение — ровно одно место, начало кадра, вместе с перерисовкой: главный цикл делает pop_upside = pop_upside_want и зовёт pop_flip_screen.

Сама перерисовка при этом СОВПАДАЕТ с оригиналом: там на need_redraw_because_flipped вызывается redraw_screen(0) — полная отрисовка, а не отражение уже нарисованного. У нас то же самое — pop_flip_screen рисует комнату заново (и получает чистый фон по построению), а вторую страницу дабл-буфера отдаёт копией акселератора.

Что проверять при регрессе. Уровень 9: выпить зелёное зелье — картинка переворачивается ровно один раз, лишних языков пламени по комнате нет. Чит U даёт тот же результат (он идёт тем же путём).

---

Окклюзия воротами: спрашиваем про рисуемого персонажа, а не жёстко про Кида

Оригинал (draw_tile_fore, seg008:0D15) первой строкой:

if (tile_left == tiles_4_gate && Kid.curr_row == drawn_row &&
    Kid.curr_col == drawn_col - 1 && Kid.room != room_R)
        draw_gate_fore();

То есть бары ворот попадают в foretable — поверх всего нарисованного — когда на тайле ворот стоит именно Кид. Это следствие устройства оригинала: foretable ОДНА на весь проход тайлов, персонажи в неё уже добавлены, и отдельного «переднего слоя на персонажа» там нет.

Мы ради скорости не рисуем foretable целиком, а возвращаем куски тайлов поверх ТОЛЬКО в прямоугольнике персонажа (pop_fore_over_char, см. memory pop_fore_layer_cost: полный проход стоил 78 % кадра). Проход идёт по персонажу, значит и вопрос естественно задавать про него — pop_gate_over_char(ch), а не про глобального Kid.

Чем платим. Наш вариант — надмножество оригинального: страж (или тень), стоящий в проёме ворот, у нас уходит ЗА решётку, а в оригинале остался бы нарисованным поверх неё, пока на том же тайле нет Кида. Визуально это правильнее, но формально расхождение. Обратной разницы нет: во всех случаях, где оригинал рисует бары поверх, рисуем и мы.

Что проверять при регрессе. Уровень 10, комната 7, тайл (2,6): Кид, стоящий в проёме ворот, виден ЗА прутьями. Решение покрыто хост-тестами (tests-host/t_char.c, набор char_gate_*) — отрисовка в харнесс не линкуется, поэтому проверяется предикат.

---

Слияние с тенью: мигания Кида спрайтами тени нет

Файлы: roomtest/guards.c (autocontrol_shadow_level12), roomtest/pop_cdraw.c. Дата: 2026-08-13.

Оригинал (draw_objtable_item, seg008:20CA) во время вспышки слияния (united_with_shadow считает 42 → 0) рисует КИДА как тень на чётных значениях счётчика: тот же кадр уходит не обычным прозрачным блиттером, а парой OR+XOR со сдвигом на пиксель. Получается мерцание «Кид/тень» примерно полторы секунды.

Мы рисуем всё это время обычного Кида, а само событие обозначаем белой вспышкой фона (pop_flash_color = POP_FLASH_WHITE, 18 кадров) — она в оригинале тоже есть и ставится тем же кодом.

Почему. У нас Кид и соперник рисуются из РАЗНЫХ атласов своими палитрами (pop_cdraw.c), а «тень» — это персонаж слота Guard с палитрой комнаты; блиттеров OR/XOR в libbgi нет вовсе, прозрачность сделана 0xFF-подавлением записи. Воспроизвести эффект — значит завести Киду второй набор спрайтов и второй путь блита ради 42 кадров за всю игру.

Чем платим. Момент слияния читается только по вспышке и по тому, что тень исчезла, — без «двоящегося» силуэта. На механику не влияет: счётчик pop_united_shadow тикает и уходит в −1 независимо от отрисовки, а от него зависят и повторный подъём тени, и появление плит в комнатах 2/13.

Что проверять при регрессе. Уровень 12: после слияния экран белеет, соперник пропал, HP-потолок вырос на единицу, тень в комнате 15 больше не появляется. Логика покрыта tests-host/t_shadow.c.

---

Отложенный старт падающих плит (уровень 13): фаза 0 у нас «не анимируется»

Файлы: roomtest/pop_map.c (pop_check_fall_flo, pop_loose_tick), roomtest/pop_trob.c (animate_loose). Дата: 2026-08-13.

Оригинал (check_fall_flo, seg000:1317) раздаёт шести плитам ряда 2 верхней комнаты модификатор −(prandom(0xFF) & 0x0F), то есть 0..−15, и заводит на каждую trob. Фаза считает вверх, проходит ноль и дальше идёт обычным отсчётом до провала — плита падает через n + 11 кадров. Ноль там безопасен: плиту держит в игре СПИСОК trob, а не значение модификатора.

Мы списка trob для loose текущей комнаты не держим — плита анимируется ровно тогда, когда её фаза не ноль (pop_loose_modif[pos] != 0). Значит счёт, дойдя до нуля, оборвался бы навсегда. Компенсируем двумя правками, которые работают только в паре:

• тик перескакивает ноль (if (m == 0) m = 1);
• стартовое значение берётся на единицу «отрицательнее» (−n−1).

Чем платим. Ничем в наблюдаемом поведении: суммарная задержка остаётся n + 11 кадров, проверено арифметикой на обоих концах диапазона (n = 0 и n = 15). Платим связностью — две правки в разных функциях, и убрать любую одну нельзя.

Что проверять при регрессе. Уровень 13, вход в комнату 23 (она же стартовая): плиты сверху сыплются ВРАЗНОБОЙ, а не разом и не «никогда». Логика покрыта tests-host/t_jaffar.c (jaffar_negative_phase_counts_through_to_fall и парный контроль на другом уровне).

---

Чит навигации по комнатам не запускает бесшовный переход уровня

Файлы: roomtest/roomtest_cold.c (pop_dbg_roomnav), roomtest/roomtest.c, roomtest/pop_state.c (pop_nav_hold). Дата: 2026-08-13.

Оригинал (play_level_2, seg000:0900) проверяет Kid.room == 23 КАЖДЫЙ кадр: уровень 12 кончается самим фактом присутствия Кида в комнате 23, двери у него нет. Никакого «как он туда попал» там нет и быть не может — телепорта между комнатами в игре 1989 года не существует.

Мы держим этот триггер, пока Кид попал в комнату ЧИТОМ навигации (+/−), и отпускаем на первой же смене комнаты обычным ходом.

Почему. Чит перебирает комнаты ПО НОМЕРУ (1..24 с обёрткой), то есть любой обход уровня 12 неизбежно наступает на 23-ю — и уровень молча становится 13-м. Поймано на первом же прогоне 2026-08-13: проверяющий час смотрел «комнату 20 уровня 12», которая на самом деле была комнатой 20 уровня 13, и сравнивал её с картой не того уровня. Комнату 23 уровня 12 читом не посмотреть в принципе. Это ровно та же болезнь чит-телепорта, что BUG-CHEAT-FIGHT-1 (выход из боя), и лечится там же.

Чем платим. Ничем в игре: в обычном прохождении Кид входит в комнату 23 ногами, флаг снят, переход срабатывает как в оригинале. Расхождение видно ТОЛЬКО при включённых читах.

Что проверять при регрессе. Уровень 12: пройти в комнату 23 ногами — уровень меняется на 13-й без заставки и без сброса HP. Обойти уровень читом + через 23-ю — уровень НЕ меняется.

---

Чит «убить стража» (K) идёт через штатный путь смерти

Файлы: roomtest/pop_guard.c (pop_guard_kill). Дата: 2026-08-13. Решение пользователя.

Оригинал (seg000:786) ставит guardhp_delta = -guardhp_curr И Guard.alive = 0. А гейт события смерти в play_guard (seg006:1490) требует Char.alive < 0 — то есть у оригинала чит убивает стража В ОБХОД on_guard_killed. На 13-м уровне это заметно: победа над Джафаром по читу не ставит leveldoor_open = 2, и выход на 14-й не открывается.

Мы Guard.alive в чите не трогаем: применённая дельта обнуляет HP, и play_guard сам переводит стража в «умирает», вызвав on_guard_killed — брызги, вспышка, флаг выхода. То есть чит даёт ровно «как будто убил Кид».

Почему. Отладочный прогон 13-го уровня иначе требует каждый раз честно выигрывать бой с Джафаром (skill 9, 6 HP) — это дорого по времени, а проверять надо совсем другое.

Чем платим. Ничем в игре: читы включаются флагом pop_cheats, в релизной сборке они выключены. Расхождение наблюдаемо только с читами.

Что проверять при регрессе. Уровень 13: K на Джафаре → белая вспышка, уход ВЛЕВО открывает дверь уровня. Честная победа в бою даёт то же самое.