📘 Разработка для ZX Spectrum на Windows

📁 Структура папок

Вся работа будет происходить в C:\Dev\ZX\ (создайте эту папку). Такая структура обеспечивает переносимость между компьютерами без необходимости настраивать PATH.

🛠️ Установка инструментов

1. Visual Studio Code

• Скачайте с code.visualstudio.com
• Установите, обязательно отметьте галочку "Add to PATH"

2. Git для Windows

• Скачайте с git-scm.com
• Установите с настройками по умолчанию

3. SjASMPlus (ассемблер)

• Перейдите на страницу релизов
• Скачайте sjasmplus-windows-x86_64.zip
• Распакуйте sjasmplus.exe в C:\Dev\ZX\tools\sjasmplus\

4. Эмулятор CSpect (для отладки)

• Скачайте CSpect.exe с официального сайта
• Поместите в C:\Dev\ZX\tools\CSpect\
• Скачайте DeZogPlugin.dll с страницы релизов
• Положите DeZogPlugin.dll рядом с CSpect.exe
• Создайте папку RomFiles\ и поместите туда прошивки:
  • spectrum.rom (для 48K)
  • spectrum128.rom (для 128K)
  • disk.rom (для бета-дисковода)
  • tr-dos.rom (для TR-DOS)

5. Эмулятор Unreal Speccy (для быстрых тестов)

• Скачайте портативную версию с официального сайта
• Распакуйте UnrealSpeccy.exe в C:\Dev\ZX\tools\UnrealSpeccy\

🔌 Установка расширений VSCode

1. Запустите VSCode
2. Нажмите Ctrl+Shift+X
3. Установите:
   • Z80 Macro Assembler (mborland) — подсветка синтаксиса Z80/sjasmplus
   • DeZog (maziac) — отладчик с поддержкой CSpect и ZX Next
   • GitLens (опционально) — удобная работа с Git из VSCode
   • Git Graph (опционально) — визуализация веток

🆕 Создание проекта

1. Создайте папку: C:\Dev\ZX\projects\mygame\
2. Внутри создайте папки:
   • .vscode\ — для настроек редактора
   • src\ — для исходных кодов
   • build\ — для собранных файлов
3. Откройте папку mygame в VSCode: File → Open Folder...

⚙️ Настройка VSCode — tasks.json

Создайте файл .vscode/tasks.json с таким содержимым:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Clean Build Folder",
            "type": "shell",
            "command": "if not exist \"${workspaceFolder}\\build\" mkdir \"${workspaceFolder}\\build\" & if exist \"${workspaceFolder}\\build\\*.*\" del /Q \"${workspaceFolder}\\build\\*.*\"",
            "group": "none",
            "presentation": {
                "reveal": "silent",
                "clear": false
            }
        },
        {
            "label": "Build All",
            "type": "shell",
            "command": "${workspaceFolder}/../../tools/sjasmplus/sjasmplus.exe",
            "args": [
                "${workspaceFolder}/src/main.asm",
                "--syntax=abf",
                "--lst=${workspaceFolder}/build/listing.lst",
                "--sym=${workspaceFolder}/build/symbols.sym"
            ],
            "dependsOn": ["Clean Build Folder"],
            "dependsOrder": "sequence",
            "group": {
                "kind": "build",
                "isDefault": true
            },
            "problemMatcher": {
                "owner": "sjasmplus",
                "fileLocation": "relative",
                "pattern": {
                    "regexp": "^(.*?)\\(([0-9]+)\\): (.*?): (.*)$",
                    "file": 1,
                    "line": 2,
                    "severity": 3,
                    "message": 4
                }
            },
            "options": {
                "cwd": "${workspaceFolder}"
            }
        },
        {
            "label": "Run CSpect 48K",
            "type": "process",
            "command": "${workspaceFolder}/../../tools/CSpect/CSpect.exe",
            "args": [
                "-remote",
                "-brk",
                "-mmc=${workspaceFolder}/build",
                "${workspaceFolder}/build/test.sna"
            ],
            "dependsOn": ["Build All"],
            "dependsOrder": "sequence",
            "presentation": {
                "reveal": "never"
            },
            "problemMatcher": []
        },
        {
            "label": "Run CSpect 128K",
            "type": "process",
            "command": "${workspaceFolder}/../../tools/CSpect/CSpect.exe",
            "args": [
                "-remote",
                "-brk",
                "-128k",
                "-mmc=${workspaceFolder}/build",
                "${workspaceFolder}/build/test.sna"
            ],
            "dependsOn": ["Build All"],
            "dependsOrder": "sequence",
            "presentation": {
                "reveal": "never"
            },
            "problemMatcher": []
        },
        {
            "label": "Run CSpect Next",
            "type": "process",
            "command": "${workspaceFolder}/../../tools/CSpect/CSpect.exe",
            "args": [
                "-remote",
                "-brk",
                "-zxnext",
                "-nextrom",
                "-mmc=${workspaceFolder}/build",
                "${workspaceFolder}/build/test.nex"
            ],
            "dependsOn": ["Build All"],
            "dependsOrder": "sequence",
            "presentation": {
                "reveal": "never"
            },
            "problemMatcher": []
        },
        {
            "label": "Run Unreal Speccy",
            "type": "process",
            "command": "${workspaceFolder}/../../tools/UnrealSpeccy/UnrealSpeccy.exe",
            "args": [
                "\"${workspaceFolder}/build/test.sna\""
            ],
            "dependsOn": ["Build All"],
            "dependsOrder": "sequence",
            "presentation": {
                "reveal": "never"
            },
            "problemMatcher": []
        }
    ]
}

