snark13/Sprinter-SDCC
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
4e43890fceb40ad6043663d2585f0ac1a112a05b
Sprinter-SDCC/applications/PoP/docs/README.md
T
snark13 47a4b084c4 Меню, статус-строка и оболочка игры: title/intro/cutscene/HoF, POP.CFG, палитры 
Эта сессия (меню + текст в служебных полосах):

* Меню: рамка выделения считается от силуэта текста (SEL_PAD сверху и
  снизу), а не «на глаз»; все экраны центрируются в игровых 200 строках
  (UI_CENTER_TOP/UI_CENTER_FIELD) и в них помещаются; Enter и Space —
  равноправные клавиши действия (ui_action_down).
* Settings: убраны SHOW SPRINTER SCREEN и BACK, добавлены DEBUG BAR и
  ABOUT.  About показывает тот же текст, что стартовый Sprinter screen,
  минус строка про клавиши — общий about_text(), чтобы экраны не
  разъехались.  CONTROLS собирается таблицей и центрируется по
  фактическому числу строк.
* GAME PAUSED переехала в нижнюю статус-строку, как в оригинале
  (SDLPoP rect_bottom_text = {193,70,202,250}): это состояние программы,
  а не пункт меню.  POP_HP_Y вынесен в pop_cdraw.h — полосу делят два
  модуля.
* pop_status.c (банк 9) — текст в обеих служебных полосах.  Нижняя:
  порт display_text_bottom + таймера (QUICKSAVE/QUICKLOAD/SOUND ON/OFF,
  24 тика).  Верхняя отладочная переведена с палочек на текст
  «Level ##, Room ##, Speed: …, Sound: …, Immortal #» малым шрифтом, с
  своим форматированием чисел (без printf и без деления).
  Заявка сообщения — запись одного байта pop_status_msg: резидент W1/W2
  не растёт, весь рендер в банке.  Бюджет после правок не изменился
  (_CODE 23981, куча 267 Б).
* Цена вывода: блит глифа ~4,6 тыс. тактов независимо от размера, поэтому
  всё change-driven, отладочная строка перерисовывается ПО ПОЛЯМ, пробелы
  не блитятся вовсе, а вход в комнату заливает только игровое поле
  (pop_screen_fill_field) — борта от комнаты к комнате не меняются.
* Интро: в PV-сцене зазвучали пропавшие эффекты оригинала — закрытие
  ворот (4) и открытие двери покоев (51), из которой входит Джафар.
* docs/status_line_text.md — полная инвентаризация ВСЕХ текстов SDLPoP в
  статус-строке: геометрия, семантика text_time_total как идентификатора
  сообщения, мигание, рестарт по истечении 36/288.

Вместе с этим выкладывается накопленная работа по оболочке полной игры:
автомат состояний (pop_app), title, intro/PV и cutscene, attract-demo,
Hall of Fame, глобальный таймер, настройки и POP.CFG, модуль палитр и
fade, звуковой набор, host-тесты на новые швы.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-25 13:58:36 +03:00

