Sprinter-SDCC/applications/SprPoP/CLAUDE.md

SprPoP — правила приложения

Порт Prince of Persia (DOS/Apple II) на Sprinter Sp2000 поверх нашего sprinter-cc / libc / libbgi. Действуют правила корневого CLAUDE.md (сборка, libc, ABI, MAME-автотест); ниже — только специфика порта. Общение и комментарии — на русском.

Приложение автономно: код, оригинальные данные, конверторы и сборка лежат внутри этой папки. Наружу оно знает ровно один путь — корень тулчейна, SPRINTER_ROOT (по умолчанию ../..).

История: SprPoP выделен из applications/PoP/roomtest 2026-08-26. Та папка ЗАМОРОЖЕНА и остаётся архивом (закрытые задачи и баги с разбором корней — ../PoP/roomtest/TASKS_CLOSED.md и BUGS_CLOSED.md; там же исполненные планы в ../PoP/docs/). Разработка идёт только здесь.

Главное правило: SDLPoP — источник истины. Сначала читай, потом кодь

assets/orig/SDLPoP/src/ (github.com/NagyD/SDLPoP, GPLv3) — ЕДИНСТВЕННЫЙ авторитетный источник того, как оригинальный движок это делает. В репозитории его нет: заполняется make fetch (make fetch-check — что уже на месте). Правило без исключений:

1. Перед реализацией ЛЮБОЙ функции (движение, коллизия, окклюзия, падение, loose-полы, стражники, отрисовка, тайминги, любые числовые константы) — СНАЧАЛА найди и прочитай соответствующий код в SDLPoP и портируй по нему. Не пиши по памяти, не выводи логику «из общих соображений», не угадывай значения — это источник багов, которые потом ловятся в MAME часами.
2. По любому вопросу «как в оригинале должно быть» (что окклюдит что, в каком порядке слои, когда меняется тайл, какая скорость/задержка, что делает такой-то кадр анимации) — ответ ищи в SDLPoP, а не строй гипотезу. Если не нашёл — это повод копать дальше в исходнике, а не додумывать.
3. Расхождение нашей реализации с SDLPoP — по умолчанию баг у нас, пока не доказано обратное (наша платформа/ABI требует отличия — тогда явно зафиксировать почему в комментарии и записью в docs/impl_diff.md: что делает оригинал, что делаем мы, чем платим, что проверять при регрессе).

Карта сегментов: seg005 control-диспетчер, seg006 play_kid/коллизия/ seqtbl, seg007 mob/loose/падающие объекты, seg008 отрисовка тайлов/ слои/окклюзия, seg009 чтение ресурсов. Слои окклюзии у нас = слои SDLPoP. См. memory pop_check_sdlpop_first.

Вторичные референсы (когда в SDLPoP непонятно или нужен другой ракурс) лежат вне приложения, в ../PoP/: Prince-of-Persia-Apple-II/ — оригинальный 6502-исходник 1989 (Мехнер), PR/ — Princed Resources, mininim/ — независимая реализация. Все они — справочник логики, структур и констант, но НЕ код для копирования (лицензии несовместимы, наш ABI другой): читаем и переписываем под наш движок.

Доски

Что в работе сейчас — docs/TASKS_OPEN.md (приоритеты, критерии готовности). Баги — docs/BUGS_OPEN.md (только ОТКРЫТЫЕ).

Правило разнесения: как только задача или баг закрыт — запись целиком переезжает в архив roomtest (../PoP/roomtest/TASKS_CLOSED.md / BUGS_CLOSED.md), а в открытом файле остаётся ссылка. Перед заведением нового бага грепни архив по симптому: корень мог уже разбираться. Открытые файлы обязаны читаться целиком за раз.

CHANGELOG. Ставишь релизный тег — добавь запись в CHANGELOG.md. Версия, дата И КОММИТ в заголовке берутся ИЗ GIT, руками не проставляются:

git for-each-ref \
    --format='%(refname:short) | %(creatordate:short) | %(*objectname:short)' \
    refs/tags/<тег>

Заголовок = <имя тега> — <дата> — <коммит>. Коммит обязателен: тег можно передвинуть или переименовать, а ревизия, на которой релиз собран, должна оставаться в записи однозначно. Берётся именно *objectname (дереференс аннотированного тега), а не objectname — последний вернёт хеш самого объекта тега, а не коммита.

В запись идёт только то, что видно ИГРОКУ или меняет сборку/запуск, — по одному пункту «симптом -> причина одной фразой -> хеш коммита». Полный разбор живёт в сообщении коммита, дублировать его сюда не надо.

Индекс документации с отметками актуальности — docs/README.md, начинать чтение оттуда.

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

