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

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

Статус: план (2026-07-15). §2 (A: kbd_mod_state / B: kbd_raw) — РЕАЛИЗОВАНО и частично проверено в MAME (tests/kbdraw, 2026-07-15, подробности в §2.2); PoC (§5) и остальные фазы — не начаты. Опирается на 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

Объём: одна комната (например 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)

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

Фаза 0 — инфраструктура порта (расширяет PoC, не переписывает):

• Хелд-стейт клавиатуры — финальное решение и реализация по §2 (после подтверждения пользователем).
• Полный конвертер уровней (все 15 файлов levels.dat/LEVELn) → бинарный формат приложения (можно 1-в-1 raw dump, читать по офсетам в рантайме — не обязательно разворачивать в C-struct с указателями).
• Полный конвертер фона (24 экрана × N уровней) в растры + конвертер спрайт-лент Кид/стражник/скелет/тень/Джаффар в атласы .atl (расширение conv_sprites.py/формата .atl, если частот кадров/атласов на актора не хватит текущего лимита — см. риск в §8).

Фаза 1 — Кид, полный набор действий: стоять/идти/бежать/тормозить/ разворот/прыжок (на месте, вперёд, «прыжок с разбега»)/повисание на краю/подтягивание/спуск по свисанию/приседание/питьё зелья/смерть от провала. Переходы между экранами (MAP-граф, INFO.KidStartScrn).

Фаза 2 — мир и ловушки: нажимные плиты/двери через граф LINKLOC/LINKMAP (см. APPLEII_RESOURCE_FORMAT.md §1.2), шипы (выдвижение/втягивание/заклинивание), шаткие плиты (loose, обрушение), зелья (эффект по BLUESPEC×32), стартовые позиции по INFO.

Фаза 3 — бой: подбор/выхватывание меча, состояние стойки, парирование/ удар, коллизия клинков — по логике AUTO.S/seg003-006.c (референс, не копия). Стражник: базовое AI-поведение по GdStartProg (несколько шаблонов программ), Y-сортировка слоями уже есть в движке для «кто спереди/сзади».

Фаза 4 — разнообразие противников: скелет, тень (копия анимации Кида — подтверждено побайтовым совпадением данных, см. MSDOS_RESOURCE_FORMAT.md §3), толстый стражник/визирь (общая база анимации с визирем).

Фаза 5 — звук: CBL-эффекты (шаги, удары, двери, падение) из digisnd*.dat→PCM; PC-спикер тройки (ibm_snd*.dat) как опциональный дешёвый бипер без CBL, если формат подтвердится простым парсингом.

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

Фаза 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) — блокирует даже PoC, если решать «правильно»; иначе PoC на компромиссном варианте 2 (таймаут-эвристика).
2. Бюджет спрайтов на насыщенный экран — сцена с 2+ стражниками + несколько анимированных ловушек может приблизиться к лимиту ~21 спрайт/кадр (sprite_engine_perf) — нужна прикидка по реальным уровням (сколько объектов одновременно активно в худшем экране).
3. Ёмкость одного атласа/страницы EMM на актора — у Кида ~220 кадров (все действия) против 4×12 у rpgwalk — потребуется либо несколько атласов на актора с переключением по фазе действия (стоять/идти отдельно от боя), либо расширение формата .atl/загрузчика на мульти-страничные атласы — оценить фактический байтовый вес конвертированных кадров Кида прежде чем проектировать.
4. Тайминг оригинала — сверить логическую частоту кадров анимации оригинала (Apple II ~60 Гц NTSC / DOS — фиксированный таймер) с 50 Гц Sprinter; если оригинал считался на другой частоте — потребуется коэффициент пересчёта смещений кадров (§6), иначе прыжки/бег будут визуально быстрее/медленнее эталона.

---

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 уже есть, просто больше конвертации ассетов).