aframe-cursor-teleport-component
Advanced tools
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.
For A-Frame.
| Property | Description | Default Value |
|---|---|---|
| cameraRig | Selector of the camera rig to teleport | |
| cameraHead | Selector of the scene's active camera | |
| collisionEntities | Selector of the meshes used to check the collisions. If no value provided a plane at Y=0 is used. | |
| 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 |
The cursor-teleport component will emit two events:
navigation-start: Entity beginning travel to a destination.navigation-end: Entity has reached destination.Install and use by directly including the browser files:
<head>
<title>My A-Frame Scene</title>
<script src="https://aframe.io/releases/1.4.2/aframe.min.js"></script>
<script src="https://cdn.jsdelivr.net/gh/c-frame/aframe-cursor-teleport@1.3.0/dist/aframe-cursor-teleport-component.min.js"></script>
</head>
<body>
<a-scene>
<!-- see usage below -->
</a-scene>
</body>
Install via npm:
npm install aframe-cursor-teleport-component
Then require and use.
require('aframe');
require('aframe-cursor-teleport-component');
<a-scene cursor="rayOrigin: mouse">
<a-entity id="cameraRig" cursor-teleport="cameraRig: #cameraRig; cameraHead: #head">
<a-entity id="head" position="0 1.52 0" camera look-controls="reverseMouseDrag: true">
</a-entity>
</a-entity>
</a-scene>
To add collision objects, simply identify them with a selector:
<a-scene cursor="rayOrigin: mouse">
<!-- camera rig -->
<a-entity id="cameraRig" cursor-teleport="cameraRig: #cameraRig; cameraHead: #head; collisionEntities: .collision">
<a-entity id="head" position="0 1.52 0" camera look-controls="reverseMouseDrag: true"></a-entity>
</a-entity>
<!-- collidable entity -->
<a-entity class="collision" position="0 -.05 0" geometry="primitive: box; width: 8; height: .1; depth: 8"></a-entity>
</a-scene>
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:
<a-scene cursor="rayOrigin: mouse" raycaster="objects: .clickable" >
<!-- camera rig -->
<a-entity id="cameraRig" cursor-teleport="cameraRig: #cameraRig; cameraHead: #head; collisionEntities: .collision; ignoreEntities: .clickable">
<a-entity id="head" position="0 1.52 0" camera look-controls="reverseMouseDrag: true"></a-entity>
</a-entity>
<!-- collidable entity -->
<a-entity class="collision" position="0 -.05 0" geometry="primitive: box; width: 8; height: .1; depth: 8"></a-entity>
<!-- UI element -->
<a-entity class="clickable" color-change geometry="primitive: octahedron" scale=".2 .2 .2" position="-.8 1 -1.5"></a-entity>
</a-scene>
This component works with aframe-blink-controls allowing for easy-to-use navigation across virtually all devices:
<a-scene cursor="rayOrigin: mouse" raycaster="objects: .clickable">
<!-- camera rig -->
<a-entity id="cameraRig" cursor-teleport="cameraRig: #cameraRig; cameraHead: #head; collisionEntities: .collision; ignoreEntities: .clickable">
<a-entity id="head" position="0 1.52 0" camera look-controls="reverseMouseDrag: true"></a-entity>
<a-entity laser-controls="hand: left" raycaster="objects: .clickable; far: 100" line="color: red; opacity: 0.75" blink-controls="cameraRig: #cameraRig; teleportOrigin: #head;"></a-entity>
<a-entity laser-controls="hand: right" raycaster="objects: .clickable" line="color: red; opacity: 0.75" blink-controls="cameraRig: #cameraRig; teleportOrigin: #head;"></a-entity>
</a-entity>
<!-- collidable entity -->
<a-entity class="collision" position="0 -.05 0" geometry="primitive: box; width: 8; height: .1; depth: 8"></a-entity>
<!-- UI element -->
<a-entity class="clickable" color-change geometry="primitive: octahedron" scale=".2 .2 .2" position="-.8 1 -1.5"></a-entity>
</a-scene>
You should disable the simple-navmesh-constraint component during the navigation transition.
You can do that like this:
<script>
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);
}
},
},
});
</script>
Then add character-controller component to your cameraRig entity. You also probably want to add .navmesh-hole to the cursor-teleport's ignoreEntities:
<a-entity id="cameraRig" cursor-teleport="cameraRig: #cameraRig; cameraHead: #head; collisionEntities: .collision; ignoreEntities: .clickable,.navmesh-hole">
<a-entity id="head" position="0 1.52 0" camera look-controls="reverseMouseDrag: true"></a-entity>
</a-entity>
FAQs
Simple teleport navigation for non-XR devices.
We found that aframe-cursor-teleport-component demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
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.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.