====== Input functions ======

ACSUtils provides a simplified interface to [[zdoom>GetPlayerInput]].

===== Function list =====

A full list of new input functions:

^ ^ Key ^ KeyAny ^ PlayerKey ^ PlayerKeyAny ^
^ up|[[functions:KeyUp]]|[[functions:KeyUpAny]]|[[functions:PlayerKeyUp]]|[[functions:PlayerKeyUpAny]]|
^ down|[[functions:KeyDown]]|[[functions:KeyDownAny]]|[[functions:PlayerKeyDown]]|[[functions:PlayerKeyDownAny]]|
^ pressed|[[functions:KeyPressed]]|[[functions:KeyPressedAny]]|[[functions:PlayerKeyPressed]]|[[functions:PlayerKeyPressedAny]]|
^ released|[[functions:KeyReleased]]|[[functions:KeyReleasedAny]]|[[functions:PlayerKeyReleased]]|[[functions:PlayerKeyReleasedAny]]|
^ toggled|[[functions:KeyToggled]]|[[functions:KeyToggledAny]]|[[functions:PlayerKeyToggled]]|[[functions:PlayerKeyToggledAny]]|

===== Introduction =====

Each key can be
  * **Up** or **down** at any moment.
  * **Pressed**, if it was **up** during the previous tick but is now **down**.
  * **Released**, if it was **down** during the previous tick but is now **up**.
  * **Toggled**, if it is **pressed** or **released**.

Pressed and released states are especially useful for menus as they allow the user to perform the action as many times as the key was pressed.

Some mods don't detect pressed state but instead check for down state periodically, causing the user to perform the action less or more times than desired, e.g.:

<code>
while (true)
{
   if (KeyDown(BT_MOVELEFT))
       menupos++;
   Delay(5);
}
</code>

will move the menu cursor 7 times per second if the button is held, and **won't move the cursor at all if the key press falls in between the checks**, whereas:

<code>
while (true)
{
    if (KeyPressed(BT_MOVELEFT))
        menupos++;
    Delay(1);
}
</code>   

will move the menu cursor down as many times as the key was hit.

===== Conventions =====

ACSUtils provides a set of functions using the following convention:

  * ''bool Key**State**(int key)''
  * ''bool Key**State**Any(int key)''
  * ''bool PlayerKey**State**(int player, int key)''
  * ''bool PlayerKey**State**Any(int player, int key)''

Here's a breakdown of the parts:
  - **State** is any of ''Up'', ''Down'', ''Pressed'', ''Released''.
  - If multiple keys are passed in (e.g. ''BT_ATTACK | BT_ALTATTACK''), then functions with the **Any** suffix return true if any of them are in the needed state, while functions without the suffix return true only if all of them are.
  - If the **Player** prefix is present, the function checks the keys of the specified player. Functions without the prefix check the activator's keys (equivalent to passing -1 to [[zdoom>GetPlayerInput]].