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

# Prince of Persia на ZX Sprinter — план порта

## СТАТУС (обновлено 2026-08-01)

Документ составлен 2026-07-15 как план «с нуля» и с тех пор во многом
исполнен.  Читать его надо так:

| Раздел | Что с ним сейчас |
|--------|------------------|
| §1 возможности библиотек | актуально как обзор, но **спрайтовый движок `sprite.h` для персонажей НЕ используется**: Kid/страж рисуются прямыми блитами атласов (`gfx_blit_cols_part*`) с ручным heal — так требует модель оригинала (§6) |
| §2 held-state клавиатуры | **сделано** (`kbd_mod_state`, `<kbd_raw.h>`).  Открытая проблема — потеря байт при аккордах Shift+стрелка; диагноз и план в `../roomtest/TASKS_CLOSED.md` (KBD-1) |
| §3 форматы данных | актуально; уровень читается живьём (`roomtest/pop_level.c`) |
| §4 стратегия фона | **сделано** — тайловый рендерер в рантайме (`roomtest/pop_bg.c`) |
| §5 PoC | **закрыт и превзойдён.**  `poc/` (плейсхолдер-персонаж) — история; активная разработка ушла в `roomtest/` с настоящей графикой |
| §6 модель движения | **сделано**: `play_seq` + `frame_table` оригинала, не физика с нуля |
| §7 фазы | см. отметки статуса прямо в разделе |
| §8 риски | п.1 закрыт, п.3 закрыт (28 страниц-атласов Кида), п.2/п.4 — см. отметки в разделе |
| §10 режим памяти | **сделано и переросло план**: `huge` + четыре банка кода; актуальная раскладка — `layout_plan_v2.md` |

**Где смотреть текущее состояние, а не план:** `../roomtest/README.md`
(что играется), `../roomtest/TASKS_OPEN.md` (что в работе), `levels_plan.md`
(следующие уровни), `layout_plan_v2.md` (раскладка кода по окнам и банкам).

---

Опирается на
`APPLEII_RESOURCE_FORMAT.md` / `MSDOS_RESOURCE_FORMAT.md` / `README.md` в
этой папке, на текущий sprinter-cc/libc/libbgi (см. §1) и на локальные копии
`applications/PoP/SDLPoP` (github.com/NagyD/SDLPoP, GPLv3) и
`applications/PoP/PR` (github.com/NagyD/PR, GPLv2) — используются только как
справочник по структурам/константам оригинального движка и как источник
готовых распакованных ассетов (`SDLPoP/data/`), не как код для копирования.

---

## 1. Что уже есть в sprinter-cc и библиотеках (используем как есть)

Собрано из `docs/TODO.md`, `docs/libc-reference.md`, `docs/sprite-api-design.md`,
`libbgi/include/{gfx.h,sprite.h,graphics.h}`, `examples/rpgwalk`.

- **Графика 320×256×256** (`GFX_MODE_320x256x256`, режим 0x81) — разрешение и
  глубина цвета совпадают почти впрямую с VGA-ассетами оригинала
  (`SDLPoP/data/VPALACE`, `VDUNGEON` — уже 256-цветные PNG). Не нужно ужимать
  в EGA/CGA палитру.
- **BGI-слой** (`graphics.h`) — примитивы, палитра, текст, `getimage/putimage`
  — Фазы 1-2d готовы и проверены в MAME.
- **Спрайтовый движок v2** (`sprite.h`, ветка `sprite-engine-v2`) — ровно то,
  что нужно персонажам PoP:
  - retained-модель (`sprite_update`/`sprite_flip`, double-buffer, dirty-биты,
    heal+blit за один проход);
  - кадровая анимация по ленте (`sprite_anim`, LOOP/PINGPONG/ONCE,
    горизонтальная/вертикальная лента) и tween-перемещение
    (`sprite_moveto`, DDA без knowledge-heavy арифметики);
  - Y-сортировка слоями (`gfx_sprite_ysort`, `layer`) — то, что нужно для
    «Кид перед/за стражником» без ручной пересортировки;
  - атласы в EMM-страницах (`atlas_t`/`atlas_load`) — на восьмерых
    персонажей в `rpgwalk` уже работает: прямой прецедент для Кида/стражника;
  - ограничение кадра ≤ 64×64 — с запасом (см. §3: кадры Кида в оригинале
    ~12-30 × 39-42 px).
- **Frame pacing** (`gfx_set_fps_div`) + цепочка кадровых IRQ — стабильный
  логический тик независимо от рендер-нагрузки экрана (проверено MAME).
- **EMM-бюджет**: ~3.3 МБ свободно на старте (`memory/sprinter_emm_budget`) —
  с большим запасом на все спрайт-атласы и предрендеренные фоны комнат (см.
  §4) даже без выгрузки неиспользуемых уровней.
