VGMPLAY.WMF/doc/02_Plugin_Header_Structure.md

Структура заголовка плагина (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 байт).

Пример:

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 байта каждое).

Важно: Расширения указываются ТОЛЬКО БОЛЬШИМИ БУКВАМИ!

Примеры:

DB "TXT"    ; Текстовые файлы
DB "MOD"    ; MOD музыка
DB "WAV"    ; WAV аудио
DB "MP3"    ; MP3 аудио
DB "VGM"    ; VGM музыка
; ... до 32 расширений
DS 27*3     ; Остальные заполняем нулями

Блок можно забить нулями, если не нужна инициация по расширениям.

Максимальный размер файла (+161, 4 байта)

Определяет максимальный размер файла, который плагин может обработать. Файлы больше этого размера плагину не передаются.

Примеры:

DW #FFFF,#FFFF  ; Без ограничений
DW #6000,#0000  ; Максимум 24КБ

Имя плагина (+165, 32 байта)

Текстовое имя плагина, которое показывается в меню.

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

DB "Edit  "   ; Для редактора
DB "Play  "   ; Для плеера

Текст для меню вьювера (+204, 24 байта)

Текст, который выводится в меню выбора вьювера (при типах #04/#05/#15):

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 опций.

Пример

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                      ; Конец списка параметров

Чтение параметров в плагине

// 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: 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) параметры записываются по длинному имени плагина:

[VGM Player v0.5]
opl_port=C4
freq=683

Пример полного заголовка

    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
; Здесь начинается код плагина