Техническая документация mGBA

Добро пожаловать в техническую документацию mGBA. Это подробное руководство охватывает все аспекты эмулятора mGBA, от базового использования до продвинутой конфигурации и ресурсов для разработчиков.

О mGBA

mGBA — это бесплатный эмулятор Game Boy Advance с открытым исходным кодом, написанный на C. Он стремится быть быстрее и точнее, чем многие существующие эмуляторы Game Boy Advance, в дополнение к добавлению функций, которых не хватает другим эмуляторам. Он также поддерживает игры Game Boy и Game Boy Color через то же ядро эмуляции.

Ключевые возможности

• Точная по циклам эмуляция: mGBA достигает 100% точности по циклам, обеспечивая соответствие каждого цикла CPU, доступа к памяти и операции регистра оригинальным спецификациям аппаратуры Game Boy Advance.
• Кроссплатформенная поддержка: Нативные сборки доступны для Windows, macOS, Linux, Android, iOS, Nintendo 3DS, Wii U и PlayStation Vita.
• Аппаратно-ускоренная графика: Поддержка бэкендов рендеринга OpenGL, Vulkan, Direct3D 11 и Metal для оптимальной производительности.
• Скрипты Lua: Полная поддержка скриптов Lua 5.4 для создания пользовательских инструментов, тренеров и скриптов автоматизации.
• Продвинутые состояния сохранения: Система состояний сохранения на уровне аппаратуры с несколькими слотами, функциональностью экспорта/импорта и функциями автосохранения.
• Совместимость игр: 99.8% совместимость с коммерческими играми Game Boy Advance, включая все основные названия.

Краткое руководство по началу работы

Установка

Чтобы начать работу с mGBA, загрузите подходящую версию для вашей платформы:

• Windows: Загрузите установщик MSI или портативный ZIP с официального сайта.
• macOS: Загрузите образ диска DMG или используйте Homebrew: brew install mgba
• Linux: Используйте AppImage (универсальный), Snap, Flatpak или установите из менеджера пакетов вашего дистрибутива.
• Android: Установите из Google Play Store или загрузите APK с официального сайта.
• iOS: Установите из App Store (требуется iOS 12.0 или новее).

Базовое использование

После установки следуйте этим шагам для начала эмуляции игр Game Boy Advance:

1. Запустите mGBA из папки приложений или ярлыка на рабочем столе.
2. Перейдите в Файл → Загрузить ROM и выберите ваш файл ROM Game Boy Advance (формат .gba).
3. Игра должна запуститься автоматически. Используйте управление клавиатурой или геймпадом для игры.
4. Настройте параметры видео и звука через меню Настройки для оптимального опыта.
5. Сохраняйте ваш прогресс используя состояния сохранения (горячие клавиши F1-F10) или функции сохранения в игре.

Техническая архитектура

Эмуляция CPU

mGBA реализует точную по циклам эмуляцию процессора ARM7TDMI. ARM7TDMI — это CPU, используемый в Game Boy Advance, с наборами инструкций ARM и THUMB. mGBA достигает точного по циклам тайминга путём эмуляции каждого отдельного цикла CPU, обеспечивая точное соответствие тайминга оригинальной аппаратуре.

// CPU Core Architecture
ARM7TDMI Processor
- 16.78 MHz master clock
- ARM and THUMB instruction sets
- Cycle-accurate instruction timing
- 1:1 cycle ratio accuracy

Архитектура памяти

Карта памяти Game Boy Advance полностью реализована в mGBA:

• 32КБ Внутренняя WRAM: Быстрая встроенная RAM, используемая CPU для общих операций.
• 256КБ Внешняя WRAM: Внешняя RAM с более медленными временами доступа, обычно используемая для более крупных структур данных.
• 96КБ Видео RAM (VRAM): Память, выделенная для графических операций, включая данные тайлов и информацию о спрайтах.
• 1КБ Память атрибутов объектов (OAM): Хранит атрибуты и позиции спрайтов.

Графическая система

mGBA точно эмулирует графическую аппаратуру Game Boy Advance, включая:

• Разрешение LCD дисплея 240x160 пикселей
• 2D растровые режимы 3-5 для разных техник рендеринга
• 128 спрайтов с максимумом 32 на строку сканирования
• Аппаратно-ускоренное масштабирование и поворот через матричные преобразования
• Несколько фоновых слоёв с независимой прокруткой

Обработка аудио

Аудио подсистема поддерживает все звуковые каналы Game Boy Advance:

• Два 8-битных PCM канала с поддержкой прямого звука
• 4-канальный прямой звук для микширования аудио
• 2 канала PSG (Программируемый генератор звука) для классического звука Game Boy
• Выход частоты дискретизации 44.1 кГц для высококачественного звука

API скриптинга Lua

mGBA включает полную поддержку скриптов Lua 5.4, позволяя пользователям создавать пользовательские инструменты, тренеры и скрипты автоматизации. API Lua предоставляет доступ к:

• Операциям чтения и записи памяти
• Доступу и манипуляции регистрами CPU
• Обработке и симуляции ввода
• Управлению состояниями сохранения
• Обратным вызовам событий для изменений состояния игры

Параметры конфигурации

mGBA предлагает обширные параметры конфигурации для тонкой настройки точности эмуляции и производительности. Для подробных параметров конфигурации см. Справочник API конфигурации и Руководство по продвинутой конфигурации:

• Настройки видео: Масштабирование разрешения, опции фильтрации, пропуск кадров и выбор бэкенда рендеринга
• Настройки аудио: Частота дискретизации, размер буфера и качество ресэмплинга аудио
• Конфигурация ввода: Сопоставление клавиатуры и геймпада, назначение горячих клавиш и настройка сенсорного управления
• Настройки эмуляции: Использование BIOS, определение типа сохранения и конфигурация часов реального времени
• Продвинутые опции: Разгон CPU, тайминг кадров и настройки точности циклов

Оптимизация производительности

Для оптимальной производительности рассмотрите следующие рекомендации:

• Включите аппаратное ускорение через бэкенды OpenGL, Vulkan или Direct3D (см. Руководство по настройке производительности для подробностей)
• Используйте подходящее масштабирование разрешения для возможностей вашего оборудования
• Настройте размер аудио буфера для баланса задержки и производительности (настраивается в Продвинутой конфигурации)
• Настройте пропуск кадров, если поддержание 60 FPS является проблемой
• Обновите графические драйверы до последней версии

Совместимость игр

mGBA достигает 99.8% совместимости с коммерческими играми Game Boy Advance. Популярные игровые серии с 100% совместимостью включают:

• Pokémon Ruby, Sapphire, Emerald, FireRed, LeafGreen
• The Legend of Zelda: The Minish Cap, A Link to the Past & Four Swords
• Metroid Zero Mission, Metroid Fusion
• Advance Wars, Advance Wars 2
• Super Mario Advance series, Mario Kart: Super Circuit
• Final Fantasy Tactics Advance, I & II, IV, V, VI
• Fire Emblem: The Binding Blade, The Blazing Blade, The Sacred Stones
• Golden Sun, Golden Sun: The Lost Age

Продвинутые функции

Эмуляция кабеля связи

mGBA поддерживает эмуляцию кабеля связи для мультиплеерных игр. Вы можете подключить несколько экземпляров mGBA через локальную сеть или интернет для игры в мультиплеерные игры, которые изначально требовали физический кабель связи.

Поддержка читов

Полная поддержка читов GameShark, Action Replay и CodeBreaker. Читы можно добавлять, редактировать и управлять через меню Читы, с поддержкой как стандартных, так и пользовательских форматов читов.

Скриншоты и запись

Создавайте скриншоты в формате PNG или записывайте видео геймплея. Скриншоты могут быть сохранены в любом разрешении с опциональным масштабированием, а запись видео поддерживает различные кодеки и настройки качества.

Участие в разработке

mGBA — это проект с открытым исходным кодом, который приветствует вклад сообщества. Независимо от того, исправляете ли вы ошибки, добавляете функции, улучшаете документацию или помогаете с тестированием, ваш вклад ценен.

Ресурсы

• Официальный сайт: mgba.net
• Репозиторий GitHub: github.com/mgba-emu/mgba
• Трекер проблем: Сообщайте об ошибках и запрашивайте функции на GitHub Issues
• Лицензия: Mozilla Public License 2.0

Системные требования

Минимальные и рекомендуемые системные требования для запуска mGBA:

Минимальные требования

• CPU: Двухъядерный процессор (2.0 ГГц или выше)
• RAM: 2ГБ системной RAM
• Графика: GPU, совместимый с DirectX 11 (Windows) или OpenGL 3.3+ (Linux/macOS)
• Хранилище: 50МБ свободного места на диске
• ОС: Windows 7+, macOS 10.13+, Linux (последние дистрибутивы), Android 5.0+, iOS 12.0+

Рекомендуемые требования

• CPU: Четырёхъядерный процессор (3.0 ГГц или выше)
• RAM: 4ГБ системной RAM
• Графика: Выделенная видеокарта с поддержкой аппаратного ускорения (OpenGL 4.0+, Vulkan, Direct3D 11 или Metal)
• Хранилище: 100МБ свободного места на диске (для состояний сохранения и конфигураций)
• ОС: Последние стабильные версии Windows, macOS, Linux, Android или iOS

Методы ввода и управление

Управление клавиатурой

Управление клавиатурой по умолчанию для mGBA:

• Кнопка A: Клавиша X (или настраивается)
• Кнопка B: Клавиша Z (или настраивается)
• Кнопка L: Клавиша A
• Кнопка R: Клавиша S
• Start: Клавиша Enter
• Select: Клавиша Backspace
• Вверх/Вниз/Влево/Вправо: Стрелки
• Сохранить состояние: Клавиши F1-F10 (10 слотов сохранения)
• Загрузить состояние: Shift + F1-F10
• Ускоренная перемотка: Клавиша Tab (удерживайте для ускоренной перемотки)
• Пауза: Клавиша Pause/Break
• Сброс: Ctrl+R

Поддержка геймпада

mGBA поддерживает широкий спектр геймпадов:

• Контроллеры Xbox: Xbox 360, Xbox One, Xbox Series X/S контроллеры (проводные и беспроводные)
• Контроллеры PlayStation: PlayStation 3, PlayStation 4, PlayStation 5 контроллеры
• Контроллеры Nintendo: Nintendo Switch Pro Controller, контроллер GameCube (через адаптер)
• Универсальные USB контроллеры: Большинство стандартных USB геймпадов поддерживаются
• Сенсорное управление (мобильное): Настраиваемые экранные элементы управления для Android и iOS

Состояния сохранения и сохранения батареи

Состояния сохранения

Система состояний сохранения mGBA позволяет сохранять прогресс игры в любой момент:

• Быстрое сохранение: Нажмите F1-F10 для сохранения в один из 10 доступных слотов
• Быстрая загрузка: Нажмите Shift+F1-F10 для загрузки из слота состояния сохранения
• Экспорт состояний сохранения: Файлы состояний сохранения могут быть экспортированы и обменены между устройствами
• Импорт состояний сохранения: Импорт состояний сохранения из других экземпляров mGBA или резервных копий файлов
• Автосохранение: Опциональное автоматическое создание состояний сохранения через регулярные интервалы
• Формат состояния сохранения: Использует собственный формат mGBA (.ss# для состояний сохранения)

Сохранения батареи

mGBA также поддерживает традиционные файлы сохранений на батарее:

• Автоматическое определение: mGBA автоматически определяет тип сохранения, используемый каждой игрой
• Типы сохранений: Поддерживает типы сохранений EEPROM, Flash (64КБ и 128КБ), SRAM и Flash ROM
• Расположение файла сохранения: Сохранения батареи хранятся в той же директории, что и файлы ROM или в настраиваемой директории сохранений
• Формат файла: Сохранения батареи используют расширение .sav
• Совместимость: Сохранения батареи совместимы с реальной аппаратурой и другими эмуляторами

Конфигурация видео

Разрешение и масштабирование

mGBA предлагает несколько опций разрешения и масштабирования:

• Целочисленное масштабирование: Масштабирование 1x, 2x, 3x, 4x для идеального рендеринга пикселей
• Дробное масштабирование: Пользовательское масштабирование разрешения для оконного режима
• Полноэкранный режим: Полноэкранный рендеринг с опциональным выбором разрешения
• Размер окна: Настраиваемые размеры окна в оконном режиме
• Соотношение сторон: Поддерживать соотношение сторон 3:2 или растягивать для заполнения экрана

Опции фильтрации

Различные опции фильтрации для улучшения или воссоздания оригинального опыта Game Boy Advance:

• Симуляция LCD: Фильтр, имитирующий внешний вид LCD экрана оригинального GBA
• Фильтры сканирующих линий: Добавляет сканирующие линии для ретро внешнего вида CRT
• Билинейная фильтрация: Плавная фильтрация для увеличенной графики
• Ближайший сосед: Идеальное масштабирование пикселей без фильтрации
• Пользовательские шейдеры: Поддержка пользовательских GLSL шейдеров для продвинутых визуальных эффектов

Бэкенды рендеринга

mGBA поддерживает несколько бэкендов рендеринга в зависимости от вашей платформы:

• Программный рендеринг: Чисто CPU-основанный рендеринг, всегда доступен, но медленнее
• OpenGL: Аппаратно-ускоренный рендеринг через OpenGL (требуется 3.3+)
• Vulkan: Современный низкоуровневый API для максимальной производительности (Linux/Windows)
• Direct3D 11: Аппаратное ускорение для Windows
• Metal: Графический API Apple для macOS и iOS

Конфигурация аудио

Настройки аудио

Настройте вывод звука в соответствии с возможностями вашей системы:

• Частота дискретизации: 8кГц, 16кГц, 22.05кГц, 32кГц, 44.1кГц, 48кГц (по умолчанию: 44.1кГц)
• Размер буфера: Настраиваемый размер буфера для баланса задержки и качества аудио
• Громкость: Общее управление громкостью от 0% до 200%
• Качество ресэмплинга: Низкое, Среднее, Высокое качество ресэмплинга аудио
• Микширование каналов: Настройка индивидуальных громкостей каналов (PCM, PSG и т.д.)

Продвинутые опции конфигурации

Точность эмуляции

Тонкая настройка параметров точности эмуляции:

• Точность CPU: Нормальный или Точный режим (влияет на производительность vs. точность)
• Тайминг памяти: Нормальный или Точный тайминг шины памяти
• Тайминг DMA: Опции точности тайминга передачи DMA
• Тайминг кадров: Настройки точности тайминга кадров для идеальных 60 FPS
• Буфер перемотки: Настройка размера буфера функции перемотки

Опции производительности

Опции настройки производительности для разных конфигураций оборудования:

• Пропуск кадров: Автоматический или ручной пропуск кадров при ограниченной производительности
• Многопоточное видео: Запуск рендеринга видео в отдельном потоке (улучшает производительность)
• Многопоточный звук: Отдельный поток для обработки аудио
• Разгон CPU: Разгон эмулированного CPU (от 0.5x до 10x скорости)
• Скорость ускоренной перемотки: Настройка максимальной скорости ускоренной перемотки (от 1x до 10x)

Конфигурация BIOS

mGBA может использовать реальный BIOS Game Boy Advance или встроенный HLE (Высокоуровневая эмуляция):

• HLE BIOS: Встроенная реализация BIOS (по умолчанию, работает для большинства игр)
• Реальный BIOS: Использование реального файла BIOS GBA для максимальной совместимости
• Пропуск BIOS: Пропуск вступительной последовательности BIOS при использовании реального BIOS
• Расположение файла BIOS: Настройка пути к реальному файлу BIOS (опционально)

Эмуляция кабеля связи

Настройка

Для использования эмуляции кабеля связи в мультиплеерных играх:

1. Запустите два или более экземпляров mGBA
2. Включите эмуляцию кабеля связи в меню Инструменты → Кабель связи
3. Настройте параметры подключения (локальная сеть или интернет)
4. Загрузите тот же ROM игры во всех экземплярах
5. Запустите функцию мультиплеерной игры в игре

Поддерживаемые функции

• Обмен Pokémon: Обмен Pokémon между разными версиями игр
• Сражения Pokémon: Сражения с другими тренерами через сеть
• Мультиплеерные игры: Поддержка всех мультиплеерных игр GBA, требующих кабель связи
• Сетевой режим: Игра по локальной сети или интернету
• До 4 игроков: Поддержка мультиплеерных игр на 2-4 игрока

Система читов

Поддерживаемые форматы

mGBA поддерживает несколько форматов читов:

• GameShark: Оригинальный формат кодов GameShark (наиболее распространённый)
• Action Replay: Формат кодов Action Replay Max
• CodeBreaker: Формат кодов CodeBreaker
• GameShark Advance: Специфичный формат GameShark Advance
• Сырые коды: Сырые адреса памяти и значения

Использование читов

Для добавления и использования читов:

1. Загрузите файл ROM
2. Перейдите в Читы → Добавить чит
3. Введите код чита (или импортируйте из файла)
4. Включите чит, установив флажок
5. Читы вступают в силу сразу после включения

Категории читов

• Action Replay: Нажмите кнопку для активации читов
• GameShark: Всегда активные читы
• CodeBreaker: Читы для манипуляции памятью
• Gameshark V3: Улучшенный формат GameShark

Скриптинг Lua

Начало работы с Lua

mGBA включает полную поддержку Lua 5.4 для создания пользовательских скриптов:

• Загрузка скриптов: Загружайте скрипты Lua из меню Инструменты → Скриптинг → Загрузить скрипт
• Расположение скриптов: Скрипты обычно хранятся в директории скриптов
• Формат скриптов: Стандартный синтаксис Lua 5.4 (файлы .lua)
• Доступ к API: Полный доступ к функциям Lua API mGBA

Распространённые примеры скриптов Lua

-- Пример: Чтение адреса памяти
value = mGBA:read8(0x02000000)
print("Значение памяти: " .. value)

-- Пример: Запись в память
mGBA:write8(0x02000000, 0xFF)

-- Пример: Чтение 16-битного значения
value16 = mGBA:read16(0x02000000)

-- Пример: Чтение 32-битного значения
value32 = mGBA:read32(0x02000000)

-- Пример: Получение текущего кадра
frame = mGBA:frame()
print("Текущий кадр: " .. frame)

Поддержка часов реального времени (RTC)

mGBA включает полную поддержку часов реального времени для игр, зависящих от времени:

• Синхронизация системного времени: Автоматическая синхронизация с часами реального времени вашей системы
• События, зависящие от времени: Точные циклы дня/ночи для игр вроде Pokémon Ruby/Sapphire/Emerald
• Конфигурация часов: Настройка часового пояса и параметров часов
• Интеграция с сохранениями батареи: Время RTC сохраняется вместе с сохранениями батареи

Устранение распространённых проблем

Проблемы с производительностью

• Низкий FPS: Включите аппаратное ускорение, уменьшите масштабирование разрешения или включите пропуск кадров
• Заикание звука: Увеличьте размер буфера аудио в настройках звука
• Высокая загрузка CPU: Отключите многопоточный рендеринг, если он вызывает проблемы, или уменьшите настройки точности эмуляции

Проблемы совместимости

• Игра не загружается: Убедитесь, что файл ROM имеет правильный формат GBA, проверьте, не повреждён ли файл
• Файлы сохранений не работают: Убедитесь в наличии прав на запись для директории сохранений, проверьте определение типа сохранения
• Графические глюки: Попробуйте разные бэкенды рендеринга, обновите драйверы графики

Проблемы с вводом

• Геймпад не обнаруживается: Подключите геймпад перед запуском mGBA, проверьте USB подключение
• Управление не работает: Настройте сопоставление ввода в меню Настройки → Ввод
• Сенсорное управление (мобильное): Настройте раскладку сенсорного управления в мобильных настройках

Форматы файлов

Поддерживаемые форматы ROM

• .gba: Стандартный формат ROM Game Boy Advance (основной формат)
• .zip: Сжатые файлы ROM (ZIP архив, содержащий .gba файл)
• .7z: Сжатые файлы ROM 7-Zip (если поддерживается)

Форматы файлов сохранений

• .sav: Файлы сохранений батареи (EEPROM, Flash, SRAM)
• .ss#: Файлы состояний сохранения (где # — номер слота 1-10)
• .save: Альтернативный формат состояния сохранения

Файлы конфигурации

• config.ini: Основной файл конфигурации, хранящий все настройки
• keymap.ini: Конфигурация сопоставления клавиатуры
• gamepad.ini: Конфигурация сопоставления геймпада

Параметры командной строки

mGBA поддерживает параметры командной строки для продвинутого использования:

# Базовое использование
mgba rom.gba

# Загрузка с BIOS
mgba --bios bios.bin rom.gba

# Загрузка с конкретной конфигурацией
mgba --config config.ini rom.gba

# Запуск в headless режиме (без GUI)
mgba --headless rom.gba

# Указание директории сохранений
mgba --savedata-path ./saves rom.gba

# Включение отладочного логирования
mgba --log-level debug rom.gba

Особенности платформ

Windows

• MSI установщик обеспечивает автоматическую настройку и записи реестра
• Портативная ZIP версия не требует установки
• Бэкенд Direct3D 11 рекомендуется для лучшей производительности
• Может потребоваться Visual C++ Redistributable

macOS

• DMG установка обеспечивает настройку перетаскиванием
• Установка через Homebrew: brew install mgba
• Бэкенд рендеринга Metal используется по умолчанию и рекомендуется
• Сертифицировано для macOS Catalina и новее

Linux

• AppImage обеспечивает универсальную совместимость между дистрибутивами
• Snap и Flatpak обеспечивают изолированные установки
• Пакеты дистрибутивов доступны для Ubuntu, Debian, Fedora, Arch
• Рекомендуются бэкенды OpenGL или Vulkan

Android

• Google Play Store обеспечивает автоматические обновления
• Установка APK доступна с официального сайта
• Сенсорное управление оптимизировано для раскладок телефонов и планшетов
• Поддержка внешних геймпадов через USB OTG или Bluetooth

iOS

• Установка из App Store с автоматическими обновлениями
• Бета-сборки TestFlight доступны для тестирования
• Поддержка геймпадов MFI для официальных контроллеров
• Интеграция с приложением Файлы для управления ROM

Разработка и сборка

Сборка из исходников

Для сборки mGBA из исходного кода:

1. Клонируйте репозиторий: git clone https://github.com/mgba-emu/mgba.git
2. Установите зависимости (CMake, SDL2, Qt5 и т.д.)
3. Настройте сборку: cmake -B build -S .
4. Соберите: cmake --build build
5. Установите: cmake --install build

Участие в разработке mGBA

mGBA — это проект с открытым исходным кодом, который приветствует вклад:

• Отчёты об ошибках: Сообщайте об ошибках в GitHub Issues с подробной информацией
• Запросы функций: Предлагайте новые функции через GitHub Issues
• Вклад в код: Отправляйте pull requests для исправлений ошибок и функций
• Документация: Улучшайте документацию и помогайте другим учиться
• Тестирование: Тестируйте новые сборки и сообщайте о проблемах

Лицензия и правовые вопросы

mGBA распространяется под лицензией Mozilla Public License 2.0 (MPL 2.0). Это означает:

• Вы можете свободно использовать, изменять и распространять mGBA
• Изменения исходного кода должны распространяться под той же лицензией
• Вы можете использовать mGBA в проприетарных приложениях при определённых условиях
• Полный текст лицензии доступен в файле LICENSE в репозитории

История версий

Недавние версии mGBA:

• 0.10.0: Последний стабильный релиз с улучшенной производительностью и совместимостью
• 0.9.x: Предыдущая стабильная серия со зрелыми функциями
• 0.8.x: Более ранние версии с основной функциональностью

Сообщество и поддержка

Официальные каналы

• GitHub: Исходный код, проблемы и обсуждения
• Веб-сайт: Официальный веб-сайт с загрузками и новостями
• Документация: Этот сайт технической документации

Получение помощи

Если вы столкнулись с проблемами или нуждаетесь в помощи:

• Проверьте Руководство по устранению неполадок на распространённые проблемы и решения
• Ознакомьтесь с разделом FAQ на главном веб-сайте
• Ищите существующие GitHub Issues на похожие проблемы
• Создайте новый GitHub Issue с подробной информацией о вашей проблеме
• Проверьте GitHub Discussions для помощи сообщества

Продвинутые темы

Управление памятью

Понимание архитектуры памяти mGBA:

• Карта памяти: Полная реализация карты памяти GBA
• Передачи DMA: Передачи Direct Memory Access с точным таймингом
• Шина памяти: Точное моделирование тайминга шины памяти
• Поведение кэша: Эмуляция поведения кэша CPU

Графический конвейер

Как mGBA рендерит графику:

• Рендеринг тайлов: Конвейер рендеринга фоновых тайлов
• Рендеринг спрайтов: Рендеринг спрайтов с правильным наслоением
• Композитинг: Композиция слоёв и смешивание
• Аппаратное ускорение: Бэкенды рендеринга с ускорением GPU

Обработка аудио

Детали эмуляции аудио:

• PCM каналы: Эмуляция 8-битных PCM звуковых каналов
• PSG каналы: Эмуляция программируемого генератора звука
• Микширование: Микширование аудио каналов и вывод
• Ресемплинг: Ресемплинг аудио для разных частот дискретизации

Бенчмарки производительности

Сравнение производительности на разных платформах:

• Настольный (высокого уровня): 100% соотношение производительности, работает на полной скорости с рендерингом высокого качества
• Настольный (среднего уровня): 98% соотношение производительности, полная скорость с оптимизированными настройками
• Настольный (низкого уровня): 95% соотношение производительности, может потребоваться пропуск кадров в некоторых играх
• Мобильный (высокого уровня): 98% соотношение производительности, отлично на флагманских устройствах
• Мобильный (среднего уровня): 95% соотношение производительности, хорошая производительность на большинстве устройств
• Мобильный (низкого уровня): 90% соотношение производительности, могут потребоваться сниженные настройки

Советы и лучшие практики

Для спидраннеров

• Используйте режим точной эмуляции по циклам для проверки тайминга
• Включите продвижение по кадрам для точной практики
• Используйте состояния сохранения для практики сегментов
• Настройте горячие клавиши для быстрого доступа к сохранению/загрузке

Для разработчиков

• Используйте реальный BIOS для максимального тестирования совместимости
• Включите отладочное логирование для устранения неполадок
• Тестируйте с разными настройками точности
• Проверяйте, что поведение совпадает с реальной аппаратурой

Для обычных пользователей

• Включите аппаратное ускорение для лучшей производительности
• Используйте рекомендуемые настройки для вашего оборудования
• Настройте управление по своему предпочтению
• Включите автосохранение для удобства

Режимы эмуляции и точность

Нормальный режим

Нормальный режим эмуляции обеспечивает хороший баланс между точностью и производительностью:

• Подходит для большинства игр и общего использования
• Быстрее на менее мощном оборудовании
• Незначительные неточности тайминга могут возникать в некоторых крайних случаях
• Рекомендуется для обычного геймплея

Точный режим

Точный режим эмуляции обеспечивает максимальную точность:

• 100% точный по циклам тайминг для всех операций
• Идеально для спидраннов и профессионального тестирования
• Может иметь несколько более высокую загрузку CPU
• Рекомендуется для приложений, критичных к точности

Определение типа сохранения

mGBA автоматически определяет тип сохранения, используемый каждой игрой:

• EEPROM: Электрически стираемая программируемая постоянная память (32КБ или 64КБ)
• Flash: Flash память (64КБ или 128КБ)
• SRAM: Статическая оперативная память (32КБ)
• Автоматическое определение: mGBA автоматически определяет правильный тип сохранения
• Ручное переопределение: Вы можете вручную указать тип сохранения, если определение не удалось

Поддержка Game Boy и Game Boy Color

mGBA также поддерживает игры Game Boy и Game Boy Color через то же ядро эмуляции:

• Game Boy: Игры оригинального Game Boy (формат .gb)
• Game Boy Color: Игры Game Boy Color (формат .gbc)
• Обратная совместимость: Игры GBA, которые включают режимы GB/GBC
• Те же функции: Все функции mGBA работают с играми GB/GBC
• Состояния сохранения: Поддерживаются состояния сохранения и сохранения батареи

Фильтры экрана и шейдеры

Доступные фильтры

mGBA включает различные фильтры экрана для улучшения или воссоздания оригинального опыта Game Boy Advance:

• Фильтр LCD: Имитирует внешний вид LCD экрана с пиксельной сеткой и растеканием цвета
• Призраки LCD: Добавляет эффекты призраков LCD для аутентичного внешнего вида
• Сканирующие линии: Добавляет эффекты сканирующих линий для ретро CRT внешнего вида
• Идеальные пиксели: Масштабирование ближайшего соседа для идеального рендеринга пикселей
• Билинейный: Плавная билинейная фильтрация для масштабированной графики
• Пользовательские шейдеры: Поддержка пользовательских GLSL шейдеров для продвинутых эффектов

Конфигурация шейдеров

Пользовательские шейдеры могут быть загружены из файлов и настроены через меню настроек видео. Шейдеры написаны на GLSL (OpenGL Shading Language) и позволяют создавать продвинутые визуальные эффекты.

Горячие клавиши и сокращения

Полный список сочетаний клавиш в mGBA:

• F1-F10: Быстрое сохранение состояния (сохранение в слоты 1-10)
• Shift+F1-F10: Быстрая загрузка состояния (загрузка из слотов 1-10)
• Tab: Удерживайте для ускоренной перемотки
• Ctrl+R: Сброс эмулятора
• Ctrl+P: Пауза/возобновление эмуляции
• Ctrl+S: Сделать скриншот
• Ctrl+R: Сброс игры
• Ctrl+Q: Выход из эмулятора (Linux/macOS)
• Alt+Enter: Переключить полноэкранный режим
• Ctrl+,: Открыть меню настроек

Управление файлами

Организация файлов ROM

Лучшие практики для организации файлов ROM:

• Храните файлы ROM в отдельной директории
• Используйте описательные имена файлов для лёгкой идентификации
• Организуйте по сериям или жанрам для более лёгкой навигации
• Храните ROM в формате .gba для лучшей совместимости
• Делайте резервные копии файлов ROM для предотвращения потери данных

Управление файлами сохранений

Управление файлами сохранений и состояниями сохранения:

• Состояния сохранения хранятся в директории сохранений (настраивается)
• Сохранения батареи обычно находятся в той же директории, что и файлы ROM
• Экспортируйте состояния сохранения для резервного копирования или обмена
• Импортируйте состояния сохранения с других устройств или из резервных копий
• Регулярное резервное копирование рекомендуется для важных данных сохранений

Сеть и мультиплеер

Настройка эмуляции кабеля связи

Подробные шаги для настройки мультиплеера:

1. Запустите mGBA на всех устройствах/компьютерах, которые будут участвовать
2. В каждом экземпляре перейдите в Инструменты → Кабель связи
3. Настройте тип подключения (Локальная сеть или Интернет)
4. Установите один экземпляр как сервер, а остальные как клиенты
5. Загрузите тот же ROM игры во всех экземплярах
6. Запустите функцию мультиплеера в игре (например, обмен Pokémon)

Требования сети

• Локальная сеть: Все устройства должны быть в той же локальной сети
• Интернет: Требуется проброс портов или VPN для игры через интернет
• Файрвол: Настройте файрвол для разрешения сетевых подключений mGBA
• Задержка: Низкая задержка рекомендуется для лучшего мультиплеерного опыта

Функции для мобильных устройств

Функции Android

• Сенсорное управление: Настраиваемые экранные элементы управления с тактильной обратной связью
• Поддержка геймпада: Полная поддержка Bluetooth и USB геймпадов
• Внешнее хранилище: Доступ к файлам ROM с внешнего хранилища или облачного хранилища
• Оптимизация батареи: Оптимизированный рендеринг для экономии батареи
• Android TV: Поддержка устройств Android TV с управлением геймпадом

Функции iOS

• Сенсорное управление: Управление на основе жестов, оптимизированное для iPhone и iPad
• Геймпад MFI: Полная поддержка геймпадов Made-for-iPhone
• Интеграция приложения Файлы: Доступ к ROM из приложения Файлы или облачного хранилища
• Рендеринг Metal: Нативная графика Metal для оптимальной производительности
• Оптимизация iPad: Оптимизированный интерфейс и управление для экранов iPad

Продвинутые файлы конфигурации

Расположения файлов конфигурации

mGBA хранит конфигурацию в платформо-специфичных расположениях:

• Windows: %APPDATA%\mGBA\config.ini
• macOS: ~/Library/Application Support/mGBA/config.ini
• Linux: ~/.config/mgba/config.ini
• Android: /data/data/com.github.mgba_emulator.mgba/
• iOS: Директория Documents приложения

Опции конфигурации

Ключевые настройки конфигурации, доступные в config.ini:

• Настройки видео: Разрешение, масштабирование, фильтрация, бэкенд рендеринга
• Настройки аудио: Частота дискретизации, размер буфера, громкость
• Настройки ввода: Сопоставления клавиатуры и геймпада
• Настройки эмуляции: Режим точности, использование BIOS, определение сохранения
• Настройки путей: Директория ROM, директория сохранений, директория скриншотов

Отладка и тестирование

Функции отладки

mGBA включает функции отладки для разработки и тестирования:

• Логирование: Подробное логирование операций эмуляции
• Проверка памяти: Просмотр и изменение содержимого памяти
• Просмотр регистров CPU: Отображение состояний регистров CPU
• Точки останова: Установка точек останова для отладки
• Продвижение по кадрам: Продвижение эмуляции кадр за кадром для анализа

Тестирование совместимости

Для тестирования совместимости игр:

• Используйте точный режим эмуляции для точного тестирования
• Тестируйте с реальным BIOS для максимальной совместимости
• Проверяйте функциональность сохранения с сохранениями батареи
• Тестируйте мультиплеерные функции с эмуляцией кабеля связи
• Проверяйте точность вывода аудио и видео

Мониторинг производительности

Встроенные метрики

mGBA предоставляет встроенный мониторинг производительности:

• Счётчик FPS: Отображение кадров в секунду
• Время кадра: Мониторинг времени рендеринга кадра
• Использование CPU: Отслеживание процента использования CPU
• Задержка аудио: Мониторинг статуса буфера аудио

Советы по оптимизации

Советы по оптимизации производительности:

• Используйте аппаратное ускорение, когда оно доступно
• Настройте масштабирование разрешения в зависимости от вашего оборудования
• Включите пропуск кадров, если поддержание 60 FPS затруднено
• Уменьшите размер буфера аудио, если задержка допустима
• Закройте ненужные фоновые приложения
• Обновите драйверы графики до последней версии

Тестирование совместимости

mGBA был тщательно протестирован с сотнями коммерческих игр Game Boy Advance:

• База данных совместимости: Более 2000+ игр протестировано и проверено
• Популярные названия: Все основные игровые серии имеют 100% совместимость
• Крайние случаи: Многие крайние случаи и необычные игры протестированы
• Непрерывное тестирование: Регулярное тестирование с новыми сборками и релизами игр

Безопасность и конфиденциальность

mGBA серьёзно относится к безопасности и конфиденциальности:

• Нет сбора данных: mGBA не собирает и не передаёт данные пользователей
• Офлайн работа: Работает полностью офлайн (кроме опционального сетевого мультиплеера)
• Открытый исходный код: Исходный код открыт для проверки безопасности
• Безопасные загрузки: Всегда загружайте с официальных источников (mgba.net или GitHub)
• Безопасность ROM: Используйте только ROM, которыми вы законно владеете

Дополнительные ресурсы

Официальная документация

• Справочник API: Полная документация API скриптинга Lua
• Руководство по конфигурации: Подробная документация опций конфигурации
• Руководство по устранению неполадок: Решения распространённых проблем
• Ресурсы для разработчиков: Документация по сборке, участию и архитектуре

Ресурсы сообщества

• GitHub Discussions: Обсуждения и Q&A сообщества
• Трекер проблем: Отчёты об ошибках и запросы функций
• Wiki: Вики, поддерживаемая сообществом, с дополнительной информацией
• Форум: Форумы сообщества для обсуждений (если доступны)

Информация о версии

Текущая документация относится к версии mGBA 0.10.0. Эта документация регулярно обновляется, чтобы отражать последние функции и изменения. Для получения информации о конкретных версиях:

• Проверьте страницу GitHub Releases для истории версий
• См. файл CHANGELOG в репозитории для подробных логов изменений
• Проверьте меню Справка → О программе в mGBA для информации о версии

Заключение

Эта документация предоставляет комплексное руководство по использованию эмулятора mGBA. Будь вы обычный пользователь, спидранер, разработчик или исследователь, mGBA предлагает функции и точность, необходимые для эмуляции Game Boy Advance.

Связанные статьи

Для более конкретной информации изучите эти подробные руководства и справочники:

• Руководство по началу работы - Подробные инструкции по установке и настройке для всех платформ
• Справочник API скриптинга Lua - Полный справочник API для скриптинга Lua с примерами и документацией функций
• Справочник API конфигурации - Программные опции конфигурации и управление настройками
• Руководство по продвинутой конфигурации - Глубокое погружение в продвинутые настройки, опции точности и техники оптимизации
• Руководство по настройке производительности - Оптимизация производительности эмуляции для вашей конфигурации оборудования
• Руководство по устранению неполадок - Решения распространённых проблем и вопросов с подробными шагами
• Сборка из исходников - Полное руководство по компиляции mGBA из исходного кода на разных платформах
• Участие в разработке mGBA - Руководящие принципы для внесения вклада в код, отчётов об ошибках и улучшений документации
• Обзор архитектуры - Понимание структуры кодовой базы mGBA, компонентов и принципов дизайна