🐛 Настройка отладки — launch.json

Создайте файл .vscode/launch.json для поддержки отладки всех трёх моделей:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "dezog",
            "request": "launch",
            "name": "🎮 48K (CSpect)",
            "remoteType": "cspect",
            "preLaunchTask": "Run CSpect 48K",
            "load": "${workspaceFolder}/build/test.sna",
            "startAutomatically": true,
            "rootFolder": "${workspaceFolder}",
            "cspect": {
                "pathToCSpectExe": "${workspaceFolder}/../../tools/CSpect/CSpect.exe",
                "instance": "0"
            },
            "sjasmplus": [
                {
                    "path": "${workspaceFolder}/build/symbols.sym",
                    "srcDirs": ["${workspaceFolder}/src"]
                }
            ]
        },
        {
            "type": "dezog",
            "request": "launch",
            "name": "🎵 128K (CSpect)",
            "remoteType": "cspect",
            "preLaunchTask": "Run CSpect 128K",
            "load": "${workspaceFolder}/build/test.sna",
            "startAutomatically": true,
            "rootFolder": "${workspaceFolder}",
            "cspect": {
                "pathToCSpectExe": "${workspaceFolder}/../../tools/CSpect/CSpect.exe",
                "instance": "0"
            },
            "sjasmplus": [
                {
                    "path": "${workspaceFolder}/build/symbols.sym",
                    "srcDirs": ["${workspaceFolder}/src"]
                }
            ]
        },
        {
            "type": "dezog",
            "request": "launch",
            "name": "⚡ ZX Next (CSpect)",
            "remoteType": "cspect",
            "preLaunchTask": "Run CSpect Next",
            "load": "${workspaceFolder}/build/test.nex",
            "startAutomatically": true,
            "rootFolder": "${workspaceFolder}",
            "cspect": {
                "pathToCSpectExe": "${workspaceFolder}/../../tools/CSpect/CSpect.exe",
                "instance": "0"
            },
            "sjasmplus": [
                {
                    "path": "${workspaceFolder}/build/symbols.sym",
                    "srcDirs": ["${workspaceFolder}/src"]
                }
            ]
        },
        {
            "type": "dezog",
            "request": "launch",
            "name": "🖥️ ZX Next (Serial/Real HW)",
            "remoteType": "zxnext",
            "zxnext": {
                "serial": "COM3"
            },
            "load": "${workspaceFolder}/build/test.nex",
            "startAutomatically": true,
            "rootFolder": "${workspaceFolder}",
            "sjasmplus": [
                {
                    "path": "${workspaceFolder}/build/symbols.sym",
                    "srcDirs": ["${workspaceFolder}/src"]
                }
            ]
        }
    ]
}