make                 собрать build/sprpop.exe и разложить build/
make hdd             + образ build/hdd/sprpop.chd
make mame-link       однократно: подставить образ в MAME (см. ниже)
make -C tests/host   модульные тесты движка под ucsim_z80 (секунды, без MAME)
make test-tools      тесты упаковщиков на хосте (форматы, которые читает Z80)
make fetch           скачать внешние данные в assets/orig/ (SDLPoP + музыка)
make resources       перегенерировать ресурсы из assets/orig/
make music-mp3       музыка из другого набора (flac|mp3|ogg|mt32)
make clean           снести build/ (ассеты не трогает)
make distclean       clean + снести assets/packed/ (вернуть — make resources)

MEMORY=huge, --gfx 256, 11 банков кода в W3. Отладочные ключи сборки: make LEVEL=9 (стартовый уровень), make ROOM=15 POS=2 (стартовая комната и тайл row*10+col), make PROF=1 (профиль фаз кадра полосами бордюра), make ALLOCS=100000 (плотная упаковка регистров — для замеров размера). Сравнивать занятость банков можно только при одном ALLOCS.

Ловушка make mame-link: он подменяет mame/v306/IMG/test_hdd.chd символьной ссылкой на наш образ. Пока ссылка стоит, make hdd любого другого приложения (в т.ч. замороженной roomtest) писал бы через неё в наш build/hdd/ — если понадобится собрать чужой образ, ссылку сначала убрать.

Раскладка папки

Папка	Что
src/	рукописный C: главный цикл sprpop.c, холодная половина sprpop_cold.c, движок pop_*.c
gen/	генерируемые заголовки (индексы архивов, таблицы кадров, шрифт, палитры). Руками не править — их печатают упаковщики; лежат в репозитории, потому что без них src/ не собрать
assets/orig/	оригинальные данные (SDLPoP, записи музыки; MSDOS — необязательно). Вне репозитория — копирайт; вместо них в репозитории лежит tools/fetch_orig.py, который их качает (make fetch). Правила — в assets/orig/README.md
assets/packed/	то, что ложится на диск игры, уже в раскладке диска (BG/, KID/, …). В репозитории — иначе из чистого клона не собрать
tools/	конверторы ресурсов. Раскладку путей знает ОДИН файл — tools/paths.py; менять пути нужно там, а не в отдельных упаковщиках. Адреса ВНЕШНИХ источников — так же в одном: tools/fetch_orig.py
docs/	планы, доски, справочники; docs/PoP/ — форматы ресурсов оригинала
tests/host/	модульные тесты движка под ucsim_z80
build/	выход: sprpop.exe, каталоги ресурсов, hdd/, промежуточные atl/

Звуковые ЭФФЕКТЫ по умолчанию берутся из SDLPoP (SND_SRC=sdlpop) — сборка обязана работать без оригинального дистрибутива DOS. У кого лежит assets/orig/MSDOS/, включает его набор явно (make SND_SRC=msdos): там оцифровка полнее — в SDLPoP пуст звук 48 spiked (насаживание на пики). Разбор — docs/sound_plan.md.

Музыка собирается из одного из четырёх наборов записей (assets/orig/PoP1_DOS_music/): flac по умолчанию, плюс mp3, ogg и mt32 (исполнение Roland MT-32 — звучит иначе, длина треков другая). Набор входит в имя stamp'а, поэтому make music-mt32 пересобирает музыку сам, без -B; разовая сборка без смены умолчания — make MUSIC_FMT=ogg resources-music.

