# Структура заголовка плагина (512 байт) > Источники: `inc/wc_api.h` (константы `WC_PLUGIN_*`, `WC_PCOND_*`), > `DiskRef/WC_History.txt` (история изменений формата) ## Общая структура Заголовок плагина имеет фиксированный размер **512 байт** и содержит всю необходимую информацию для загрузки и запуска плагина системой WC. **Текущая версия формата:** `#10` (`WC_PLUGIN_VERSION`), идентификатор: `WildCommanderMDL`. Формат неоднократно менялся (WC v0.56, v1.00, v1.02, v1.06, v1.09) — старые плагины несовместимы с новой версией. ## Детальная структура | Offset | Размер | Описание | |--------|--------|----------| | +0 | 16 | Резерв (reserved) | | +16 | 16 | Идентификатор: "WildCommanderMDL" | | +32 | 1 | Версия формата (#10) | | +33 | 1 | Резерв | | +34 | 1 | Количество страниц для плагина | | +35 | 1 | Номер страницы для #8000 (от 0) | | +36 | 12 | Блоки данных (6 x 2 байта) | | +48 | 15 | Резерв | | +63 | 1 | Флаги для блока расширений | | +64 | 96 | Блок расширений (32 x 3 байта) | | +160 | 1 | #00 (маркер окончания расширений) | | +161 | 4 | Максимальный размер файла | | +165 | 32 | Имя плагина | | +197 | 1 | Тип условий вызова плагина | | +198 | 6 | Текст для F4 или F2 | | +204 | 24 | Текст для меню вьювера | | +228 | 32 | Резерв | | +260 | 252 | Структура параметров INI | ## Детальное описание полей ### Количество страниц (+34) Указывает, сколько 16 КБ страниц памяти будет выделено плагину. Максимум: **64 страницы** (`WC_PLUGIN_MAX_PAGES`) = 1 МБ. Страницы выделяются из пула `#61–#A0` (физические), плагин обращается по логическому номеру 0..N−1 через `wc_mngc_pl()` / `wc_mng0_pl()` / `wc_mng8_pl()`. Часть страниц может использоваться как буфер, который **сохраняется между повторными запусками** плагина (NEXT/PREV) — код плагина WC не перезагружает, если плагин уже загружен. ### Номер стартовой страницы (+35) Номер страницы (от 0), которая будет включена в окно #8000 при запуске плагина. Нумерация начинается с 0. ### Блоки данных (+36, 12 байт) Описывает до 6 блоков данных плагина: ``` Для каждого блока (2 байта): Байт 0: Номер страницы (от 0) для размещения блока Байт 1: Размер блока (x512 байт) ``` Блоки данных следуют сразу за заголовком плагина (512 байт). Пример: ```asm DB 0,16 ; Блок 0: код плагина, 16x512 = 8КБ DB 1,32 ; Блок 1: данные плеера, 32x512 = 16КБ DB 2,9 ; Блок 2: дополнительный плеер, 9x512 = 4.5КБ DB 0,0 ; Остальные блоки не используются DB 0,0 DB 0,0 ``` ### Флаги блока расширений (+63) Определяет, какая клавиша запускает плагин по расширению: ``` BIT 0: Режим запуска 0 - запуск и по ENTER, и по F3 1 - см. BIT 1 BIT 1 (если BIT 0 = 1): 0 - запуск только по ENTER 1 - запуск только по F3 ``` | Биты [1:0] | Поведение | |------------|------------------------------------------| | `00` | ENTER и F3 — оба запускают плагин | | `01` | Только ENTER (F3 = встроенный вьювер WC) | | `11` | Только F3 (ENTER = вход в файл как данные) | > Разделение ENTER и F3 добавлено в WC v1.00 (октябрь 2019). ### Блок расширений (+64, 96 байт) Содержит до 32 расширений файлов (по 3 байта каждое). **Важно:** Расширения указываются **ТОЛЬКО БОЛЬШИМИ БУКВАМИ!** Примеры: ```asm DB "TXT" ; Текстовые файлы DB "MOD" ; MOD музыка DB "WAV" ; WAV аудио DB "MP3" ; MP3 аудио DB "VGM" ; VGM музыка ; ... до 32 расширений DS 27*3 ; Остальные заполняем нулями ``` Блок можно забить нулями, если не нужна инициация по расширениям. ### Максимальный размер файла (+161, 4 байта) Определяет максимальный размер файла, который плагин может обработать. Файлы больше этого размера плагину не передаются. Примеры: ```asm DW #FFFF,#FFFF ; Без ограничений DW #6000,#0000 ; Максимум 24КБ ``` ### Имя плагина (+165, 32 байта) Текстовое имя плагина, которое показывается в меню. ```asm DB "VGM Player for OPL3 v1.0 " ``` ### Тип условий вызова (+197) Определяет, при каких условиях плагин должен вызываться (помимо расширений): | Код | Константа (C) | Условие вызова | |-----|---------------|----------------| | #00 | `WC_PCOND_EXT_ONLY` | Только по расширению | | #01 | `WC_PCOND_ON_LOAD` | Сразу после загрузки (при ENTER) | | #02 | `WC_PCOND_TIMER` | По таймеру скринсейвера + из меню F10 | | #03 | `WC_PCOND_F10` | Из меню F10 | | #04 | `WC_PCOND_VIEWER` | Из меню вьювера (SHIFT+F3) | | #05 | `WC_PCOND_F10_VIEW` | F10 + SHIFT+F3 | | #11 | `WC_PCOND_F10_F2` | F10 + F2 | | #12 | `WC_PCOND_F2` | По F2 | | #13 | `WC_PCOND_F10_F4` | F10 + F4 | | #14 | `WC_PCOND_F4` | По F4 | | #15 | `WC_PCOND_F10_V_F4` | F10 + SHIFT+F3 + F4 | **Примечание:** Все плагины с указанными расширениями также вызываются по расширению. Тип вызова расширяет набор способов запуска. ### Текст для F2/F4 (+198, 6 байт) Если тип вызова #11/#12 - текст для подсказки F2 Если тип вызова #13/#14/#15 - текст для подсказки F4 ```asm DB "Edit " ; Для редактора DB "Play " ; Для плеера ``` ### Текст для меню вьювера (+204, 24 байта) Текст, который выводится в меню выбора вьювера (при типах #04/#05/#15): ```asm DB "Play VGM on OPL3 " ``` ## Структура параметров INI (+260, 252 байта) > Добавлено в WC v1.09 (31.07.2024) Позволяет плагину принимать параметры из INI-файла WC (`wc.ini`). Параметры отображаются в меню F9 → настройки плагина. ### Формат записи ``` +0: 1 байт - длина ПОЛНОЙ структуры (включая этот байт) или #00 (конец) +1: 1 байт - default_option (1-based номер опции по умолчанию) +2: N байт - "parameter_name" (ASCII, без терминатора) +2+N: 1 байт - количество опций (1-10) +3+N: M байт - "option1",0, "option2",0, ... ... следующая запись или #00 ``` Максимум 8 параметров, каждый до 10 опций. ### Пример ```asm PAR1: DB PAR1END-PAR1 ; Длина структуры DB 1 ; Опция по умолчанию = 1 DB "opl_port" ; Имя параметра DB 2 ; Количество опций DB "C4",0 ; Опция 1 DB "C0",0 ; Опция 2 PAR1END: PAR2: DB PAR2END-PAR2 DB 1 DB "freq" DB 3 DB "683",0 DB "1367",0 DB "2734",0 PAR2END: DB 0 ; Конец списка параметров ``` ### Чтение параметров в плагине ```c // wc_prm_pl(param_num) — param_num с 0 // Возвращает: номер опции (1-based), 0xFF если параметр не задан uint8_t opt = wc_prm_pl(0); // прочитать 1-й параметр if (opt == 0xFF) opt = 1; // значение по умолчанию ``` ```asm ; ASM: A' = номер параметра (0-based) EXA LD A,0 ; Параметр #0 CALL WLD EXA LD A,#53 ; PRM_PL CALL WLD ; Z=не задан, NZ: A=номер опции (1-based) ``` В INI-файле (`wc.ini`) параметры записываются по длинному имени плагина: ```ini [VGM Player v0.5] opl_port=C4 freq=683 ``` ## Пример полного заголовка ```asm ORG #6000 ; +0: Резерв DS 16 ; +16: Идентификатор DB "WildCommanderMDL" ; +32: Версия DB #10 ; +33: Резерв DB 0 ; +34: Количество страниц DB 2 ; +35: Стартовая страница DB 0 ; +36: Блоки данных DB 0,8 ; Код: 4КБ DB 1,16 ; Данные: 8КБ DB 0,0 DB 0,0 DB 0,0 DB 0,0 ; +48: Резерв DS 15 ; +63: Флаги расширений DB 0 ; +64: Расширения DB "VGM" DB "VGZ" DS 30*3 ; +160: Конец расширений DB 0 ; +161: Максимальный размер DW #FFFF,#FFFF ; +165: Имя плагина DB "VGM Player v1.0 " ; +197: Тип вызова DB #00 ; По расширению ; +198-228: Резерв/меню DS 6 DS 24 DS 32 ; +260: Параметры INI DB 0 ; Нет параметров ORG #8000,#6200 ; Здесь начинается код плагина ```