more detailed instructions for modification

docs/aframe-oculus-hands.md

@@ -1,19 +1,83 @@
-# components
+# **Oculus Quest Hands**
 
-## portal
+![image](https://imgur.com/UQ2pqAd.gif =150x150)
 
-Requires `camera` component. Renders view from another camera in scene to a texture on another object.
+A set of components meant to emulate the behavior and controls of the virtual hands as seen in the [First Steps](https://www.oculus.com/experiences/quest/1863547050392688) app for the [Oculus Quest](https://www.oculus.com/quest/).
 
-### Example
+These components enable the ability to pick up, move and drop virtual items with the Oculus Touch controllers. This module includes all the components necessary to enable this functionality. 
 
+_These components should **not** be used in conjunction with other hand-control modules or components_, such as `hand-controls` or `super-hands` components. The prescribed model may, however, be modified to replace the default hand model for the `hand-controls` component.
+
+The design file for the hand model can be found in [`./src/assets`](./src/assets). The model may be edited in [Autodesk Maya](https;//autodesk.com/maya) to add additional [gestures](#Gestures) or customize [alignment targets](#Alignments). Additional 3D editors such as Blender may be supported in the future. Please refrain from adding crude or insulting gestures to the model.
+
+
+Support may eventually be added for [Oculus Hand Tracking](https://www.oculus.com/blog/introducing-hand-tracking-on-oculus-quest-bringing-your-real-hands-into-vr/?locale=en_US).
+
+<hr>
+
+## **oculus-quest-hands**
+
+<hr>
+
+A wrapper for [oculus-touch-controls](https://aframe.io/docs/master/components/oculus-touch-controls.html) that adds additional events, methods and a [prescribed hand model](./assets.md). This model supports a range of pre-animated poses and gestures to accommodate common gestures a user might make in VR.
+
+Advanced users may consider replacing native grab and drop methods with their preferred grab controls. To use a custom grab or drop method, please use 
+```js
+AFRAME.utils.extendComponent('oculus-quest-hands', 'grab', (grabEvent) => {/*your custom grab code here*/});
+```
+
+The appearance can be modified with [A-Frame 'material' component](https://aframe.io/docs/master/components/material.html).
+
+**Examples**
 ```html
-<a-entity id="cctv" camera="fov: 120; active: false;" spectator="screen: #tv; fps: 25;"></a-entity>
-<a-entity id="tv" geometry="primitive: plane;"></a-entity>
+<!--     with url(path/to/asset);    -->
+<a-entity id="leftHand" 
+	 oculus-quest-hands="model: url(./handLeft.glb); hand: left; camera: #vr-camera;"
+	 material="color: blue;">
+</a-entity>
 ```
+```html
+<!--     with asset-item   -->
+
+<a-asset-item id="md-hand" src="path/to/handLeft.glb"></a-asset-item>
 
-### Component Properties
+<a-entity id="leftHand" 
+	 oculus-quest-hands="model: #md-hand hand: left; camera: #vr-camera;"
+	 material="color: blue;">
+</a-entity>
+```
 
-| property | type | default  |  usage  |
+**Properties**
+| Property | Property Type | Default Value |  Description  |
 |---|---|---|---|
-|  screen | selector |  `null` |  the entity to apply the screen to |
-|  fps | number  |  `30.00`  |  the refresh rate of the screen texture. _Increasing this number impacts performance_ |
+|  model | _asset_ |  `./handRight.glb` | The path to the prescribed hand model in glb format. |
+|  hand | _string_  |  'right'  | The hand this entity represents. Can be one of 'right' or 'left' |
+|  camera | _selector_  |  `null`  | The height of the rectangle. |
+|  debug | _boolean_  |  `false`  | Show debug information and log all events to console. |
+
+<hr>
+
+### Gestures
+
+Gestures are stored as animation targets in the [prescribed hand model](./assets.md). 
+
+Several poses are triggered by default controller events such as _triggertouchstart_ and _gripdown_. All gestures and poses may be triggered with the addition of a new state or by an event of type 'pose' with the detail of `{pose: 'posename'}`:
+```js
+var leftHandEl = document.querySelector('#leftHand');
+leftHandEl.emit('pose',{pose: 'hold-tennisball'});
+```
+
+**Available ready-made gestures**
+| Gesture | Event(s) | State |
+|---|---|---|
+|  fist | _gripdown_ |  fist |
+|  grab | _gripdown_ |  holding-something |
+|  hold-hammer | _grab_, _hold_ |  holding-hammer |
+|  hold-tennisball | _grab_, _hold_ |  holding-tennisball |
+|  hold-brick | _grab_, _hold_ |  holding-brick |
+|  hold-pistol | _grab_, _hold_ |  holding-pistol |
+|  hold-sword | _grab_, _hold_ |  holding-sword |
+
+### Alignments
+
+The presribed hand model includes a number of transforms which assist in aligning objecst to different hand gestures when they are picked up. WHich alignment a grabbed item aligns to may be configured with the ['grabbable' component](#grabbable).