https://github.com/justinfrost47/aframe-virtual-joystick
aframe-virtual-joystick is a simple aframe component that integrates virtual joystick to touch enabled devices for A-frame
https://github.com/justinfrost47/aframe-virtual-joystick
3d aframe aframe-component joystick touch vr
Last synced: 6 months ago
JSON representation
aframe-virtual-joystick is a simple aframe component that integrates virtual joystick to touch enabled devices for A-frame
- Host: GitHub
- URL: https://github.com/justinfrost47/aframe-virtual-joystick
- Owner: JustinFrost47
- Created: 2024-10-28T18:03:10.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2024-10-28T19:16:52.000Z (7 months ago)
- Last Synced: 2024-10-28T19:24:01.183Z (7 months ago)
- Topics: 3d, aframe, aframe-component, joystick, touch, vr
- Language: JavaScript
- Homepage:
- Size: 97.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: Readme.md
Awesome Lists containing this project
README
# aframe-virtual-joystick
`aframe-virtual-joystick` is an A-Frame component that integrates a virtual joystick into your VR scene. This joystick enables easy navigation in VR environments, especially for mobile and touch-based devices. The joystick can be customized to fit the look and feel of your application.
## Installation
You can install the package via npm:
```bash
npm install aframe-virtual-joystick
```
Alternatively, you can include the script tag in your HTML file:
```html
```
Then, import the package into your A-Frame project:
```javascript
import 'aframe-virtual-joystick';
```
## Usage
To use the `joystick` component in your A-Frame scene, ensure to add `id="camera"` to your camera element, or create a new camera entity with `id="camera"`:
```html
```
### Example 1 (Default):
```html
```
This setup makes the virtual joystick follow the default behavior. The left half of the touch screen will be reserved for movement, similar to most modern games.
### Example 2 (Custom Parameters):
```html
```
This example demonstrates how to customize the joystick's appearance and behavior.
## Component Parameters
The `joystick` component supports various parameters for customization. You can either pass these parameters directly in the HTML or use the default settings.
### Available Parameters
- **`joystickAreaStyle`**: Customize the joystick area with CSS. Control the dimensions, position, background, and appearance of the joystick. Dragging on this area will trigger the movement joystick For example:
```
"position:fixed; display:block; width:40%; height:100%; left:10px; bottom:10px; background-color:rgba(255,255,255,0.1); z-index:20;"
```
- **`textOverlayStyle`**: Customize the text overlay appearance with CSS, controlling the font, position, size, and opacity. Example:
```
"position:fixed; bottom:10px; left:10px; font-size:14px Arial; opacity:0.5;"
```
- **`textContent`**: Set the text displayed on the joystick overlay (useful for instructions). For example:
```
"Use joystick to navigate"
```
- **`speedReductionFactor`**: Controls the movement speed relative to the joystick force. Higher values reduce speed, while lower values increase speed. Default is `50`.
### Default Parameters
- **`joystickAreaStyle`** (string):
```
"position:fixed; display:block; width:50%; height:100%; left:0px; bottom:0px; background-color:rgba(0,0,0,0); z-index:20;"
```
by default the left half of the screen is reserved as joystickArea
- **`textOverlayStyle`** (string):
```
"position:fixed; bottom:0px; left:0px; margin-top:99%; font-size:12px Roboto; opacity:.3;"
```
it is supposed to be shown on the bottom region
- **`textContent`** (string): `""` (no text by default)
- **`speedReductionFactor`** (number): `50` (lower values increase speed)
## Event Binding
The joystick component uses **NippleJS** for event handling. Events such as `move` and `end` are bound to provide a responsive and interactive experience. `moveData` is updated with the joystick’s `force` and `angle`, which are then used to adjust the camera's position.
## Example Configuration
Here’s an example that demonstrates all parameters with custom values:
```html
```
## Notes
- The `joystick` component checks for touch capability. It only initializes if the device supports touch events.
- The joystick component assumes that there’s an element with the `camera` ID in the scene.
## License
This project is licensed under the MIT License.