Sprinter-SDCC/docs/kbd-games.md

# Клавиатура в играх на Sprinter (raw-канал, held-state)

Как правильно читать клавиатуру в play-цикле: что даёт платформа, чего
она НЕ даёт, и какие паттерны использовать.  Выжато из порта Prince of
Persia (applications/PoP/roomtest) и отладки багов «залипание клавиш»
(2026-07-16) и «отвал Shift» (2026-07-22).

## Почему не ESTEX

ESTEX-функции (kbhit/getch/getkey, WAITKEY/SCANKEY) — **событийные**:
нажатие кладётся в буфер, отпускание не видно вообще.  Live-состояние
есть только у модификаторов (CTRLKEY/kbd_mod_state) — и то с багом BIOS:
для стрелок/Home/End/PgUp/PgDn признак Shift не выставляется
(docs/converted/bugs.txt §4).  Игре же нужно «клавиша X зажата ПРЯМО
СЕЙЧАС» для каждой клавиши.  Отсюда raw-канал `<kbd_raw.h>`.

## Матчасть: как клавиатура устроена снизу

- AT/PS-2 клавиатура сидит на SIO-A Z84C015: порт 0x18 — данные
  (деструктивное чтение!), 0x19 — статус (RR0, бит 0 = «байт принят»).
- Прерывание клавиатуры приходит с тем же IM2-вектором 0xFF, что и
  кадровое; различаются битом 0 порта 0x19.
- Приёмный FIFO — **3 байта**.  Обработчик ОБЯЗАН вычерпывать его в
  цикле «пока бит 0 установлен» (docs/converted/IvanMak.txt §9.4), иначе
  пачка байт переполнит FIFO и байты потеряются.
- Поток — PS/2 Scan Code Set 2: `код` = нажатие (make), `F0 код` =
  отпускание (break), `E0` — префикс расширенных клавиш (стрелки и
  т.п.), т.е. отпускание стрелки = `E0 F0 код`.  Быстрый тап стрелки =
  5 байт подряд.
- **Typematic (автоповтор): повторяется только ПОСЛЕДНЯЯ нажатая
  клавиша** — make-код шлётся снова и снова без break между ними.
  Модификаторы, зажатые вместе с другой клавишей, не шлют НИЧЕГО.
  Это ключевой факт для дизайна recovery (см. ниже).

## API libc

```c
#include <kbd_raw.h>

kbd_raw_open();               // забрать клавиатуру у DSS (весь поток наш)
...
while (!kbd_raw_down(KBD_ESC)) {   // выход проверяем САМИ — DSS слеп
    kbd_raw_sync();                // раз в кадр, ДО чтения клавиш
    if (kbd_raw_down(KBD_RIGHT)) ...
    if (kbd_raw_down(KBD_LSHIFT) || kbd_raw_down(KBD_RSHIFT)) ...
}
kbd_raw_close();              // вернуть клавиатуру DSS (есть и на atexit)
```

- Пока канал открыт, DSS клавиатуру **не видит**: kbhit/getch/getkey/
  kbd_mod_state заморожены.  Перед экраном с консольным вводом —
  `kbd_raw_close()`.
- Декодер живёт прямо в IM2-трамплине (libc/irq/_irq_tramp.c): drain-
  цикл FIFO + FSM префиксов F0/E0 + битмап `_kbdraw_down[512]`
  (0..255 обычные, 256..511 расширенные, `KBD_EXT`).
- `kbd_raw_down(code)` — O(1) чтение битмапа, зовите сколько угодно.
- Требование памяти: BSS модуля должен быть в W2 (в `--memory small`
  у крошечных программ может уехать в W1 → kbd_raw_open вернёт EINVAL;
  huge/big — всегда ок).

## Rx-overrun и политика восстановления

Если прерывания запрещены дольше ~3 байт-тактов (длинные DI-окна,
тяжёлый кадр), FIFO переполняется, SIO теряет байты и взводит Rx Overrun
(RR1 бит 5).  Потерянный break = залипшая клавиша.  Трамплин ловит это и
взводит флаг; `kbd_raw_sync()` раз в кадр делает восстановление:

