đ nubs
=======
*nubs is a user-input system for web games.*
[⥠**live demo!** *nubs.benevolent.games*](https://nubs.benevolent.games/)
đ nubs listens to keyboards, mice, gamepads, etc
đšī¸ nubs has mobile-friendly virtual devices, like thumbsticks and buttons
đ nubs has a keybinds editor so users to customize their controls
đ nubs has a grid-based menu system that is good for hotkeys
đŧ a project by [benevolent.games](https://benevolent.games/)
đ free and open source
## install nubs onto your html page
- **the easy way** *(for html enthusiasts)*
- install these scripts into your page's ``
```html
```
- **the advanced way** *(for web developers)*
- install the nubs npm package
```sh
npm install @benev/nubs
```
- import nubs elements, register them to the dom
```js
import {getElements, registerElements, themeElements, themeCss} from "@benev/nubs"
// run customElements.define
registerElements(
// apply a common css theme
themeElements(
// stylesheet applied into the shadow doms
themeCss,
// get all nub element classes
getElements(),
)
)
```
## how to start using nubs
1. let's add some cool nub devices to your html ``
- ```html
```
- it's a mobile-friendly thumbstick!
- it will emit `nub_cause` events
- ```html
```
- also emits `nub_cause` events
- this one doesn't render any ui (all of the "real" devices are like this)
1. wrap your nub elements inside a ``
```html
```
- nub-context is for grouping nub devices
- the context will only listen to devices nested under it
- the context may contain devices and editing ui
- nub-context introduces `bindings`
- bindings define the associations between "causes" and "effects"
- nub-context has ui that allows users to edit their `bindings`
- an example *cause* might be `KeyW`
- an example *effect* might be `forward`
- in most cases, you probably want your app to listen to `nub_effect` events like `forward` rather than the causes
## understanding *cause* and *effect* in nubs
- **`nub_cause`** events:
like keyboard key presses and mouse movements.
all nub *devices* like `` or `` dispatch these events.
- **`nub_effect`** events:
like "forward" or "open menu".
these are dispatched by a `` element, based on the user's bindings.
the bindings allow users to customize which *effects* are triggered by which *causes*.
## nubs element reference
devices
- **``** *(real device)*
listens to real mouse or touch inputs.
- **``** *(real device)*
listens to real keyboard inputs.
- **``** *(virtual device)*
mobile-friendly thumbstick.
- **``** *(virtual device)*
thumbstick area, which centers the stick wherever your touch starts.
- **``** *(virtual device)*
area for tracking touch movements, to emulate a mouse.
- **``** *(hybrid device)*
bindings, editing, and troubleshooting
- **``**
listens for `nub_cause` events, and dispatches `nub_effect` events, based on the current `bindings`.
only listens to `nub_cause` events nested within the nub-context element.
- **``**
interface for users to customize their bindings.
- **``**
see what's going on, which `nub_effect` events are being dispatched.