👂 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>
```

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(),
  )
)

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)
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 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 <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 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.
<nub-editor> interface for users to customize their bindings.
<nub-visualizer> see what's going on, which nub_effect events are being dispatched.

Keywords

FAQs

What is @benev/nubs?

Is @benev/nubs popular?

Is @benev/nubs well maintained?

Package last updated on 04 Nov 2023

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@benev/nubs

🔘 nubs

install nubs onto your html page

how to start using nubs

understanding cause and effect in nubs

nubs element reference

Keywords

Related posts

Socket Integrates With Bun 1.3’s Security Scanner API

North Korea’s Contagious Interview Campaign Escalates: 338 Malicious npm Packages, 50,000 Downloads