- **Файловый ввод-вывод** (FILE* v2, `fopen/fread/...`) — для загрузки
  уровней/атласов/палитр с дискеты, по образцу `rpgwalk` (`atlas_load`,
  `gfx_pal_fload`).
- **Клавиатура (событийная)** — `kbhit/getch/getkey` (ASCII + `KEY_*` скан-код
  для стрелок), см. §2 — это НЕ то, что нужно для управления Кидом один в
  один (см. ниже).
- **Звук** — `cbl.h` (потоковый CBL/COVOX, callback-модель, verified MAME) —
  подходит для оцифрованных эффектов (`digisnd*.dat` — PC-звук
  ~11 кГц 8-бит, см. `MSDOS_RESOURCE_FORMAT.md` §4).

Вывод: **движок отрисовки и анимации почти не требует нового кода** —
самый близкий по духу пример (`rpgwalk`: атласы, анимация, tween, дабл-буфер,
FPS-делитель) переносится на PoP почти без изменений архитектуры.

---

## 2. Единственный принципиальный пробел: удержание клавиш

**Спайк проведён (2026-07-15), вопрос закрыт артефактами — не догадкой.**

`getch`/`getkey` — это события ESTEX WAITKEY/SCANKEY (по нажатию), без чёткой
информации о СОСТОЯНИИ (что зажато прямо сейчас, несколько клавиш
одновременно). Prince of Persia на управлении требует именно состояния:
держать направление (бег) + одновременно нажать вверх (прыжок вперёд), держать
Shift (модификатор) + направление и т.д.

### 2.1 Находки

1. **`docs/converted/ProgrammerManual.txt` документирует функцию, которую мы
   раньше пропустили: `CTRLKEY` (ESTEX $33h)** — «Получить состояние
   клавиатуры». Дословно: «данные берутся не из буфера клавиатуры (как в
   остальных функциях), а непосредственно из результатов ПОСЛЕДНЕГО
   сканирования» — то есть это НАСТОЯЩЕЕ live-state, не событие. Но
   покрывает только модификаторы: Left/Right Shift, Ctrl, Alt,
   Rus/Lat, Num/Scroll/Caps Lock, Insert (не обычные клавиши вроде стрелок).
   Готовое решение для «держать Shift = бежать» — тривиальная обёртка,
   без архитектурных рисков.
2. Для ОБЫЧНЫХ клавиш (стрелки, буквы) такого live-state нет нигде в ESTEX —
   `WAITKEY`/`SCANKEY`/`TESTKEY` ($30/$31/$37h) — все три отдают ОДИНАКОВЫЙ
   формат «очередное нажатие», без release. `TESTKEY` не удаляет событие из
   буфера (полезно для «подсмотреть, не потребляя»), но это тоже разовое
   нажатие, не состояние.
3. Автоповтор клавиатуры (typematic) не годится как замена held-state:
   `MAME_MCP_GUIDE.md` фиксирует задержку до первого повтора ~1 секунда
   (типично для PS/2) — на порядок медленнее кадра (20 мс), не подходит для
   платформера.
4. **Решающий артефакт — `libc/irq/_irq_tramp.c` (сам трамплин прерывания,
   не гипотеза):** вектор 0xFF общий для кадра/клавиатуры/CBL. Ветка
   клавиатуры (бит 0 порта 0x19 = SIO-A RR0 «байт принят») делает буквально
   `jp 0x0038` (прямиком в DSS) **до какого-либо чтения порта данных 0x18 И
   до нашей кадровой цепочки (`_irq_chain`)** — наш `irq_chain_add`
   вообще не видит клавиатурные прерывания, они физически не доходят до
   цепочки (см. `tr_notkbd`/`tr_frame` разбор в файле). Значит текущая
   инфраструктура (тот же механизм, что несёт FPS-делитель) НЕ дает
   зацепки для клавиатуры без правки самого трамплина.
5. Регистр данных SIO (порт 0x18) — аппаратный приёмный буфer, чтение
   деструктивно (дёргает байт из очереди); кто прочитал первым, тот и
   владеет байтом. Значит «подглядеть, не мешая DSS» технически
   невозможно — необходимо либо совсем не трогать этот путь (статус-кво),
   либо взять его СЕБЕ полностью на время геймплея.

### 2.2 Рекомендация (конкретная, не три равнозначных варианта)

**A. Тривиально, почти без риска — обернуть `CTRLKEY` ($33h)** отдельной
функцией (например `kbd_mod_state()` в `<conio.h>`) — даёт настоящий
held-state для Shift/Ctrl/Alt. Можно делать хоть сейчас, не архитектурное
решение.

