https://github.com/c-frame/aframe-cursor-teleport
An A-Frame component for navigating scenes on non-VR devices
https://github.com/c-frame/aframe-cursor-teleport
Last synced: about 1 year ago
JSON representation
An A-Frame component for navigating scenes on non-VR devices
- Host: GitHub
- URL: https://github.com/c-frame/aframe-cursor-teleport
- Owner: c-frame
- License: mit
- Created: 2020-07-27T23:21:40.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2025-02-21T10:43:32.000Z (over 1 year ago)
- Last Synced: 2025-04-02T03:54:49.765Z (about 1 year ago)
- Language: JavaScript
- Size: 12.9 MB
- Stars: 34
- Watchers: 3
- Forks: 13
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
## aframe-cursor-teleport-component
[](https://npmjs.org/package/aframe-cursor-teleport-component)
[](https://npmjs.org/package/aframe-cursor-teleport-component)
A simple A-Frame component for navigating scenes on non-VR devices. When combined with A-Frame's cursor and look-controls components, this allows users to freely explore A-Frame scenes using device orientation and touch on mobile or using the mouse on desktop.
- [Live Example - Basic](https://c-frame.github.io/aframe-cursor-teleport/examples/basic/index.html)
- [Live Example - Custom Collision](https://c-frame.github.io/aframe-cursor-teleport/examples/custom/index.html)
For [A-Frame](https://aframe.io).
### API
| Property | Description | Default Value |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- | ------------- |
| enabled | Enable or disable the component | true |
| cameraRig | Selector of the camera rig to teleport | |
| cameraHead | Selector of the scene's active camera | |
| cursorColor | Color of the cursor, default blue | '#4d93fd' |
| cursorType | Type of the cursor, cylinder or ring | 'cylinder' |
| collisionEntities | Selector of the meshes used to check the collisions. If no value provided a plane at Y=0 is used. | |
| defaultPlaneSize | Size of the default plane created for collision when `collisionEntities` is not specified | 100 |
| ignoreEntities | Selector of meshes that may obstruct the teleport raycaster, like UI or other clickable elements. | |
| landingNormal | Normal vector to detect collisions with the `collisionEntities` | (0, 1, 0) |
| landingMaxAngle | Angle threshold (in degrees) used together with `landingNormal` to detect if the mesh is so steep to jump to it. | 45 |
### Events
The `cursor-teleport` component will emit two events:
- `navigation-start`: Entity beginning travel to a destination.
- `navigation-end`: Entity has reached destination.
### Installation
#### Browser
Install and use by directly including the [browser files](dist):
```html
My A-Frame Scene
```
#### npm
Install via npm:
```bash
npm install aframe-cursor-teleport-component
```
Then require and use.
```js
require('aframe');
require('aframe-cursor-teleport-component');
```
### Usage
#### Basic Setup
```html
```
#### Collision Entities
To add collision objects, simply identify them with a selector:
```html
```
#### Ignored Entities
If your scene has interactive entities that should not initiate a teleport when clicked, you can add them to the ignoredEntities array using a selector:
```html
```
#### Use with aframe-blink-controls
This component works with [aframe-blink-controls](https://github.com/jure/aframe-blink-controls) allowing for easy-to-use navigation across virtually all devices:
```html
```
#### Use with simple-navmesh-constraint
You should disable the `simple-navmesh-constraint` component during the navigation transition.
You can do that like this:
```html
AFRAME.registerComponent('character-controller', {
events: {
'navigation-start': function () {
if (this.el.hasAttribute('simple-navmesh-constraint')) {
this.el.setAttribute('simple-navmesh-constraint', 'enabled', false);
}
},
'navigation-end': function () {
if (this.el.hasAttribute('simple-navmesh-constraint')) {
this.el.setAttribute('simple-navmesh-constraint', 'enabled', true);
}
}
}
});
```
Then add `character-controller` component to your cameraRig entity. You also probably want to add `.navmesh-hole` to the `cursor-teleport`'s `ignoreEntities`:
```html
```
#### teleportTo API
You can use the same teleport animation programmatically to teleport to a destination knowing
the position and quaternion (optional):
```js
const cameraRig = document.getElementById('cameraRig');
const cursorTeleport = cameraRig.components['cursor-teleport'];
cursorTeleport.teleportTo(destination.object3D.position, destination.object3D.quaternion);
```
Look at the source code of the basic example, the black button triggers the teleportation to the black arrow on the second platform.