144 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# `applications/PoP/docs` — индекс + сводка по форматам ресурсов
## Индекс документов (актуальность на 2026-08-22)
**Живые планы — читать перед работой:**
| Документ | О чём |
|----------|-------|
| [`../roomtest/TASKS_OPEN.md`](../roomtest/TASKS_OPEN.md) | **Что берётся в работу сейчас** (не в этой папке, но входная точка) |
| [`../roomtest/BUGS_OPEN.md`](../roomtest/BUGS_OPEN.md) | Открытые баги roomtest (закрытые — в `BUGS_CLOSED.md` рядом) |
| [`impl_diff.md`](impl_diff.md) | **Осознанные расхождения с SDLPoP**: где мы сделали не дословно и почему |
| [`perf_l13_room23.md`](perf_l13_room23.md) | **Сцена и метод замера кадра** (каскад плит, ур.13 к.23): как воспроизвести, зонды, канал `clog`, сводка по кадрам, габариты спрайтов и ответ про `uint8_t`. 2026-08-17 |
| [`perf_green_phase.md`](perf_green_phase.md) | **ЗЕЛЁНАЯ фаза (слой фона)**: раскладка тактов, способы ускорения (G1..G6), журнал правок — рабочий документ между сессиями. 2026-08-17 |
| [`perf_cyan_phase.md`](perf_cyan_phase.md) | **ЦИАН фаза (персонажи + передний слой)**: раскладка тактов, способы ускорения (C1..C7), журнал правок — рабочий документ между сессиями. 2026-08-17 |
| [`perf_backlog.md`](perf_backlog.md) | Отложенная оптимизация отрисовки с замерами 2026-08-10 + **как мерить** (wait-state'ы, границы кадра). Позиции 1–7 переехали в фазовые документы выше |
| [`quicksave_plan.md`](quicksave_plan.md) | **QuickSave/QuickLoad** (✅ реализовано, F6/F9, POP.SAV+BAK): разбор (это enhancement SDLPoP, в оригинале 1989 его НЕТ), инвентаризация нашего состояния, формат снимка 'POPQ' v3, шаги QS1..QS6. Справочник. 2026-08-22 |
| [`full_game_plan.md`](full_game_plan.md) | **Полноценная игра**: app state machine, title/intro, demo level 0, таймер, cutscenes, уровни 1..14, ending и Hall of Fame. Уровень 15 исключён. 2026-08-21 |
| [`menu_settings_plan.md`](menu_settings_plan.md) | **Pause menu и Settings**: QuickSave/QuickLoad в основном menu, `POP.CFG`, один `POP.SAV` + `POP.BAK`, текущий VANILLA и задел под ENHANCED; §10 — выбор UI-рендера (текстовые строки + свой растровый рендерер, референс SDLPoP: два шрифта), restart без подтверждения. 2026-08-22 |
| [`palette_plan.md`](palette_plan.md) | **Палитры и fade**: карта всех 256 слотов (kid.pal/title/story, тайлсеты dungeon/palace, стражи), механика fade (4 ступени vs ~64 у SDLPoP), план модуля `pop_pal.c` (API load/apply/black) + переход уровня через fade. 2026-08-23 |
| [`status_line_text.md`](status_line_text.md) | **Строка HP как статус-строка**: полная инвентаризация ВСЕХ текстов SDLPoP в `rect_bottom_text` (геометрия, семантика `text_time_total`, мигание, рестарт по истечении) + что из этого уже есть у нас. 2026-08-25 |
| [`levels_plan.md`](levels_plan.md) | Следующий этап: уровни 2+, второй тайлсет, читы SDLPoP |
| [`levels_12_15_plan.md`](levels_12_15_plan.md) | **Уровни 12/13** (тень, Джафар, падающие плиты) + что такое 14/15 и 0. 2026-08-13 |
| [`midtable_analysis.md`](midtable_analysis.md) | **Слои отрисовки**: как устроены back/mid/fore и objtable в оригинале, чего стоит порт, развилки. 2026-08-13 |
| [`roomnav_skip.md`](roomnav_skip.md) | **Комнаты для отладочного телепорта**: какие пропускать и почему (посчитано по данным уровней). 2026-08-13 |
| [`layout_plan_v2.md`](layout_plan_v2.md) | Раскладка кода по окнам/банкам/страницам + замеры скорости отрисовки |
| [`room_model_plan.md`](room_model_plan.md) | `kid_room ≠ drawn_room` (straddle): сделан S1, остальное впереди |
| [`host_tests_plan.md`](host_tests_plan.md) | Модульные тесты движка под ucsim_z80: два шва, регрессии из `BUGS_CLOSED.md`, дифф против SDLPoP |
| [`shadow_render.md`](shadow_render.md) | **Вид Тени (OR+XOR)** — отложено: почему XOR несовместим с прозрачностью `#FF`, замер подготовки источника, четыре варианта |
| [`ideas_backlog.md`](ideas_backlog.md) | Осознанно отложенные гипотезы (мышь, PRNG) |
| [`prng_alternatives.md`](prng_alternatives.md) | Запасные генераторы, если упрёмся в бюджет кадра |
**Исполненные планы, оставленные как справочники:**
| Документ | Чем ещё полезен |
|----------|-----------------|
| [`PORT_PLAN.md`](PORT_PLAN.md) | Общая карта фаз со статусами; §6 (модель движения), §10 (режим памяти) |
| [`KID_PLAN.md`](KID_PLAN.md) | Модель персонажа: `char_type`, `actions_*`, устройство `play_seq` — нужна для скелета/тени/визиря |
| [`gates_spikes_plan.md`](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`](./APPLEII_RESOURCE_FORMAT.md) — формат
уровней и графики по официально опубликованным исходникам 1989 года
(6502-ассемблер). Уверенность высокая везде — восстановлено прямым чтением
кода движка, а не догадками.
- [`MSDOS_RESOURCE_FORMAT.md`](./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) — отдельная архитектурная задача порта, не формат
ресурсов как таковой.
Reference in New Issue View Git Blame Copy Permalink