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

# Prince of Persia — Kid (персонаж): анализ и план

Статус: план (2026-07-16).  Опирается на разбор `SDLPoP/src/seg006.c`
(ядро физики/управления Kid), `seqtbl.c` (таблицы последовательностей),
`types.h` (char_type, seq_*, SEQ_*, actions_*), `SDLPoP/data/KID` (спрайты).
Фон уже готов и проверен на MAME (`applications/PoP/roomtest`, см.
`memory/pop_background_strategy`) — Kid развиваем в том же `roomtest` как
новый PoC (решение пользователя: старый `poc/` не трогаем).

**Копирайт:** спрайты Kid (`SDLPoP/data/KID`) — Broderbund/Ubisoft.
Использование настоящей графики Kid — сознательное решение пользователя
(в отличие от плейсхолдера в старом `poc/`, см. PORT_PLAN §5.1).

---

## 1. Как устроен персонаж в оригинале (что портируем)

### 1.1 Состояние — `char_type` (14 полей, types.h)

```
frame       текущий номер кадра (индекс во frame_table_kid)
x, y        позиция (byte; x — с учётом direction)
direction   -1 влево / 0 вправо
curr_col,   логическая клетка (тайл), где персонаж
curr_row
action      КАТЕГОРИЯ действия (actions_*, см. 1.2)
fall_x,     скорость падения (fall_y<22 = 1 ряд, <33 = 2 ряда)
fall_y
room        комната
repeat      счётчик для удержания-ввода (напр. повторный прыжок)
sword       есть ли меч (бой — вне Фазы 1)
alive       жив/мёртв
curr_seq    УКАЗАТЕЛЬ в seqtbl (байткод текущей последовательности)
```

Состояние крошечное — легко живёт в W2.

### 1.2 Категории действия — `actions_*` (9 шт)

`0 stand`, `1 run_jump`, `2 hang_climb`, `3 in_midair`, `4 in_freefall`,
`5 bumped`, `6 hang_straight`, `7 turn`, `99 hurt`.  `action` определяет,
как `check_action()`/`play_kid()` реагируют на ввод и физику каждый тик.

### 1.3 Движок анимации/движения — ГЛАВНОЕ

**Движение НЕ физика, а байткод + per-frame смещения** (подтверждает
PORT_PLAN §6).  Три уровня:

1. **`seqtbl`** — байткод-программа на действие.  Опкоды (types.h):
   `SEQ_DX`(0xFB) сдвиг x на amount×direction, `SEQ_DY`(0xFA) сдвиг y,
   `SEQ_FLIP`(0xFE) разворот, `SEQ_JMP`(0xFF)/`SEQ_JMP_IF_FEATHER`(0xF7),
   `SEQ_UP`/`SEQ_DOWN`(0xFD/0xFC) смена ряда, `SEQ_ACTION`(0xF9) задать
   `Char.action`, `SEQ_SET_FALL`(0xF8), `SEQ_KNOCK_UP/DOWN`, `SEQ_SOUND`,
   `SEQ_DIE`/`SEQ_END_LEVEL`/`SEQ_GET_ITEM`.  **Байт < 0xF0 = НОМЕР КАДРА**
   → ставит `Char.frame` и play_seq возвращается (один кадр за тик).
2. **`play_seq()`** (seg006.c:570) — интерпретатор: крутит опкоды из
   `seqtbl + Char.curr_seq`, пока не встретит кадр.  ~15 case — портируется
   1-в-1.  **Квирк:** seqtbl использует АБСОЛЮТНЫЕ DOS-адреса в JMP;
   `SEQTBL_0 = seqtbl - SEQTBL_BASE(0x196E)` — при порте пересчитать
   базу (JMP-адреса в наших данных).
3. **`frame_table_kid[]`** (seg006.c:127, ~180 кадров) — на КАЖДЫЙ кадр:
   `{image, sword_flags, dx, dy, flags}`.  `image` — индекс спрайта Kid;
   `dx/dy` — смещение позиции ЭТОГО кадра; `flags`: 0x1F weight_x, 0x20
   thin, 0x40 needs_floor, 0x80 even/odd-pixel (влияет на x-рендер).

