Sprinter-SDCC/applications/SprPoP/docs/gates_spikes_plan.md

# Интерактивные объекты (кнопки/гейты/пики) + HP/смерть — ПОДРОБНЫЙ план

> **Статус: РЕАЛИЗОВАНО (2026-08-01).**  Все фазы плана (P0 персистентный
> per-room `room_modif`, S пики, B кнопки+ворота) сделаны и играются:
> `src/pop_trob.c` (trob-диспетчер, `LINKLOC`/`LINKMAP`, ворота, дверь
> уровня, факелы, зелья), `pop_map.c` (HP, смерть на пиках, урон падения),
> `pop_redraw.c` (пометки перерисовки вместо прямых блитов).  Ограничения
> из §0 закрыты: тайлы персистентны, HP/смерть есть, loose обобщён в trob;
> L3-вверх (climb-up в комнату сверху) тоже сделан (`pop_leave_dir = 3`).
> Из §5 остаётся открытым только **переход на следующий уровень через дверь
> уровня** — он вынесен в `levels_plan.md`.
>
> **Документ оставлен как СПРАВОЧНИК**, а не как план: §1 (раскладка
> объектов уровня 1 по комнатам, декод связей кнопка→цель) и §2 (точные
> ссылки на механику SDLPoP) продолжают экономить время при отладке.
> Текущие задачи — `../TASKS_OPEN.md`.

Составлен 2026-07-20.  Документ самодостаточный: рассчитан на старт
«с чистого листа» (пустой контекст).  Всё сверено с
`applications/PoP/SDLPoP/src/` и данными `res2001.bin`.

Правило проекта (см. `applications/PoP/CLAUDE.md`): **SDLPoP — источник истины**,
перед кодингом читать соответствующий код seg*.c, не гадать.

---

## 0. КОНТЕКСТ: текущее состояние `applications/SprPoP` (что уже готово)

SprPoP — живой прототип порта PoP: комната 1 уровня 1 живой композицией
тайлов + Kid (анимация/управление/коллизия/падение/зацеп/переходы).  Собрать:
`cd applications/SprPoP && make`.  Тест в MAME: см. memory
`mame_mcp_bridge`/`mame_hdd_test_disk` (канонический цикл: `make` → пересобрать
`mame/v306/IMG/test_hdd.chd` через `toolchain/make_hdd.sh` со всеми ассетами →
рестарт `run_bridge.sh` → `resume` → ~13с бут → `type_string("d:{ENTER}SprPoP.exe{ENTER}")`).
Отладка: клавиши `1`=freeze / `2`=resume в SprPoP; MCP-мост `mame-z80`
(read_logical_memory, set_breakpoint, disassemble); адреса символов —
`.sprinter-cc-build/.sprinter-cc-sprpop/sprpop.map` (сдвигаются при пересборке!).

### Модули (все в `applications/SprPoP/`)
- `sprpop.c` — главный цикл (дабл-буфер 2 стр.), `enter_room(room)`,
  обработчики переходов.  File-static рабочие массивы (W2):
  `room_fg[30]`, `room_bg[30]`, `lcol_fg/lcol_bg[3]`, `rcol_fg/rcol_bg[3]`,
  `below_fg[10]`, `cur_room`.
- `pop_level.c/.h` — **уровень из файла** (Фаза L1):
  - `pop_level_load("res2001.bin")` — читает сырой blueprnt в EMM-страницу
    (данные с offset `0x100`, ISR-стаб как атлас).
  - `pop_room_load(room, fg,bg, lcol_fg,lcol_bg, rcol_fg,rcol_bg, below_fg)` —
    извлекает комнату (fg маскирован `&0x1F`, bg raw) + срезы соседей:
    leftcol=col9 левого соседа, rightcol=col0 правого, belowrow=row0 нижнего.
  - `pop_room_link(room, side)` — связь (side 0=L,1=R,2=U,3=D; 0=нет).
  - `pop_level_start_room/pos/dir()`.
