Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/felixtrz/xrkeys
Super performant WebXR keyboard
https://github.com/felixtrz/xrkeys
Last synced: 3 months ago
JSON representation
Super performant WebXR keyboard
- Host: GitHub
- URL: https://github.com/felixtrz/xrkeys
- Owner: felixtrz
- License: mit
- Created: 2023-09-04T05:58:56.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-09-05T00:59:46.000Z (over 1 year ago)
- Last Synced: 2024-02-14T05:35:07.144Z (12 months ago)
- Language: TypeScript
- Size: 17 MB
- Stars: 16
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-webxr-development - XRKeys - badge] - A highly performant and plug-and-play WebXR keyboard library for Three.js applications (Interaction / XR Interaction)
README
# XRKeys
[](https://badge.fury.io/js/xrkeys)
[](https://www.typescriptlang.org/)
[](/LICENSE.md)
A highly performant and plug-and-play WebXR keyboard library for Three.js applications. XRKeys empowers your WebXR applications with typing capabilities at the minimal expense of just **two draw calls**, while eliminating the need for extra setup such as loading fonts for the keyboard.
## Features
- 🔌 **Plug-and-Play:** No need for extra setup like loading fonts for the keyboard. Just install and use it right away.
- ⚡️ **High Performance:** Requires only 2 drawcalls, minimal impact on performance of your WebXR applications.
- 🌍 **Three.js Compatible:** Specifically built for Three.js WebXR applications.
## Demo App
A demo app has been built using Three.js to showcase XRKeys in action. You can check out the demo app at https://felixtrz.github.io/xrkeys/ to see how XRKeys works and to get a feel for its capabilities.
This demo app is a great resource for developers who are considering using XRKeys in their projects. It provides a hands-on experience with the library and will give you a better understanding of how it works and what it can do.
## Installation
To install XRKeys, simply run the following command in your terminal:
```sh
$ npm install xrkeys
```
Or if you prefer using Yarn:
```sh
$ yarn add xrkeys
```
## Usage
Using XRKeys is simple. First, import the package in your WebXR project:
```js
import XRKeys from 'xrkeys';
```
> **_NOTE:_** NOTE: XRKeys requires Three.js as a peer dependency, make sure to have a recent version installed.
Then, create an instance of the XR keyboard:
```js
const keyboard = await XRKeys.create();
```
The XRKeys object created extends [THREE.Group](https://threejs.org/docs/#api/en/objects/Group), and can be used as such. Setup the keyboard and add it to your scene:
```js
// listen for keypress events
keyboard.addEventListener('keypress', (e) => {
console.log('Key pressed: ' + e.key);
});
// you can bind a custom function to the enter key
keyboard.onEnter = (text) => {
console.log('Entered text: ' + text);
};
scene.add(keyboard);
```
Update the keyboard in your render loop:
```js
function render() {
// update the keyboard with a target ray and a pressing flag
const targetRaySpace = renderer.xr.getController(0);
keyboard.update(targetRaySpace, triggerIsPressed);
// you can also access the keyboard's text content anytime
console.log(keyboard.text);
}
```
## API Reference
### `XRKeysConfig` type
`XRKeysConfig` is an object type that can have the following optional properties:
- `path?: string`: Path override for custom keyboard model.
- `keyMaskOffset?: number`: Z Offset for the key mask.
- `hoverColor?: string`: Color of the key mask when hovered.
- `pressedColor?: string`: Color of the key mask when pressed.
### `XRKeys` class
`XRKeys` is a class that extends `THREE.Group`.
#### Properties
- `activeKeyboard: THREE.Mesh`: Returns the active keyboard mesh.
- `activeKeysetIndex: number`: Returns the index of the active keyset.
- `text: string`: Returns the text inputted using the keyboard.
- `onEnter: (text: string) => void`: Callback function called when the Enter key is pressed.
#### Methods
- `static create(config?: XRKeysConfig): Promise`: Static method that creates and returns a promise that resolves to an `XRKeys` instance. Takes an optional `XRKeysConfig` object as a parameter.
- `update(targetRaySpace: THREE.Object3D, pressed: boolean): void`: Method to update the keyboard based on the target ray space and whether a key is being pressed.
## License
[MIT License](/LICENSE.md) © 2023 Felix Zhang