**B. Для обычных клавиш (стрелки и т.д.) — по прецеденту CBL.** В
`_irq_tramp.c` уже есть пример «приватного» пути на том же векторе 0xFF,
который сознательно НЕ чейнится к DSS (CBL: бит 7 порта 0xFE, свой
хук `_irq_cbl_hook`, полный сейв, свой `reti`). Предлагаемый новый
компонент `<kbd_raw.h>` — симметричный: ветка по биту 0 порта 0x19 читает
порт 0x18 САМА (декодирует PS/2 make/break, `0xF0`-префикс — протокол
уже задокументирован в `docs/samples/sprinterKeybLib.asm`), ведёт битовую
карту «клавиша N зажата», и НЕ прыгает в DSS, пока путь активен —
жизненный цикл `kbd_raw_open()`/`kbd_raw_close()` один в один как у
`cbl_open`/`cbl_close`.

  **Важное следствие (сообщить пользователю явно, не прятать):** пока
  `kbd_raw_open()` активен, DSS вообще не получает клавиатурных байт —
  `kbhit/getch/getkey/CTRLKEY` заведомо не будут работать, ESC для выхода
  в DSS-смысле тоже (нужно проверять raw-битовую карту самим). Это
  нормально для активной фазы геймплея (у самой игры и так свой цикл
  ввода), но означает: экраны/паузы, которым нужен ESTEX-ввод (например,
  диалог сохранения через `fopen`, если тот когда-либо потребует ввода
  с консоли), должны на это время `kbd_raw_close()`.

**Не рекомендую вариант «таймаут-эвристика поверх SCANKEY»** — after
находки о typematic-задержке ~1с он не даёт нужной задержки для игры;
рекомендация A+B закрывает потребность без компромиссов.

**Статус: A+B РЕАЛИЗОВАНЫ (2026-07-15, по согласованию с пользователем).**

- A: `kbd_mod_state()` — `libc/conio/kbd_mod_state.c` + `<conio.h>`
  (`KBD_MOD_*`).
- B: `<kbd_raw.h>` (`libc/kbd/`) + правка `libc/irq/_irq_tramp.c`
  (новая ветка на бите 0 порта 0x19: raw активен → сама читает порт
  0x18, декодирует make/break, НЕ чейнится к DSS; raw выключен —
  поведение как раньше, без изменений).  Трамплин вырос со 150 до
  220 байт — `_IRQ_TRAMP_BUF_SIZE` поднят с 224 до 288 (было 4 байта
  запаса, стало ≥60).  `make -C libc` (fast+safe) — чисто.
- **Верификация в MAME** (`tests/kbdraw`, полный цикл open→держать→
  отпустить→ESC-выход→close): `KBD_LEFT` (0x16B, расширенный код
  E0 6B) — down на нажатие, up на отпускание, ТОЧНО совпало с
  константой из `<kbd_raw.h>`; `KBD_ESC` (0x76, обычный код) —
  корректно закрыл raw-канал и вернул DSS (`IM` вернулся в 1).
  Побочно найдено и задокументировано в `docs/libc-reference.md`
  (`<kbd_raw.h>`): MAME-мостовой `press_key` дёргает ОБЕ клавиатуры
  (PC+ZX) одновременно и через ZX-путь давал паразitный незатухающий
  бит — не относится к реальному сценарию (пользователь подтвердил:
  матрица на Sprinter давно не используется), но означает, что
  будущие MAME-тесты этой функции надо гонять через `:kbd:ms_naturl:*`
  напрямую, не через удобный `press_key`.  UP/DOWN/RIGHT/SPACE/SHIFT
  константы — НЕ перепроверены поштучно (тот же общеизвестный
  стандарт PS/2 Set 2, что и подтверждённые LEFT/ESC — проверить перед
  использованием в PoC, если управление будет ощущаться неверно).
- На реальном железе — не проверено (только MAME).

---

## 3. Формат данных — что напрямую переносим из docs/*RESOURCE_FORMAT.md

- **Уровень** (`BLUETYPE`/`BLUESPEC`/`LINKLOC`/`LINKMAP`/`MAP`/`INFO`,
  2304 байта, 24 экрана × 30 тайлов) — читаем один раз при загрузке уровня
  в свою C-структуру (прямой memcpy дампа файла, поля читаем по офсетам
  из `APPLEII_RESOURCE_FORMAT.md` §1). DOS `levels.dat` даёт то же самое
  +1 байт в конце записи — отбросить.