- `pop_bg.c/.h` — отрисовка тайлов (порт seg008 draw_tile), fore-окклюзия над
  Kid (`pop_fore_over_char`, порт set_char_collision+redraw_at_char/char2),
  **loose-полы** (shake/bake/mob).  `draw_tile` — статическая, знает
  `draw_gate_back` (грань гейта из левой комнаты).
- `pop_kid.c/.h` — анимация Kid (интерпретатор seqtbl `play_seq`, порт seg006),
  `Kid` struct (frame,x,y,dir,curr_col,curr_row,action,fall_x,fall_y,repeat,
  curr_seq); `knock`-флаг; `kid_cur_dx/flags`, `kid_fp_*` (футпринт).
- `pop_ctrl.c/.h` — ввод (порт seg005 control) через `<kbd_raw.h>`.
- `pop_map.c/.h` — коллизия/физика (порт seg005/006).  Ключевое:
  - `pop_map_set(fg)` — карта текущей комнаты.
  - `pop_map_set_edges(l,r,u,d, lcol_fg, rcol_fg)` — связи + кромки швов для
    коллизии (`get_tile(col=-1)`=lcol, `get_tile(col=10)`=rcol; порт
    find_room_of_tile).
  - `pop_phys_tick()` — кадр физики (fall/land/wall/knock/leave).
  - Переходы: `pop_fell_out` (вниз, y>=211), `pop_leave_dir` (1=left,2=right,
    x∓140).
  - **loose-состояние**: `pop_loose_modif[30]` (публично, читает pop_bg),
    `loose_bake[30]`, `loose_rest[30]` (static); `pop_loose_tick()`,
    `pop_loose_reset()` (сброс при смене комнаты).

### Что сделано по фазам
- **L1** — данные уровня из файла (room1_data.h удалён).  Коммит `21f978d`.
- **L2** — переход в комнату снизу (провал/спуск), фиксы окклюзии.  Коммит `7f3e32d`.
- **L3** — переходы вбок (право+лево) через швы.  **Не закоммичено** на момент
  написания (вместе с этим планом).  **L3-вверх (climb-up в комнату сверху) —
  НЕ сделано.**
- **Loose-полы** (тряска knock / падение mob+окклюзия) — коммит `8b30dc2`.

### Известные ОГРАНИЧЕНИЯ (важно для этого плана)
1. **Нет персистентности тайлов**: `enter_room`→`pop_room_load` каждый раз
   перезагружает ИСХОДНЫЕ тайлы из level-страницы.  Изменения (упавший loose,
   открытый гейт) при повторном входе ТЕРЯЮТСЯ.  Для кнопок/гейтов это
   блокер (см. P0).
2. **Нет HP/смерти** Кида (нужно для пик).
3. Loose-механика — частный случай trob (нужно обобщить).

---

## 1. ДАННЫЕ УРОВНЯ (формат, offsets, объекты)

Сырой `res2001.bin` (2305 Б) = blueprnt DAT 1.0 (Table 6 в
`POP-DAT-FormatSpecifications.txt`).  Читается в EMM-страницу с offset `0x100`.
Тайл-код = байт `& 0x1F`; верхние биты (модификатор BLUETYPE) сейчас отброшены.

| Блок | Offset | Размер |
|------|--------|--------|
| foretable (fg) | 0 | 720 (24 комн × 30) |
| backtable (bg=modifier) | 720 | 720 |
| **LINKLOC** (doorlink1) | **1440** | 256 |
| **LINKMAP** (doorlink2) | **1696** | 256 |
| links (roomlinks) | 1952 | 96 (24×{L,R,U,D}) |
| start_position | 2112 | 3 (room,pos,dir) |

Тайл-коды: `0x00`empty `0x01`floor `0x02`**SPIKE** `0x03`pillar `0x04`**GATE**
`0x06`**DROP-кнопка(closer)** `0x0B`loose `0x0F`**RAISE-кнопка(opener)**
`0x10`lvldoor-L `0x11`lvldoor-R `0x13`torch `0x14`wall.

