using System;

using Framework.Services;

namespace Framework.Input {

  /// <summary>Maps input from any number of devices to actions</summary>
  /// <remarks>
  ///   <para>
  ///     Actions need to be created through the <see cref="CreateAction" /> method
  ///     before they can be used. It is a good idea to assign default key bindings
  ///     at the start of your game (even if loading the player's settings overwrites
  ///     these bindings again) to ensure the game never ends up in a state where
  ///     the player has no usable controls.
  ///   </para>
  ///   <para>
  ///     Consider adding another layer between your code and the input mapper instead
  ///     of querying inputs directory in order to allow for unit testing with simulated
  ///     inputs. The <see cref="InputManager" /> can collect input and package it in
  ///     arbitrary state structures that you could mock in your tests.
  ///   </para>
  ///   <para>
  ///     Basic usage example:
  ///   </para>
  ///   <para>
  ///     <example>
  ///       <code>
  ///         IAction fireAction = this.myInputManager.CreateAction("Fire");
  ///         fireAction.BoundKeys.Add(KeyCode.Mouse0);
  ///         fireAction.BoundKeys.Add(KeyCode.Joystick1Button);
  ///
  ///         IAction forwardAction = this.myInputManager.CreateAction("Forward");
  ///         forwardAction.BoundKeys.Add(KeyCode.W);
  ///         forwardAction.BoundJoystickAxes.Add("Joystick1_Axis1");
  ///
  ///         if(fireAction.IsActive) {
  ///           fireWeapon();
  ///         }
  ///
  ///         transform.Translate(0.0f, 0.0f, forwardAction.State, Space.Self);
  ///       </code>
  ///     </example>
  ///   </para>
  /// </remarks>
  [
    ServiceScope(Scope.Global),
    DefaultBinding(typeof(InputMapper))
  ]
  public interface IInputMapper {

    /// <summary>Actions that have been set up for binding inputs</summary>
    IActionCollection Actions { get; }

    /// <summary>Creates a new input action ready for binding</summary>
    /// <param name="name">Name of the action that will be created</param>
    /// <returns>The newly created action</returns>
    /// <remarks>
    ///   If an action with the same name already exists, the existing action will
    ///   be returned.
    /// </remarks>
    IAction CreateAction(string name);

    /// <summary>Creates a new input action ready for binding</summary>
    /// <param name="name">Name of the action that will be created</param>
    /// <returns>The newly created action</returns>
    /// <remarks>
    ///   If an action with the same name already exists, the existing action will
    ///   be returned.
    /// </remarks>
    IAction CreateAction(string name, string description);

    /// <summary>Updates the states of all inputs in Unity if needed</summary>
    /// <remarks>
    ///   <para>
    ///     Writing an input manager that relies on Update() or FixedUpdate() always runs
    ///     the risk that it will update somewhere between other game objects (as the update
    ///     order is undefined). If the game object carrying the InputMapper ends up near
    ///     the beginning of the update queue, input will be fresh. If it's near the end
    ///     of the udpate queue, input will already be one frame old when it's checked.
    ///   </para>
    ///   <para>
    ///     To avoid any lag, you can call this method before processing any input to
    ///     ensure that the input update for the current frame is performed before querying
    ///     any inputs.
    ///   </para>
    /// </remarks>
    void UpdateIfNeeded();

  }

} // namespace Framework.Input