Сборщик образов игр *.alf для приставки "Эльф"
(C) Prusak, https://zxbyte.ru
---------------------------------------------------

Сборщик представляет собой несколько скриптов на языке Python и позволяет собрать образ игры *.alf из отдельных кодовых блоков.

Системные требования: требуется Python (проверялось на версии 3.10).

Вводные данные: допустим, вы адаптировали игру для приставки "Эльф" (переделали её управление) и теперь хотите проверить её работу в эмуляторе (или на "железной" приставке). Первым этапом нужно собрать все файлы игры и их загрузчик в один моноблок (файл с расширением *.alf). Второй этап - из этого моноблока собрираем образ картриджа (это отдельный процесс, который описан в файле "help Сборка образа картриджа.txt").

Сборка образа (моноблока игры) состоит из трёх этапов:
1) Написание и компиляция загрузчика
2) Написание и перекодировка в формат приставки "Эльф" описания игры
3) Сборка загрузчика, описания и файлов игры в один моноблок.

Проще всего посмотреть на готовом примере - игра Bruce Lee в папке games/Bruce_Lee.
Для автоматизации процесса все этапы сборки собраны в один bat-файл: _createGame.bat

..\..\sjasmplus loader.asm --raw=loader.cod
python ..\..\descriptionBuilder.py opis.cod opis.txt 
python ..\..\AlfBuilder.py BruceLee.alf BruceLee.ini

Первая строка - компиляция загрузчика при помощи ассемблера sjasmplus;
Вторая строка - перекодировка описания игры в формат приставки "Эльф"
Третья строка - непосредственно сборка моноблока BruceLee.alf из полученных файлов.

Пройдёмся более подробно по этапам сборки.

-------------------
Загрузчик игры

Находится в файле loader.asm. Файл должным образом закомментирован, поэтому понять как он работает, будет несложно. Мало того, в папке Games есть уже готовый шаблон загрузчика, который можно взять и просто немного откорректировать под свои нужды.

Перед тем, как заняться написанием загрузчика нужно определиться из каких файлов у нас будет состоять игра. Для этого создаём (или корректируем готовый) ini-файл:

#---- ini-файл -----
# Первый файл - всегда описание игры
OPIS.COD
# Второй файл - всегда загрузчик
LOADER.COD
# Дальше располагаются кодовые блоки игры
SCR.COD
MAIN.COD
#---- конец ini-файла ----

В ini-файле просто указывается список файлов игры. Допускаются строки с комментариями, начинающиеся с символа "#".
Первый файл - это всегда файл описания игры (как его готовить, см. ниже по тексту).
Второй файл - это всегда скопилированный файл загрузчика игры. Как он делается, я как раз рассказываю сейчас.
А дальше просто перечисляем файлы игры, которые в процессе загрузки надо будет поместить в память. Как видим, у нас 2 файла - заставка (scr.cod) и основной кодовый блок игры (main.cod)


В общих чертах  - в загрузчике указываем сколько файлов игры у нас есть. Пусть у нас будет два файла - заставка и основной кодовой блок игры (сам файл загрузчика и описание игры не входят в это число):
FILES  EQU 2
В начале загрузчика формируется каталог файлов, из которых состоит игра, поэтому для правильного расчёта его размера надо указать число файлов.

Загружаем заставку (это необязательно, но красиво):
       LD A,1          ;Номер файла с заставкой игры (из ini-файла)
       LD DE,#4000     ;Грузим в экранную область
       LD HL,TABLE     ;Адрес таблицы файлов игры
       CALL LDBLK      ;Вызов подпрограммы, которая загружает файл с указанным номером в память

Загружаем основной кодовый блок игры
       LD A,2          ;Номер файла с основным кодовым блоком игры (из ini-файла)
       LD DE,#8000     ;Грузим в память
       LD HL,TABLE     ;Адрес таблицы файлов игры
       CALL LDBLK      ;Вызов подпрограммы, которая загружает файл с указанным номером в память

       JP #8000        ;Запускаем игру


Загрузчик компилируется следующей строкой в bat-файле:

..\..\sjasmplus loader.asm --raw=loader.cod

Компиляция идёт из файла loader.asm в файл loader.cod.
В процессе компиляции могут быть ошибки, поэтому внимательно смотрите на текст в окне командной строки при выполнении bat-файла!

--------------------
Описание игры

Для каждой игры должно быть её описание. Это тот текст, который появляется при выборе игры в меню приставки. Вам нужно просто создать текстовый файл в кодировке UTF-8, что-нибудь в нём написать и сохранить в файл opis.txt (вы можете выбрать любое другое имя файла, только в этом случае придётся скорректировать bat-файл, в котором конвертируется описание игры).

Перекодировка текстового файла с описанием игры осуществляется следующей строчкой в bat-файле:
python ..\..\descriptionBuilder.py opis.cod opis.txt 

где opis.txt - входной текстовый файл, который вы сейчас создали;
    opis.cod - выходной файл в кодировке приставки "Эльф", куда помещается скорвертированный текст описания. В дальнейшем этот файл мы указываем в ini-файле игры.

Требования к входному текстовому файлу:
- кодировка UTF-8 с BOM;
- для правильного форматирования текста желательно, чтобы строки были выровнены по правой границе 28 символов, чтобы текст "красиво" попадал в экран приставки "Эльф";
- строки, начинающиеся с символа ";" считаются комментариями и не обрабатываются;

Выходной файл opis.cod не может быть длиной больше чем #02F4 байта, поэтому все "лишние" символы обрезаются при перекодировке.


------------------
Окончательная сборка моноблока игры

Итак, у нас есть скомпилированный файл загрузчика (loader.cod) и файл описания игры (opis.cod).
Финальным этапом из всех файлов собирается моноблок с игрой. Это делается следующей строкой в bat-файле:

python ..\..\AlfBuilder.py BruceLee.alf BruceLee.ini

Где BruceLee.alf - выходной файл с игрой
BruceLee.ini - тут указаны все входящие в игру файлы (его описание смотри выше по тексту).

После отработки скрипта, если не было никаких ошибок, вы получите *.alf файл, который пригоден для создания из него образа картриджа. Как это сделать, вы можете прочитать в файле "help Сборка образа картриджа.txt"

В дальнейшем созданный образ картриджа можно либо использовать в эмуляторе приставки "Эльф", либо "прошить" в микросхему ПЗУ/Flash для изготовления картриджа.