Ресурсы: упаковщик пишет промежуточные атласы в build/atl/<набор>/, из них Makefile склеивает архивы прямо в assets/packed/<КАТАЛОГ>/, а make копирует их в build/. Порядок файлов в списках *_ATL Makefile — это порядок индексов внутри архива, и он же напечатан в gen/*_arc.h: менять порядок нельзя, не перегенерировав заголовок.

Каноническая спецификация форматов .DAT — docs/PoP/POP-DAT-FormatSpecifications.pdf (грепаемая копия — .txt): первоисточник Princed для DAT v1.0. Наши разборы (docs/PoP/MSDOS_RESOURCE_FORMAT.md, docs/PoP/APPLEII_RESOURCE_FORMAT.md) — практические заметки; при расхождении источник истины — спецификация.

Проверка в MAME

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

Игра лежит на образе в D:\GAMES\SPRPOP\, а НЕ в корне диска (так с обобщения HDD-сборки, коммит ea8efdb — один образ рассчитан на несколько приложений). dir D:\ показывает только каталог GAMES; запуск из корня отвечает Bad command or file name.

Тайминги моста (не ждать дольше, см. docs/mame-autotest.md §10): старт run_bridge.sh → 6 с → go → 8 с → keyseq d:{ENTER} + keyseq cd games\sprpop{ENTER} + keyseq sprpop{ENTER} → 5 с → программа работает.

Отладочные тумблеры в живой сессии (src/sprpop.c): 1 — заморозить кадр, 2 — продолжить (разбор позы/окклюзии); ESC — выход. Читы (src/pop_cheat.h): K — убить стража, I — бессмертие, Shift+L — следующий уровень, +/− — обход комнат (ROOMNAV). Не чит, а штатная клавиша оригинала: Ctrl+S — вкл/выкл звук (пурпурная палочка в борте = звука нет). Целевая раскладка управления, к которой подгоняем SprPoP, — docs/keys.txt.

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

Модули

Файл	Роль (порт SDLPoP)
sprpop.c	Главный цикл: дабл-буфер (2 страницы + флип на vsync), порядок tick→draw.
sprpop_cold.c	Холодная половина главного цикла (банк 8): старт уровня, отладочная навигация.
pop_tile.c/.h	Общие ЛИСТЬЯ слоя фона — РЕЗИДЕНТ W1: блит куска атласа, чтение тайла комнаты, tile_table, метка «фон трогали вот здесь» (pop_cd_touch). Резидент потому, что их зовут обе половины слоя фона из разных банков, а const-таблицы банка из чужого банка не видны.
pop_bg.c/.h	ГОРЯЧАЯ половина слоя фона (банк 2, каждый кадр): fore-окклюзия поверх ЛЮБОГО персонажа (seg003 redraw_at_char/char2 — один проход на всех Char), оверлеи кромки, кладка стены (wall_pattern), клип. pop_bg.h — публичный API ВСЕГО слоя.
pop_room.c	ХОЛОДНАЯ половина слоя фона (банк 7, раз на комнату/событие): полная отрисовка комнаты (seg008 draw_tile), точечные перерисовки тайлов (пики, ворота, кнопки, дверь уровня, дрожащие плиты), падающие куски loose (seg007 mob), загрузка атласов.
_pop_bg.h	Внутренний контракт между половинами: общее состояние + три тонкие __banked-обёртки; там же почему рез прошёл именно здесь и сколько стоит.
pop_kid.c/.h	Анимация/движение: интерпретатор seqtbl play_seq + frame_table (seg006), окна Char (loadkid/loadshad), атласы Кида.
pop_cdraw.c/.h	ОТРИСОВКА персонажей — одна на всех Char (порт add_kid_to_objtable/add_guard_to_objtable): спрайт, clip_char, брызги, клинок, heal; полоса HP и палитры соперника. Там же ПРОПУСК неизменившегося кадра (pop_char_skip_mask).
pop_ctrl.c/.h	Управление: диспетчер control() (seg005) + ввод read_user_control (seg006) поверх <kbd_raw.h>.
pop_sfx.c + pop_sfx_cold.c	Звук: насос CBL в резиденте + холодная загрузка набора. Раскладка эффектов НЕ компилируется в EXE — читается с диска (SND/snd.idx, формат PSI1); см. docs/sound_plan.md §10.
pop_music.c	Музыка (банк 9): загрузка треков, кольцо для финальной темы. Длины и длительности — из MUS/mus.idx (EMM-страница + accessor pop_music_info), в EXE их нет; см. docs/sound_plan.md §11.
pop_snd_tbl.h + pop_snd_data.c	Тип записи набора и инварианты (рукописный заголовок) + резидентные pop_snd_tbl/pop_snd_page/pop_snd_pages. Размер записи 5 байт — часть дискового контракта, проверяется статически.
pop_map.c/.h	Коллизия с картой + физика падения/приземления/стены + loose-полы (seg005/006/007).

Банки: две мины, которых компилятор не видит

Обе стреляют молча, обе поймали нас 2026-08-27 (разбор — в ../PoP/roomtest/BUGS_CLOSED.md, поиск «FINAL-BANKCALL»).

1. Прямой вызов в чужой банк. Трамплин SDCC выбирает по __banked в ОБЪЯВЛЕНИИ, а не по тому, где функция лежит. Функция без пометки зовётся прямым call — верно ровно пока вызывающий и вызываемый в одном банке. Перенесли модуль ради разгрузки банка — и тот же call уходит в пустой хвост чужого банка, процессор ползёт по 0xFF до 0x0000, DSS убивает процесс. Ловит toolchain/check_bank_calls.py, она встроена в сборку и ВАЛИТ её (проверено намеренной поломкой).

2. Указатель на данные своего банка, отданный в чужой. Обратная сторона: пока обе стороны в одном банке, указатель на литерал или const-таблицу работает; пометили функцию __banked — и трамплин на время вызова переключает W3, а указатель показывает уже в чужой банк. Так экран таблицы рекордов залило знаками вопроса: в pop_text_draw_mapped (банк 9) уходил литерал "_" из банка 10.

Правило: всё, что уходит указателем в другой банк, обязано лежать в W2 — стек, _DATA или копия. const-таблицы и строковые литералы банкового модуля наружу отдавать нельзя (то же, что уже записано про pop_tile.c). Вторая проверка скрипта предупреждает о явных случаях, но она эвристическая и гарантией не является.

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

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

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

Ключевые memory

pop_port_project, pop_check_sdlpop_first, pop_banking_architecture, pop_background_strategy, pop_kid_plan, pop_hang_state, pop_fore_layer, pop_fall_debug_baseline, accel_vertical_copy, kbd_raw_fifo_drain, pop_perf_registry.