# Prince of Persia → ZX Sprinter — правила подпроекта

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

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

**`SDLPoP/src/` (github.com/NagyD/SDLPoP, GPLv3) — ЕДИНСТВЕННЫЙ авторитетный
источник того, как оригинальный движок это делает.**  Правило без исключений:

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

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

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

Все эти папки — **справочник логики/структур/констант и источник ассетов**,
но НЕ код для копирования (лицензии несовместимы, наш ABI другой): читаем
и переписываем под наш движок, а не вставляем куски.

## Ассеты

Готовые распакованные VGA-256 ассеты (то, что нужно под 320×256×256) —
`SDLPoP/data/` (`res<id>.png`/`.pal`/`.bin`).  Брать оттуда, а НЕ писать свой
декодер DOS `.DAT`.  Локальные `.DAT` — в `MSDOS/`.

**Каноническая спецификация форматов `.DAT` — `docs/POP-DAT-FormatSpecifications.pdf`**
(грепаемая копия — `docs/POP-DAT-FormatSpecifications.txt`): первоисточник
Princed для DAT v1.0 (контейнер/индекс/чек-сумма, кодеки RLE/LZG, палитры,
формат уровней, звук), на нём построены и SDLPoP, и Princed Resources.  Наши
разборы (`docs/MSDOS_RESOURCE_FORMAT.md` / `docs/APPLEII_RESOURCE_FORMAT.md` /
`docs/README.md`) — практические заметки/сверки; при расхождении источник
истины — спецификация.  Формат уровня почти идентичен в Apple II и DOS.

Упаковка ассетов под Sprinter (атласы `.atl`, палитра) — python-скрипты в
`toolchain/` (`render_room.py`, `pop_pack_bg.py`, `pop_pack_kid.py`,
`pop_extract_kid_data.py`).  Их дёргают Makefile'ы тестов.

## Структура папки

- `docs/` — планы и форматы: `PORT_PLAN.md` (общий план фаз),
  `KID_PLAN.md`, `double_buffer_plan.md`, `loose_floors_plan.md`, форматы
  ресурсов.  Начинать чтение отсюда.
- `roomtest/` — **активная разработка**: комната 1 + Kid (анимация, ввод,
  коллизия, падение, зацеп, fore-окклюзия, loose-полы).  Свой `CLAUDE.md`.
- `poc/` — ранний proof-of-concept (снег/атлас/kbd_raw); ассеты в `poc/res/`.
- `bgtest/`, `coltest/` — отдельные проверки фона/коллизии.
- `toolchain/` — python-упаковщики ассетов + эталонные PNG (`1.1-2.png`).
- `SDLPoP/`, `PR/`, `Prince-of-Persia-Apple-II/`, `mininim/`, `MSDOS/` —
  референсы/оригинальные данные (см. выше).

## Ключевые архитектурные решения (memory/)

- `pop_port_project` — общий статус порта.
- `pop_banking_architecture` — будущее: big+BANK_W1, графику нельзя в W3,
  один файл = один банк = прямые вызовы, main резидентен.
- `pop_background_strategy` — фон = композиция тайлов в рантайме (вариант 3).
- `pop_kid_plan` / `pop_hang_state` / `pop_fore_layer` /
  `pop_fall_debug_baseline` — этапы Kid.
- `kbd_raw_fifo_drain` — held-state клавиатуры (единственный принципиальный
  пробел движка, закрыт `<kbd_raw.h>`): вычерпывать FIFO SIO циклом.
- `png_strip_padding_tradeoff`, `pop_tile_atlas_palette_merge` — квирки
  упаковки ассетов.