📝 Код программы — src/main.asm

Универсальный шаблон с поддержкой всех форматов и моделей:

; ============================================================
;   Универсальный проект для ZX Spectrum
;   Поддерживает: 48K, 128K, Next
;   Форматы: SNA, TAP, TRD, NEX
; ============================================================

    ; Раскомментируйте нужную строку для целевой модели:
    device ZXSPECTRUM48      ; для 48K и 128K
    ; device ZXSPECTRUM128   ; для 128K с банками
    ; device ZXSPECTRUMNEXT  ; для ZX Spectrum Next

    org $8000

Start:
    di
    ld sp, $FF00
    
    ; Очищаем экран
    call Cls
    
    ; Бесконечный цикл
    jr $

; ------------------------------------------------------------
;  Очистка экрана
; ------------------------------------------------------------
Cls:
    ld hl, $4000
    ld de, $4001
    ld bc, $1800
    ld (hl), 0
    ldir
    
    ld hl, $5800
    ld de, $5801
    ld bc, $0300
    ld (hl), $47
    ldir
    ret

; ------------------------------------------------------------
;  Конец программы — выбор форматов
; ------------------------------------------------------------
EndOfProgram:

    ; === Для 48K/128K ===
    savesna "build/test.sna", Start           ; Быстрое тестирование
    ; savetap "build/test.tap", Start, EndOfProgram-Start   ; Лента
    ; emptytrd "build/test.trd", "MYGAME"    ; Диск TR-DOS
    ; savetrd "build/test.trd", "CODE", Start, EndOfProgram-Start, "TEST.BIN"

    ; === Для ZX Spectrum Next ===
    ; savenex open "build/test.nex", 0
    ; savenex auto
    ; savenex entry Start
    ; savenex close

🎯 Форматы сборки

SjASMPlus поддерживает несколько форматов выходных файлов для ZX Spectrum:

Формат	Директива	Для чего	Скорость загрузки
SNA	SAVESNA	Быстрое тестирование и отладка	⚡ Мгновенно
TAP	SAVETAP	Релиз на ленте	🎵 Реалистичная
TRD	SAVETRD / EMPTYTRD	Релиз на дискете (TR-DOS)	⚡ Мгновенно
NEX	SAVENEX	ZX Spectrum Next	⚡ Мгновенно

🎮 ZX Spectrum Next

📦 Формат NEX

Официальный формат программ для Next. Поддерживает:

• Несколько банков памяти (до 1.75 МБ)
• Экран загрузки (Layer2, ULA, LoRes, Timex)
• Палитры и эффекты загрузки
• Установку точки входа и стека

Пример кода для Next

    DEVICE ZXSPECTRUMNEXT
    
    ; Настройка банков памяти
    MMU 6, 0        ; слот 6 ($C000) -> страница 0
    ORG $C000
    
Start:
    di
    ld sp, $FF00
    call Cls
    jr $

Cls:
    ld hl, $4000
    ld de, $4001
    ld bc, $1800
    ld (hl), 0
    ldir
    ret

    SAVENEX OPEN "build/demo.nex", 0
    SAVENEX AUTO
    SAVENEX SCREEN ULA, $4000, 6912
    SAVENEX ENTRY Start
    SAVENEX CLOSE

🚀 Запуск и отладка

Способ 1: Быстрый запуск в Unreal Speccy

Первый раз (настройка быстрой загрузки):

1. Соберите проект: Ctrl+Shift+B
2. Откройте UnrealSpeccy.exe
3. Нажмите F3, выберите build/test.sna
4. Нажмите Alt+F2 — сохраните в qsave1.sna

После каждого изменения:

1. Ctrl+Shift+B (сборка)
2. Переключитесь в Unreal Speccy
3. Alt+F3 — мгновенная загрузка

Способ 2: Отладка в CSpect (48K / 128K / Next)

