Check in of initial documentation

Author: SimonDarksideJ

.gitattributes

@@ -0,0 +1,11 @@
+*.cs text diff=csharp
+.gitattributes text
+*.txt text
+*.md text
+
+*.asset eol=lf
+*.controller eol=lf
+*.prefab eol=lf
+*.meta eol=lf
+*.mat eol=lf
+*.anim eol=lf

CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing
+
+The Mixed Reality Toolkit welcomes contributions from the community. 
+If you have any questions, please reach out on the [HoloLens forums](https://forums.hololens.com/).
+
+# Process
+
+1. [Make a proposal](https://github.com/Microsoft/MixedRealityToolkit-Unity/issues) (either new, or for one of the elements in our backlog)
+2. Implement the proposal and its tests.
+3. Rebase commits to tell a compelling story.
+4. Start a pull request & address comments.
+5. Merge.
+
+# Proposal
+
+For things like fixing typos and small bug fixes, you can skip this step.
+
+If your change is more than a simple fix, please don't just create a big pull request. 
+Instead, start by [opening an issue](https://github.com/Microsoft/MixedRealityToolkit-Unity/issues) describing the problem you want to solve and how you plan to approach the problem. 
+This will let us have a brief discussion about the problem and, hopefully, identify some potential pitfalls before too much time is spent.
+
+Note:  If you wish to work on something that already exists on our backlog, you can use that work item as your proposal.  
+
+# Implementation
+
+1. Fork the repository. Click on the "Fork" button on the top right of the page and follow the flow.
+2. If your work needs more time, the consider branching off of master else just code in your fork.
+3. Instructions for getting the project building and running the tests are in the [README](README.md). 
+4. Make small and frequent commits that include tests which could be a unity scene showing usage of your feature.
+5. Make sure that all the tests continue to pass.
+6. Ensure the code is [WACK compliant](https://developer.microsoft.com/en-us/windows/develop/app-certification-kit). To do this, generate a Visual Studio solution, right click on project; Store -> Create App Packages. Follow the prompts and run WACK tests. Make sure they all succeed.
+7. Ensure you update the [README](README.md) with additional documentation as needed.
+8. Also update the [MixedRealityToolkit-Unity wiki](https://github.com/Microsoft/MixedRealityToolkit-Unity/wiki) if you think it will be useful for other developers.
+
+# Rebase commits
+
+The commits in your pull request should tell a story about how the code got from point A to point B. 
+Good stories are edited, so you'll want to rebase your commits so that they tell a good story.
+
+Each commit should build and pass all of the tests. 
+If you want to add new tests for functionality that's not yet written, ensure the tests are added disabled.
+
+Don't forget to run git diff --check to catch those annoying whitespace changes.
+ 
+Please follow the established [Git convention for commit messages](https://www.git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines). 
+The first line is a summary in the imperative, about 50 characters or less, and should not end with a period. 
+An optional, longer description must be preceded by an empty line and should be wrapped at around 72 characters. 
+This helps with various outputs from Git or other tools.
+
+You can update message of local commits you haven't pushed yet using git commit --amend or git rebase --interactivewith reword command.
+
+# Pull request
+
+Start a GitHub pull request to merge your topic branch into the [main repository's Dev_Working_Branch](https://github.com/Microsoft/MixedRealityToolkit-Unity/tree/Dev_Working_Branch). 
+(If you are a Microsoft employee and are not a member of the [Microsoft organization on GitHub](https://github.com/Microsoft) yet, please link your Microsoft and GitHub accounts on corpnet by visiting [Open Source at Microsoft](https://opensource.microsoft.com/) before you start your pull request. There's some process stuff you'll need to do ahead of time.)
+If you haven't contributed to a Microsoft project before, you may be asked to sign a [contribution license agreement](https://cla.microsoft.com/). 
+A comment in the PR will let you know if you do.
+
+The project maintainers will review your changes. We aim to review all changes within three business days.
+Address any review comments, force push to your topic branch, and post a comment letting us know that there's new stuff to review.
+
+# Merge
+
+If the pull request review goes well, a project maintainer will merge your changes. Thank you for helping improve MixedRealityToolkit!

External/HowTo/README.md

@@ -0,0 +1,7 @@
+# How to ...
+This readme is intended to document any questions developers might have around how to achieve certain things using the MixedRealityToolkit-vNext.
+
+## How to migrate from the old MixedRealityToolkit to the vNext?
+For now, this should be treated like a completely different project and highly experimental while it's being constructed.
+For the final version, there will be a migration back for basic and advanced users alike.
+

External/ReadMeImages/MRTK-SDK-Example1.jpg

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Microsoft Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

External/ReadMeImages/MRTK-SDK-Example2.jpg

@@ -0,0 +1,132 @@
+# Mixed Reality Toolkit – User SDK approach *(High level)*
+
+## Problem Statement
+
+Current examples / implementations are far too involved and require users to build new scripts / behaviours to build their project.  Users complain the project is too hard to pick up and the current examples are not conducive to implementation (only demonstration)
+
+## Objective
+
+To rearchitect the generic consumption of the Mixed Reality Toolkit to enable users to build scenes through easy to use “drag and drop” components.
+
+
+An example workflow should resemble:
+
+ * Consumer builds a 3D scene
+ * MRTK is added to the project
+ * Add a simple way to define walkable areas (Either through locomotion, free teleportation or restricted teleportation)
+ * Enable selecting of an object in a scene and configuring it for interaction (pickup, push, throw, etc)
+ * Enable animation interactions, e.g. opening doors
+ * Enable passive interactions, interacting one object with another that is in control by the player
+ * Quickly add Speech / Gesture / Focus / Controller services
+
+(purely a working set, needs refining)
+
+The ultimate goal is to deliver new users (and existing) with a rapid way to build projects / scenes, trying to cover the 80/20 rule.
+The simple promise for users building with these controls, is that they should always work, regardless of our plans under the hood for MRTK and preserve the projects they build. 
+
+## High Level required components
+
+In transforming the frontend of the MRTK for consumers to construct their projects / scenes with, we need to define and develop a simple set of prefabs / scripts / Editor options to quickly and easily add MRTK activities / behaviors to a 3D scene (or virtual scene in the case of HoloLens)
+These can be categorized as:
+
+### Scene elements
+
+Scene elements relate to management style components / configuration to activate core components for the MRTK.  Current elements would include:
+
+ * Camera (current MRCP)
+ * Managers (focus / gaze / controllers / motion controllers / etc)
+ * Controllers (scene object collections, interactions)
+
+### Interaction controls
+
+Controls form how the user moves and interacts in the scene, ranging from:
+
+ * Locomotion / Teleportation control
+ * Locomotion / Teleportation boundaries / targets
+ * Speech commands
+ * Gestures
+ * Pointers / Hands
+
+### Reaction Controls
+
+These components relate to things the user will interact with in a scene, enabling the player to affect the scene, ranging from:
+
+ * Grabbing
+ * Pushing
+ * Opening
+ * Pointer targets
+ * Buttons / UX
+ * Hot Zones (reaction-based events from either the player or an interaction control collision)
+ * Highlighting
+
+### UX Systems
+
+In any project the user will need a friendly UX system to assist in their scenes, for example:
+
+ * Menu Systems (Grid / Radial)
+ * Layout components (Grid / Radial / Curved / Layered)
+ * Controller systems (menu overlays for hands / controllers)
+ * Tooltips
+ * Fade Assist
+
+> **This is not an extensive list and subject to debate.**
+
+## Initial Plans
+
+The proposal is to build a small subset of controls that utilize the current functionality of the MRTK, applying the above objectives and principles to define some of the high-Level components.
+
+An initial scene which should support both HL & Immersive (subject to discussion, separate may be easier for now), should walk a user in a common room style scenario.
+
+The example (lending from the Cliffhouse setup) should display a simple room, with hot spot teleport zones and activities that can be performed at each location, something akin to Rick and Morty VR or Job Simulator:
+
+![](External/ReadMeImages/MRTK-SDK-Example1.jpg)![](External/ReadMeImages/MRTK-SDK-Example2.jpg)
+<div style="text-align:center"> Figure 1 : Reference examples (Rick and Morty / Job Simulator) </div>
+
+The example should include a walk-through example for building the scene in Unity that any consumer can follow, starting from the empty room populated with some simple elements, e.g.
+
+ * Buttons that show text on a wall – showing button interaction
+ * Mugs that you can pick up (stretch and empty liquid :P) – showing grabbing / dropping
+ * A puzzle where you slide tiles around a maze – showing pushing constrained objects around
+
+More examples can be added to the same room, building from a simple start.
+We ensure we build the components to meet these objectives and refine as necessary.  The example scene and starter components should then be added to the existing MRTK solution for testing / consumption whilst more are built.
+
+## Work in progress
+
+The team have been working on the initial SDK setup scene with the first components, aims to have (as a start):
+
+ * A starting workroom with defined workplaces
+ * An area to pick up and interact with objects
+ * An area to push objects around, possibly pick up
+ * An area with buttons and UX interactive elements
+ * A UX panel display area
+
+
+### Current working scene
+
+![](External/ReadMeImages/MRTK-SDK-WIP1.png)
+<div style="text-align:center"> Figure 2 : Work in progress example scene 1 </div> 
+
+Elements being built in to the scene:
+
+1. Alcove for object to pick up, thinking a cube, cylinder, cup, picture frame
+2. A contained bin where balls will be dropped from *5 when buttons are pressed. Balls can be pushed around and possibly picked up and thrown
+3. Button table for push interaction UX items
+4. Display frame and information box area.  Should also have some switchable indicators
+5. Drop points for adding new spheres
+
+For HoloLens, the room would not be displayed, and objects should interact with the environment, e.g.
+
+ * Window or shelf for the Alcove (1)
+ * Table for buttons (3) with Display elements in 4 floating
+ * Elements dropped from (5) will just drop and interact with the Spatial Mesh
+
+# Reference Example
+
+VRTK are refactoring / rebuilding their new example scenes for their next release, which show an interesting path for example scenes:
+
+![](External/ReadMeImages/MRTK-SDK-VRTKReference1.png)
+<div style="text-align:center"> Figure 3 : Reference, VRTK new samples </div>
+
+These do look cleaner and easier to digest, this doesn’t change how VRTK is currently implemented which is part of the work detailed here.
+But it is a great showcase for the quality level we should be aiming for which has started with Yoon’s updates to the examples.