@benev/nubs
v0.3.0-dev.2
Published
user-input system for web games
Downloads
88
Maintainers
Readme
🔘 nubs
nubs is a user-input system for web games.
⚡ live demo! 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
💖 free and open source
install nubs onto your html page
- the easy way (for html enthusiasts)
- install these scripts into your page's
<head>
<script type=importmap-shim src="https://unpkg.com/@benev/nubs/x/importmap.json" defer ></script> <script type=module-shim src="https://unpkg.com/@benev/nubs/x/html.js" defer ></script> <script src="https://unpkg.com/es-module-shims/dist/es-module-shims.wasm.js" defer ></script>
- install these scripts into your page's
- the advanced way (for web developers)
- install the nubs npm package
npm install @benev/nubs
- import nubs elements, register them to the dom
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(), ) )
- install the nubs npm package
how to start using nubs
- let's add some cool nub devices to your html
<body>
<nub-stick></nub-stick>
- it's a mobile-friendly thumbstick!
- it will emit
nub_cause
events
<nub-pointer></nub-pointer>
- also emits
nub_cause
events - this one doesn't render any ui (all of the "real" devices are like this)
- also emits
- wrap your nub elements inside a
<nub-context>
<nub-context> <nub-keyboard></nub-keyboard> <nub-pointer></nub-pointer> <nub-stick name=Stick1></nub-stick> <nub-stick name=Stick2></nub-stick> </nub-context>
- 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 likeforward
rather than the causes
- nub-context is for grouping nub devices
understanding cause and effect in nubs
nub_cause
events: like keyboard key presses and mouse movements. all nub devices like<nub-keyboard>
or<nub-stick>
dispatch these events.nub_effect
events: like "forward" or "open menu". these are dispatched by a<nub-context>
element, based on the user's bindings. the bindings allow users to customize which effects are triggered by which causes.
nubs element reference
devices
<nub-keyboard>
(real device) listens to real mouse or touch inputs.<nub-pointer>
(real device) listens to real keyboard inputs.<nub-stick>
(virtual device) mobile-friendly thumbstick.<nub-stickpad>
(virtual device) thumbstick area, which centers the stick wherever your touch starts.<nub-lookpad>
(virtual device) area for tracking touch movements, to emulate a mouse.<nub-gridboard>
(hybrid device)
bindings, editing, and troubleshooting
<nub-context>
listens fornub_cause
events, and dispatchesnub_effect
events, based on the currentbindings
. only listens tonub_cause
events nested within the nub-context element.<nub-editor>
interface for users to customize their bindings.<nub-visualizer>
see what's going on, whichnub_effect
events are being dispatched.