Часть 1: Что такое SjASMPlus и почему он?​

SjASMPlus — это современный, активно развиваемый кроссплатформенный ассемблер и менеджер проектов для процессора Z80 и совместимых. Он пришел на смену старому доброму SjASM.

Преимущества для спектрумиста:

  • Кроссплатформенность: Работает под Windows, Linux, macOS.
  • Мощный препроцессор: Поддерживает директивы #include, #define, #if, макросы, что делает код модульным и читаемым.
  • Управление памятью: Директивы MMU, PAGE, SLOT для работы с банковой памятью (например, для ZX Spectrum 128K/+2/+3).
  • Генерация современных форматов: Может создавать не только .TAP и .TZX, но и .TRD (дискеты), .SNA (снапшоты), .NEX (расширенный формат для ZX Spectrum Next).
  • Встроенный эмулятор (бета): Позволяет тестировать код без переключения между программами.
  • Интеграция: Легко встраивается в любую IDE или текстовый редактор.

Часть 2: Установка и базовая настройка​

Шаг 1: Скачивание
  1. Перейдите на официальный репозиторий: https://github.com/z00m128/sjasmplus
  2. В разделе Releases скачайте последнюю стабильную версию.
    • Для Windows: архив sjasmplus-win-x.y.z.zip. Извлеките sjasmplus.exe в удобную папку, например, C:\Dev\ZX\.
    • Для Linux/macOS: соберите из исходников (см. инструкцию в README) или найдите в пакетном менеджере (например, apt install sjasmplus в некоторых дистрибутивах).
Шаг 2: Проверка установки (Windows)

  1. Откройте командную строку (Win+R -> cmd).
  2. Перейдите в папку с sjasmplus.exe:
Bash: 
cd C:\Dev\ZX\

3. Выполните команду:
Bash: 
sjasmplus --version

  1. Если вы увидите версию ассемблера (например, v1.20.3), значит, всё установлено корректно.
Шаг 3: Настройка рабочего окружения (рекомендация)
Создайте структуру папок для проекта:
MySpectrumGame/
├── src/ # Исходные коды (.asm, .inc)
├── build/ # Собранные файлы (.tap, .bin)
├── assets/ Графика, музыка (конвертированные)
└── tools/ # Вспомогательные скрипты, утилиты
Нажмите, чтобы развернуть...

Часть 3: Первая программа — «Hello, Speccy!»​

Создайте в папке src файл hello.asm.
Assembler Z80: 
    ; ============================================
    ; hello.asm - Первая программа для SjASMPlus
    ; ============================================

    ; Устанавливаем начальный адрес загрузки для 48K Spectrum
    ; Программа будет располагаться с адреса 32768
    org 32768

    ; Точка входа программы
start:
    ; Очищаем экран
    call 0x0DAF   ; Используем стандартный ROM-процедуру CLS

    ; Выводим сообщение в центре экрана
    ld de, hello_string  ; DE = адрес строки
    ld bc, 0x020A        ; B = строка (2), C = столбец (10) - примерно центр
    call print_at

    ; Бесконечный цикл
loop:
    jr loop

; ----------------------------
; Подпрограмма печати строки
; Вход: DE - адрес строки, терминированной 0x80
;       B  - строка (0..23), C - столбец (0..31)
; ----------------------------
print_at:
    push bc
    ; Вычисляем адрес в экранной области
    ld a, b
    and 0x18
    add a, 0x40
    ld h, a
    ld a, b
    and 0x07
    rra
    rra
    rra
    add a, c
    ld l, a
    pop bc
    ; Выводим символы
print_loop:
    ld a, (de)
    or a
    ret z        ; Выход, если встретили 0
    and 0x7F     ; Убираем бит терминатора
    ld (hl), a   ; Кладем символ в видеобуфер
    inc de
    inc hl
    jr print_loop

; ----------------------------
; Данные программы
; ----------------------------
hello_string:
    db "Hello, ZX Spectrum!", 0

; Указываем точку входа для создания SNA-файла (опционально)
    ; savesna "build/hello.sna", start

; Директива для создания TAP-файла
    ; Она обернет наш бинарник в формат .TAP
    EMPTYTAP "build/hello.tap"
    ; Добавляем автостартующий блок с кодом
    SAVETAP "build/hello.tap", CODE, "hello", start, 32768
