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

План: порт clip_char() — обрезка спрайта персонажа

Статус: в работе с 2026-07-28. Контекст: баг «спуск Кида с кнопки в комнате 8» (Kid просвечивает в щель между кнопкой и ближним столбом, мусор на кромке).

Симптом

room 8, Kid спускается (climbdown) с тайла-кнопки у ближней колонны. Спрайт Кида нарисован ЦЕЛИКОМ, включая часть, которая в оригинале обрезана по линии пола: видно «просвет» Кида в щели между кнопкой и колонной и мусор на кромке.

Корень

Не портирован clip_char() (SDLPoP seg006.c:1749, вызывается из add_kid_to_objtable/add_guard_to_objtable, seg008.c:1671/1690, ПОСЛЕ set_char_collision/set_objtile_at_char/redraw_at_char* и ПЕРЕД add_objtable). Оригинал кладёт в objtable не только позицию спрайта, но и прямоугольник клипа obj_clip_{top,bottom,left,right}; блиттер рисует только внутри него. Мы рисуем без клипа вообще.

Что делает оригинал (дословно)

reset_obj_clip() → left=0, top=0, right=320, bottom=192.

Дальше (упрощая C-трюк с глобалью curr_tile2, которую ставит каждый get_tile: X == wall || tile_is_floor(curr_tile2) — это «тайл X = стена ИЛИ пол»):

T_L = get_tile(room, char_col_left,  char_top_row)
T_R = get_tile(room, char_col_right, char_top_row)
if (T_L — стена или пол) &&
   ( (action == stand && (frame == 79 || frame == 81))   /* прыжок вверх / зацеп */
     || (T_R — стена или пол) )
{
    clip_row = Char.curr_row + 1;
    clip_y   = y_clip[clip_row];          /* y_clip[] = {-60, 3, 66, 129, 192} */
    if (clip_row == 1 || (clip_y < obj_y && clip_y - 15 < char_top_y))
        obj_clip_top = char_top_y = clip_y;
}

Смысл: y_clip[row+1] — верхняя граница СВОЕЙ полосы ряда. Если над головой пол/стена — всё, что выше этой линии, не рисуется (персонаж «уходит под пол»). Для ряда 0 (clip_row == 1) клип применяется БЕЗУСЛОВНО.

Метрики из set_char_collision (seg006:0723):

• char_x_left = obj_x/2 + 58 (и -= char_width_half, если смотрит вправо)
• char_x_right = char_x_left + char_width_half, char_width_half = (w+1)/2
• char_top_y = obj_y - h + 1; если >= 192 → 0
• char_top_row = y_to_row_mod4(char_top_y)
• char_col_left = MAX(get_tile_div_mod(char_x_left), 0), char_col_right = MIN(get_tile_div_mod(char_x_right), 9)

Второй блок clip_char — obj_clip_right (doortop / стена / зеркало для виса-полёта-подъёма при взгляде влево, кадры 137..139) и ветка кадров 224..228 (выход в дверь уровня). Фаза 2, не в этом заходе.

Наши точки касания

• roomtest/pop_kid.c kid_draw() — сам считает obj_x/obj_y/w/h и блитит через gfx_blit_cols(bx, top + POP_YOFF, img, flip); запоминает прямоугольник в kid_l{x,y,w,h}[page] для kid_heal().
• roomtest/pop_map.c — там get_tile(), tile_is_floor(), y_to_row(), get_tile_div_mod_m7(), Kid-структура. Аналогичный расчёт габарита уже есть в check_spike_below() (строка ~1198) — брать за образец.
• libbgi/common/gfx_blit_cols.c — клип по экрану есть (при y < 0 пропускает sy верхних строк колонки), но произвольной верхней границы нет.

Шаги

1. libbgi: gfx_blit_cols_part(int x, int y, const void *img, uint8_t flip, int sy, int h) — «пропустить sy верхних строк спрайта, нарисовать h». Реализация = тело gfx_blit_cols с предустановленными sy/h (источник += sy, экранный y += sy). Прототип в libbgi/include/gfx.h. Стоимость: 0 в общем пути (обычный gfx_blit_cols вызывает то же ядро).
2. pop_map.c: int pop_clip_char_top(int obj_x, int obj_y, uint16_t w, uint16_t h) — порт первого блока clip_char; возвращает КОМНАТНЫЙ y (0 = клипа нет). Экспорт в pop_map.h.
3. pop_kid.c: в kid_draw() после расчёта top — ct = pop_clip_char_top(...); если ct > top → sy = ct - top, рисовать gfx_blit_cols_part(bx, ct + POP_YOFF, img, flip, sy, h - sy); в kid_l*[page] класть ОБРЕЗАННЫЙ прямоугольник (иначе heal чистит лишнее и стирает кромку пола). То же для kid_draw_splash — там оригинал делает reset_obj_clip(), т.е. splash НЕ клипится (ничего не менять).
4. Сборка: make -C libbgi, make -C applications/PoP/roomtest, make size-check; вывести свободное место в W2/W3 (порог 512 Б).
5. Проверка в MAME (mame_hdd_test_disk, полный рестарт после пересборки образа): комната 6 → переход в 8 → влезть на кнопку → спуск. Сверять с эталоном: живой SDLPoP той же позой (см. pop_check_sdlpop_first).

Риски / что проверить отдельно

• char_top_row считается y_to_row_mod4 — у нас y_to_row() даёт −1 для полосы у потолка; get_tile(row −1) уже умеет ряд 2 верхнего соседа.
• Kid ниже комнаты (char_top_y >= 192 → 0) — обязателен ресет, иначе клип прыгнет.
• clip_row == 1 (ряд 0) — клип БЕЗУСЛОВНЫЙ: проверить, что не режет Кида в обычной стойке на ряду 0 (условие внешнего if про пол/стену над головой должно отсекать).
• Клип меняет прямоугольник heal → возможен «хвост» на второй странице дабл-буфера: проверять оба кадра (SPACE — выключить дабл-буфер).

Дальше (Фаза 2, отдельно)

obj_clip_right (doortop/стена/зеркало) — нужен для виса и подъёма при взгляде влево; и obj_clip_left для зеркала (уровень 4). Требует клипа по колонкам в gfx_blit_cols (обрезка справа = уменьшить w) — дёшево, но без тестовой сцены проверять нечем.

См. memory: pop_clip_char_todo, pop_backtable_vs_midtable, pop_check_sdlpop_first, gfx_blit_noclip_fast.