### Объекты уровня 1 (по комнатам)
```
room 5: DROP(0,2)m11  RAISE(0,4)m9  GATE(0,5)m2  RAISE(0,6)m8  GATE(0,9)m1
room 6: RAISE(0,2)m7  SPIKE(2,3)  SPIKE(2,4)          <-- тестовая
room 7: RAISE(0,2)m6  GATE(0,9)m2
room 8: RAISE(0,6)m5  GATE(0,9)m2  RAISE(1,7)m4
room 9: RAISE(0,0)m3        (+ lvldoor(1,3)/(1,4) — выход на level2, отложено)
room12: RAISE(0,3)m2  GATE(0,9)m2  SPIKE(2,4)
room10/13/14/16/19/24: только SPIKE
room20: DROP(1,4)m1  RAISE(1,7)m0
```
(m = modifier тайла = ИНДЕКС в LINKLOC/LINKMAP.)

### Room6 (тестовая) — раскладка
```
fg row0: 13 01 0F 00 03 01 01 13 01 03   (0,2)=RAISE-кнопка, (0,0)/(0,7)=torch
fg row1: 14 14 14 00 14 14 14 14 14 14   (1,3)=empty
fg row2: 14 14 14 02 02 14 14 14 14 14   (2,3)(2,4)=SPIKE
links: L=8 R=2 U=5 D=0
```
- **Шахта пик**: col3 (row0=empty, row1=empty, row2=spike) + col4 (spike).
- **Гейт, видимый у ЛЕВОЙ кромки room6, — это гейт room8 (0,9)**, отрисованный
  в col0 room6 через левый шов (L=8, leftcol=col9 room8).  В room6 гейта НЕТ.

### Связь кнопка→цель (декод LINKLOC/LINKMAP), проверено:
- `get_doorlink_tile(i)  = d1[i] & 0x1F`
- `get_doorlink_next(i)  = !(d1[i] & 0x80)`  (0 = конец цепочки)
- `get_doorlink_room(i)  = ((d1[i]&0x60)>>5) + ((d2[i]&0xE0)>>3)`
- `get_doorlink_timer(i) = d2[i] & 0x1F`
- где `d1`=LINKLOC@1440, `d2`=LINKMAP@1696.  Цепочка: idx++ пока next.

**Кнопка room6 (0,2) mod=7 → цель: room8 tile(0,9) = ГЕЙТ.**  Подтверждено
в SDLPoP-скринах: нажатие кнопки поднимает решётку у левой кромки room6.
Связь КРОСС-КОМНАТНАЯ (кнопка в room6, гейт в room8) и задаётся таблицей,
а НЕ позицией.  Кнопка может открывать НЕСКОЛЬКО гейтов в разных комнатах.

---

## 2. МЕХАНИКА SDLPoP (точные ссылки)

### 2.1 Trob-система (анимируемые тайлы)
- `add_trob(room,tilepos,type)` seg007:0A5A — в список анимируемых.
- Каждый кадр `redraw_needed_tiles`/`process_trobs` продвигает; диспетч по
  типу тайла → `animate_button/animate_door/animate_spike/animate_loose`
  (seg007:0033+ таблица `animate_*`).
- Состояние тайла хранится в `curr_room_modif[tilepos]` (per-room modifier).
- У нас есть частный случай для loose (`pop_loose_tick`+`pop_loose_modif[30]`).

### 2.2 Пики (spike)
- **Триггер выдвижения** — `check_spike_below()` seg006:1199 (зовётся в
  физике Кида каждый кадр): для каждой колонки футпринта Кида
  (`get_tile_div_mod_m7(char_x_left)`..`char_x_right`) идёт ВНИЗ от
  `Char.curr_row` через НЕ-floor тайлы; если встретил `tiles_2_spike` →
  `start_anim_spike(room,tilepos)`.  → Кид у края (0,2) правым краём задевает
  col3 → скан вниз col3 (empty/empty/spike) → пики вылезают.
- `start_anim_spike` seg007:596: если `modif<=0`: `modif==0` → add_trob(type1)
  + звук; `modif<0` (кроме 0xFF disabled) → `modif=0x8F`.
