Reuh/ubiquitousse
1
0
Fork 0
mirror of https://github.com/Reuh/ubiquitousse.git synced 2025-10-27 17:19:31 +00:00
Code Releases Activity

abstract is ded

Browse source
This commit is contained in:
Reuh 2016-12-24 21:15:27 +01:00
parent 07cc7216a1
commit 42738cc7c9
8 changed files with 219 additions and 135 deletions
Download patch file Download diff file Expand all files Collapse all files

214
input.lua
View file

@ -10,14 +10,17 @@ local updated = {}
--- Input stuff
-- Inspired by Tactile by Andrew Minnich (https://github.com/tesselode/tactile).
-- I don't think I need to include the license since it's just inspiration, but for the sake of information, Tactile is under the MIT license.
-- Abstract considers two input methods, called buttons (binary input) and axes (analog input).
-- Ubiquitousse considers two input methods, called buttons (binary input) and axes (analog input).
local input
input = {
---------------------------------
--- Detectors (input sources) ---
---------------------------------
-- Buttons detectors --
-- A button detector is a function which returns true (pressed) or false (unpressed).
-- Any fuction which returns a boolean can be used as a button detector, but you will probably want to get the data from an HID.
-- Abstract being abstract, it doesn't suppose there is a keyboard and mouse available for example, and all HID buttons are identified using
-- Ubiquitousse being platform-agnostic, it doesn't suppose there is a keyboard and mouse available for example, and all HID buttons are identified using
-- an identifier string, which depends of the backend. Identifier strings should be of the format "source1.source2.[...].button", for example "keyboard.up"
-- or "gamepad.button.1.a" for the A-button of the first gamepad.
-- If the button is actually an axis (ie, the button is pressed if the axis value passes a certain threshold), the threshold should be in the end of the
@ -27,7 +30,7 @@ input = {
--- Makes a new button detector(s) from the identifier(s) string.
-- The function may error if the identifier is incorrect.
-- @tparam string button identifier, depends on the platform abstract is running on (multiple parameters)
-- @tparam string button identifier, depends on the platform Ubiquitousse is running on (multiple parameters)
-- @treturn each button detector (multiple-returns)
-- @impl backend
buttonDetector = function(...) end,
@ -37,20 +40,24 @@ input = {
-- Threshold value can be used similarly with %.
-- Axis detectors should support "binary axis", ie an axis defined by two buttons: if the 1rst button is pressed, value will be -1, if the 2nd is pressed it will be 1
-- and if none or the both are pressed, the value will be 0. This kind of axis identifier should have an identifier like "button1,button2" (comma-separated).
-- Axis detectors may also optionally return after the number between -1 and 1 the raw value and max value. The raw value is between -max and +max.
--- Makes a new axis detector(s) from the identifier(s) string.
-- @tparam string axis identifier, depends on the platform abstract is running on (multiple parameters)
-- @tparam string axis identifier, depends on the platform Ubiquitousse is running on (multiple parameters)
-- @treturn each axis detector (multiple-returns)
-- @impl backend
axisDetector = function(...) end,
------------------------------------------
--- Inputs (the thing you want to use) ---
------------------------------------------
-- Buttons inputs --
-- Button input is a container for buttons detector. A button will be pressed when one of its detectors returns true.
-- Inputs also knows if the button was just pressed or released.
-- @tparam ButtonDetectors ... all the buttons detectors or buttons identifiers
-- @tretrun ButtonInput the object
-- @impl abstract
-- @impl ubiquitousse
button = function(...)
local r -- object
local detectors = {} -- detectors list
@ -82,6 +89,8 @@ input = {
end
-- Object
r = {
--- Returns a new ButtonInput with the same properties.
-- @treturn ButtonInput the cloned object
clone = function(self)
local clone = input.button()
for name, detector in pairs(detectors) do
@ -94,6 +103,9 @@ input = {
return clone
end,
--- Bind new ButtonDetector(s) to this input.
-- @tparam ButtonDetectors ... buttons detectors or buttons identifiers to add
-- @treturn ButtonInput this ButtonInput object
bind = function(self, ...)
for _,d in ipairs({...}) do
if type(d) == "string" then
@ -106,6 +118,9 @@ input = {
end
return self
end,
--- Unbind ButtonDetector(s).
-- @tparam ButtonDetectors ... buttons detectors or buttons identifiers to remove
-- @treturn ButtonInput this ButtonInput object
unbind = function(self, ...)
for _,d in ipairs({...}) do
detectors[d] = nil
@ -113,15 +128,21 @@ input = {
return self
end,
pressed = function(_)
--- Returns true if the input was just pressed.
-- @treturn boolean true if the input was pressed, false otherwise
pressed = function(self)
update()
return state == "pressed"
end,
down = function(_)
--- Returns true if the input is down.
-- @treturn boolean true if the input is currently down, false otherwise
down = function(self)
update()
return state == "down" or state == "pressed"
end,
released = function(_)
--- Returns true if the input was just released.
-- @treturn boolean true if the input was released, false otherwise
released = function(self)
update()
return state == "released"
end,
@ -130,7 +151,12 @@ input = {
return r
end,
-- TODO: doc
-- Axis inputs --
-- Axis input is a container for axes detector. An axis input will return the value of the axis detector the most far away from their center (0).
-- Axis input provide a threshold setting ; every axis which has a distance to the center below th threshold will be ignored.
-- @tparam AxisDetectors ... all the axis detectors or axis identifiers
-- @tretrun AxisInput the object
-- @impl ubiquitousse
axis = function(...)
local r -- object
local detectors = {} -- detectors list
@ -150,6 +176,8 @@ input = {
end
-- Object
r = {
--- Returns a new AxisInput with the same properties.
-- @treturn AxisInput the cloned object
clone = function(self)
local clone = input.axis()
for name, detector in pairs(detectors) do
@ -163,6 +191,9 @@ input = {
return clone
end,
--- Bind new AxisDetector(s) to this input.
-- @tparam AxisDetectors ... axis detectors or axis identifiers to add
-- @treturn AxisInput this AxisInput object
bind = function(self, ...)
for _,d in ipairs({...}) do
if type(d) == "string" then
@ -175,6 +206,9 @@ input = {
end
return self
end,
--- Unbind AxisDetector(s).
-- @tparam AxisDetectors ... axis detectors or axis identifiers to remove
-- @treturn AxisInput this AxisInput object
unbind = function(self, ...)
for _,d in ipairs({...}) do
detectors[d] = nil
@ -182,58 +216,52 @@ input = {
return self
end,
--- Sets the default detection threshold (deadzone).
-- @tparam number new the new detection threshold
-- @treturn AxisInput this AxisInput object
threshold = function(self, new)
threshold = tonumber(new)
return self
end,
value = function(_, curThreshold)
--- Returns the value of the input (between -1 and 1).
-- @tparam[opt=default threshold] number threshold value to use
-- @treturn number the input value
value = function(self, curThreshold)
update()
return math.abs(value) > math.abs(curThreshold or threshold) and value or 0
end,
raw = function(_, rawThreshold)
--- Returns the raw value of the input (between -max and +max).
-- @tparam[opt=default threshold*max] number raw threshold value to use
-- @treturn number the input raw value
raw = function(self, rawThreshold)
update()
return math.abs(raw) > math.abs(rawThreshold or threshold*max) and raw or 0
end,
max = function(_)
--- Return the raw max of the input.
-- @treturn number the input raw max
max = function(self)
update()
return max
end
end,
--- The associated button pressed when the axis reaches a positive value.
positive = input.button(function() return r:value() > 0 end),
--- The associated button pressed when the axis reaches a negative value.
negative = input.button(function() return r:value() < 0 end)
}
r:bind(...)
return r
end,
--- Returns a list of the buttons currently in use, identified by their string button identifier.
-- This may also returns "axis threshold" buttons if an axis passes the threshold.
-- @treturn table<string> buttons identifiers list
-- @treturn[opt=0.5] number threshold the threshold to detect axes as button
-- @impl backend
buttonsInUse = function(threshold) end,
--- Returns a list of the axes currently in use, identified by their string axis identifier
-- @treturn table<string> axes identifiers list
-- @treturn[opt=0.5] number threshold the threshold to detect axes
-- @impl backend
axesInUse = function(threshold) end,
--- Returns a nice name for the button identifier.
-- Can be locale-depedant and stuff, it's only for display.
-- May returns the raw identifier if you're lazy.
-- @tparam string... button identifier string(s)
-- @treturn string... the displayable names
-- @impl backend
buttonName = function(...) end,
--- Returns a nice name for the axis identifier.
-- Can be locale-depedant and stuff, it's only for display.
-- May returns the raw identifier if you're lazy.
-- @tparam string... axis identifier string(s)
-- @treturn string... the displayable names
-- @impl backend
axisName = function(...) end,
-- TODO: doc
-- Pointer inputs --
-- Pointer inputs are container for two axes input, in order to represent a two-dimensionnal pointing device, e.g. a mouse or a stick.
-- Each pointer detector is a table with 3 fields: mode(string), XAxis(axis), YAxis(axis). mode can either be "relative" or "absolute".
-- In relative mode, the pointer will return the movement since last update (for example to move a mouse pointer with a stick).
-- In absolute mode, the pointer will return the pointer position directly deduced of the current axes position.
-- @tparam table{mode,XAxis,YAxis} ... couples of axis detectors, axis identifiers or axis input to add and in which mode
-- @tretrun PointerInput the object
-- @impl ubiquitousse
pointer = function(...)
local pointers = {} -- pointers list
local x, y = 0, 0 -- pointer position
@ -277,6 +305,8 @@ input = {
end
end
r = {
--- Returns a new PointerInput with the same properties.
-- @treturn PointerInput the cloned object
clone = function(self)
return input.pointer(unpack(pointers))
:dimensions(width, height)
@ -284,6 +314,9 @@ input = {
:speed(xSpeed, ySpeed)
end,
--- Bind new axis couples to this input.
-- @tparam table{mode,XAxis,YAxis} ... couples of axis detectors, axis identifiers or axis input to add and in which mode
-- @treturn PointerInput this PointerInput object
bind = function(self, ...)
for _,p in ipairs({...}) do
if type(p) == "table" then
@ -296,6 +329,9 @@ input = {
end
return self
end,
--- Unbind axis couples.
-- @tparam table{mode,XAxis,YAxis} ... couples of axis detectors, axis identifiers or axis input to remove
-- @treturn PointerInput this PointerInput object
unbind = function(self, ...)
for _,p in ipairs({...}) do
for i,pointer in ipairs(pointers) do
@ -312,7 +348,9 @@ input = {
-- Call without argument to use half the window dimensions.
-- It's the half dimensions because axes values goes from -1 to 1, so theses dimensions only
-- covers values from x=0,y=0 to x=1,y=1. The full moving area will be 4*newWidth*newHeight.
-- @impl abstract
-- @tparam number newWidth new width
-- @tparam number newHeight new height
-- @treturn PointerInput this PointerInput object
dimensions = function(self, newWidth, newHeight)
width, height = newWidth, newHeight
return self
@ -320,7 +358,9 @@ input = {
--- Set the moving area coordinates offset.
-- The offset is a value automatically added to the x and y values when using the x() and y() methods.
-- Call without argument to automatically offset so 0,0 <= x(),y() <= width,height, i.e. offset to width,height.
-- @impl abstract
-- @tparam number newOffX new X offset
-- @tparam number newOffY new Y offset
-- @treturn PointerInput this PointerInput object
offset = function(self, newOffX, newOffY)
offsetX, offsetY = newOffX, newOffY
return self
@ -328,46 +368,108 @@ input = {
--- Set maximal speed (pixels-per-milisecond)
-- Only used in relative mode.
-- Calls without argument to use the raw data and don't apply a speed modifier.
-- @impl abstract
-- @tparam number newXSpeed new X speed
-- @tparam number newYSpeed new Y speed
-- @treturn PointerInput this PointerInput object
speed = function(self, newXSpeed, newYSpeed)
xSpeed, ySpeed = newXSpeed, newYSpeed or newXSpeed
return self
end,
--- Returns the current X value of the pointer.
-- @treturn number X value
x = function()
update()
return x + (offsetX or width or draw.width/2)
end,
--- Returns the current Y value of the pointer.
-- @treturn number Y value
y = function()
update()
return y + (offsetY or height or draw.height/2)
end
end,
--- The associated horizontal axis.
horizontal = input.axis(function()
local h = r:x()
return h/width, h, width
end),
--- The associated vertical axis.
vertical = input.axis(function()
local v = r:y()
return v/height, v, height
end),
--- The associated button pressed when the pointer goes to the right.
right = nil,
--- The associated button pressed when the pointer goes to the left.
left = nil,
--- The associated button pressed when the pointer points up.
up = nil,
--- The associated button pressed when the pointer points down.
down = nil
}
r.right, r.left = r.horizontal.positive, r.horizontal.negative
r.up, r.down = r.vertical.negative, r.vertical.positive
r:bind(...)
return r
end,
------------------------------
--- Input detection helpers --
------------------------------
--- Returns a list of the buttons currently in use, identified by their string button identifier.
-- This may also returns "axis threshold" buttons if an axis passes the threshold.
-- @treturn table<string> buttons identifiers list
-- @treturn[opt=0.5] number threshold the threshold to detect axes as button
-- @impl backend
buttonsInUse = function(threshold) end,
--- Returns a list of the axes currently in use, identified by their string axis identifier
-- @treturn table<string> axes identifiers list
-- @treturn[opt=0.5] number threshold the threshold to detect axes
-- @impl backend
axesInUse = function(threshold) end,
--- Returns a nice name for the button identifier.
-- Can be locale-depedant and stuff, it's only for display.
-- May returns the raw identifier if you're lazy.
-- @tparam string... button identifier string(s)
-- @treturn string... the displayable names
-- @impl backend
buttonName = function(...) end,
--- Returns a nice name for the axis identifier.
-- Can be locale-depedant and stuff, it's only for display.
-- May returns the raw identifier if you're lazy.
-- @tparam string... axis identifier string(s)
-- @treturn string... the displayable names
-- @impl backend
axisName = function(...) end,
-------------------
--- Other stuff ---
-------------------
--- Some default inputs.
-- The backend may bind detectors to thoses inputs.
-- The backend should bind detectors to thoses inputs.
-- These are used to provide some common input default detectors to allow to start a game quickly on
-- any platform without having to configure the keys.
-- If some key function in your game match one of theses defaults, using it instead of creating a new
-- input would be a good idea.
-- @impl mixed
default = {
pointer = nil, -- A default Pointer: used to move. Example binds: arrow keys, stick.
up = nil, -- Button: similar to pointer, but only the up button.
down = nil, -- Button: similar to pointer, but only the down button.
right = nil, -- Button: similar to pointer, but only the right button.
left = nil, -- Button: similar to pointer, but only the left button.
pointer = nil, -- Pointer: used to move and select. Example binds: arrow keys, WASD, stick.
confirm = nil, -- Button: used to confirm something. Example binds: Enter, A button.
cancel = nil -- Button: used to cancel something. Example binds: Escape, B button.
},
--- Update all the Inputs.
-- Supposed to be called in ubiquitousse.event.update.
-- The backend can hook into this function to to its input-related updates.
-- @tparam numder dt the delta-time
-- @impl abstract
-- @impl ubiquitousse
update = function(dt)
updated = {}
end
@ -375,10 +477,6 @@ input = {
-- Create default inputs
input.default.pointer = input.pointer()
input.default.up = input.button()
input.default.down = input.button()
input.default.right = input.button()
input.default.left = input.button()
input.default.confirm = input.button()
input.default.cancel = input.button()