using System;

using UnityEngine;

namespace Framework.Actors {

  /// <summary>Component allowing the player to control where an actor is looking</summary>
  /// <remarks>
  ///   <para>
  ///     There typically are multiple components implementing this interface present on
  ///     an actor, supporting different input profiles (i.e. the look direction in VR is
  ///     controlled by a different component than look direction using the mouse).
  ///   </para>
  ///   <para>
  ///     The actor itself will usually make use of the <see cref="HeadControllerCombiner" />
  ///     component to route calls to the currently active head controller.
  ///   </para>
  ///   <para>
  ///     Head controllers can store and manage the head orientation on their own terms
  ///     (for example, as pitch and yaw if that covers their needs). When the
  ///     <see cref="HeadControllerCombiner" /> notices a switch to another head controller,
  ///     it will transfer the local head orientation from the old to the new controller.
  ///   </para>
  /// </remarks>
  public interface IHeadController {

    /// <summary>Fired to pass on head rotation that was clamped</summary>
    /// <remarks>
    ///   <para>
    ///     When the player rotates the character's head beyond its movement range,
    ///     by default the head simply stops. For first person games, it is more
    ///     intuitive (and established practice) to rotate the body so the player can
    ///     use the mouse not only turn the head but also the whole body around.
    ///     Use this event to get notified of head rotation that was clamped off so
    ///     you can apply it to the body.
    ///   </para>
    ///   <para>
    ///     Fancy implementations might even want to watch this event and play
    ///     a &quot;step in place&quot; animation to turn the body completely
    ///     into the direction the player is looking once it reaches the boundaries
    ///     of what pure head movement allows.
    ///   </para>
    /// </remarks>
    event Action<Quaternion> ExcessHeadRotation;

    /// <summary>Transform to which the virtual reality camera is parented</summary>
    /// <remarks>
    ///   <para>
    ///     This should be set only for VR-based head controllers. In Unity, when
    ///     VR is enabled the active camera will always assume the position of
    ///     the player's eyes in the real world (relative to the camera's parent
    ///     transform).
    ///   </para>
    ///   <para>
    ///     So the only way to adjust the position from which the player sees
    ///     the scene is to parent the camera to a transform that can be moved around
    ///     in order to adjust its <em>neutral</em> position. This is called
    ///     a &quot;camera root&quot; and can either be a child of other nodes
    ///     (for example, of a car if the player is driving a car) or scene-global.
    ///   </para>
    ///   <para>
    ///     Head controllers that are not VR or do not work in this fashion will
    ///     simply return <code>null</code> here.
    ///   </para>
    /// </remarks>
    Transform VirtualRealityCameraRoot { get; }

    /// <summary>Base transform in which the player controls the look direction</summary>
    /// <remarks>
    ///   <para>
    ///     Translates from the global coordinate space into the coordinate space
    ///     in which head movements take place.
    ///   </para>
    ///   <para>
    ///     Depending on the complexity of the look controller used, this may simply be
    ///     the actor transform's orientation or it may be the transform of the neck's parent
    ///     bone (allowing the actor to bow or wobble and altering the head's frame of
    ///     reference accordingly).
    ///   </para>
    /// </remarks>
    Quaternion HeadBaseOrientation { get; }

    /// <summary>Where the player is looking within the head's coordinate space</summary>
    /// <remarks>
    ///   Append this rotation to the <see cref="HeadBaseOrientation" /> to get the direction
    ///   the player is looking at in the global coordinate frame.
    /// </remarks>
    Quaternion LocalHeadOrientation { get; set; }

    /// <summary>Whether this head controller is in the active input profile</summary>
    /// <remarks>
    ///   It is not unusual for actors to have multiple head controllers. For example,
    ///   there might be a mouse look head controller and a virtual reality head controller
    ///   that are switched between depending on the input profile the game runs with.
    ///   This property allows the actor controller to figure out which one to talk to.
    /// </remarks>
    bool IsActive { get; }

  }

} // namespace Framework.Actors