- `animate_spike` seg007:317: автомат по modif — выдвиг `++modif` (1..4; на 5 →
  `0x8F`; на 9 → 0, trob кончился); убирание `& 0x80` → `--modif` (на 0 → `=6`).
  `0xFF` = disabled (не двигать).
- `is_spike_harmful` seg007:1178: modif `0/-1`→0 (безопасно); `<0`→1;
  `1..4`→2; `>=5`→0.
- **Смерть**: `check_spiked` seg006:0968 — если тайл под Кидом = spike И harmful
  И кадр бега (7..14) / старта прыжка (34..39) с harmful>=2, ИЛИ кадр приземления
  (43/26) с harmful!=0 → `spiked()`.  Падение на пики — отдельный путь (см.
  `is_dead` seg006:1907, frame_177_spiked).  Осторожный ШАГ по невыдвинутым — ок.

### 2.3 Кнопки
- `trigger_button(playsound, button_type, modifier)` seg007:0C53: modifier =
  индекс LINKLOC.  `link_timer = get_doorlink_timer(mod)`; если `!=0x1F`
  (не заклинено): `set_doorlink_timer(mod,5)`; если был `<2` → `add_trob`
  (кнопка нажимается) + звук; затем `do_trigger_list(mod, button_type)`.
- `do_trigger_list` seg007:09E5: идёт по цепочке LINKLOC от idx, для каждой
  цели `trigger_1(target_type,room,tilepos,button_type)` → если >=0
  `add_trob(room,tilepos,result)`.
- `animate_button` seg007:0D3A: `timer=get_doorlink_timer(mod)-1`;
  `set_doorlink_timer(mod,timer)`; `timer<2` → кнопка отжимается.
- Когда Кид ВСТАЁТ на кнопку: `check_press`-путь seg006 (opener → trigger_button,
  closer → тоже; если Кид мёртв — `died_on_button`).  RAISE=`tiles_15_opener`
  (0x0F), DROP=`tiles_6_closer` (0x06).

### 2.4 Гейты
- `trigger_1` seg007:0999 → для `tiles_4_gate` → `trigger_gate`.
- `trigger_gate(room,tilepos,button_type)` seg007:092C: modif = высота открытия.
  opener: `0xFF`→игнор; `>=188`(открыт)→держать `238`; иначе `modif=(modif+3)&0xFC`,
  return 1 (открывать).  closer/иначе: `modif!=0` → return 3 (закрыть быстро).
- `animate_door` seg007:0522: анимация открытия/закрытия; `door_delta[]={-1,4,4}`,
  `gate_close_speeds[]={0,0,0,20,40,60,80,100,120}`.  Гейт медленно закрывается
  после истечения таймера кнопки.
- Отрисовка: кадры гейта; у нас `draw_gate_back` в pop_bg (грань из левой комн.).
- **Проходимость**: Кид блокируется недостаточно открытым гейтом (коллизия
  как стена, порог по высоте открытия); проходит при `modif` открытом.

---

## 3. Поправки к описанию пользователя (что важно)

1. Гейт НЕ в room6 (0,0) — он в **room8 (0,9)**, виден через левый шов; связь
   кросс-комнатная (по таблице LINKLOC, не по позиции).
2. Кнопка может открывать несколько гейтов в разных комнатах.
3. Пики выдвигаются по `check_spike_below` (Кид над колонкой с пиками),
   имеют состояния (не всегда смертельны), убираются со временем.
4. **Кросс-комнатное состояние тайлов ДОЛЖНО ПЕРСИСТИТЬ** — блокер (см. P0).
5. HP/смерть — новая подсистема.
6. Кнопка сама анимируется (нажата/отжата).

---

## 4. ПЛАН РЕАЛИЗАЦИИ (фазы)

### P0 — Персистентное per-room modifier-состояние + trob-каркас (ПРЕРЕКВИЗИТ)
**Проблема:** нажатие кнопки в room6 меняет modif гейта room8 (не текущей
комнаты); при входе в room8 нужно отрисовать гейт в текущем состоянии.  Плюс
это чинит «re-entry восстанавливает тайлы» (loose/гейты).

