Noble.Input

A complete encapsulation of the Playdate's input system.

The Playdate SDK gives developers multiple ways to manage input. Noble Engine's approach revolves around the SDK's "inputHandlers," extending them to include additional input methods, and pull in other hardware functions that the SDK puts elsewhere. See usage below for the full list of supported methods.

By default, Noble Engine assumes each scene will have an inputManager assigned to it. So, for example, you can define one inputManager for menu screens and another for gameplay scenes in your main.lua, and then in each scene, set which one that scene uses. You can instead define a unique inputHandler in each scene.

You may also create and manage inputManagers within and outside of scenes. When a NobleScene is loaded, its inputHandler will become active, thus, inputHandlers do not carry across scenes, and all input is suspended during scene transitions. An advanced use-case is to leave a scene's inputHandler as nil, and manage it separately.

NOTE: While the Playdate SDK allows you to stack as many inputHandlers as you want, Noble Engine assumes only one active inputHandler at a time. You may still manually call playdate.inputHandlers.push() and playdate.inputHandlers.pop() yourself, but Noble Engine will not know about it and it may cause unexpected behavior.

In addition, you may directly query button status using the SDK's methods for that, but it is not advised to use that as the primary way to manage input for Noble Engine projects, because much of Noble.Input's functionality will not apply.

See

Usage

local myInputHandler = {
	AButtonDown = function() end,	-- Fires once when button is pressed down.
	AButtonHold = function() end,	-- Fires each frame while a button is held (Noble Engine implementation).
	AButtonHeld = function() end,	-- Fires once after button is held for 1 second (available for A and B).
	AButtonUp = function() end,		-- Fires once when button is released.
	BButtonDown = function() end,
	BButtonHold = function() end,
	BButtonHeld = function() end,
	BButtonUp = function() end,
	downButtonDown = function() end,
	downButtonHold = function() end,
	downButtonUp = function() end,
	leftButtonDown = function() end,
	leftButtonHold = function() end,
	leftButtonUp = function() end,
	rightButtonDown = function() end,
	rightButtonHold = function() end,
	rightButtonUp = function() end,
	upButtonDown = function() end,
	upButtonHold = function() end
	upButtonUp = function() end,

	cranked = function(change, acceleratedChange) end,	-- See Playdate SDK.
	crankDocked = function() end,						-- Noble Engine implementation.
	crankUndocked = function() end,						-- Noble Engine implementation.

	orientationChanged = function() end					-- Noble Engine implementation.
}

Functions

Noble.Input.getHandler()
Get the currently active input handler. Returns nil if none are active.

Returns

    table A table of callbacks which handle input events.

See

Noble.Input.setHandler([__inputHandler=nil])
Use this to change the active inputHandler.

Enter nil to disable input. Use Noble.Input.setEnabled to disable/enable input without losing track of the current inputHandler.

Parameters

  • __inputHandler table = nil (default)
    A table of callbacks which handle input events.

See

Noble.Input.clearHandler()
A helper function that calls Noble.Input.setHandler() with no argument.

See

Noble.Input.setEnabled(__value)
Enable and disable user input without dealing with inputHanders. The Playdate SDK requires removing all inputHanders to halt user input, so while the currentHandler is cleared when false is passed to this method, it is cached so it can be later re-enabled by passing true it.

Parameters

  • __value boolean
    Set to false to halt input. Set to true to resume accepting input.

See

Noble.Input.getEnabled()
Checks to see that there is an active inputHandler

Returns

    bool Returns true if the input system is enabled. Returns false if setEnabled(false) was used, or if currentHandler is nil.
Noble.Input.setCrankIndicatorStatus(__active[, __evenWhenUndocked=false])
Enable/disable on-screen system crank indicator.

NOTE: The indicator will only ever show if the crank is docked, unless __evenWhenUndocked is true.

Parameters

  • __active boolean
    Set true to start showing the on-screen crank indicator. Set false to stop showing it.
  • __evenWhenUndocked boolean = false (default)
    Set true to show the crank indicator even if the crank is already undocked (__active must also be true).
Noble.Input.getCrankIndicatorStatus()
Checks whether the system crank indicator status. Returns a tuple.

Returns

  1. bool Is the crank indicator active?
  2. bool Is the crank indicator being forced when active, even when the crank is undocked?

See

Noble.Input.getOrientation([__getStoredValues=false])
Checks the current display orientation of the device. Returns a tuple. If the accelerometer is not currently enabled, this method will turn it on, return current values, and then turn it off. If you are trying to get raw accelerometer values rather than the display orientation, you may want to use playdate.readAccelerometer() instead.

Parameters

  • __getStoredValues boolean = false (default)
    If true, this method will simply return the most recently stored values, rather than use the accelerometer to check for new ones.

Returns

  1. str The named orientation of the device (a pseudo enum Noble.Input.ORIENTATION_XX)
  2. list Accelerometer values, where list[1] is x, list[2] is y and list[3] is z

See

Constants

A set of constants referencing device inputs, stored as strings. Can be used for querying button input, but are mainly for on-screen prompts or other elements where a string literal is useful, such as a filename, GameData value, or localization key. For faster performance, use the ones that exist in the Playdate SDK (i.e.: playdate.kButtonA), which are stored as binary numbers.

Usage

function newPrompt(__input, __promptString)
	-- ...
	local icon = Graphics.image.new("assets/images/UI/Icon_" .. __input)
	-- ...
end

promptMove = newPrompt(Noble.Input.DPAD_HORIZONTAL, "Move!")				-- assets/images/UI/Icon_dPadHorizontal.png"
promptJump = newPrompt(Noble.Input.BUTTON_A, "Jump!") 						-- assets/images/UI/Icon_buttonA.png"
promptCharge = newPrompt(Noble.Input.CRANK_FORWARD, "Charge the battery!")	-- assets/images/UI/Icon_crankForward.png"
Noble.Input.BUTTON_A
"buttonA"
Noble.Input.BUTTON_B
"buttonB"
Noble.Input.BUTTON_MENU
The system menu button.

"buttonMenu"

Noble.Input.DPAD
Referencing the D-pad component itself, rather than an input.

"dPad"

Noble.Input.DPAD_HORIZONTAL
Referencing the left and right input D-pad inputs.

"dPadHorizontal"

Noble.Input.DPAD_VERTICAL
Referencing the up and down input D-pad inputs.

"dPadVertical"

Noble.Input.DPAD_UP
"dPadUp"
Noble.Input.DPAD_DOWN
"dPadDown"
Noble.Input.DPAD_LEFT
"dPadLeft"
Noble.Input.DPAD_RIGHT
"dPadRight"
Noble.Input.CRANK
Referencing the crank component itself, rather than an input.

"crank"

Noble.Input.CRANK_FORWARD
AKA: Clockwise. See Playdate SDK.

"crankForward"

Noble.Input.CRANK_REVERSE
AKA: Anticlockwise. See Playdate SDK.

"crankReverse"

Noble.Input.CRANK_DOCK
Referencing the action of docking the crank.

"crankDock"

Noble.Input.CRANK_UNDOCK
Referencing the action of undocking the crank.

"crankUndock"

Noble.Input.ORIENTATION_UP
Referencing the display orientations.

"orientationUp"

Noble Engine by Mark LaCroix, Noble Robot Documentation created using LDoc 1.5.0.