Documenting a quick short tutorial on how to add this library to your project and make something pick-upabble

[kylebakerio]

1. add libraries:

    <script src="https://unpkg.com/super-hands/dist/super-hands.min.js"></script>
    <script src="https://cdn.jsdelivr.net/gh/n5ro/aframe-physics-system@v4.0.1/dist/aframe-physics-system.js"></script>
    <script src="https://unpkg.com/aframe-event-set-component@^4.1.1/dist/aframe-event-set-component.min.js"></script>
    <script src="https://unpkg.com/aframe-physics-extras/dist/aframe-physics-extras.min.js"></script>

2. add physics:
   add the physics component to your scene
   note: trying physics="gravity: 0" can sometimes help with debugging some issues, try at your own risk.

`<a-scene physics>`

3. add mixins
   add these mixins within your <a-assets>

        <a-mixin id="all-interactions"
                 hoverable grabbable stretchable draggable
                 event-set__hoveron="_event: hover-start; material.opacity: 0.7; transparent: true"
                 event-set__hoveroff="_event: hover-end; material.opacity: 1; transparent: false"
                 dynamic-body
        ></a-mixin>

        <a-mixin id="grab-move"
                 hoverable grabbable draggable
                 event-set__hoveron="_event: hover-start; material.opacity: 0.7; transparent: true"
                 event-set__hoveroff="_event: hover-end; material.opacity: 1; transparent: false"
                 dynamic-body="shape: box; sphereRadius: 0.1"
        ></a-mixin>
        
        <a-mixin id="physics-hands"
                 physics-collider phase-shift
                 collision-filter="collisionForces: false"
                 static-body="shape: sphere; sphereRadius: 0.02"
                 super-hands="colliderEvent: collisions;
                              colliderEventProperty: els;
                              colliderEndEvent: collisions;
                              colliderEndEventProperty: clearedEls;"
        ></a-mixin>

3.5 make it efficient
add the following component to your project:

      AFRAME.registerComponent('phase-shift', {
       init: function () {
         var el = this.el
         el.addEventListener('gripdown', function () {
           el.setAttribute('collision-filter', {collisionForces: true})
         })
         el.addEventListener('gripup', function () {
           el.setAttribute('collision-filter', {collisionForces: false})
         })
       }
     });

4. give hands the ability to grab
   add the physics-hands mixin to your hand entities

        <a-entity id="rhand" mixin="physics-hands"
                hand-controls="hand: right">
      </a-entity>
      <a-entity id="lhand" mixin="physics-hands"
                hand-controls="hand: left">
      </a-entity>

5. make a floor things won't fall through
   add static-body component to your ground and whatever surfaces you want to be able to put things on

<a-box static-body width="100" height="0.01" depth="100" visible="false"></a-box>
<!-- if you already have a ground, you should just be able to add static-body to it -->

6. make your thing able to be picked up
   add the mixin 'all-interactions' or 'grab-move'

      <a-entity class="cube" mixin="cube all-interactions" position="0 0.265 -1" material="color: red"></a-entity>

Might be good to have this somewhere as a helpful starting point. From here, people can start modifying. This is basically what I extrapolated from the working demo I found.

[wmurphyrd]

@kylebakerio this is great! Would you please send a PR to add this as either on the examples index.html or a new .md with a link from the readme?

Note on 3.5, phase-shift is not for performance, it allows you to control whether your hands pass through solid objects (gripup) or collide with them (gripdown)

[kylebakerio]

Oh, good to know!

I'll gladly do that. I can easily just make a new .md with these instructions and link to it, but I'm curious if there's a more ideal form. I might chew on the idea a bit more?

Not sure how you are suggesting with a PR on the examples index.html, could you clarify what you had in mind?

[wmurphyrd]

@kylebakerio re the index.html, I just meant you could add this content to the examples html page if you wanted. But the md option is also good and you've already written it out in this format

[kylebakerio]

I understand now about the index.html idea, I forgot that you have that text file there and was wondering how to include this info within a VR space, haha.

I added the .md, once accepted I can pull to request a reference within the README.

I went ahead and added a dynamic fetch + MD to HTML client side conversion in the example index.html, so that we can avoid copy/pasting and avoid it falling out of date in the future. Let me know what you think. Formatting may need to be updated to allow the longer lines of code to be pretty, but it's getting late here.

[kylebakerio]

(Just wanted to ping to ask if anything was needed on that pull request. I've referred to this issue twice in the last month, figured it'd be nice to be able to point them to the finished doc.)

[rchovatiya88]

Thank so much @kylebakerio and @wmurphyrd - i can confirm this works really well I also documented in the ReadMe of my demo project- https://github.com/rchovatiya88/chessvr

[kylebakerio]

Nice. I imagine using networked-aframe will come up soon, so I'll probably hear from you again soon. ;)