retroinput - simple & crappy input library
Posted: Sat Nov 27, 2021 1:52 pm
so I was making multiple retro-themed project and made a universal input system, so I thought someone could find it useful too
im not that experienced and this probably need a lot of improvement, but it is enough for what I needed
the library can load the controls from a config file, call functions on keypresses & retrieve input from the keyboard, joysticks and gamepads, supports mapping multiple keys/buttons to a single input key
so this is some quick documentation:
installation
download the file/copy its contents and paste them into a file
require the file in your project as usual
initialization
before using the library, you first have to initialize it with the function
<optional> cfgname [string] - the name of the file to load the controls from (def: "controls.cfg")
<optional> keys [table] - a list of the names of all the inputs (def:)
<optional> defcontrols [table] - a table with default controls in case there is no config file yet (has to contain key from the 'keys' table with string values, the different keys/buttons are separated with commas and no spaces:(def: )
updating
you have to call
every frame/period of time (up to you), to actually update the inputs (no 'dt' variable is needed)
retrieving input
you can check if an input key is pressed by using
key [string] - the name of the input (e.g. "left", "right", "a", "b", etc...)
you can get a normally distributed (between -1 and 1) axis value from 2 keys by using
neg [string] - the name of the key that "tilts" the value towards -1
pos [string] - the name of the key that "tilts" the value towards 1
EXPLANATION: if neg is pressed, the function returns -1, if pos is pressed, it returns 1, if both are pressed, they "negate" each other and the result is 0, and obviously if neither are pressed the result is also 0
and you can get a table with all the inputs with
this function is mainly for debugging, the table is in the format
{
left = 0/1,
right = 0/1,
up = 0/1,
. . .
}
1 means pressed and 0 means not pressed
I might update it to boolean values, but they caused some problems before so I replaced them with numbers
callbacks
you can define callbacks same as in love:
IMPORTANT NOTE: MAKE SURE YOU DEFINE THE CALLBACKS AFTER THE LIBRARY IS REQUIRED (EITHER DO BOTH IN love.load() OR BOTH OUTSIDE IT)
config format
the controls are saved into the config in the following format:
joystick/gamepad input
you can write the key (in the config) in this format to map joystick/gamepad input:
DEVICE - either JOY or PAD, represents joystick and gamepad
TYPE - either A or B, represents axis or button
INDEX - the index of the axis/button (a number with joysticks, a GamepadButton/GamepadAxis with gamepads)
<optional> VALUE - either POS or NEG, represents the positive/negative value of an axis
so thats about it, please feel free to reply if:
something is unclear (its kinda hard to explain these things properly)
something in the code can be done in a better/cleaner/more efficient/simpler/... way (Im not that experienced, will gladly learn)
I misspelld something or maked a gramatic mistake (haha lol)
the library misses something and I should add it (this is all I needed, but I can try to make it suit more people)
anything other like these things
its crappy, but I hope at least someone finds it helpful
im not that experienced and this probably need a lot of improvement, but it is enough for what I needed
the library can load the controls from a config file, call functions on keypresses & retrieve input from the keyboard, joysticks and gamepads, supports mapping multiple keys/buttons to a single input key
so this is some quick documentation:
installation
download the file/copy its contents and paste them into a file
require the file in your project as usual
Code: Select all
retroinput = require "retroinput"
before using the library, you first have to initialize it with the function
Code: Select all
retroinput:init(cfgname, keys, defcontrols)
<optional> keys [table] - a list of the names of all the inputs (def:
Code: Select all
{"left", "right", "up", "down", "a", "b", "start", "select"}
<optional> defcontrols [table] - a table with default controls in case there is no config file yet (has to contain key from the 'keys' table with string values, the different keys/buttons are separated with commas and no spaces:
Code: Select all
{left="left,a", right="right,d", up="up,w", down="down,s", etc...}
Code: Select all
{
left = "left,a,JOY_A_1_NEG,PAD_A_LEFTX_NEG,PAD_B_DPLEFT",
right = "right,d,JOY_A_1_POS,PAD_A_LEFTX_POS,PAD_B_DPRIGHT",
up = "up,w,JOY_A_2_NEG,PAD_A_LEFTY_NEG,PAD_B_DPUP",
down = "down,s,JOY_A_2_POS,PAD_A_LEFTY_POS,PAD_B_DPDOWN",
a = "c,i,JOY_B_2,PAD_B_A",
b = "x,u,JOY_B_1,PAD_B_B",
["start"] = "lshift,l,JOY_B_10,PAD_B_START",
["select"] = "z,k,JOY_B_9,PAD_B_BACK"
}
updating
you have to call
Code: Select all
retroinput:update()
retrieving input
you can check if an input key is pressed by using
Code: Select all
retroinput:isDown(key)
you can get a normally distributed (between -1 and 1) axis value from 2 keys by using
Code: Select all
retroinput:getAxis(neg, pos)
pos [string] - the name of the key that "tilts" the value towards 1
EXPLANATION: if neg is pressed, the function returns -1, if pos is pressed, it returns 1, if both are pressed, they "negate" each other and the result is 0, and obviously if neither are pressed the result is also 0
and you can get a table with all the inputs with
Code: Select all
retroniput:getInputs()
{
left = 0/1,
right = 0/1,
up = 0/1,
. . .
}
1 means pressed and 0 means not pressed
I might update it to boolean values, but they caused some problems before so I replaced them with numbers
callbacks
you can define callbacks same as in love:
Code: Select all
function retroinput.pressed(key)
--called when a key is pressed
end
function retroinput.held(key)
--called every update a key is held, you are probably gonna use isDown() instead but whatever
end
function retroinput.released(key)
--called when a key is released
end
config format
the controls are saved into the config in the following format:
Code: Select all
inputkey1:key1,key2,key3,...,
inputkey2:key1,key2,key3,...,
...
you can write the key (in the config) in this format to map joystick/gamepad input:
Code: Select all
DEVICE_TYPE_INDEX[_VALUE]
TYPE - either A or B, represents axis or button
INDEX - the index of the axis/button (a number with joysticks, a GamepadButton/GamepadAxis with gamepads)
<optional> VALUE - either POS or NEG, represents the positive/negative value of an axis
so thats about it, please feel free to reply if:
something is unclear (its kinda hard to explain these things properly)
something in the code can be done in a better/cleaner/more efficient/simpler/... way (Im not that experienced, will gladly learn)
I misspelld something or maked a gramatic mistake (haha lol)
the library misses something and I should add it (this is all I needed, but I can try to make it suit more people)
anything other like these things
its crappy, but I hope at least someone finds it helpful