- сбрасываются ВСЕ обычные клавиши — реально зажатые перечитаются
  ближайшим typematic-повтором (~0.1 с), а залипшие исчезнут;
- **модификаторы (Shift/Ctrl/Alt) НЕ сбрасываются** — их перечитать
  нечем (typematic по ним не идёт), сброс превращался в «отвал» Shift
  при каждом overrun (баг PoP: Shift+→ давал 1-4 осторожных шага, после
  чего Кид начинал бежать — Shift пропадал из битмапа навсегда).

Цена компромисса (осознанная):

- залипший модификатор (если overrun потерял именно его break) живёт до
  следующего нажатия этого модификатора — редкий случай;
- дырка с аккордами: держим →, тапаем ↑ (run-jump) — теперь typematic
  идёт по ↑, и если overrun случится ДО отпускания →, стрелка сбросится
  и не перечитается (повтор к предыдущей клавише не возвращается).
  По замерам в MAME overrun'ы при стабильном удержании не возникают
  вовсе (они кластеризуются в момент пачек make/break при тапах),
  поэтому на практике окно узкое.

## Паттерны игрового цикла

- **held-state против «свежего нажатия»**: битмап отвечает только на
  «зажата ли».  Для действий «одно нажатие = одно срабатывание» нужен
  edge-detect: `if (sp && !sp_prev) toggle(); sp_prev = sp;`
  (roomtest.c, тумблер дабл-буфера по SPACE).
- **Подавление автоповтора действий** — конечный автомат
  RELEASED/HELD/IGNORE в стиле SDLPoP (pop_ctrl.c,
  read_user_control): действие срабатывает на переходе RELEASED→HELD,
  затем переводится в IGNORE и не повторяется, пока клавишу физически
  не отпустят.  Битмап при этом остаётся level-triggered.
- **Оси**: собирать `control_x/control_y` из пар клавиш каждый кадр из
  битмапа заново, не копить дельты.
- `kbd_raw_sync()` звать строго один раз в кадр и строго ДО опроса
  клавиш этого кадра.

## Тестирование в MAME (bridge)

- Держать клавиши через `set_input` на `:kbd:ms_naturl:*` **защёлкой**:
  `value=1` без `frames`, потом явный `value=0`.  Вариант с
  `frames=N` для удержаний ненадёжен (холд может не породить ни одного
  скан-кода).  Комбинации вида Shift+стрелка так подаются нормально
  (LShift = `:kbd:ms_naturl:P1.7` mask 0x0002, Cursor Right =
  `:kbd:ms_naturl:P2.4` mask 0x0040) — проверено 2026-07-22.
- Наблюдать состояние — по символам map-файла: `_kbdraw_down` (+0x12 =
  LShift, +0x174 = Right и т.д.), `_kbdraw_overrun`; счётчики событий —
  watchpoint с действием `{tempN=tempN+1; g}` (не останавливает
  эмуляцию).
- **Не тестировать вдвоём одновременно** (человек за клавиатурой +
  бридж-эмуляция): незакрытая защёлка `set_input` выглядит как
  «залипшая» клавиша и съедает часы отладки.
- Overrun'ы в MAME заметно чаще, чем ожидается на железе (пачка тапа
  прилетает плотнее реальных ~1 мс/байт); открытый вопрос — эмулирует
  ли MAME прерывание на каждый принятый байт SIO (см. TODO).

## История багов (чтобы не повторять)

1. **Залипание клавиш** (2026-07-16): трамплин читал 1 байт за
   прерывание → FIFO(3) переполнялся пачкой break-кодов → break терялся
   → клавиша зажата навсегда.  Фикс: drain-цикл в ISR (как эталоны
   docs/samples/sprinterKeybLib.asm, SIO_CTC_KEY.asm).
2. **Отвал Shift** (2026-07-22): recovery по overrun сбрасывал ВЕСЬ
   битмап; модификаторы не перечитываются typematic'ом → Shift
   «отпускался» до перенажатия.  Фикс: селективный сброс (модификаторы
   сохраняются), см. libc/kbd/kbd_raw_sync.c.

Связанные документы: docs/mame-autotest.md, docs/im2_isr_design.md,
docs/converted/IvanMak.txt §9.4, applications/PoP/docs/PORT_PLAN.md §2.