Шаг 4: Компиляция
В командной строке перейдите в папку проекта (MySpectrumGame) и выполните:
Bash: 
sjasmplus src/hello.asm --lst=build/hello.lst
  • src/hello.asm — путь к исходному файлу.
  • --lst=build/hello.lst — опционально, создаст листинг с адресами и кодом для отладки.
В папке build появится файл hello.tap.

Шаг 5: Запуск
Откройте эмулятор (например, UnrealSpeccy, Fuse, ZX-Poly) и загрузите файл hello.tap. Вы должны увидеть черный экран и надпись "Hello, ZX Spectrum!".

Часть 4: Продвинутые возможности и лучшие практики​

1. Использование препроцессора и инклудов
Разделяйте код на модули. Создайте файл macros.inc:
Assembler Z80: 
; macros.inc
MACRO WAIT_FRAMES frames
    ld b, frames
wait_loop:
    halt            ; Ждем прерывание (1/50 сек)
    djnz wait_loop
ENDM

MACRO SET_BORDER color
    ld a, color
    out (0xFE), a
ENDM
И используйте в основном файле:
Код: 
include "macros.inc"
    SET_BORDER 2   ; Красная бордюрка
    WAIT_FRAMES 50 ; Ждем 1 секунду
2. Работа с памятью 128K
Используйте директивы BANK и PAGE для переключения банков:
Assembler Z80: 
    ; Помещаем данные в банк 5 (обычно для данных)
    BANK 5
music_data:
    incbin "assets/music.pt3"
    ; Возвращаемся в банк 0 (основной)
    BANK 0
main:
    ; Переключаемся на банк 5
    ld bc, 0x7FFD
    ld a, 5
    out (c), a
    ; ... работаем с данными ...
3. Создание TRD-образа (для работы с дисковыми системами)
Код: 
    EMPTYTRD "build/game.trd"
    SAVETRD "build/game.trd", "MYGAME   C", start, 32768
4. Интеграция с Visual Studio Code (рекомендуется!)

  1. Установите расширение ASM Code Lens или Z80 Macro Assembler.
  2. Настройте задачу сборки (.vscode/tasks.json):
JSON: 
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build with SjASMPlus",
            "type": "shell",
            "command": "sjasmplus",
            "args": [
                "--color=on",
                "--lst=${workspaceFolder}/build/${fileBasenameNoExtension}.lst",
                "--sym=${workspaceFolder}/build/${fileBasenameNoExtension}.sym",
                "${file}",
                "--exp=${workspaceFolder}/build/${fileBasenameNoExtension}.exp"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "problemMatcher": []
        }
    ]
}
Теперь можно собирать проект клавишей Ctrl+Shift+B.

Часть 5: Частые ошибки и их решение​

  1. Error: unknown instruction
    • Проверьте регистры (нельзя ld bc, hl). Сверьтесь со справочником команд Z80.
  2. Программа в эмуляторе зависает или ведет себя странно
    • Используйте отладчик эмулятора (например, в UnrealSpeccy F11). Установите брейкпоинт на start и пройдитесь по шагам.
    • Проверьте, не затираете ли вы стек или важные области памяти.
  3. SjASMPlus не видит инклуд-файлы
    • Используйте абсолютные пути или укажите папку для поиска через опцию -I:
Bash: 
sjasmplus -I./src -I./assets src/main.asm
  1. Большой проект собирается медленно
    • Используйте --nologo и собирайте только измененные файлы через скрипты.

Часть 6: Полезные ссылки и следующий шаг​

  • Официальная документация: https://github.com/z00m128/sjasmplus/blob/master/docs/ — читайте обязательно!
  • Примеры проектов: Изучите исходники современных демок и игр на https://spectrumcomputing.co.uk/ или на ZX Modules.
  • Следующий шаг: Попробуйте собрать проект из нескольких файлов, подключить музыку в формате PT3 (используя AY-3-8910 эмулятор) и спрайты.
Для обсуждения на форуме предлагаю создать тему:
«[GUIDE] Современный стек разработки под ZX Spectrum: SjASMPlus + VS Code + Git»
В теме можно делиться своими конфигами, скриптами автоматизации, задавать вопросы по тонкой настройке и обсуждать best practices для больших проектов.

Удачи в программировании!
Уровень сложности
Средний
Язык программирования
Ассебмлер
Требования к памяти
48 К
Совместимость
Spectrun