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

applications/PoP/docs — индекс + сводка по форматам ресурсов

Индекс документов (актуальность на 2026-08-01)

Живые планы — читать перед работой:

Документ	О чём
../roomtest/TASKS_OPEN.md	Что берётся в работу сейчас (не в этой папке, но входная точка)
../roomtest/BUGS_OPEN.md	Открытые баги roomtest (закрытые — в BUGS_CLOSED.md рядом)
impl_diff.md	Осознанные расхождения с SDLPoP: где мы сделали не дословно и почему
perf_backlog.md	Отложенная оптимизация отрисовки с замерами + как мерить (wait-state'ы, границы кадра)
levels_plan.md	Следующий этап: уровни 2+, второй тайлсет, читы SDLPoP
levels_12_15_plan.md	Уровни 12/13 (тень, Джафар, падающие плиты) + что такое 14/15 и 0. 2026-08-13
layout_plan_v2.md	Раскладка кода по окнам/банкам/страницам + замеры скорости отрисовки
room_model_plan.md	kid_room ≠ drawn_room (straddle): сделан S1, остальное впереди
host_tests_plan.md	Модульные тесты движка под ucsim_z80: два шва, регрессии из BUGS_CLOSED.md, дифф против SDLPoP
shadow_render.md	Вид Тени (OR+XOR) — отложено: почему XOR несовместим с прозрачностью #FF, замер подготовки источника, четыре варианта
ideas_backlog.md	Осознанно отложенные гипотезы (мышь, PRNG)
prng_alternatives.md	Запасные генераторы, если упрёмся в бюджет кадра

Исполненные планы, оставленные как справочники:

Документ	Чем ещё полезен
PORT_PLAN.md	Общая карта фаз со статусами; §6 (модель движения), §10 (режим памяти)
KID_PLAN.md	Модель персонажа: char_type, actions_*, устройство play_seq — нужна для скелета/тени/визиря
gates_spikes_plan.md	Раскладка объектов уровня 1 по комнатам, декод LINKLOC/LINKMAP, точные ссылки на seg-код

Форматы ресурсов (ниже по этому файлу): POP-DAT-FormatSpecifications.pdf / .txt (первоисточник), APPLEII_RESOURCE_FORMAT.md, MSDOS_RESOURCE_FORMAT.md.

Удалены 2026-08-01 как полностью исполненные и перекрытые кодом: clip_char_plan.md, double_buffer_plan.md, loose_floors_plan.md, size_optimization_plan.md (его §8 про скорость отрисовки перенесён в layout_plan_v2.md §9). Ищутся в истории git, если понадобятся.

---

Форматы ресурсов — сводка

Каноническая спецификация форматов — POP-DAT-FormatSpecifications.pdf (+ текстовая конверсия POP-DAT-FormatSpecifications.txt для grep/цитирования): «Prince of Persia — Specifications of File Formats», Princed Development Team, 2008. Это первоисточник формата DAT v1.0 (контейнер, индекс, чек-сумма, кодеки RLE/LZG, палитры, уровни, звук), на котором построены и SDLPoP, и Princed Resources. Документы ниже — наши практические заметки/сверки; при расхождении источником истины считать спецификацию.

Цель этих документов — подготовить почву для будущего порта Prince of Persia на ZX Sprinter, разобрав, как устроены ресурсы игры в двух доступных нам версиях:

• APPLEII_RESOURCE_FORMAT.md — формат уровней и графики по официально опубликованным исходникам 1989 года (6502-ассемблер). Уверенность высокая везде — восстановлено прямым чтением кода движка, а не догадками.
• MSDOS_RESOURCE_FORMAT.md — формат .DAT ресурсов DOS-версии (исходников нет). Восстановлено эмпирически (разбор байтов + перепроверка скриптами) и сверено с документацией открытых сторонних инструментов (SDLPoP, Princed Resources).

Главный вывод

Формат уровня практически идентичен в обеих версиях: Apple II LEVELn занимает ровно 2304 байта (структура blueprnt — тайлы, связи плит/дверей, граф экранов, метаданные старта Кида/стражников), а запись уровня в DOS levels.dat занимает 2305 байт с байтовыми значениями тайлов того же диапазона. То есть Джордан Мехнер перенёс формат карты уровня в DOS-порт практически без изменений (+1 байт, вероятно контрольная сумма от DOS-упаковщика). Это значит: раскладку BLUETYPE/BLUESPEC/LINKLOC/ LINKMAP/MAP/INFO, задокументированную по Apple II исходникам, можно применять напрямую и к DOS levels.dat.

Формат же графики отличается принципиально: на Apple II это простой несжатый rowbyte-формат hi-res экрана с плоской таблицей указателей; в DOS — контейнер с оглавлением ресурсов (id/size/offset), с отдельными вариантами под CGA/EGA/VGA — точный кодек пикселей внутри сырого .DAT-чанка не восстановлен ни для той, ни для другой версии до конца. Но для DOS-графики это не блокирует работу: в репозитории github.com/NagyD/SDLPoP (папка data/) уже лежат готовые распакованные PNG для каждого спрайта/фона (включая VGA-256-цветный вариант VPALACE/VDUNGEON — то, что нужно под 320×256×256 Sprinter), см. §5 MSDOS_RESOURCE_FORMAT.md. Это другой релиз/сборка данных, чем наш локальный MSDOS/ (некоторые звуковые .dat отличаются по размеру), но нумерация ресурсов и формат контейнера — те же, что подтверждено побайтовой сверкой уровня res2001.bin.

Общий контейнерный формат DOS .DAT (кратко)

[0x00] u32 LE  tableOffset   — смещение начала таблицы оглавления
[0x04] u16 LE  tableSize     — размер таблицы оглавления
[0x06..tableOffset)          — данные ресурсов (конкатенация чанков)
[tableOffset..tableOffset+tableSize)
                              — массив записей по 8 байт:
                                u16 size, u16 id, u16 offset(абсолютный), u16 reserved(=0)

Инвариант tableOffset + tableSize == размер файла подтверждён на всех 28 .dat-файлах в MSDOS/, и независимо — именованием файлов res<id>.* в data/ репозитория SDLPoP.

Готовые ассеты для порта (важно для практической работы)

github.com/NagyD/SDLPoP/tree/master/data содержит не только код движка, но и сами ресурсы игры — как сырые .DAT, так и распакованные поштучно файлы (res<id>.png для спрайтов/фонов, res<id>.pal для палитр, res<id>.bin для уровней). Для арт-ассетов (в т.ч. нужного полноцветного VGA-варианта дворца/подземелий) практичнее взять их оттуда напрямую, чем писать свой декодер сжатия пикселей DOS .DAT.

Что дальше по форматам (не сделано и пока не нужно)

Порт читает уровень напрямую из res200N.bin (roomtest/pop_level.c), а графику берёт из распакованных PNG SDLPoP/data/ — поэтому ни один пункт ниже сейчас не блокирует работу.

1. Точный кодек сжатия пикселей спрайтов в сыром DOS .DAT (нужен только если понадобится читать именно нашу локальную копию MSDOS/*.dat "как есть", а не ассеты из SDLPoP data/) — сверка с исходником SDLPoP, src/seg009.c.
2. Семантика служебных полей digisnd*.dat/ibm_snd*.dat перед сырыми сэмплами/нотами (частично прояснено документацией Princed Resources — PC speaker: 1 байт заголовка + повторяющиеся тройки байт "2 байта частоты
   • 1 байт длительности"; WAV: 8 бит, моно, unsigned, 11025 Гц).
3. Назначение бит secmask в BLUETYPE (Apple II) и служебного блока id=2000 в начале DOS levels.dat (16 байт в нашей копии, но 2305 байт в версии SDLPoP — расхождение между релизами, не разобрано).
4. Оценка, какие видеорежимы/цветовые палитры ZX Sprinter реалистично покрывают исходную графику (CGA/EGA/VGA варианты в DOS-ресурсах против hi-res Apple II) — отдельная архитектурная задача порта, не формат ресурсов как таковой.