DOWNLOAD DoubleClick 1.0.0 MODULEDOWNLOAD KeyListener 0.9.7 MODULEBoth modules require AGS 3.2.1 or higher.
Module sources:
DoubleClickKeyListenerGit clone address:
https://ivan-mogilko@bitbucket.org/ivan-mogilko/ags-script-modules.gitDouble ClickAs of now, AGS does not have built-in mouse double-click events. DoubleClick module solves this by detecting when player made two consecutive clicks within short duration.
Usage is very simple:
function on_mouse_click(MouseButton mb)
{
if (mb = eMouseLeft)
{
if (DoubleClick.Event[eMouseLeft])
{
player.SayBackground("Double-clicked!");
}
else
{
// regular click
}
}
}
DoubleClick supports claiming events similar to standart ClaimEvent() function. If you are detecting double clicks in several modules, you may use
DoubleClick.ClaimThisEvent() to not let double-click "through" to lower scripts.
DoubleClick.Timeout property is used to set up max timeout (in milliseconds) which may pass between two clicks for them to be considered "double click". Default is 300 ms.
Key ListenerKeyListener is a more sophisticated script module, that
keeps track and record of the particular key and mouse button states in your game. Since AGS is limited in which key and mouse events it reports to the script, this module may be a useful workaround.
With KeyListener you do:
- Setup which keys or mouse buttons to listen (track) and change that list dynamically at any moment in the game;
- Optionally configure deduction parameters, such as maximal time between two key presses while they still counted as a sequence;
- Enable and disable listener work at will.
With KeyListener you acquire following information about any of the listened keys and mouse buttons at any time:
- Is key currently up or down;
- Was the key just released or pushed;
- Has the player double clicked a mouse button;
- How long was the key up or down (in milliseconds);
- How much times was the key tapped in a sequence;
- How much times was the key "auto-repeated" while being held down;
NOTE that if you are using KeyListener, you do not need DoubleClick module.
ConceptsOn sequencing.
Sequencing is pressing same key (or mouse button) over and over again, when every next press was made within certain time limit since the previous one. KeyListener lets you configure the maximal waiting time (timeout), default value being 300 ms. You are able to know when the key was "sequenced" another once, and how many times it was pressed in sequence already ("sequence length").
On key autorepeats.
In KeyListener terminology, a key's autorepeats start to occur periodically when the key is being held down for some time. This simulates the common operating system behavior, which can be easily observed in any text editor: when you press and hold the key first only one letter is typed, but after small amount of time it starts typing same letter again and again automatically, without you releasing and pressing key again.
You may configure two parameters related to key repeats: the first delay, which has to pass before key begins "repeating", and the (usually shorter) period between repeat count increments.
You may get when autorepeat occurs, and how many times this key was autorepeated.
Signal propertiesSince AGS does not support custom callbacks (calling your own functions when something happened in script module), KeyListener tells you about immediate events by setting certain signal properties. These properties are easily distinguished by
"Evt*" prefix.
The positive values on signal properties only set for 1 game tick (update), and are reset immediately afterwards. They literally mean that the key event has just occured, and you should react to that. The next tick they will be reset until some key event occurs again.
You will have to check these properties periodically, in the "repeatedly_execute" or "repeatedly_execute_always" functions of GlobalScript or your own custom script to know when the related events occur.
Lifetime of key recordsAnother important peculiarity is that some properties are kept for just 1 tick more after key state changes, before getting reset. These are
KeyUpTime,
KeyDownTime and
KeyAutoRepeatCount. This is done so to allow you get their
final value after being notified about key state change. For example, you may want to know how long the key was held down right
after it was released.
Module APIFollowing are properties of the KeyListener class, that are exposed for use in your scripts:
struct KeyListener
{
///////////////////////////////////////////////////////////////////////////
//
// Setting up
// ------------------------------------------------------------------------
// Functions and properties meant to configure the listener's behavior.
//
///////////////////////////////////////////////////////////////////////////
// Enables or disables KeyListener, without cancelling tracked keys settings
import static attribute bool Enabled;
/// Commences or ceases to listen keycode
import static void ListenKey(eKeyCode keycode, bool enable = true);
import static void ListenMouse(bool enable = true);
/// Stops listening all keycodes
import static void StopListenAllKeys();
/// Resets all listener parameters to default values
import static void ResetToDefaults();
/// Get/set minimal time (in milliseconds) for a held down key to be down to be considered "repeating"
import static attribute int KeyAutoRepeatDelay;
/// Get/set period (in milliseconds) between each "repeating" key count
import static attribute int KeyAutoRepeatPeriod;
/// Get/set maximal period (in milliseconds) between two key taps while they still considered a sequence
import static attribute int KeySequenceTimeout;
///////////////////////////////////////////////////////////////////////////
//
// Event signals
// ------------------------------------------------------------------------
// Properties meant to signal user about keys events.
//
///////////////////////////////////////////////////////////////////////////
/// Gets if key was just pushed
readonly import static attribute bool EvtKeyPushed[];
readonly import static attribute bool EvtMousePushed[];
/// Gets if key was just released after being held down
readonly import static attribute bool EvtKeyReleased[];
readonly import static attribute bool EvtMouseReleased[];
/// Gets if key command was repeated for a held down key
readonly import static attribute bool EvtKeyAutoRepeated[];
readonly import static attribute bool EvtMouseAutoRepeated[];
/// Gets if key was tapped another time in sequence
readonly import static attribute bool EvtKeySequenced[];
readonly import static attribute bool EvtMouseSequenced[];
/// Gets if key was tapped twice in sequence just now
readonly import static attribute bool EvtKeyDoubleTap[];
readonly import static attribute bool EvtMouseDoubleClick[];
///////////////////////////////////////////////////////////////////////////
//
// Key records
// ------------------------------------------------------------------------
// Properties meant to tell gathered information about keys the listener
// is listening to.
//
///////////////////////////////////////////////////////////////////////////
/// Gets if key is currently held down
readonly import static attribute bool IsKeyDown[];
readonly import static attribute bool IsMouseDown[];
/// Gets how many times the pressed down key command was repeated
readonly import static attribute int KeyAutoRepeatCount[];
readonly import static attribute int MouseAutoRepeatCount[];
/// Gets how many times the key was tapped in sequence
readonly import static attribute int KeySequenceLength[];
readonly import static attribute int MouseSequenceLength[];
/// Gets how long (in milliseconds) the key was not pressed
readonly import static attribute int KeyUpTime[];
readonly import static attribute int MouseUpTime[];
/// Gets how long (in milliseconds) the key was held down
readonly import static attribute int KeyDownTime[];
readonly import static attribute int MouseDownTime[];
};
Example 1: Some simple actions.
function game_start()
{
// We are going to track spacebar and the mouse buttons
KeyListener.ListenKey(eKeySpace);
KeyListener.ListenMouse();
// Start tracking
KeyListener.Enabled = true;
}
function repeatedly_execute()
{
if (KeyListener.EvtMouseDoubleClick[eMouseLeft])
{
// player double clicked with mouse; do something
}
if (KeyListener.EvtMousePushed[eMouseLeft] && KeyListener.MouseSequenceLength[eMouseLeft] == 2)
{
// this is essentially the same as above
}
if (KeyListener.IsKeyDown[eKeySpace] && KeyListener.KeyDownTime[eKeySpace] > 1000)
{
// player is holding space bar for more than 1 second
}
}
Example 2: displaying particular key records on GUI.
int key;
function game_start()
{
key = eKeyA;
KeyListener.ListenKey(key);
KeyListener.Enabled = true;
}
function repeatedly_execute()
{
Label1.Text = String.Format("Key is down: %d", KeyListener.IsKeyDown[key]);
Label2.Text = String.Format("Key just pushed: %d", KeyListener.EvtKeyPushed[key]);
Label3.Text = String.Format("Key just released: %d", KeyListener.EvtKeyReleased[key]);
Label4.Text = String.Format("Key uptime: %d", KeyListener.KeyUpTime[key]);
Label5.Text = String.Format("Key downtime: %d", KeyListener.KeyDownTime[key]);
Label6.Text = String.Format("Key repeats: %d", KeyListener.KeyAutoRepeatCount[key]);
Label7.Text = String.Format("Key taps: %d", KeyListener.KeySequenceLength[key]);
Label8.Text = String.Format("Key double tap: %d", KeyListener.EvtKeyDoubleTap[key]);
Label9.Text = String.Format("Key sequenced: %d", KeyListener.EvtKeySequenced[key]);
Label10.Text = String.Format("Key repeated: %d", KeyListener.EvtKeyAutoRepeated[key]);
}
The module is currently in BETA stage and needs extensive testing.
Comments, critism, suggestions and bug reports are welcome.