- **Графика фона/спрайтов** — кодек сжатия DOS `.DAT` не восстановлен и
  восстанавливать не будем: используем уже распакованные PNG из
  `SDLPoP/data/{KID,GUARD,VPALACE,VDUNGEON,...}` (см.
  `MSDOS_RESOURCE_FORMAT.md` §5, §7 — тот же контейнерный формат/нумерация,
  просто другой релиз сборки данных). Измерено локально: кадры Кида —
  ~12×39 .. 30×42 px (P-режим, 4-бит палитра), фоновые тайлы подземелья —
  32 px по ширине (10 колонок × 32 = 320 — сходится с шириной экрана), высота
  тайла 20/60/62 px (неоднородные ряды пола/потолка/арок) — укладывается в
  лимит спрайтового движка (кадр ≤ 64×64) без всяких изменений движка.
- **Звук** — `digisnd*.dat` (PC-звук 8-бит ~11 кГц) — конвертация в сырой
  PCM и проигрывание через `cbl_open`/`cbl_push_*`; `ibm_snd*.dat` (PC-спикер
  тройки «частота×2Б + длительность») — тривиальный бипер, не требует CBL.
  MIDI-семейство (`midisnd`, `mt32snd`, `prince.dat`) — вне скоупа (нет
  синтеза MIDI на платформе; не блокирует геймплей).

---

## 4. Стратегия фона — ПЕРЕСМОТРЕНО 2026-07-15: тайловый рендерер В РАНТАЙМЕ

**Было** (первая версия плана): офлайн-склейка каждой комнаты в готовую
растровую картинку 320×~193, `gfx_blit` целиком при входе — обоснование
было «ноль нового кода в libbgi». Пересчёт по факту наличия структурных
данных комнаты (§3.4 формата, `level.h`) показал: 16 уровней × 24 комнаты ×
~60-80 КБ/картинка — это **30+ МБ**, при том что одна и та же картинка
тайла (пол/стена/колонна) переиспользуется в десятках комнат — офлайн-
склейка печёт её заново в каждую копию.

**Стало**: тайлы — переиспользуемый набор картинок ОДИН на визуальный
стиль (не на комнату), структурные данные комнаты — компактные (60 байт:
30×foretable+30×backtable, все 16 уровней ≈ 37 КБ, см. `level.h`).
`room_draw()` (applications/PoP/poc/room.c) проходит 30 тайлов комнаты и
зовёт `gfx_blit` для каждого, читая картинку из таблицы по типу тайла
(`tile_images[TILE_TYPE]`). Итог: десятки-сотни КБ переиспользуемых
тайл-картинок на весь визуальный стиль + ~37 КБ структуры уровней —
вместо 30+ МБ.

**Почему это НЕ бьёт по бюджету кадра**: `room_draw()` зовётся ОДИН РАЗ
при входе в комнату (смена комнаты — не every-frame событие), не в
игровом цикле — это не `sprite_update`, тактовый бюджет кадра не
затронут.

Анимированные тайлы (факел, шипы, дверь-плита) по-прежнему рисуются как
отдельные `sprite_t` поверх фона — движок это уже умеет (Y-order/layers,
dirty-биты, heal против фона через ОЗУ-копию); `room_draw()` кладёт в
ОЗУ-копию именно статичную геометрию (пол/стены/колонны Фазы 1 — §5.2),
поверх неё heal спрайтов работает как обычно.

`toolchain/room_compose.py` (генерик-компоновщик тайлов в одну картинку,
§6.1) остаётся полезным ИНСТРУМЕНТОМ конвертации отдельных тайл-картинок
(PNG → getimage raw), просто теперь его выход — 32 маленьких файла
`tileNN.raw` (по одному на тип тайла), а не один большой файл на комнату;
сама раскладка/повторное использование по комнатам — в C-коде
(`room_draw`), не в офлайн-склейке.

---

## 5. Proof-of-Concept — цель: доказать, что порт вообще ощущается как PoP

> **Закрыт (исторический раздел).**  PoC в `poc/` свою задачу выполнил и
> дальше не развивается: управление ощущается как PoP, held-state работает.
> Всё, что ниже про плейсхолдер-персонажа и приблизительную дугу прыжка,
> — уже неправда для активной ветки: в `roomtest/` стоит настоящая графика
> Кида и авторские таблицы кадров (§6).  Раздел оставлен ради истории
> решений (в частности §5.1 — почему сначала был плейсхолдер).

**Объём**: одна комната (например Level 1, экран старта Кида), без
переходов между экранами, без стражников (стретч-цель, не обязательна).

**Что показываем**:
1. Кид на экране, с закреплённым офлайн-конвертированным набором кадров
   (подмножество: idle, walk L/R, jump-начало/дуга/приземление, стоп-на-краю,
   возможно повисание на краю) — атлас в W0-странице, по образцу `rpgwalk`.