**Тик персонажа:** `play_kid()` (диспетчер по action+вводу) → `play_seq()`
(двигает curr_seq, ставит кадр, применяет seq-dx/dy) → `frame_table[frame]`
даёт image+собственные dx/dy → позиция и спрайт.  У нас это ложится на
`sprite_frame`+`sprite_move` (НЕ `sprite_anim`/`sprite_moveto` — см.
PORT_PLAN §6: авторские таблицы, не автопрогрессия).

### 1.4 Управление — `control_kid()`/`read_user_control()` (seg006.c)

Читает ввод (у нас — held-state `kbd_raw`, уже готово, §2 PORT_PLAN) и по
`Char.action` выбирает последовательность (`seqtbl_offset_char(seq_id)`).
Логика «что можно из какого состояния» — ядро ощущения PoP.

### 1.5 Взаимодействие с картой — collision (seg006.c)

`check_on_floor()`/`start_fall()` — пол под ногами / падение в яму;
`in_wall()` — упор в стену (сдвиг наружу); `check_grab()`/
`can_grab_front_above()` — зацеп за уступ; `fell_out()` — вывалиться из
комнаты; `check_spiked()`/loose — ловушки; `fall_accel()`/`fall_speed()` —
ускорение падения.  Всё читает ТИП тайла (`get_tile`) — у нас это уже
разобранные `fg[]/bg[]` (level.h/room1_data.h).

---

## 2. Спрайты Kid (219 шт, 16 цветов, 177 КБ)

- 219 PNG (`data/KID`), 16-цветные (палитра `res400.pal`, 16×RGB как env/
  wall), макс кадр **53×35** — влезает в лимит движка 64×64.  177 КБ в
  8bpp.
- `frame_table_kid` отображает кадр→`image` (индекс спрайта).  Число
  РАЗЛИЧНЫХ image — уточнить (≤219); паковать те, что реально используются
  платформинг-последовательностями Фазы 1 (не все 219 — бой/катсцены
  отдельно).
- **Палитра:** Kid 16 цветов → слоты Sprinter `0x70-0x7F` (env 0x50, wall
  0x60 уже заняты; Kid не пересекается).  Пиксель i: 0→0xFF, i→0x70+i.
  Тот же пайплайн, что `pop_pack_bg.py`.
- **Атлас:** прямая адресация по номеру image (как фон): `kid[img>>5]`,
  idx `img&31`; ~7 EMM-страниц (или SHIFT=4). Свой пакер `pop_pack_kid.py`
  (переиспользовать код `pop_pack_bg.py`).

### 2.1 РЕШЕНИЕ ДО СТАРТА: per-frame offset vs padding

Кадры Kid — РАЗНОГО размера, а `sprite_t` рисует от угла фикс. w/h.  Два
пути (см. PORT_PLAN §6.1, `memory/png_strip_padding_tradeoff`):
- **Padding** (bottom-center) — просто, но 219×53×35 ≈ 406 КБ (раздув ×2.3).
- **Per-frame offset** — хранить XCO/YCO кадра (у оригинала он и есть,
  `APPLEII_RESOURCE_FORMAT §2.2`), рисовать `blit(x+xco, y+yco)`; паддинг не
  нужен, память по факту (177 КБ).  Требует лёгкого расширения хранения
  (offset рядом с кадром) ИЛИ ручного смещения в коде рендера Kid.
**Рекомендация:** per-frame offset — оригинал так и делает (frame_table dx/dy
+ image XCO/YCO), даёт точное позиционирование И экономию.  Хранить xco/yco
в нашей копии frame_table (добавить 2 байта/кадр — ~360 Б).  Не тянуть
расширение `sprite.h` — рисовать Kid прямым `gfx_blit(x+xco, y+yco, img)`
(как фон), НЕ через retained `sprite_t`, раз позиция и кадр всё равно
задаются вручную каждый тик.

---

## 3. Данные для порта (объём)

- `frame_table_kid` → C-массив ~180×(5+2 offset) ≈ 1.3 КБ (const, ROM).
- `seqtbl` (нужные последовательности) → C-массив байт.  Весь seqtbl ~1-2 КБ;
  для Фазы 1 можно взять только платформинг-последовательности (вырезать
  бой/гардов 55-92) — оценить после разметки.  JMP-адреса пересчитать под
  свою базу.
