❤
npm
Sign UpSign In

@benev/nubs
TypeScript icon, indicating that this package has built-in type declarations

0.3.0-dev.2 • Public • Published

🔘 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>
  • 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

  1. 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)
  2. 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.

Readme

Keywords

Package Sidebar

Install

npm i @benev/nubs

Repository

github.com/benevolent-games/nubs

Homepage

github.com/benevolent-games/nubs#readme

Weekly Downloads

18

Version

0.3.0-dev.2

License

MIT

Unpacked Size

351 kB

Total Files

593

Last publish

Collaborators

  • chasemoskal
Try on RunKit
Report malware