2. Управление: держать влево/вправо — идёт; отпустил — тормозит/стоит;
   нажатие вверх во время бега — прыжок вперёд (дуга по авторским таблицам
   смещений, не по gravity-физике «с нуля» — см. §6). Здесь же проверяется
   решение по §2 (реальный held-state).
3. Столкновения: пол/край экрана/провал — по факту чтения тайла из
   `BLUETYPE` под ногами (без LINKLOC-триггеров пока).
4. Стабильный кадр 50 Гц через уже готовый `gfx_wait_vsync`/дабл-буфер
   (без FPS-делителя — Кид анимируется каждый видеокадр, как в оригинале).

**Критерий успеха**: субъективно «прыжок ощущается как в PoP» (дистанция и
тайминг прыжка сверены с оригинальными таблицами, не подобраны на глаз —
см. §6), управление отзывчивое (не событийное с задержкой), сцена не мерцает
на стыке спрайт/фон.

**Не входит в PoC**: стражники/бой, звук, HUD/таймер, переходы между
комнатами, ловушки/триггеры, титры/меню, сохранения.

**Расположение**: `applications/PoP/poc/` (свой sprinter-cc проект + Python
конвертер ассетов, по структуре `examples/rpgwalk`).

### 5.1 Статус (2026-07-15) — первая итерация: управление + коллизия края

Сделано и проверено в MAME (`applications/PoP/poc/`, `make run`):
держать LEFT/RIGHT (`kbd_raw_down`, raw-канал из §2) — идёт непрерывно,
отпустил — стоит на месте (не событийно, реальный held-state);
столкновение с краями экрана (клип по `MINX`/`MAXX`); анимация
ходьбы/разворота лицом по направлению (`sprite_anim` пинг-понг);
дабл-буфер + `gfx_wait_vsync` — без видимого мерцания. Сборка —
`--memory huge` без `--bank` (§10, подтверждено рабочим).

**Важное отступление от плана (осознанно, не молча):** персонаж —
ВРЕМЕННАЯ заглушка (лицензированный спрайт-пак
`third_party/16x16-RPG-characters` через `tools/gen_kid_placeholder.py`,
тот же источник, что уже использует `examples/rpgwalk`), а НЕ
конвертированная графика оригинальной Prince of Persia. Причина:
исходный набор кадров Кида (`SDLPoP/data/KID`) — копирайт
Broderbund/Ubisoft; автоматический конвейер, который систематически
извлекает и переупаковывает его в новый формат, — это на практике
внутрипроектное решение, которое стоит принимать пользователю явно
для каждого шага, а не проводить асинхронно агентом без лишнего
подтверждения. Сама графика — не то, что проверяет PoC (§5 явно:
цель — ощущение управления/коллизий, не визуальная точность). Замена
на настоящую графику Кида — отдельный шаг, на усмотрение пользователя.

**Ещё не сделано** (следующие итерации §5): авторские таблицы
смещений кадров (§6 — движение при ходьбе линейное, px/кадр),
реальный уровень/фон по `BLUETYPE`/`LEVEL1` (сейчас — плейсхолдер:
плоский пол на весь экран, без ямы/выступа), `kbd_mod_state`/
Shift-бег не подключены к игровому циклу (обёртка готова с Фазы A).

**Прыжок/присед добавлены и ПРОВЕРЕНЫ (2026-07-15)**: состояние
`jumping`/`jump_t`/`crouching`, своя приблизительная дуга прыжка
(`jump_height[]`, 40 кадров) — не авторская таблица, см. §6.1.
HUD-текст статуса (нет отдельной позы).

Живое тестирование пользователем нашло реальный баг: держа UP чуть
дольше 0.8 с (длительность дуги), получали ДВА прыжка подряд — код
проверял `kbd_raw_down(KBD_UP)` как уровень (держится, пока клавиша
физически зажата), а не как фронт нажатия, поэтому в момент
приземления «UP всё ещё зажат» тут же триггерил новый прыжок.
Исправлено edge-detect'ом (`up_prev` — предыдущее состояние UP,
триггер только на переход 0→1). Проверено брейкпоинтом в отладчике
MAME на адресе входа в код прыжка: за одно длинное удержание UP
брейкпоинт срабатывает РОВНО ОДИН РАЗ — фикс подтверждён на уровне
кода, не только «на глаз».

Побочный урок (см. `docs/libc-reference.md` `<kbd_raw.h>`): моя
более ранняя попытка проверить UP/DOWN/RIGHT по скриншотам после
`press_key` ошибочно решила, что скрипт их не нажимает вообще —
на самом деле нажимает исправно, просто скриншот ловил случайный
момент дуги. Брейкпоинт/watchpoint на конкретный адрес кода —
надёжнее скриншота для таких проверок.

---

## 6. Модель движения: авторские таблицы кадров, не физика с нуля

