Skip to content

Commit

Permalink
reformat README
Browse files Browse the repository at this point in the history
  • Loading branch information
@vincentfretin
vincentfretin committed Aug 12, 2024
1 parent e924510 commit 7640508
Showing 1 changed file with 101 additions and 58 deletions.
159 changes: 101 additions & 58 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,15 +14,15 @@ For [A-Frame](https://aframe.io).

### API

| 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. | |
| 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
| 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. | |
| 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

Expand Down Expand Up @@ -71,10 +71,9 @@ require('aframe-cursor-teleport-component');

```html
<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-entity id="cameraRig" cursor-teleport="cameraRig: #cameraRig; cameraHead: #head">
<a-entity id="head" position="0 1.6 0" camera look-controls="reverseMouseDrag: true"></a-entity>
</a-entity>
</a-scene>
```

Expand All @@ -84,13 +83,17 @@ To add collision objects, simply identify them with a selector:

```html
<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>
<!-- camera rig -->
<a-entity id="cameraRig" cursor-teleport="cameraRig: #cameraRig; cameraHead: #head; collisionEntities: .collision">
<a-entity id="head" position="0 1.6 0" camera look-controls="reverseMouseDrag: true"></a-entity>
</a-entity>

<!-- collidable entity -->
<a-entity
class="collision"
position="0 -0.05 0"
geometry="primitive: box; width: 8; height: 0.1; depth: 8"
></a-entity>
</a-scene>
```

Expand All @@ -99,17 +102,30 @@ To add collision objects, simply identify them with a selector:
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
<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 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.6 0" camera look-controls="reverseMouseDrag: true"></a-entity>
</a-entity>

<!-- collidable entity -->
<a-entity
class="collision"
position="0 -0.05 0"
geometry="primitive: box; width: 8; height: 0.1; depth: 8"
></a-entity>

<!-- UI element -->
<a-entity
class="clickable"
color-change
geometry="primitive: octahedron"
scale="0.2 0.2 0.2"
position="-0.8 1 -1.5"
></a-entity>
</a-scene>
```

Expand All @@ -119,18 +135,41 @@ This component works with [aframe-blink-controls](https://github.com/jure/aframe

```html
<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>
<!-- camera rig -->
<a-entity
id="cameraRig"
cursor-teleport="cameraRig: #cameraRig; cameraHead: #head; collisionEntities: .collision; ignoreEntities: .clickable"
>
<a-entity id="head" position="0 1.6 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 -0.05 0"
geometry="primitive: box; width: 8; height: 0.1; depth: 8"
></a-entity>

<!-- UI element -->
<a-entity
class="clickable"
color-change
geometry="primitive: octahedron"
scale="0.2 0.2 0.2"
position="-0.8 1 -1.5"
></a-entity>
</a-scene>
```

Expand All @@ -141,28 +180,32 @@ You can do that like this:

```html
<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);
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`:

```html
<a-entity id="cameraRig" character-controller 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
id="cameraRig"
character-controller
cursor-teleport="cameraRig: #cameraRig; cameraHead: #head; collisionEntities: .collision; ignoreEntities: .clickable,.navmesh-hole"
>
<a-entity id="head" position="0 1.6 0" camera look-controls="reverseMouseDrag: true"></a-entity>
</a-entity>
```

Expand Down

0 comments on commit 7640508

Please sign in to comment.