Дизайн (предложение — уточнить в реализации):
- Массив `room_modif[24][30]` (или lazy per-visited-room) — modifier каждого
  тайла каждой комнаты.  Инициализируется из bg уровня при первой загрузке
  комнаты; далее ЖИВЁТ (не перезагружается).  ~720 Б — влезает в W2 (или в
  EMM-страницу уровня рядом с данными: остаётся >10КБ).
- `enter_room` берёт modif из `room_modif[room]`, а fg — из level-страницы
  (fg почти не меняется; исключения — loose→empty, надо тоже персистить: либо
  отдельный `room_fg_override`, либо флаг «loose упал»).
- Обобщить loose-trob: единый список trob (room,tilepos,type) + диспетчер
  `animate_*` по коду тайла.  Loose (`pop_loose_*`) — перевести на него.
- Кросс-комнатный trigger: `add_trob` в НЕ текущую комнату меняет
  `room_modif[room][tilepos]`; анимация продвигается даже для невидимой комнаты
  (в оригинале — да; можно упростить: для невидимой комнаты гейт сразу в
  финальном состоянии, анимировать только при видимости — решить при реализации).

### Фаза S — Пики (самодостаточно; отладит HP/смерть)
Порядок:
1. `room_modif` для пик (из P0 или временно локально).
2. `check_spike_below` (порт seg006:1199) — в `pop_phys_tick`.
3. `start_anim_spike` + `animate_spike` (порт seg007) — состояние в modif.
4. `is_spike_harmful` + `check_spiked` (порт seg006:0968).
5. **HP/смерть**: ввести `hitp_curr` (старт напр. 3); `take_hp`; при пиках —
   мгновенная смерть; seq смерти (`seq_22_crushed`/`frame_177_spiked`..185);
   анимация смерти; респавн (kid_init на старте или чек-поинт).
6. Отрисовка: кадры выдвижения пик.  В pop_bg есть `SPIKES_FRAM_RIGHT` — нужны
   pop-out кадры (spikes_fram по modif) + fore над Кидом.

### Фаза B — Кнопки + гейты (нужен P0)
Порядок:
1. Доступ к LINKLOC/LINKMAP из pop_level (добавить геттеры doorlink1/2[i] с
   маппингом W0 или скопировать таблицы в W2 при load — 512 Б).
2. `pop_map` детект «Кид встал на кнопку» (check_press-путь) → `trigger_button`.
3. `trigger_button` → таймер + `do_trigger_list` (обход цепочки) →
   `trigger_gate` для целей → изменить `room_modif[целевой]`.
4. `animate_button` (кнопка отжимается) + `animate_door` (гейт откр/закр +
   авто-закрытие).
5. Отрисовка гейта (кадры по modif) через ЛЕВЫЙ шов (гейт room8 в room6) +
   при входе в room8.  Расширить `draw_gate_back`/добавить `draw_gate`.
6. Коллизия: закрытый гейт = стена (порог по высоте открытия); открытый —
   проход.  Учесть кросс-комнатный гейт на шве (проход влево room6→room8).

**Порядок фаз:** P0 → S → B.  S в основном независим (кроме HP/trob-каркаса),
но проще и отладит смерть/анимацию; B требует P0 (кросс-комнатное состояние).

---

## 5. Открытые вопросы / грабли
- Персистентность `fg` для loose (тайл→empty): решить в P0 (override-массив или
  флаг), иначе упавший loose «вернётся».
- Анимация trob в НЕВИДИМОЙ комнате: упростить (финальное состояние сразу) или
  портировать честно.
- Двоебуфер: любой транзиент (пики/гейт/кнопка) финализировать перерисовкой
  «покоя» на ОБЕИХ страницах (урок из loose — см. memory `pop_loose_floors`).
- Дверь уровня (lvldoor room9) + переход на level 2 — ОТДЕЛЬНО, отложено.
- L3-**вверх** (climb-up в комнату сверху) — ещё не сделан; можно закрыть до
  объектов или параллельно.