Оригинальный движок PoP не считает прыжок как непрерывную физику
(gravity/velocity каждый тик) — движение персонажа задано таблицами кадров
анимации, где у части кадров зашито фиксированное смещение (dx, dy) для
ЭТОГО конкретного кадра последовательности (структура видна и в
исходниках Apple II — `SEQTABLE.S`/`MOVER.S`, и в SDLPoP `seg003.c`/`seq*`
таблицах). Практическое следствие для нашего движка:
- **Не использовать** `sprite_anim`/`sprite_moveto` для основного
  персонажа как есть (они лианейно тянут по таймеру/тянут к линейной
  цели) — вместо этого приложение само на каждый логический тик:
  переключает кадр (`sprite_frame`, атлас как лента поз, не «прогрессия
  первый..последний» автоматом) и одновременно применяет dx,dy ЭТОГО
  кадра к позиции (`sprite_move`).
- Готовая автоматика движка (`sprite_anim`/`sprite_moveto`/tween,
  Y-сортировка) остаётся полезной для декоративных/фоновых элементов
  (факелы, патрулирующий стражник вне боя — почти один в один паттерн
  `rpgwalk`).
- Источник таблиц смещений: переснять из `Prince-of-Persia-Apple-II/01 POP
  Source/Source/{MOVER.S,SEQTABLE.S,FRAMEADV.S}` и/или
  `SDLPoP/src/seq*.c` — задача Фазы 1 полной реализации (§7), не PoC
  (для PoC можно взять урезанный набор смещений вручную по количеству
  пикселей на кадр, посчитанному по видео/скриншотам оригинала, и уточнить
  позже).

### 6.1 Инструмент конвертации кадров разного размера (`toolchain/png_strip.py`)