- Спрайты — атласы (EMM, не W2).

---

## 4. Фазы работы (по твоему списку, порядок по зависимостям)

**Фаза K0 — конвейер спрайтов + отрисовка одного кадра**
- `pop_pack_kid.py`: 219 (или подмножество) → `kid*.atl` + `kid.pal`
  (слоты 0x70), таблица кадр→image + xco/yco.
- Отрисовать Kid ОДНИМ кадром (stand) в roomtest поверх фона на верном
  тайле — проверить палитру/позицию/прозрачность на MAME.
- Артефакт-цель: Kid стоит на уступе комнаты 1 как в `1.1-2.png`.

**Фаза K1 — движок анимации (play_seq + frame_table)**
- Портировать `play_seq()` (интерпретатор) + `frame_table_kid` + минимальный
  `seqtbl` (stand/run/turn).
- Прогнать несколько последовательностей вручную (stand→run→stop) —
  проверить, что кадры и смещения совпадают с оригиналом (сверять с
  SDLPoP/скриншотами, тайминг 50 Гц).

**Фаза K2 — управление на месте + ходьба (твои а, б)**
- `control_kid` подмножество: stand (2), run (1/84/13), turn (5/6),
  standing_jump (3), crouch (50/49), safe_step (29-44 — аккуратный шаг).
- Held-state через `kbd_raw` (готово).

**Фаза K3 — коллизия с картой (твой п.3)**
- `check_on_floor`/`start_fall` — падение в ямы (тип тайла под ногами из
  `fg[]`); `in_wall`/стоп у стены; `fell_out` (край экрана — пока без
  перехода комнат).
- Падения/приземления (seq 7/17/19/20) + `fall_accel/fall_speed`.

**Фаза K4 — прыжки и повисание (твои а-прыжок, в)**
- run_jump (4), jump_up (28/14), grab (8/16/24), climb_up (10)/down (68),
  hang (25/6), release (11/23).  Это самый «PoP-овый» кусок — сверять
  дистанции/тайминг с оригиналом (не на глаз).

**Фаза K5 — прочее (твой г)**
- drink (78), level_door (70), crouch_hop (79), spiked/loose/chomped
  (ловушки, если тайлы есть в комнате), death (71).

Бой (меч, seq 55-92, стражники — seg005) — ВНЕ этого плана (отдельная фаза
полного приложения, PORT_PLAN §7 Фаза 3).

---

## 5. Риски/решения ДО кода (правило defer_unexplained_quirks)

1. **Per-frame offset** (§2.1) — решить до K0 (влияет на формат данных).
   Рекомендация: xco/yco в frame_table, прямой blit.
2. **seqtbl rebasing** — JMP-адреса абсолютные (SEQTBL_BASE 0x196E); при
   порте пересчитать в оффсеты своего массива.  Проверить на 1-2 seq.
3. **Тайминг** — оригинал (DOS) фиксированный тик; наш 50 Гц.  Если
   логическая частота кадров иная — пересчёт dx/dy (PORT_PLAN §8.4).
   Сверять дистанцию бега/прыжка с эталоном.
4. **Число реально нужных кадров/последовательностей** для Фазы 1 —
   разметить (вырезать бой/катсцены/гардов), чтобы не тянуть все 219
   спрайта и весь seqtbl.
5. **Копирайт графики Kid** — подтверждено решение пользователя (§вводная).

---

## 6. Что переиспользуем (готово)

- Фон комнаты (`pop_bg.c`) — Kid рисуется ПОВЕРХ (сейчас — прямым blit;
  heal против фона — когда/если понадобится через RAM-копию, фон её уже
  заполняет, `GFX_BANK_TRANSPARENT`).
- `kbd_raw` held-state (§2 PORT_PLAN) — готов и проверен.
- Пакер спрайтов/палитра (`pop_pack_bg.py`) — шаблон для `pop_pack_kid.py`.
- Разобранная карта комнаты (`fg[]/bg[]`, level.h) — для коллизий.
- `gfx_blit`/`gfx_w0_map` из W0-атласа — проверенный путь (bgtest/roomtest).