Input functions

ACSUtils provides a set of wrappers for GetPlayerInput to make writing correct input code easier.

Basic concepts

Every key is either up or down at any time.

If the key was up the previous tic, but is now down, it is said to have been pressed.

If the key was down the previous tic, but is now up, it is said to have been released.

If the key has been pressed or released, it is said to have been toggled.

ACSUtils provide a way to easily check these all these states for every key without writing compliated GetPlayerInput expressions.

What's the point of "pressed" and "released"?

If you want to detect if the player has pressed the key just once, you can't do so just by checking if they key is down like this:

// This code is bugged.
if (GetPlayerInput(-1, INPUT_BUTTONS) & BT_X)
print("You pressed X once");

The key will be down for some time after the press, causing the condition to trigger multiple times. To avoid this, you need to check whether the key was up the previous tic, which is exactly what KeyPressed checks:

if (KeyPressed(BT_X))
print("You pressed X once");

The same goes for released state.

Functions

To check one key or a key combination:

bool KeyUp(int key)

bool KeyDown(int key)

bool KeyPressed(int key)

bool KeyReleased(int key)

bool KeyToggled(int key)

Examples:

Checking one key:

if (KeyPressed(BT_FORWARD))
print(s:"You just pressed W");

Checking a key combination:

if (KeyDown(BT_FORWARD | BT_BACK))
print(s:"You are trying to move forward and back at the same time."
s:"You are not going anywhere this way.");

If you try to use KeyPressed with a key combination, you are requiring that the whole combination is pressed within the same tic. It is extremely hard to do so.

To check if at least one of the keys is in a given state:

bool KeyUpAny(int keys)

bool KeyDownAny(int keys)

bool KeyPressedAny(int keys)

bool KeyReleasedAny(int keys)

bool KeyToggledAny(int keys)

For example:

if (KeyPressedAny(BT_ATTACK | BT_ALTATTACK))
print(s:"You just tried to shoot.");

if (KeyDown(BT_FORWARD | BT_BACK | BT_MOVELEFT | BT_MOVERIGHT))
print(s:"You are trying to move.");

To use these wrappers on players other than the activator, prefix any function with Player and add player number as the first argument:

bool PlayerKeyUp(int player, int key)

bool PlayerKeyDown(int player, int key)

bool PlayerKeyPressed(int player, int key)

bool PlayerKeyReleased(int player, int key)

bool PlayerKeyToggled(int player, int key)

bool PlayerKeyUpAny(int player, int keys)

bool PlayerKeyDownAny(int player, int keys)

bool PlayerKeyPressedAny(int player, int keys)

bool PlayerKeyReleasedAny(int player, int keys)

bool PlayerKeyToggledAny(int player, int keys)