Кадры персонажа в оригинале — РАЗНОГО размера каждый (bbox зависит от
позы; `sprite_t` нашего движка (`libbgi/include/sprite.h`) хранит ОДИН
фиксированный w/h на весь спрайт и рисует от угла, без per-frame
смещения — в отличие от оригинала, где на каждый кадр было своё XCO/YCO
(`APPLEII_RESOURCE_FORMAT.md` §2.2). `toolchain/png_strip.py` (генерик,
не завязан на PoP — принимает произвольный список PNG) закрывает это
ПАДДИНГОМ: канвас = макс. w/h среди кадров ленты, якорь по умолчанию
bottom-center («ноги на месте»), остальное — прозрачность.

**Компромисс, не полноценное решение**: один сильно выбивающийся по
размеру кадр в ленте раздувает канвас (и память) ВСЕХ кадров этой же
ленты. Смягчается группировкой по похожим размерам в отдельные атласы
(не одна лента на все позы актора — так уже сделано для ходьбы отдельно
от прыжка).

**Полноценное решение (кандидат в будущее расширение библиотеки, НЕ
делать без предложения и подтверждения пользователя)**: per-frame
смещение в `sprite_t` (аналог XCO/YCO оригинала) — тогда паддинг
не нужен вообще, экономия памяти по полной. Делать только если память
станет РЕАЛЬНОЙ проблемой (не гипотетической) — тогда предложить как
отдельную правку `sprite.h`/движка. Подробности компромисса —
memory/png_strip_padding_tradeoff.

---

## 7. Полноценное приложение — фазы (после PoC)

Порядок — по риску и зависимостям, не по геймплейной важности.
**Отметки статуса — на 2026-08-01.**

**Фаза 0 — инфраструктура порта** — **СДЕЛАНА**, но иначе, чем задумано:
- Хелд-стейт клавиатуры по §2 — сделан.
- Конвертер уровней не понадобился: `res200N.bin` из `SDLPoP/data/LEVELS`
  кладётся на образ как есть и читается по офсетам в рантайме
  (`roomtest/pop_level.c`), уровень живёт в EMM-странице.
- Конвертер фона в растры **отменён осознанно** (§4): фон собирается
  тайлами в рантайме.  Спрайты — `toolchain/pop_pack_bg.py` /
  `pop_pack_kid.py` / `pop_pack_guard.py` → атласы `.atl` (Kid — 28
  страниц, риск §8 п.3 закрыт).

**Фаза 1 — Кид, полный набор действий** — **СДЕЛАНА**: стоять/идти/бежать/
тормозить/разворот/прыжки/повисание/подтягивание/спуск/приседание/
осторожный шаг/питьё зелья/смерть от провала и от пик; переходы между
комнатами во все четыре стороны.  Осталось: **старт по данным уровня**
(`pop_level_start_*` реализованы, но не подключены) — задача L1-START в
`../roomtest/TASKS_OPEN.md`.

**Фаза 2 — мир и ловушки** — **СДЕЛАНА**: кнопки/ворота через
`LINKLOC`/`LINKMAP`, шипы, loose-полы (тряска, обрушение, щебень, пробой
потолка), зелья, дверь уровня (открывается), факелы.  Подробности и
справочник — `gates_spikes_plan.md`.

**Фаза 3 — бой** — **СДЕЛАНА в объёме обычного стражника**: подбор и
выхватывание меча, стойка, удар/парирование, коллизия клинков, HP обеих
сторон, смерть; ИИ стража (замечает Кида, подходит, боевые ветки),
персистентность трупа между комнатами.

**Фаза 4 — разнообразие противников** — **НЕ НАЧАТА**.  Скелет нужен на
уровне 3, толстый — на 6, тень — на 12, визирь — на 13; привязка
«уровень → тип стража» (`tbl_guard_type`) описана в `levels_plan.md` §1.

**Фаза 5 — звук** — **НЕ НАЧАТА**: CBL-эффекты (шаги, удары, двери,
падение) из `digisnd*.dat`→PCM; PC-спикер тройки (`ibm_snd*.dat`) как
опциональный дешёвый бипер без CBL, если формат подтвердится простым
парсингом.  Опкод `SOUND` в `play_seq` пока просто съедает свой аргумент —
точки вызова уже на месте.

**Фаза 6 — оболочка** — **НЕ НАЧАТА**: титры, меню/выбор уровня, HUD
(таймер/жизни), сохранение прогресса (FILE*), финальные катсцены — по
минимуму, геймплейно не критично.  Полоса HP — единственное, что уже есть.

**Между Фазами 4 и 5 вклинивается то, чего в этом плане не было:
переход между УРОВНЯМИ** (загрузка следующего уровня, второй тайлсет
palace, потабличные различия уровней).  Отдельный документ —
`levels_plan.md`.

**Фаза 7 — стабилизация**: полный прогон всех 14 уровней в MAME
(`mame_interactive.py`), затем на реальном железе; профилирование бюджета
кадра по методике `sprite_engine_perf`/`sprite-api-design.md` §9д на самых
насыщенных экранах (несколько стражников + ловушки одновременно —
проверить лимит ~21 спрайт/кадр и Y-sort лимит 32); при необходимости —
банкинг (`--memory big/huge`) для кода/уровня, если размер вылезет за
tiny/small.

---

## 8. Риски, требующие спайка/артефакта до架构 решений

(по правилу `defer_unexplained_quirks` — не гадать, проверять)

1. ~~**Held-state клавиатуры** (§2)~~ — **закрыт** (`<kbd_raw.h>`).  Открытый
   остаток — не «есть ли held-state», а потеря байт при аккордах
   Shift+стрелка: `../roomtest/TASKS_CLOSED.md`, KBD-1.
2. **Бюджет кадра** — риск подтвердился, но не в том виде, в каком ожидался:
   спрайтовый движок для персонажей не используется, поэтому лимит
   «~21 спрайт/кадр» неприменим.  Реальный бюджет упирается в heal+блиты и
   перерисовку тайлов; замер 2026-07-30 — типичный кадр ~371 К тактов
   (~86 % периода).  Инструмент замера уже в коде: полосы бордюра `PROF()`
   в `roomtest.c`.  План выжимания — `../roomtest/TASKS_CLOSED.md` (CLIP-1) и
   `../roomtest/bug_list.md` (T-1/T-2).
3. ~~**Ёмкость атласа на актора**~~ — **закрыт**: Kid разложен на 28
   атласов-страниц по 8 спрайтов (`pop_pack_kid.py`), страж — на 5;
   мульти-страничного формата `.atl` не потребовалось.  Побочно
   подтвердился компромисс паддинга (§6.1).
4. **Тайминг оригинала** — **ОТКРЫТ, и сверка 2026-08-01 показывает
   расхождение.**  Цифры оригинала (SDLPoP): базовый таймер `BASE_FPS = 60`
   (`types.h:1373`), логический кадр игры — `base_speed = 5` тиков
   (`data.h:869`), то есть **83.3 мс (12 лог. кадров/с)**; в бою
   `fight_speed = 6` → **100 мс (10/с)**.  У нас (`roomtest.c`) — три
   ожидания `gfx_wait_vsync()` на итерацию, то есть **60 мс (16.7/с)** и
   без отдельной скорости боя.  Значит **игра идёт примерно на 39 %
   быстрее эталона**.  Точное соответствие даёт 4 ожидания vsync (80 мс
   против 83.3) и 5 в бою (100 мс — совпадает точно).
   Проверять не «на глаз», а секундомером по одинаковому отрезку
   (SDLPoP рядом на том же экране), и только после того, как кадр
   перестанет иногда вылезать за период (см. п.2) — иначе замедление
   спрячет проблему бюджета вместо того, чтобы её показать.

---

## 10. Режим памяти сборки

Пользователь предложил `huge` (горячий код в W1, данные в W2, редко
вызываемая логика — банками в W3) как целевой режим. Согласен, с уточнением
по срокам принятия решения.

**`huge` — правильная цель для ПОЛНОГО приложения**, но не то, с чего надо
стартовать:

- Layout `huge` (см. `memory_modes_implemented`): CODE_LOC=0x4100 (W1),
  DATA_LOC=0x8000 (W2), банки — W3 (порт 0xE2), `crt0_banked` +
  автодетект W2 (как `small`). Состояние приложения (структуры Кида,
  уровня, массив `sprite_t`) остаётся в обычном W2-heap ДАЖЕ если код,
  который его трогает, забанкован — `malloc` из банка возвращает
  W2-указатель (`bank_local_data_pattern`), так что данные не привязаны к
  конкретному банку.
- Оверхед `__banked`-вызова (trampoline: +3 байта на стеке между ret и
  аргументами, виртуальный 24-битный адрес, см. `sdcc_banking`) — фиксированная
  небольшая цена ЗА ВЫЗОВ, не за такт. Это не страшно для функций, которые
  вызываются РЕДКО за кадр (AI одного стражника, диалог, переход между
  комнатами) — страшно было бы забанковать что-то, что дёргается ВНУТРИ
  горячего цикла отрисовки (там уже и так основной бюджет уходит на
  `sprite_update`/блиты — см. `sprite_engine_perf`, ~19.5К тактов/спрайт).
  Правило простое: **не банковать код на пути "раз в кадр на объект",
  банковать код на пути "раз в кадр на комнату/раз в переход/раз в
  редкое событие"**: логика ИИ стражника целиком, диалоги/катсцены, меню/
  титры/выбор уровня, парсинг уровня при входе в комнату, сериализация
  сохранений — хорошие кандидаты в банки; тик Кида, чтение столкновений,
  вызов `sprite_update`/`gfx_wait_vsync`, обработка ввода — должны остаться
  небанкованными (W1/W2).
- Гранулярность банкования — целый файл (`--bank N=FILE.c`), это уже
  системный паттерн проекта (тот же принцип, что и «1 файл = 1 юнит DCE» в
  libc) — значит выгодно с САМОГО начала Фазы 1 (не задним числом) резать
  исходники приложения по границе «горячее/холодное» файл-в-файл: например
  `kid_tick.c`/`collision.c`/`room.c`/`input.c` — неизменно вне банков;
  `guard_ai_*.c`/`dialogue.c`/`menu.c`/`levelload.c`/`combat.c` — кандидаты
  под `--bank`. Тогда переход на `huge` позже — это правка Makefile/
  sprinter-cc-вызова (`--memory huge --bank N=file.c ...`), а не рефакторинг
  логики.

**Уточнение (проверено в `bin/sprinter-cc`, строки ~342-350): можно сразу
собирать PoC на `--memory huge` без единого `--bank`.** Скрипт сам
подставляет стаб `const unsigned char n_banks = 0;`, когда `--bank` не
передан ни один раз — `crt0_banked` линкуется и корректно пропускает цикл
загрузки банков при старте. Layout при этом byte-в-byte совпадает с тем,
что делает `crt0_small` для режима `small` (CODE 0x4100/W1, DATA 0x8000/W2,
автодетект W2) — разница только в том, что попутно линкуется сам
`bank.s` (таблица `_bank_pages` + trampoline-инфраструктура), это
незначительный довесок к размеру, не к рантайм-цене. Значит **PoC можно
сразу собирать вызовом `sprinter-cc --memory huge` без `--bank`-флагов** —
и когда в полном приложении появятся первые «холодные» файлы, переход на
банкование — это просто добавление `--bank N=file.c`, без смены
`--memory`/адресов/crt0. Сборочная конфигурация не потребует миграции
между PoC и полным приложением.

Единственное, что стоит сделать уже в Фазе 1 полного приложения (не в
PoC) — планировать структуру исходников с расчётом на будущий файл-в-файл
сплит под банки (см. выше), раз гранулярность банкования — целый файл.

---

## 9. Что нужно от пользователя, прежде чем двигаться дальше

- Подтверждение направления по §2 (какой из трёх вариантов held-state
  клавиатуры пробовать первым, или сначала спайк-эксперимент в MAME).
- Подтверждение объёма PoC (§5) — устраивает ли «одна комната без
  стражников», или сразу закладывать хотя бы одного патрулирующего
  стражника (это не архитектурно сложнее — Y-order и tween уже есть,
  просто больше конвертации ассетов).