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

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

Начало работы со скриптами Lua

Загрузка скриптов

Чтобы загрузить скрипт Lua в mGBA:

1. Перейдите в Инструменты → Скрипты → Загрузить скрипт
2. Перейдите к файлу скрипта Lua (формат .lua)
3. Выберите файл скрипта и нажмите Открыть
4. Скрипт будет загружен и выполнен автоматически

Функции доступа к памяти

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

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

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

-- Пример: Запись 8-битного значения
mGBA:write8(0x02000000, 0xFF)

Функции CPU и регистров

-- Пример: Получение значения PC (счётчика команд)
pc = mGBA:getRegister("pc")
print("Счётчик команд: " .. string.format("0x%08X", pc))

Функции кадров и времени

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

-- Пример: Сброс эмулятора
mGBA:reset()

Функции сохранений

Функции ввода

-- Пример: Нажатие кнопки A
mGBA:pressButton("A")

Обратные вызовы событий

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

-- Пример: Обратный вызов кадра
function onFrame()
    -- Эта функция вызывается каждый кадр
    local frame = mGBA:frame()
    if frame % 60 == 0 then
        print("Кадр: " .. frame)
    end
end

-- Регистрация обратного вызова
mGBA:onFrame(onFrame)

Примеры распространённых скриптов

Тренер здоровья

-- Пример тренера здоровья
local healthAddress = 0x02000000  -- Замените на реальный адрес

function infiniteHealth()
    mGBA:write16(healthAddress, 999)
end

-- Выполнять каждый кадр
mGBA:onFrame(infiniteHealth)

Счётчик кадров

-- Скрипт счётчика кадров
local startFrame = mGBA:frame()

function countFrames()
    local current = mGBA:frame()
    local elapsed = current - startFrame
    print("Прошедших кадров: " .. elapsed)
end

mGBA:onFrame(countFrames)

Адреса памяти

Распространённые адреса памяти для игр Game Boy Advance:

• Внутренняя WRAM: 0x03000000 - 0x03007FFF (32KB)
• Внешняя WRAM: 0x02000000 - 0x0203FFFF (256KB)
• Видео RAM: 0x06000000 - 0x06017FFF (96KB)
• ROM картриджа: 0x08000000 - 0x0DFFFFFF (зависит от игры)
• SRAM картриджа: 0x0E000000 - 0x0E00FFFF (зависит от игры)

Рекомендации

• Всегда проверяйте адреса памяти перед чтением/записью
• Используйте подходящие типы данных (8-битные, 16-битные, 32-битные) для операций с памятью
• Будьте осторожны с обратными вызовами кадров, чтобы избежать проблем с производительностью
• Тщательно тестируйте скрипты перед использованием в важном геймплее
• Создавайте резервные копии файлов сохранений перед использованием скриптов, изменяющих состояние игры

Ограничения

• Скрипты Lua выполняются в основном потоке эмулятора (может влиять на производительность)
• Некоторые операции могут быть недоступны в зависимости от состояния эмулятора
• Адреса памяти могут изменяться между версиями или регионами игры

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

Для получения дополнительной информации о конфигурации и разработке mGBA:

• Справочник API конфигурации - Параметры программной конфигурации и управление настройками
• Руководство по продвинутой конфигурации - Подробное описание продвинутых настроек и техник оптимизации
• Обзор архитектуры - Понимание структуры кодовой базы mGBA и принципов проектирования
• Руководство для начинающих - Инструкции по установке и базовой настройке