1. Убедитесь, что DeZogPlugin.dll лежит рядом с CSpect.exe
2. В VSCode: Ctrl+Shift+D
3. Выберите нужную конфигурацию в выпадающем меню:
   • 🎮 48K (CSpect) — для классических программ
   • 🎵 128K (CSpect) — для AY-музыки и банков
   • ⚡ ZX Next (CSpect) — для Next в эмуляторе
   • 🖥️ ZX Next (Serial/Real HW) — для отладки на реальном устройстве
4. Нажмите F5

📦 GitHub и .gitignore

Файл .gitignore в корне проекта:

# Собранные файлы
build/*.sna
build/*.tap
build/*.trd
build/*.nex
build/*.bin
build/*.lst
build/*.sym

# Настройки VSCode (опционально)
# .vscode/

# Системный мусор
.DS_Store
Thumbs.db
*.tmp
*.log

Пример README.md для репозитория:

# MyGame for ZX Spectrum

## Совместимость
- ✅ ZX Spectrum 48K
- ✅ ZX Spectrum 128K
- ✅ ZX Spectrum Next

## Сборка
1. Установите SjASMPlus, CSpect, Unreal Speccy
2. Откройте проект в VSCode
3. Нажмите Ctrl+Shift+B

## Отладка
- 48K: "🎮 48K (CSpect)" → F5
- 128K: "🎵 128K (CSpect)" → F5
- Next: "⚡ ZX Next (CSpect)" → F5

## Форматы
- `.sna` — для разработки
- `.tap` — для ленты
- `.trd` — для tr-dos
- `.nex` — для Next

🐙 GitHub и работа с Git

📦 Первоначальная настройка Git

Выполните один раз после установки Git:

🚀 Публикация проекта на GitHub (пошагово)

Шаг 1: Инициализация репозитория в папке проекта

Шаг 2: Добавление всех файлов в Git

Шаг 3: Создание первого коммита

Шаг 4: Создание репозитория на GitHub

• Зайдите на github.com
• Нажмите зелёную кнопку "New repository"
• Название: mygame (как папка проекта)
• Описание: My ZX Spectrum game
• Оставьте репозиторий Public или выберите Private
• НЕ создавайте README, .gitignore или лицензию — они уже есть в проекте
• Нажмите "Create repository"

Шаг 5: Связывание локального репозитория с GitHub

🔄 Повседневные команды Git

Команда	Что делает
git status	Показывает изменённые файлы
git add src/main.asm	Добавляет конкретный файл
git add .	Добавляет все изменённые файлы
git commit -m "Описание"	Создаёт коммит
git push	Отправляет коммиты на GitHub
git pull	Забирает изменения с GitHub
git log --oneline	Показывает историю коммитов
git diff	Показывает изменения в файлах

🔀 Продвинутые команды Git: ветки, merge, конфликты, теги

🌿 Работа с ветками (branches)

Ветки позволяют разрабатывать новые функции изолированно от основного кода.

Основные команды для веток

Команда	Что делает
git branch	Показывает список веток (* — текущая ветка)
git branch new-feature	Создаёт новую ветку с именем new-feature
git checkout new-feature	Переключается на ветку new-feature
git checkout -b new-feature	Создаёт и сразу переключается на новую ветку
git branch -d new-feature	Удаляет ветку new-feature

🔗 Слияние веток (merge)

Когда функция готова, нужно влить её обратно в основную ветку (main).

Пошаговый процесс merge

⚠️ Разрешение конфликтов (conflicts)

Конфликт возникает, когда две ветки меняют одни и те же строки кода. Git не может автоматически выбрать правильный вариант.

Как разрешить конфликт:

1. Откройте файл с конфликтом — увидите маркеры:

<<<<<<< HEAD
    ld a, 10        # ваш код в main
=======
    ld a, 20        # код из ветки feature
>>>>>>> feature/sprite

2. Отредактируйте файл, оставив нужный код (или объединив оба варианта).
3. Удалите маркеры <<<<<<<, =======, >>>>>>>.
4. Сохраните файл.
5. Добавьте исправленный файл в Git:

🏷️ Теги (tags) — создание версий релиза

Теги фиксируют состояние кода в определённый момент (например, версия 1.0).

Основные команды для тегов

Команда	Что делает
git tag	Показывает список тегов
git tag v1.0.0	Создаёт лёгкий тег (lightweight)
git tag -a v1.0.0 -m "First release"	Создаёт аннотированный тег с сообщением
git push origin v1.0.0	Отправляет тег на GitHub
git push --tags	Отправляет все теги на GitHub
git tag -d v1.0.0	Удаляет тег локально

📥 Клонирование чужого проекта

📤 Pull Request (PR) — предложение изменений

Если вы хотите внести изменения в чужой проект (форк), алгоритм такой:

1. Сделайте Fork репозитория на GitHub (кнопка "Fork").
2. Склонируйте форк к себе: git clone https://github.com/ВАШ_ЛОГИН/project.git
3. Создайте ветку: git checkout -b my-fix
4. Внесите изменения, сделайте коммит и пуш: git push origin my-fix
5. На GitHub нажмите "Compare & pull request" → создайте PR.
6. Дождитесь, пока автор проекта примет или отклонит изменения.

📋 Полезные команды для работы с удалённым репозиторием

Команда	Что делает
git remote -v	Показывает список удалённых репозиториев
git remote add upstream URL	Добавляет оригинальный репозиторий как upstream
git fetch upstream	Забирает изменения из upstream
git merge upstream/main	Сливает изменения из upstream в свою ветку

🎯 Типичный рабочий цикл с ветками

⌨️ Быстрые команды

VSCode и сборка

Действие	Команда
Собрать проект	Ctrl+Shift+B
Открыть терминал	Ctrl+`
Перейти к отладке	Ctrl+Shift+D
Запустить отладку	F5 (с выбранной конфигурацией)
Установить брейкпоинт	F9 (на строке кода)
Шаг с обходом	F10
Шаг с заходом	F11

Git (базовые)

КомандаДействие git statusУзнать состояние git add .Добавить все изменения git commit -m "msg"Создать коммит git pushОтправить на GitHub git pullЗабрать с GitHub git log --onelineИстория коммитов

Git (продвинутые)

Команда	Действие
git branch	Список веток
git checkout -b new	Создать и переключиться на ветку new
git merge branch	Слить ветку branch в текущую
git tag v1.0.0	Создать тег v1.0.0
git push --tags	Отправить все теги на GitHub
git clone URL	Склонировать репозиторий

В Unreal Speccy:

Горячая клавиша	Действие
Alt+F3	Быстрая загрузка
Alt+F2	Быстрое сохранение

🐛 Устранение проблем

Проблема	Решение
sjasmplus.exe not found	Проверьте путь в tasks.json. Убедитесь, что папка tools на два уровня выше проекта.
CSpect.exe not found	Аналогично — проверьте количество ../.
DeZogPlugin.dll not found	Положите файл рядом с CSpect.exe.
CSpect запускается, но не подключается	Убедитесь, что в аргументах есть -remote. Закройте CSpect вручную, нажмите F5 заново.
Ошибка "Cannot find ROM files"	Создайте папку RomFiles\ рядом с CSpect.exe и положите туда прошивки.
SAVETRD не работает	Обновите sjasmplus до версии 1.15.0 или выше.
Ошибки при сборке .nex	Добавьте DEVICE ZXSPECTRUMNEXT в начало файла. Заполните банки через MMU.
git не распознаётся	Переустановите Git для Windows, отметьте "Add to PATH". Перезагрузите компьютер.
Ошибка при push: "failed to push"	Сначала сделайте git pull --rebase, потом git push.
Merge conflict	Отредактируйте файл с маркерами <<<<<<<, сделайте git add и git commit.
Как удалить файл из Git?	git rm --cached файл.asm (оставить локально) или git rm файл.asm (удалить везде).
Как отменить последний коммит?	git reset --soft HEAD~1 (оставить изменения) или git reset --hard HEAD~1 (удалить изменения).

---