/// <summary>
/// Абстрактный базовый класс для всех источников ввода в системе.
/// Определяет унифицированный интерфейс для работы с аппаратными кнопками и виртуальными действиями игроков.
/// </summary>
/// <remarks>
/// Наследники этого класса реализуют конкретные способы ввода:
/// - COMinput: работа с периферийной платой через COM-порт
/// - KeyboardInput: эмуляция ввода с клавиатуры для тестирования
/// 
/// Класс предоставляет три уровня абстракции:
/// 1. Низкоуровневый доступ к физическим пинам
/// 2. Доступ к абстрактным игровым действиям 
/// 3. Мультиплеерные методы для работы с несколькими игроками
/// </remarks>
public abstract class InputSource
{
    /// <summary>
    /// Инициализирует источник ввода. Должен быть вызван перед использованием других методов.
    /// </summary>
    /// <returns>true если инициализация прошла успешно, false в случае ошибки</returns>
    public abstract bool Initialize();

    //----------------------------------------------------------------------------------

    /// <summary>
    /// Получает текущее состояние конкретной кнопки по её физическому пину.
    /// </summary>
    /// <param name="button">Пин кнопки на периферийной плате</param>
    /// <returns>true если кнопка нажата в текущий момент</returns>
    public abstract bool GetButton(InSignal button);

    /// <summary>
    /// Проверяет, была ли кнопка нажата в начале текущего кадра.
    /// </summary>
    /// <param name="button">Пин кнопки на периферийной плате</param>
    /// <returns>true только в первом кадре после нажатия кнопки</returns>
    public abstract bool GetButtonDown(InSignal button);

    /// <summary>
    /// Проверяет, была ли кнопка отпущена в начале текущего кадра.
    /// </summary>
    /// <param name="button">Пин кнопки на периферийной плате</param>
    /// <returns>true только в первом кадре после отпускания кнопки</returns>
    public abstract bool GetButtonUp(InSignal button);

    //----------------------------------------------------------------------------------

    /// <summary>
    /// Получает состояние кнопки по числовому индексу пина.
    /// Перегрузка для работы с системами, где количество пинов превышает размер перечисления.
    /// </summary>
    /// <param name="pinIndex">Числовой индекс пина (0-based)</param>
    /// <returns>true если кнопка нажата в текущий момент</returns>
    public abstract bool GetButton(int pinIndex);

    /// <summary>
    /// Проверяет нажатие кнопки по числовому индексу пина в текущем кадре.
    /// </summary>
    /// <param name="pinIndex">Числовой индекс пина (0-based)</param>
    /// <returns>true только в первом кадре после нажатия</returns>
    public abstract bool GetButtonDown(int pinIndex);

    /// <summary>
    /// Проверяет отпускание кнопки по числовому индексу пина в текущем кадре.
    /// </summary>
    /// <param name="pinIndex">Числовой индекс пина (0-based)</param>
    /// <returns>true только в первом кадре после отпускания</returns>
    public abstract bool GetButtonUp(int pinIndex);

    //----------------------------------------------------------------------------------

    /// <summary>
    /// Получает состояние игрового действия для любого из игроков.
    /// Используется для мультиплеерных сценариев где важно действие любого игрока.
    /// </summary>
    /// <param name="button">Абстрактное игровое действие</param>
    /// <returns>true если действие активно у первого ИЛИ второго игрока</returns>
    public abstract bool GetButtonAnyPlayer(PlayerAction button);

    /// <summary>
    /// Проверяет начало игрового действия любым игроком в текущем кадре.
    /// </summary>
    /// <param name="button">Абстрактное игровое действие</param>
    /// <returns>true если действие начато любым игроком в этом кадре</returns>
    public abstract bool GetButtonDownAnyPlayer(PlayerAction button);

    /// <summary>
    /// Проверяет завершение игрового действия любым игроком в текущем кадре.
    /// </summary>
    /// <param name="button">Абстрактное игровое действие</param>
    /// <returns>true если действие завершено любым игроком в этом кадре</returns>
    public abstract bool GetButtonUpAnyPlayer(PlayerAction button);

    //----------------------------------------------------------------------------------

    /// <summary>
    /// Получает состояние игрового действия для текущего активного игрока.
    /// Используется для одиночной игры или поочередного управления.
    /// </summary>
    /// <param name="button">Абстрактное игровое действие</param>
    /// <returns>true если действие активно у текущего игрока</returns>
    public abstract bool GetButtonCurrentPlayer(PlayerAction button);

    /// <summary>
    /// Проверяет начало игрового действия текущим игроком в текущем кадре.
    /// </summary>
    /// <param name="button">Абстрактное игровое действие</param>
    /// <returns>true если действие начато текущим игроком в этом кадре</returns>
    public abstract bool GetButtonDownCurrentPlayer(PlayerAction button);

    /// <summary>
    /// Проверяет завершение игрового действия текущим игроком в текущем кадре.
    /// </summary>
    /// <param name="button">Абстрактное игровое действие</param>
    /// <returns>true если действие завершено текущим игроком в этом кадре</returns>
    public abstract bool GetButtonUpCurrentPlayer(PlayerAction button);

    public abstract bool AnyButton();
}