diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml new file mode 100644 index 000000000..87eb9d416 --- /dev/null +++ b/.github/workflows/gh-pages.yml @@ -0,0 +1,74 @@ +name: Deploy docs to GitHub Pages + +on: + push: + branches: ["main"] + paths: + [ + "docs/**", + "**/README.md", + "**/CHANGELOG.md", + "Pipelines/Scripts/prepare-pages.ps1", + ] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages +permissions: + contents: read + pages: write + id-token: write + +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + # Build job + build: + runs-on: ubuntu-latest + defaults: + run: + working-directory: docs + steps: + - name: Checkout + uses: actions/checkout@v5 + - name: Copy documentation files + shell: pwsh + run: ${{ github.workspace }}/Pipelines/Scripts/prepare-pages.ps1 -ProjectRoot ${{ github.workspace }} + - name: Setup Ruby + # https://github.com/ruby/setup-ruby/releases/tag/v1.207.0 + uses: ruby/setup-ruby@4a9ddd6f338a97768b8006bf671dfbad383215f4 + with: + ruby-version: "3.3" # Not needed with a .ruby-version file + bundler-cache: true # runs 'bundle install' and caches installed gems automatically + cache-version: 0 # Increment this number if you need to re-download cached gems + working-directory: "${{ github.workspace }}/docs" + - name: Setup Pages + id: pages + uses: actions/configure-pages@v5 + - name: Build with Jekyll + # Outputs to the './_site' directory by default + run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}" + env: + JEKYLL_ENV: production + - name: Upload artifact + # Automatically uploads an artifact from the './_site' directory by default + uses: actions/upload-pages-artifact@v3 + with: + path: docs/_site/ + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/pr_labeler.yaml b/.github/workflows/pr_labeler.yaml index 9a3c67832..a04405afb 100644 --- a/.github/workflows/pr_labeler.yaml +++ b/.github/workflows/pr_labeler.yaml @@ -1,8 +1,9 @@ -name: "PR Labeling" +name: PR Labeling + on: pull_request_target: types: [opened, closed, synchronize, reopened, edited, ready_for_review] - + permissions: contents: read pull-requests: write diff --git a/.github/workflows/validation_mrtk3.yaml b/.github/workflows/validation_mrtk3.yaml index 2f7e1f9c3..24faff603 100644 --- a/.github/workflows/validation_mrtk3.yaml +++ b/.github/workflows/validation_mrtk3.yaml @@ -4,7 +4,7 @@ on: push: branches: - main - - 'feature/*' + - "feature/*" pull_request: jobs: @@ -12,22 +12,22 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v6 + - uses: actions/checkout@v6 - - name: Get Pull Request changes - if: github.event_name == 'pull_request' - run: | - ${{ github.workspace }}/Pipelines/Scripts/gitchanges.ps1 -TargetBranch '${{ github.base_ref }}' -OutputFile '${{ runner.temp }}/build/changed_files.txt' -RepoRoot '${{ github.workspace }}' - shell: pwsh + - name: Get Pull Request changes + if: github.event_name == 'pull_request' + run: | + ${{ github.workspace }}/Pipelines/Scripts/gitchanges.ps1 -TargetBranch '${{ github.base_ref }}' -OutputFile '${{ runner.temp }}/build/changed_files.txt' -RepoRoot '${{ github.workspace }}' + shell: pwsh - - name: Scoped code validation - if: github.event_name == 'pull_request' - run: | - ${{ github.workspace }}/Pipelines/Scripts/validatecode.ps1 -Directory '${{ github.workspace }}' -ChangesFile '${{ runner.temp }}/build/changed_files.txt' - shell: pwsh + - name: Scoped code validation + if: github.event_name == 'pull_request' + run: | + ${{ github.workspace }}/Pipelines/Scripts/validatecode.ps1 -Directory '${{ github.workspace }}' -ChangesFile '${{ runner.temp }}/build/changed_files.txt' + shell: pwsh - - name: Global code validation - if: github.event_name == 'push' - run: | - ${{ github.workspace }}/Pipelines/Scripts/validatecode.ps1 -Directory '${{ github.workspace }}' - shell: pwsh \ No newline at end of file + - name: Global code validation + if: github.event_name == 'push' + run: | + ${{ github.workspace }}/Pipelines/Scripts/validatecode.ps1 -Directory '${{ github.workspace }}' + shell: pwsh diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index d2af6b9de..f2dc97ec1 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,3 +1,3 @@ # Mixed Reality Toolkit Code of Conduct -Contributors of this project must abide by the Mixed Reality Toolkit Organization's [code of conduct](https://github.com/MixedRealityToolkit/MixedRealityToolkit-MVG/blob/main/org-docs/CODE-OF-CONDUCT.md). \ No newline at end of file +Contributors of this project must abide by the Mixed Reality Toolkit Organization's [code of conduct](https://github.com/MixedRealityToolkit/MixedRealityToolkit-MVG/blob/main/org-docs/CODE-OF-CONDUCT.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3aecec2dd..c119f35e4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,15 +6,17 @@ This project welcomes contributions, suggestions, and feedback. All contribution Contributors must abide by the Mixed Reality Toolkit Organization's [code of conduct](https://github.com/MixedRealityToolkit/MixedRealityToolkit-MVG/blob/main/org-docs/CODE-OF-CONDUCT.md), [trademark policy](https://github.com/MixedRealityToolkit/MixedRealityToolkit-MVG/blob/main/org-docs/TRADEMARKS.md), and observe the following procedures: -* [Project Tenets](contributions/project-tenets.md) -* [Code Contributions](contributions/code-contributions.md) -* [Opening and Assessing Issues](contributions/opening-and-assessing-issues.md) -* [Approving Pull Requests](contributions/merging-pull-requests.md) -* [Versioning and Releases](contributions/versioning-and-releases.md) +* [Project tenets](./contributions/project-tenets.md) +* [Code contributions](./contributions/code-contributions.md) +* [Opening and assessing issues](./contributions/opening-and-assessing-issues.md) +* [Approving pull requests](./contributions/merging-pull-requests.md) +* [Versioning and releases](./contributions/versioning-and-releases.md) ### GitHub roles -Project roles are assigned by Maintainers via procedures outlined in the [GOVERNANCE.md](../GOVERNANCE.md) fileContributors may have one for the following roles: +Project roles are assigned by Maintainers via procedures outlined in the [Governance document](./GOVERNANCE.md). + +Contributors may have one for the following roles: * **Read** Read and clone repositories. Open and comment on issues and pull requests. * **Triage** Read permissions plus manage issues and pull requests. @@ -56,7 +58,7 @@ Maintainers have the **maintain** role, which grants write permissions plus mana * Should have participated in multiple code reviews of other PR’s, including those of other Maintainers and Contributors. * Should be active on the Project's community forums. -Maintainers are added and removed via procedures outlined in the [GOVERNANCE.md](./GOVERNANCE.md) file. +Maintainers are added and removed via procedures outlined in the [Governance document](./GOVERNANCE.md). --- Part of MVG-0.1-beta. diff --git a/GOVERNANCE.md b/GOVERNANCE.md index bc0aeb6aa..6870c437c 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -1,8 +1,8 @@ # Governance Policy -This document provides the governance policy for the Mixed Reality Toolkit for Unity Project. Maintainers agree to this policy and to abide by all Project polices, including the [code of conduct](../org-docs/CODE-OF-CONDUCT.md), [trademark policy](../org-docs/TRADEMARKS.md), and [antitrust policy](../org-docs/ANTITRUST.md) by adding their name to the [MAINTAINERS.md](./MAINTAINERS.md) file. +This document provides the governance policy for the Mixed Reality Toolkit for Unity Project. Maintainers agree to this policy and to abide by all Project polices, including the [code of conduct](https://github.com/MixedRealityToolkit/MixedRealityToolkit-MVG/blob/main/org-docs/CODE-OF-CONDUCT.md), [trademark policy](https://github.com/MixedRealityToolkit/MixedRealityToolkit-MVG/blob/main/org-docs/TRADEMARKS.md), and [antitrust policy](https://github.com/MixedRealityToolkit/MixedRealityToolkit-MVG/blob/main/org-docs/ANTITRUST.md) by adding their name to the [MAINTAINERS.md](./MAINTAINERS.md) file. -All projects under the Mixed Reality Toolkit organization are governed by the Steering Committee. The Steering Committee is responsible for all technical oversight, project approval and oversight, policy oversight, and trademark management for the Organization. To learn more about the Steering Committee, visit this link: https://github.com/MixedRealityToolkit/MixedRealityToolkit-MVG/blob/main/org-docs/CHARTER.md +All projects under the Mixed Reality Toolkit organization are governed by the Steering Committee. The Steering Committee is responsible for all technical oversight, project approval and oversight, policy oversight, and trademark management for the Organization. To learn more about the Steering Committee, visit this link: ## 1. Roles diff --git a/LICENSE.md b/LICENSE.md index f5efea740..6e8fd4a19 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Mixed Reality Toolkit Contributors +Copyright (c) 2025, Mixed Reality Toolkit Contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/Pipelines/Scripts/pack-upm.ps1 b/Pipelines/Scripts/pack-upm.ps1 index 51c2b581f..3997f501f 100644 --- a/Pipelines/Scripts/pack-upm.ps1 +++ b/Pipelines/Scripts/pack-upm.ps1 @@ -49,7 +49,7 @@ try { # Update package versions . $PSScriptRoot\update-versions.ps1 -PackagesRoot $ProjectRoot -PrereleaseTag $PrereleaseTag -Revision $Revision -BuildNumber $BuildNumber - # Loop through package directories and copy documentation + # Loop through package directories, copy documentation, and package Get-ChildItem -Path $ProjectRoot/*/package.json | ForEach-Object { $packageName = Select-String -Pattern "org\.mixedrealitytoolkit\.\w+(\.\w+)*" -Path $_ | Select-Object -First 1 @@ -58,7 +58,7 @@ try { } $packageName = $packageName.Matches[0].Value - $packagePath = $_.Directory + $packagePath = $_.DirectoryName $docFolder = "$packagePath/Documentation~" Write-Host "" @@ -73,28 +73,15 @@ try { else { Copy-Item -Path "$ProjectRoot/Pipelines/UPM/Documentation~" -Destination $docFolder -Recurse } - } - - # Package the package directories - Get-ChildItem -Path $ProjectRoot/*/package.json | ForEach-Object { - $currentPackageName = Select-String -Pattern "org\.mixedrealitytoolkit\.\w+(\.\w+)*" -Path $_ | Select-Object -First 1 - - if (-not $currentPackageName) { - return # this is not an MRTK package, so skip - } Write-Host "" Write-Host -ForegroundColor Green "=======================================" Write-Host -ForegroundColor Green "Packing Package" Write-Host -ForegroundColor Green "=======================================" - Write-Host "Package name: $currentPackageName" + Write-Host "Package name: $packageName" - $currentPackageName = $currentPackageName.Matches[0].Value $packageFriendlyName = (Select-String -Pattern "`"displayName`": `"(.+)`"" -Path $_ | Select-Object -First 1).Matches.Groups[1].Value - $packagePath = $_.Directory - $docFolder = "$packagePath/Documentation~" - # build the package npm pack $packagePath diff --git a/Pipelines/Scripts/prepare-pages.ps1 b/Pipelines/Scripts/prepare-pages.ps1 new file mode 100644 index 000000000..e2c2d643e --- /dev/null +++ b/Pipelines/Scripts/prepare-pages.ps1 @@ -0,0 +1,177 @@ +# Copyright (c) Mixed Reality Toolkit Contributors +# Licensed under the BSD 3-Clause + +<# +.PARAMETER ProjectRoot + The root folder of the project. +#> +param( + [Parameter(Mandatory = $true)] + [string]$ProjectRoot +) + +$ProjectRoot = Resolve-Path -Path $ProjectRoot +$docs = Join-Path $ProjectRoot "docs" +$images = Join-Path $docs "images" + +New-Item -Path $images -ItemType Directory -Force +# Copy root README images to docs +Copy-Item -Path (Join-Path $ProjectRoot "images" "*") -Destination $images -Recurse -Force + +Copy-Item -Path (Join-Path $ProjectRoot "org.mixedrealitytoolkit.standardassets" "Textures" "Logos" "MRTK_Logo_White.png") -Destination $images -Force +Copy-Item -Path (Join-Path $ProjectRoot "org.mixedrealitytoolkit.standardassets" "Textures" "Logos" "IconMRTKLogo.png") -Destination $images -Force + +$destination = Join-Path $docs "index.md" +# Create page, add front matter, and copy content +New-Item -Path $destination -ItemType File -Force -Value @" +--- +title: Home +nav_order: 1 +--- + + +"@ +Add-Content -Path $destination -Value (Get-Content -Path (Join-Path $ProjectRoot "README.md")) + +$destination = Join-Path $docs "CONTRIBUTING.md" +# Create page, add front matter, and copy content +New-Item -Path $destination -ItemType File -Force -Value @" +--- +title: Contributing +nav_order: 6 +--- + + +"@ +Add-Content -Path $destination -Value (Get-Content -Path (Join-Path $ProjectRoot "CONTRIBUTING.md")) + +$fileFolder = Join-Path $docs "contributions" +New-Item -Path $fileFolder -ItemType Directory -Force + +Get-ChildItem -Path (Join-Path $ProjectRoot "contributions") -File | ForEach-Object { + # Create file, add front matter, and copy content + $destination = Join-Path $fileFolder $_.Name + $fileTitle = Select-String -Pattern "# (.+)" -Path $_ | Select-Object -First 1 + New-Item -Path $destination -ItemType File -Force -Value @" +--- +title: $($fileTitle.Matches ? $fileTitle.Matches[0].Groups[1] : $_.BaseName) +parent: Contributing +--- + + +"@ + Add-Content -Path $destination -Value (Get-Content -Path $_) +} + +$destination = Join-Path $docs "LICENSE.md" +# Create page, add front matter, and copy content +New-Item -Path $destination -ItemType File -Force -Value @" +--- +title: License +parent: Home +--- + + +"@ +Add-Content -Path $destination -Value (Get-Content -Path (Join-Path $ProjectRoot "LICENSE.md")) + +$destination = Join-Path $docs "MAINTAINERS.md" +# Create page, add front matter, and copy content +New-Item -Path $destination -ItemType File -Force -Value @" +--- +title: Maintainers +parent: Home +--- + + +"@ +Add-Content -Path $destination -Value (Get-Content -Path (Join-Path $ProjectRoot "MAINTAINERS.md")) + +$destination = Join-Path $docs "GOVERNANCE.md" +# Create page, add front matter, and copy content +New-Item -Path $destination -ItemType File -Force -Value @" +--- +title: Governance +parent: Home +--- + + +"@ +Add-Content -Path $destination -Value (Get-Content -Path (Join-Path $ProjectRoot "GOVERNANCE.md")) + +# Convert GitHub admonitions to just-the-docs syntax for in-place docs files +# We leave them checked-in so they render correctly in the GitHub repo, but we convert them for Pages +Get-ChildItem -Path (Join-Path $docs "*" "*.md") -Recurse | ForEach-Object { + $fileContent = Get-Content -Path $_ + Set-Content -Path $_ -Value ($fileContent -replace "> \[!(\w+)\]", { "{: .$("$($_.Groups[1])".ToLower()) }" } -replace "/docs/", "/") +} + +# Loop through package directories and copy documentation +Get-ChildItem -Path (Join-Path $ProjectRoot "*" "package.json") | ForEach-Object { + $packageName = Select-String -Pattern "org\.mixedrealitytoolkit\.\w+(\.\w+)*" -Path $_ | Select-Object -First 1 + + if (-not $packageName) { + return # this is not an MRTK package, so skip + } + + if ($packageName.Matches[0].Value -eq "org.mixedrealitytoolkit.data") { + return # this is a deprecated package, so skip + } + + $packageName = $packageName.Matches[0].Value + $packageFriendlyName = (Select-String -Pattern "`"displayName`": `"(.+)`"" -Path $_ | Select-Object -First 1).Matches.Groups[1].Value + $packagePath = $_.DirectoryName + $packageDocsPath = Join-Path $docs $packageName + + New-Item -Path $packageDocsPath -ItemType Directory -Force + + # Create README, add front matter, and copy content + $packageReadmeDestination = Join-Path $packageDocsPath "index.md" + New-Item -Path $packageReadmeDestination -ItemType File -Force -Value @" +--- +title: $packageFriendlyName +parent: Packages +--- + + +"@ + $readmeContent = Get-Content -Path (Join-Path $packagePath "README.md") + # Convert GitHub admonitions to just-the-docs syntax + Add-Content -Path $packageReadmeDestination -Value ($readmeContent -replace "> \[!(\w+)\]", { "{: .$("$($_.Groups[1])".ToLower()) }" }) + + # Create CHANGELOG, add front matter, and copy content + $packageChangelogDestination = Join-Path $packageDocsPath "CHANGELOG.md" + New-Item -Path $packageChangelogDestination -ItemType File -Force -Value @" +--- +title: Changelog +parent: $packageFriendlyName +--- + + +"@ + Add-Content -Path $packageChangelogDestination -Value (Get-Content -Path (Join-Path $packagePath "CHANGELOG.md")) + + Get-ChildItem -Path (Get-ChildItem -Path $packagePath -Directory) -Recurse -File -Include "*.md" | ForEach-Object { + if ($_.BaseName -in @("LICENSE", "CHANGELOG")) { + return # skip specific files that we don't need to publish through this path + } + + # Create file, add front matter, and copy content + # Remove the ~ from the Documentation~ folder name + $fileFolder = (Join-Path $packageDocsPath ($_.DirectoryName | Split-Path -Leaf)).Replace('~', '') + New-Item -Path $fileFolder -ItemType Directory -Force + $fileDestination = Join-Path $fileFolder $_.Name + $fileTitle = Select-String -Pattern "# (.+)" -Path $_ | Select-Object -First 1 + New-Item -Path $fileDestination -ItemType File -Force -Value @" +--- +title: $($fileTitle.Matches ? $fileTitle.Matches[0].Groups[1] : $_.BaseName) +parent: $packageFriendlyName +--- + + +"@ + $fileContent = Get-Content -Path $_ + # Convert GitHub admonitions to just-the-docs syntax + Add-Content -Path $fileDestination -Value ($fileContent -replace "> \[!(\w+)\]", { "{: .$("$($_.Groups[1])".ToLower()) }" }) + } +} diff --git a/Pipelines/Scripts/repackage-for-release.ps1 b/Pipelines/Scripts/repackage-for-release.ps1 index 02c3f5c71..fc63d55fc 100644 --- a/Pipelines/Scripts/repackage-for-release.ps1 +++ b/Pipelines/Scripts/repackage-for-release.ps1 @@ -57,7 +57,7 @@ try { } $packageName = $packageName.Matches[0].Value - $packagePath = $_.Directory + $packagePath = $_.DirectoryName Write-Host "" Write-Host -ForegroundColor Green "=======================================" @@ -85,7 +85,7 @@ try { $currentPackageName = $currentPackageName.Matches[0].Value $packageFriendlyName = (Select-String -Pattern "`"displayName`": `"(.+)`"" -Path $_ | Select-Object -First 1).Matches.Groups[1].Value - $packagePath = $_.Directory + $packagePath = $_.DirectoryName Write-Output "Packing $packageFriendlyName to $OutputDirectory" npm pack $packagePath -pack-destination $OutputDirectory diff --git a/Pipelines/Scripts/update-versions.ps1 b/Pipelines/Scripts/update-versions.ps1 index c6ddef9a9..cb947ed89 100644 --- a/Pipelines/Scripts/update-versions.ps1 +++ b/Pipelines/Scripts/update-versions.ps1 @@ -70,7 +70,7 @@ Get-ChildItem -Path $PackagesRoot -Filter "package.json" -Recurse | ForEach-Obje $version = $jsonContent.version # Get the package path - $packagePath = $_.Directory + $packagePath = $_.DirectoryName Write-Host "" Write-Host -ForegroundColor Green "=======================================" diff --git a/Pipelines/Scripts/validatecode.ps1 b/Pipelines/Scripts/validatecode.ps1 index 1705279a9..2fdaba050 100644 --- a/Pipelines/Scripts/validatecode.ps1 +++ b/Pipelines/Scripts/validatecode.ps1 @@ -514,7 +514,7 @@ else { # Gets all package.json files one layer down, to determine which folders represent MRTK packages # Also checks TestProjects Get-ChildItem -Path $Paths | ForEach-Object { - $package = $_.Directory + $package = $_.DirectoryName if (-not $package) { $package = $_ } diff --git a/README.md b/README.md index 07e680d12..877e006ac 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,28 @@ # Mixed Reality Toolkit for Unity -![Mixed Reality Toolkit](./Images/MRTK_Unity_header.png) +![Mixed Reality Toolkit](./images/MRTK_Unity_header.png) -![MRTK3 Banner](./Images/MRTK3_banner.png) +![MRTK3 Banner](./images/MRTK3_banner.png) **MRTK3** is the third generation of the Mixed Reality Toolkit for Unity. It's an open source project designed to accelerate cross-platform mixed reality development in Unity. MRTK3 is built on top of [Unity's XR Interaction Toolkit (XRI)](https://docs.unity3d.com/Packages/com.unity.xr.interaction.toolkit@2.1/manual/index.html) and OpenXR. This new generation of MRTK is intended to be faster, cleaner, and more modular, with an easier cross-platform development workflow enabled by OpenXR and the Unity Input System. +[Mixed Reality Toolkit Organization](https://github.com/MixedRealityToolkit) maintains MRTK3, released MRTK3 for general availability (GA), and will announce future releases. + ## Key improvements ### Architecture * Built on Unity XR Interaction Toolkit and the Unity Input System. -* Dedicated to OpenXR, with flexibility for other XRSDK backends -* Open-ended and extensible interaction paradigms across devices, platforms, and applications +* Dedicated to OpenXR, with flexibility for other XRSDK backends. +* Open-ended and extensible interaction paradigms across devices, platforms, and applications. ### Performance * Rewrote and redesigned most features and systems, from UX to input to subsystems. * Zero per-frame memory allocation. -* Tuned for maximum performance on HoloLens 2 and other resource-constrained mobile platforms. +* Tuned for maximum performance on mixed reality devices and other resource-constrained mobile platforms. -### UI +### User Interface * New interaction models (gaze-pinch indirect manipulation). * Updated Mixed Reality Design Language. @@ -28,60 +30,96 @@ * Unified 2D & 3D input for gamepad, mouse, and accessibility support. * Data binding for branding, theming, dynamic data, and complex lists. -## Requirements +### Long Term Support + +* Minimum requirements: OpenXR, Unity 2022.3 LTS, Unity’s XR Interaction Toolkit 3.0. + +## Packages + +| Name | Package | Changelog | +|------|---------|-----------| +| Audio Effects | [org.mixedrealitytoolkit.audio](./org.mixedrealitytoolkit.audio) | [Changelog](./org.mixedrealitytoolkit.audio/CHANGELOG.md) | +| Core Definitions | [org.mixedrealitytoolkit.core](./org.mixedrealitytoolkit.core) | [Changelog](./org.mixedrealitytoolkit.core/CHANGELOG.md) | +| Diagnostics | [org.mixedrealitytoolkit.diagnostics](./org.mixedrealitytoolkit.diagnostics) | [Changelog](./org.mixedrealitytoolkit.diagnostics/CHANGELOG.md) | +| Extended Assets | [org.mixedrealitytoolkit.extendedassets](./org.mixedrealitytoolkit.extendedassets) | [Changelog](./org.mixedrealitytoolkit.extendedassets/CHANGELOG.md) | +| Input | [org.mixedrealitytoolkit.input](./org.mixedrealitytoolkit.input) | [Changelog](./org.mixedrealitytoolkit.input/CHANGELOG.md) | +| Spatial Manipulation | [org.mixedrealitytoolkit.spatialmanipulation](./org.mixedrealitytoolkit.spatialmanipulation) | [Changelog](./org.mixedrealitytoolkit.spatialmanipulation/CHANGELOG.md) | +| Standard Assets | [org.mixedrealitytoolkit.standardassets](./org.mixedrealitytoolkit.standardassets) | [Changelog](./org.mixedrealitytoolkit.standardassets/CHANGELOG.md) | +| Tools | [org.mixedrealitytoolkit.tools](./org.mixedrealitytoolkit.tools) | [Changelog](./org.mixedrealitytoolkit.tools/CHANGELOG.md) | +| UX Components | [org.mixedrealitytoolkit.uxcomponents](./org.mixedrealitytoolkit.uxcomponents) | [Changelog](./org.mixedrealitytoolkit.uxcomponents/CHANGELOG.md) | +| UX Components (Non-Canvas) | [org.mixedrealitytoolkit.uxcomponents.noncanvas](./org.mixedrealitytoolkit.uxcomponents.noncanvas) | [Changelog](./org.mixedrealitytoolkit.uxcomponents.noncanvas/CHANGELOG.md) | +| Windows Speech | [org.mixedrealitytoolkit.windowsspeech](./org.mixedrealitytoolkit.windowsspeech) | [Changelog](./org.mixedrealitytoolkit.windowsspeech/CHANGELOG.md) | + +### Early preview packages + +Some parts of MRTK3 are at earlier stages of the development process than others. Early preview packages can be identified in the Mixed Reality Feature Tool and Unity Package Manager by the `Early Preview` designation in their names. + +The following components are considered to be in early preview. + +| Name | Package | Changelog | +|------|---------|-----------| +| Accessibility | [org.mixedrealitytoolkit.accessibility](./org.mixedrealitytoolkit.accessibility) | [Changelog](./org.mixedrealitytoolkit.accessibility/CHANGELOG.md) | + +It is important to note that the packages may not contain the complete feature set that is planned to be released or they may undergo major, breaking architectural changes before release. -MRTK3 requires Unity 2021.3.21 or higher. In addition, you need the [Mixed Reality Feature Tool for Unity](https://aka.ms/mrfeaturetool) to find, download, and add the packages to your project. +We encourage you to provide any and all feedback to help shape the final form of these early preview features. ## Getting started -[Follow the documentation for setting up MRTK3 packages as dependencies in your project here.](https://learn.microsoft.com/windows/mixed-reality/mrtk-unity/mrtk3-overview/getting-started/setting-up/setup-new-project) Alternatively, you can clone this repo directly to experiment with our template project. However, we *strongly* recommend adding MRTK3 packages as dependencies through the Feature Tool, as it makes updating, managing, and consuming MRTK3 packages far easier and less error-prone. +[Follow the documentation for setting up MRTK3 packages as dependencies in your project here.](./docs/mrtk3-overview/getting-started/setting-up/setup-new-project.md) Alternatively, you can clone this repo directly to experiment with our template project. However, we *strongly* recommend adding MRTK3 packages as dependencies through the Feature Tool, as it makes updating, managing, and consuming MRTK3 packages far easier and less error-prone. ## Supported devices | Platform | Supported Devices | -|---|---| -| OpenXR devices | Microsoft HoloLens 2
Magic Leap 2
Meta Quest 1/2
Windows Mixed Reality (experimental)
SteamVR (experimental)
Oculus Rift on OpenXR (experimental)
Varjo XR-3 (experimental)
**If your OpenXR device already works with MRTK3, let us know!** -| Windows | Traditional flat-screen desktop (experimental) -| And more coming soon! | +|----------|-------------------| +| OpenXR devices | [Android XR](https://www.android.com/xr/)
Microsoft HoloLens 2
Meta Quest
Magic Leap 2
Lenovo ThinkReality A3 (with [Qualcomm Snapdragon Spaces](https://docs.spaces.qualcomm.com/unity/samples/preview/mrtk3-setup-guide))
Windows Mixed Reality (experimental)
SteamVR (experimental)
Varjo XR-3 (experimental)
**If your OpenXR device already works with MRTK3, let us know!** | +| Windows | Traditional flat-screen desktop (experimental) | -## Versioning +## UX building blocks -In previous versions of MRTK (HoloToolkit and MRTK v2), all packages were released as a complete set, marked with the same version number (ex: 2.8.0). Starting with MRTK3 GA, each package will be individually versioned, following the [Semantic Versioning 2.0.0 specification](https://semver.org/spec/v2.0.0.html). (As a result, the '3' in MRTK3 is not a version number!) +| | | | +|---|---|---| +| ![Button](./docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Button.png)
**Button**
A volumetric button optimized for a wide range of input modalities, including poking, gaze-pinch, ray interactions, mouse click, and gamepad. | ![Bounds Control](./docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_BoundsControl.png)
**Bounds Control**
Intent feedback and precision manipulation affordances. | ![Object Manipulator](./docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_ObjectManipulator.png)
**Object Manipulator**
Move and manipulate objects with one or two hands with a wide variety of input modalities. | +| ![Hand Menu](./docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_HandMenu.png)
**Hand Menu**
A hand-anchored collection of UX controls for easy access to quick actions. | ![Near Menu](./docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_NearMenu.png)
**Near Menu**
Collection of UX controls that can be manipulated, pinned, and set to follow the user. | ![Slider](./docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Slider.png)
**Slider**
Adjust a value along a one-dimensional axis. | +| ![Solver](./docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_Solver_Main.png)
**Solver**
Various object positioning behaviors such as tag-along, body-lock, constant view size and surface magnetism. | ![Dialog](./docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Dialog.png)
**Dialog**
Prompt for user action. | ![Slate](./docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Slate.png)
**Slate**
A flat panel for displaying large-format interfaces and content. | +### Figma Toolkit for MRTK3 Preview -Individual versioning will enable faster servicing while providing improved developer understanding of the magnitude of changes and reducing the number of packages needing to be updated to acquire the desired fix(es). +The [prerelease of Figma Toolkit for MRTK3](https://www.figma.com/community/file/1145959192595816999) includes UI components based on Microsoft's new Mixed Reality Design Language introduced in MRTK3. You can use the 2D representations of the components in the design process for creating UI layouts and storyboards. -For example, if a non-breaking new feature is added to the UX core package, which contains the logic for user interface behavior the minor version number will increase (from 3.0.x to 3.1.0). Since the change is non-breaking, the UX components package, which depends upon UX core, is not required to be updated. +## Session videos from Microsoft Mixed Reality Dev Days 2022 -As a result of this change, there is not a unified MRTK3 product version. +| | | | +|---|---|---| +| [![Introducing MRTK3](./docs/mrtk3-overview/images/MRDevDays/MRDD-June8-04-IntroducingMRTK3-1920x1080_w800.png)](https://youtu.be/fjQFkeF-ZOM?list=PLlrxD0HtieHhkPlibqfQf1pGvM0vLNPpL)
**[Introducing MRTK3 – Shaping the future of the MR Developer Experience](https://youtu.be/fjQFkeF-ZOM?list=PLlrxD0HtieHhkPlibqfQf1pGvM0vLNPpL)** | [![Getting started with your first MRTK3 project](./docs/mrtk3-overview/images/MRDevDays/MRDD-04-GettingStartedMRTK3-1920x1080_w800.png)](https://youtu.be/aVnwIq4VUcY?list=PLlrxD0HtieHhkPlibqfQf1pGvM0vLNPpL)
**[Getting started with your first MRTK3 project](https://youtu.be/aVnwIq4VUcY?list=PLlrxD0HtieHhkPlibqfQf1pGvM0vLNPpL)** | [![MRTK3 Interaction building blocks](./docs/mrtk3-overview/images/MRDevDays/MRDD-07-MRTK3BuildingBlocks-1920x1080_w800.png)](https://youtu.be/naVziEJ-yDg?list=PLlrxD0HtieHhkPlibqfQf1pGvM0vLNPpL)
**[MRTK3 Interaction building blocks](https://youtu.be/naVziEJ-yDg?list=PLlrxD0HtieHhkPlibqfQf1pGvM0vLNPpL)** | +| [![Building Rich UI for MR in MRTK3](./docs/mrtk3-overview/images/MRDevDays/MRDD-10-BuildingRichUI-1920x1080_w800.png)](https://youtu.be/g2HF5HMy-2c?list=PLlrxD0HtieHhkPlibqfQf1pGvM0vLNPpL)
**[Building Rich UI for MR in MRTK3](https://youtu.be/g2HF5HMy-2c?list=PLlrxD0HtieHhkPlibqfQf1pGvM0vLNPpL)** | [![Working with Dynamic Data and Theming in MRTK3](./docs/mrtk3-overview/images/MRDevDays/MRDD-12-WorkingWithDynamicData-1920x1080_w800.png)](https://youtu.be/IiTpZ2ojyno?list=PLlrxD0HtieHhkPlibqfQf1pGvM0vLNPpL)
**[Working with Dynamic Data and Theming in MRTK3](https://youtu.be/IiTpZ2ojyno?list=PLlrxD0HtieHhkPlibqfQf1pGvM0vLNPpL)** | [![#Open - Deploy Everywhere with OpenXR and MRTK3](./docs/mrtk3-overview/images/MRDevDays/MRDD-15-HashOpenDeploy-1920x1080_w800.png)](https://youtu.be/LI6lyW9TG9o?list=PLlrxD0HtieHhkPlibqfQf1pGvM0vLNPpL)
**[#Open - Deploy Everywhere with OpenXR and MRTK3](https://youtu.be/LI6lyW9TG9o?list=PLlrxD0HtieHhkPlibqfQf1pGvM0vLNPpL)** | -To help identify specific packages and their versions, MRTK3 provides an about dialog that lists the relevant packages included in the project. To access this dialog, select `Mixed Reality` > `MRTK3` > `About MRTK` from the Unity Editor menu. +### Versioning + +In previous versions of MRTK (HoloToolkit and MRTK v2), all packages were released as a complete set, marked with the same version number (ex: 2.8.0). Starting with MRTK3 GA, each package will be individually versioned, following the [Semantic Versioning 2.0.0 specification](https://semver.org/spec/v2.0.0.html). (As a result, the '3' in MRTK3 is not a version number!) -![About MRTK Panel](Images/AboutMRTK.png) +Individual versioning will enable faster servicing while providing improved developer understanding of the magnitude of changes and reducing the number of packages needing to be updated to acquire the desired fix(es). -## Early preview packages +For example, if a non-breaking new feature is added to the UX core package, which contains the logic for user interface behavior the minor version number will increase (from 3.0.x to 3.1.0). Since the change is non-breaking, the UX components package, which depends upon UX core, is not required to be updated. -Some parts of MRTK3 are at earlier stages of the development process than others. Early preview packages can be identified in the Mixed Reality Feature Tool and Unity Package Manager by the `Early Preview` designation in their names. +As a result of this change, there is not a unified MRTK3 product version. -As of June 2022, the following components are considered to be in early preview. +To help identify specific packages and their versions, MRTK3 provides an about dialog that lists the relevant packages included in the project. To access this dialog, select `Mixed Reality` > `MRTK3` > `About MRTK` from the Unity Editor menu. -| Name | Package Name | -| --- | --- | -| Accessibility | org.mixedrealitytoolkit.accessibility | -| Data Binding and Theming | org.mixedrealitytoolkit.data | +![About MRTK Panel](images/AboutMRTK.png) -The MRTK team is fully committed to releasing this functionality. It is important to note that the packages may not contain the complete feature set that is planned to be released or they may undergo major, breaking architectural changes before release. +## Branch Status -We very much encourage you to provide any and all feedback to help shape the final form of these early preview features. +[Mixed Reality Toolkit Organization](https://github.com/MixedRealityToolkit) maintains and updates MRTK3. We appreciate your feedback, and you can open bugs and feature request at the [Mixed Reality Toolkit for Unity](https://github.com/MixedRealityToolkit/MixedRealityToolkit-Unity) GitHub project. ## Contributing This project welcomes contributions, suggestions, and feedback. All contributions, suggestions, and feedback you submitted are accepted under the [Project's license](./LICENSE.md). You represent that if you do not own copyright in the code that you have the authority to submit it under the [Project's license](./LICENSE.md). All feedback, suggestions, or contributions are not confidential. -For more information on how to contribute Mixed Reality Toolkit for Unity Project, please read [CONTRIBUTING.md](./CONTRIBUTING.md). +For more information on how to contribute Mixed Reality Toolkit for Unity Project, please read the [contributing guidelines](./CONTRIBUTING.md). ## Governance -For information on how the Mixed Reality Toolkit for Unity Project is governed, please read [GOVERNANCE.md](./GOVERNANCE.md). +For information on how the Mixed Reality Toolkit for Unity Project is governed, please read the [Governance document](./GOVERNANCE.md). -All projects under the Mixed Reality Toolkit organization are governed by the Steering Committee. The Steering Committee is responsible for all technical oversight, project approval and oversight, policy oversight, and trademark management for the Organization. To learn more about the Steering Committee, visit this link: https://github.com/MixedRealityToolkit/MixedRealityToolkit-MVG/blob/main/org-docs/CHARTER.md +All projects under the Mixed Reality Toolkit organization are governed by the Steering Committee. The Steering Committee is responsible for all technical oversight, project approval and oversight, policy oversight, and trademark management for the Organization. To learn more about the Steering Committee, visit this link: diff --git a/Tooling/create-assemblyinfo.ps1 b/Tooling/create-assemblyinfo.ps1 index 2412b34d2..61e565f39 100644 --- a/Tooling/create-assemblyinfo.ps1 +++ b/Tooling/create-assemblyinfo.ps1 @@ -12,7 +12,7 @@ Get-ChildItem -Path (Join-Path $gitRoot * package.json) | ForEach-Object { $packageName = $packageName.Matches[0].Value - $asmdefs = Get-ChildItem $_.Directory *.asmdef -Recurse | Select-Object FullName + $asmdefs = Get-ChildItem $_.DirectoryName *.asmdef -Recurse | Select-Object FullName foreach ($asmdef in $asmdefs) { # The AssemblyInfo.cs file will be added as a sibling of the .asmdef location, # so we need to trim off the filename. diff --git a/UnityProjects/MRTKDevTemplate/Assets/UX Theming Example/Themes/README.md b/UnityProjects/MRTKDevTemplate/Assets/UX Theming Example/Themes/README.md index 3077a2c55..a655a5193 100644 --- a/UnityProjects/MRTKDevTemplate/Assets/UX Theming Example/Themes/README.md +++ b/UnityProjects/MRTKDevTemplate/Assets/UX Theming Example/Themes/README.md @@ -2,10 +2,10 @@ All UXComponents controls can easily be themed. New UX elements that are application specific can also be themed quite easily by creating either a new binding profile, or extending the existing UXComponents binding profile. A single script, DataBindingConfigurator, added to the root of a prefab, will do all the necessary binding. -Any data source of any kind such as DataSourceReflection, DataSourceDictionary, or DataSourceJSON can be used to provide theming data. +Any data source of any kind such as DataSourceReflection, DataSourceDictionary, or DataSourceJSON can be used to provide theming data. -The default UXComponents controls uses a ScriptableObject, MRTK_UXComponents_ThemeProfile, as a data source, which is then attached to a DataSourceReflection data source instance to retrieve data from it. +The default UXComponents controls uses a ScriptableObject, MRTK_UXComponents_ThemeProfile, as a data source, which is then attached to a DataSourceReflection data source instance to retrieve data from it. As long as the data source uses the same naming conventions as the UXComponents controls, as seen in the MRTK_UXComponents_ThemeProfile instance of the UXCoreThemeProfile ScriptableObject, it will work properly with the standard UXComponents controls. -Although not a requirement, a helper script called ThemeProvider, can be used to make it easy to set up and provide the right profile. If this is higher in the Scene's GameObject heirarchy than the controls that depend on it, it will automatically be discovered and used because it implements IDataSourceProvider \ No newline at end of file +Although not a requirement, a helper script called ThemeProvider, can be used to make it easy to set up and provide the right profile. If this is higher in the Scene's GameObject hierarchy than the controls that depend on it, it will automatically be discovered and used because it implements IDataSourceProvider. diff --git a/contributions/code-contributions.md b/contributions/code-contributions.md index 58b072ce5..a29b14932 100644 --- a/contributions/code-contributions.md +++ b/contributions/code-contributions.md @@ -1,23 +1,23 @@ -# Code Contributions +# Code contributions This project is an open source project under the BSD 3-Clause license. Community contributions are welcome and appreciated, both for new features and bug fixes. -Contributing to this project is easy. We recommend using the `MRTKDevTemplate` Unity project as a convenient development testbed, as it already includes all of the Project packages as local on-disk dependencies. See [Exploring MRTK3 sample scenes](https://learn.microsoft.com/windows/mixed-reality/mrtk-unity/mrtk3-overview/getting-started/exploring-features/mrtk3-sample-scenes) for more information on how to use this Unity project. +Contributing to this project is easy. We recommend using the `MRTKDevTemplate` Unity project as a convenient development testbed, as it already includes all of the Project packages as local on-disk dependencies. See [Exploring MRTK3 sample scenes](../docs/mrtk3-overview/getting-started/exploring-features/mrtk3-sample-scenes.md) for more information on how to use this Unity project. ## Contribution guide 1. Fork the Project repository to your GitHub account. -2. Clone your forked Project repository by following our guide on [starting from a template project](https://learn.microsoft.com/windows/mixed-reality/mrtk-unity/mrtk3-overview/getting-started/setting-up/setup-new-project) Ensure you have the required tooling, especially the correct Unity version. To ensure you are on the right branch, clone using the command: +2. Clone your forked Project repository by following our guide on [starting from a template project](../docs/mrtk3-overview/getting-started/setting-up/setup-new-project.md) Ensure you have the required tooling, especially the correct Unity version. To ensure you are on the right branch, clone using the command: `` - git clone --branch main YOUR_GIT_URL +git clone --branch main YOUR_GIT_URL `` 3. Create a new branch for your changes or fixes. `` - git checkout -b foobar_fix +git checkout -b foobar_fix `` 4. Open the `MRTKDevTemplate` template project located in `UnityProjects/MRTKDevTemplate`. You can add the project to your Unity Hub for easy access. diff --git a/contributions/code-owners.md b/contributions/code-owners.md index e013ed7b8..6c993389d 100644 --- a/contributions/code-owners.md +++ b/contributions/code-owners.md @@ -1,4 +1,4 @@ -# Code Owners +# Code owners Code owners are Contributors that a maintain particular parts of the Project, and are defined in [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) file. @@ -22,7 +22,7 @@ Any project [Maintainer](../CONTRIBUTING.md#maintainers) can approve additions t ## Removal of a code owner -To remove code owner, follow the appeal process in section 2.2 of the [GOVERNANCE.md](../GOVERNANCE.md#2-decisions) file. +To remove a code owner, follow the appeal process in section 2.2 of the [Governance document](../GOVERNANCE.md#2-decisions). ## Project maintainers diff --git a/contributions/merging-pull-requests.md b/contributions/merging-pull-requests.md index 9f9fce33a..0841d1b08 100644 --- a/contributions/merging-pull-requests.md +++ b/contributions/merging-pull-requests.md @@ -1,4 +1,4 @@ -# Approving Pull Requests +# Approving pull requests All merges into the `main` branch must be done through a pull request process to ensure changes are reviewed and approved by code owners. @@ -22,7 +22,7 @@ If any of these criteria are not met, the pull request can not be merged. ## Additional considerations -Pull requests should be kept as small as possible. If a change requires a large amount of code, it should be split into smaller requests that are easier to review. When in doubt, please contact the [maintainers group](../MAINTAINERS.md) *before* opening a large pull request. They can often assist in refactoring the change into smaller pieces that facilite effective code reviews. +Pull requests should be kept as small as possible. If a change requires a large amount of code, it should be split into smaller requests that are easier to review. When in doubt, please contact the [maintainers group](../MAINTAINERS.md) *before* opening a large pull request. They can often assist in refactoring the change into smaller pieces that facilitate effective code reviews. The pull request author should also consider adding the following before a PR is merged: @@ -36,7 +36,7 @@ If a merged pull request breaks subsequent builds or automated tests, the author ## Blocking pull requests -There may be times when a pull request contains changes that need further consideration before approval. Such occurrences include, but not limited to, design and breaking changes. In such cases, you should block the pull request by adding the "Merge: Blocked" label, and kindly explain your reasoning for blocking. Then notify the Project's Maintainers. +There may be times when a pull request contains changes that need further consideration before approval. Such occurrences include, but not limited to, design and breaking changes. In such cases, you should block the pull request by adding the "Merge: Blocked" label, and kindly explain your reasoning for blocking. Then notify the Project's Maintainers. ### Design changes @@ -48,4 +48,4 @@ A change is considered breaking if it contains incompatible API or behavior chan ### Unblocking a pull request -Only project Maintainers can unblock a pull request, and remove the "Merge: Blocked" label. To unblock a pull request, Maintainers follow the decision making rules in the [GOVERNANCE.md](../GOVERNANCE.md) file. +Only project Maintainers can unblock a pull request, and remove the "Merge: Blocked" label. To unblock a pull request, Maintainers follow the decision making rules in the [Governance document](../GOVERNANCE.md). diff --git a/contributions/opening-and-assessing-issues.md b/contributions/opening-and-assessing-issues.md index a59278218..821127be7 100644 --- a/contributions/opening-and-assessing-issues.md +++ b/contributions/opening-and-assessing-issues.md @@ -1,4 +1,4 @@ -# Opening and Assessing Issues +# Opening and assessing issues All Contributors can open issues using the templates available for a [bug](https://github.com/MixedRealityToolkit/MixedRealityToolkit-Unity/issues/new?assignees=&labels=Bug&template=bug-report.md&title=), [document issue](https://github.com/MixedRealityToolkit/MixedRealityToolkit-Unity/issues/new?assignees=&labels=Documentation&template=documentation-issue.md&title=), [feature request](https://github.com/MixedRealityToolkit/MixedRealityToolkit-Unity/issues/new?assignees=&labels=Documentation&template=documentation-issue.md&title=), and [security vulnerability](https://github.com/MixedRealityToolkit/MixedRealityToolkit-Unity/security/advisories/new). Consider the following when opening a new Project issue: @@ -11,7 +11,7 @@ All Contributors can open issues using the templates available for a [bug](https ## The role -Contributors with the **triage** role can assist with issue assessment. +Contributors with the **triage** role can assist with issue assessment. ## Assessing issues @@ -33,7 +33,7 @@ In some cases, an issue may not be a valid discussion topic, bug, or feature req ### Project appeals -Project appeals are discussed in section 2.2 of the [GOVERNANCE.md](../GOVERNANCE.md) file. These issues can only be triaged by the Project Maintainers, and should be labeled with "Type: Appeal". +Project appeals are discussed in section 2.2 of the [Governance document](../GOVERNANCE.md). These issues can only be triaged by the Project Maintainers, and should be labeled with "Type: Appeal". ## Continue assessment @@ -107,7 +107,7 @@ If a particular organization must resolve the issue and it’s unclear what Cont GitHub [milestones](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones) should be used sparingly. Only assign a milestone if the milestone has a clear dependency on the issue. -Before a new milestone can be created in the repository, the new milestone must be approved by the project Maintainers, following the decision making rules in the [GOVERNANCE.md](../GOVERNANCE.md) file. +Before a new milestone can be created in the repository, the new milestone must be approved by the project Maintainers, following the decision making rules in the [Governance document](../GOVERNANCE.md). ## GitHub project assignments diff --git a/contributions/project-tenets.md b/contributions/project-tenets.md index babf1c884..612577137 100644 --- a/contributions/project-tenets.md +++ b/contributions/project-tenets.md @@ -1,4 +1,4 @@ -# MRTK3 Tenets +# Project tenets The following are the guiding principles by which the MRTK3 project abides. This is a living document and the list may be modified over time. @@ -24,9 +24,9 @@ MRTK3 is designed to be used by developers of new and existing Unity projects. F ## Centralized project authority -MRTK3 is governed by a [steering committee](https://github.com/MixedRealityToolkit/MixedRealityToolkit-MVG/blob/main/org-docs/CHARTER.md). This committee is comprised of members from multiple companies with a vested interest in the success of MRTK. Decisions are made per the documented [governance](../GOVERNANCE.md). +MRTK3 is governed by a [steering committee](https://github.com/MixedRealityToolkit/MixedRealityToolkit-MVG/blob/main/org-docs/CHARTER.md). This committee is comprised of members from multiple companies with a vested interest in the success of MRTK. Decisions are made per the [Governance document](../GOVERNANCE.md). -Being an open source project does not mean that everyone has the ability to approve or reject changes. The [maintainers group](../MAINTAINERS.md) has the responsibility for determining if a change is appropriate and meets the project guidelines and standards. This is not to imply that the MRTK3 project does not wish to receive code review feedback from non-maintainers, we openly encourage feedback and will take it under advisement when making approval decisions. +Being an open source project does not mean that everyone has the ability to approve or reject changes. The [maintainers group](../MAINTAINERS.md) has the responsibility for determining if a change is appropriate and meets the project guidelines and standards. This is not to imply that the MRTK3 project does not wish to receive code review feedback from non-maintainers, we openly encourage feedback and will take it under advisement when making approval decisions. ## Get community feedback on large decisions diff --git a/contributions/versioning-and-releases.md b/contributions/versioning-and-releases.md index 59919726c..5234bc234 100644 --- a/contributions/versioning-and-releases.md +++ b/contributions/versioning-and-releases.md @@ -1,4 +1,4 @@ -# Versioning and Releases +# Versioning and releases ## Semantic versioning diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..74a9223a4 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,7 @@ +_site/ +.sass-cache/ +.jekyll-cache/ +.jekyll-metadata +# Ignore folders generated by Bundler +.bundle/ +vendor/ diff --git a/docs/Gemfile b/docs/Gemfile new file mode 100644 index 000000000..d78730303 --- /dev/null +++ b/docs/Gemfile @@ -0,0 +1,5 @@ +source 'https://rubygems.org' + +gem 'jekyll', '~> 4.4.1' +gem 'just-the-docs', '0.10.1' +gem 'jekyll-relative-links', '~> 0.7.0' diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock new file mode 100644 index 000000000..34ca866eb --- /dev/null +++ b/docs/Gemfile.lock @@ -0,0 +1,93 @@ +GEM + remote: https://rubygems.org/ + specs: + addressable (2.8.8) + public_suffix (>= 2.0.2, < 8.0) + base64 (0.3.0) + bigdecimal (3.3.1) + colorator (1.1.0) + concurrent-ruby (1.3.5) + csv (3.3.5) + em-websocket (0.5.3) + eventmachine (>= 0.12.9) + http_parser.rb (~> 0) + eventmachine (1.2.7) + ffi (1.17.2-x86_64-linux-gnu) + forwardable-extended (2.6.0) + google-protobuf (4.33.1-x86_64-linux-gnu) + bigdecimal + rake (>= 13) + http_parser.rb (0.8.0) + i18n (1.14.7) + concurrent-ruby (~> 1.0) + jekyll (4.4.1) + addressable (~> 2.4) + base64 (~> 0.2) + colorator (~> 1.0) + csv (~> 3.0) + em-websocket (~> 0.5) + i18n (~> 1.0) + jekyll-sass-converter (>= 2.0, < 4.0) + jekyll-watch (~> 2.0) + json (~> 2.6) + kramdown (~> 2.3, >= 2.3.1) + kramdown-parser-gfm (~> 1.0) + liquid (~> 4.0) + mercenary (~> 0.3, >= 0.3.6) + pathutil (~> 0.9) + rouge (>= 3.0, < 5.0) + safe_yaml (~> 1.0) + terminal-table (>= 1.8, < 4.0) + webrick (~> 1.7) + jekyll-include-cache (0.2.1) + jekyll (>= 3.7, < 5.0) + jekyll-relative-links (0.7.0) + jekyll (>= 3.3, < 5.0) + jekyll-sass-converter (3.1.0) + sass-embedded (~> 1.75) + jekyll-seo-tag (2.8.0) + jekyll (>= 3.8, < 5.0) + jekyll-watch (2.2.1) + listen (~> 3.0) + json (2.16.0) + just-the-docs (0.10.1) + jekyll (>= 3.8.5) + jekyll-include-cache + jekyll-seo-tag (>= 2.0) + rake (>= 12.3.1) + kramdown (2.5.1) + rexml (>= 3.3.9) + kramdown-parser-gfm (1.1.0) + kramdown (~> 2.0) + liquid (4.0.4) + listen (3.9.0) + rb-fsevent (~> 0.10, >= 0.10.3) + rb-inotify (~> 0.9, >= 0.9.10) + mercenary (0.4.0) + pathutil (0.16.2) + forwardable-extended (~> 2.6) + public_suffix (7.0.0) + rake (13.3.1) + rb-fsevent (0.11.2) + rb-inotify (0.11.1) + ffi (~> 1.0) + rexml (3.4.4) + rouge (4.6.1) + safe_yaml (1.0.5) + sass-embedded (1.94.2-x86_64-linux-gnu) + google-protobuf (~> 4.31) + terminal-table (3.0.2) + unicode-display_width (>= 1.1.1, < 3) + unicode-display_width (2.6.0) + webrick (1.9.2) + +PLATFORMS + x86_64-linux-gnu + +DEPENDENCIES + jekyll (~> 4.4.1) + jekyll-relative-links (~> 0.7.0) + just-the-docs (= 0.10.1) + +BUNDLED WITH + 2.4.20 diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 000000000..d18fde08a --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,39 @@ +title: Mixed Reality Toolkit +description: MRTK3 is the third generation of the Mixed Reality Toolkit for Unity. +theme: just-the-docs +color_scheme: dark + +url: https://mixedrealitytoolkit.github.io/MixedRealityToolkit-Unity/ +logo: "/images/MRTK_Logo_White.png" +favicon_ico: "/images/IconMRTKLogo.png" + +plugins: + - jekyll-relative-links +relative_links: + enabled: true + collections: true +include: [ 'CONTRIBUTING.md', 'LICENSE.md', '**/CHANGELOG.md' ,'GOVERNANCE.md'] + +defaults: + - scope: + path: "" # an empty string here means all files in the project + values: + layout: "default" + +callouts_level: loud +callouts: + note: + title: ℹ️ Note + color: blue + tip: + title: 💡 Tip + color: green + important: + title: ❕Important + color: purple + warning: + title: ⚠️ Warning + color: yellow + caution: + title: 🛑 Caution + color: red diff --git a/docs/mrtk3-overview/api-reference.md b/docs/mrtk3-overview/api-reference.md new file mode 100644 index 000000000..890fdba04 --- /dev/null +++ b/docs/mrtk3-overview/api-reference.md @@ -0,0 +1,20 @@ +--- +title: API reference +nav_order: 8 +--- + +# API reference + +MRTK3 is now shipping as [a set of individually versioned packages](index.md#versioning). As a result, each MRTK3 package ships its API reference individually. Please find the links to the API references for MRTK3 packages below: + +- [MRTK Core Definitions](https://aka.ms/mrtk3coreapi) +- [MRTK Accessibility](https://aka.ms/mrtk3accessibilityapi) +- [MRTK Audio Effects](https://aka.ms/mrtk3audioapi) +- [MRTK Data Binding and Theming](https://aka.ms/mrtk3dataapi) +- [MRTK Diagnostics](https://aka.ms/mrtk3diagnosticsapi) +- [MRTK Graphics Tools](https://learn.microsoft.com/dotnet/api/Microsoft.MixedReality.GraphicsTools) +- [MRTK Input](https://aka.ms/mrtk3inputapi) +- [MRTK Spatial Manipulation](https://aka.ms/mrtk3spmanipapi) +- [MRTK UX Components](https://aka.ms/mrtk3uxcompapi) +- [MRTK UX Core](https://aka.ms/mrtk3uxcoreapi) +- [MRTK Windows Speech](https://aka.ms/mrtk3winspeechapi) diff --git a/docs/mrtk3-overview/architecture/architecture.md b/docs/mrtk3-overview/architecture/architecture.md new file mode 100644 index 000000000..abb9a1f6d --- /dev/null +++ b/docs/mrtk3-overview/architecture/architecture.md @@ -0,0 +1,39 @@ +--- +title: Architecture overview +nav_order: 5 +--- + +# Architecture overview + +![Architecture MRTK3](../images/MRTK_v3_Architecture.png) + +One of the goals with MRTK3 was to take everything we've learned from the start of MRTK2 back in early 2018, combine it with the work that's been done by our industry partners across OpenXR and Unity since then, and come out the other side with a strong, extensible foundation that allows MRTK to focus more on providing differentiators and an overall improved user (and developer!) experience. + +## Input and interactions + +The overall architecture of the input stack of MRTK3 is built on four foundational components: + +1. OpenXR + 1. [Khronos Specification](https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html) + 1. [Unity OpenXR Plugin documentation](https://docs.unity3d.com/Packages/com.unity.xr.openxr@latest) +1. [Unity subsystems](https://docs.unity3d.com/ScriptReference/UnityEngine.SubsystemsModule.html) +1. [Unity's Input System](https://docs.unity3d.com/Packages/com.unity.inputsystem@latest) +1. [Unity's XR Interaction Toolkit](https://docs.unity3d.com/Packages/com.unity.xr.interaction.toolkit@latest) + +along with a layer of MRTK-defined [interactors](interactors.md) and [subsystems](subsystems.md), providing features like poke and speech. + +### OpenXR + +OpenXR is the interface between an application and an XR runtime system, allowing for a common set of features to be called generically and allow the hardware-specific implementation to be handled by the XR runtime. Adopting this in MRTK3, along with Unity's Input System, lets Unity handle more of the cross-platform and extensible input story while allowing MRTK3 to focus on helping you build rich experiences on top. + +### Subsystems + +[Subsystems](subsystems.md) and Unity's [SubsystemManager](https://docs.unity3d.com/ScriptReference/SubsystemManager.html) should be conceptually familiar to MRTK2 users, as they're the new "data providers". The idea is that different platforms or services can provide an implementation of a specific type of MRTK subsystem and have that run when relevant, providing data to MRTK3 and the app overall, just like data providers did to the various systems in MRTK2. Since we're focusing on OpenXR, the goal is that many features are covered by a cross-vendor EXT extension in OpenXR and multiple subsystems aren't needed, but vendor-specific extensions can represent early tech advancements that we want to support. + +### Unity Input System + +Conceptually, Unity's Input System will also feel familiar to users of the MRTK2 controller mapping profile. It provides a central place for mapping the buttons and other input axes on a controller or hand to a set of actions. These actions are then consumed by Unity's XR Interaction Toolkit (XRI) and MRTK3, so the object being interacted with doesn't care as much about _what_ is manipulating it, just that it _is_. + +### XR Interaction Toolkit + +XRI provides a foundation of interactors and interactables. MRTK builds upon this with its own set of [interactors](interactors.md) and [interactables](interactables.md), allowing for additional features like articulated hand tracking, gaze, and pinch. diff --git a/docs/mrtk3-overview/architecture/images/UGUI.svg b/docs/mrtk3-overview/architecture/images/UGUI.svg new file mode 100644 index 000000000..6fb37a1e6 --- /dev/null +++ b/docs/mrtk3-overview/architecture/images/UGUI.svg @@ -0,0 +1,15 @@ + + + + + + + + + + + + + + + diff --git a/docs/mrtk3-overview/architecture/images/configuration.png b/docs/mrtk3-overview/architecture/images/configuration.png new file mode 100644 index 000000000..fc4b2d377 Binary files /dev/null and b/docs/mrtk3-overview/architecture/images/configuration.png differ diff --git a/docs/mrtk3-overview/architecture/images/create-mrtk-asset.png b/docs/mrtk3-overview/architecture/images/create-mrtk-asset.png new file mode 100644 index 000000000..1113432d4 Binary files /dev/null and b/docs/mrtk3-overview/architecture/images/create-mrtk-asset.png differ diff --git a/docs/mrtk3-overview/architecture/images/create-new-asset.png b/docs/mrtk3-overview/architecture/images/create-new-asset.png new file mode 100644 index 000000000..b88a68d41 Binary files /dev/null and b/docs/mrtk3-overview/architecture/images/create-new-asset.png differ diff --git a/docs/mrtk3-overview/architecture/images/interactable_classes.svg b/docs/mrtk3-overview/architecture/images/interactable_classes.svg new file mode 100644 index 000000000..4d65b8240 --- /dev/null +++ b/docs/mrtk3-overview/architecture/images/interactable_classes.svg @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/docs/mrtk3-overview/architecture/images/pressable.png b/docs/mrtk3-overview/architecture/images/pressable.png new file mode 100644 index 000000000..883ede73d Binary files /dev/null and b/docs/mrtk3-overview/architecture/images/pressable.png differ diff --git a/docs/mrtk3-overview/architecture/images/profiles.png b/docs/mrtk3-overview/architecture/images/profiles.png new file mode 100644 index 000000000..87e5f05f0 Binary files /dev/null and b/docs/mrtk3-overview/architecture/images/profiles.png differ diff --git a/docs/mrtk3-overview/architecture/images/selectedness.svg b/docs/mrtk3-overview/architecture/images/selectedness.svg new file mode 100644 index 000000000..4dbb4bd5b --- /dev/null +++ b/docs/mrtk3-overview/architecture/images/selectedness.svg @@ -0,0 +1,16 @@ + + + + + + + + + + + + + + + + diff --git a/docs/mrtk3-overview/architecture/interactables.md b/docs/mrtk3-overview/architecture/interactables.md new file mode 100644 index 000000000..2f087961e --- /dev/null +++ b/docs/mrtk3-overview/architecture/interactables.md @@ -0,0 +1,61 @@ +--- +title: Interactables +parent: Architecture overview +nav_order: 2 +--- + +# Interactables + +MRTK builds on the `XRBaseInteractable` provided by Unity's XR Interaction Toolkit. The existing interactable behavior and API is fully supported in MRTK, and all of our custom interactables obey the existing XRI interactable API. + +For developers new to XRI, we _strongly_ recommend that you first review Unity's [XRI architecture documentation](https://docs.unity3d.com/Packages/com.unity.xr.interaction.toolkit@2.0/manual/architecture.html). + +To expand upon the interactable mechanisms included in XRI, MRTK offers two base classes upon which advanced interactions can be built, one extending the other. + +![Interactables inheritance diagram](images/interactable_classes.svg) + +- `MRTKBaseInteractable : XRBaseInteractable` + - This class offers filtering and flagging for different types of interactors. While the base XRI `XRBaseInteractable` doesn't discriminate between interactor types, `MRTKBaseInteractable` provides convenience functions for checking whether common types of interactions are occurring. Convenience properties like `IsGazeHovered` or `IsGrabSelected` are shortcuts to querying whether a participating interactor implements a given interface (correspondingly, `IGazeInteractor` or `IGrabInteractor`). These flags are more performant than iterating through the list of `interactorsHovering` or `interactorsSelecting`. In addition, `MRTKBaseInteractable` can filter/reject certain types of interactors in the case that the developer wishes to exclude certain input modalities. +- `StatefulInteractable : MRTKBaseInteractable` + - While `MRTKBaseInteractable` adds flags and filters, and avoids adding any additional state to the interactable, `StatefulInteractable` introduces useful stateful features like toggling and variable selection. + +## Strict separation of state and visuals + +In MRTK 2.x, interactables were often responsible for driving their own visual effects, be it the compressing of a 3D button, a hover effect, or even just changing color on a click. The limitation of this approach is that the interaction logic is tightly bound to the visuals. If you were to redesign the visuals or use a different size/shape/displacement/etc. of button, the interaction script itself would need to change. + +In MRTK3, **interactables are pure state and interaction.** The interactable doesn't render any visual changes or effects based on its internal state. It's purely a collection of state and interaction logic that's highly portable between visual presentation setups. + +![Strict isolation of state and visuals](images/pressable.png) + +The same `PressableButton` script can be used to build a squishy ball, a pressable "trackpad"-like plane, or an abstract pressable that issues network events on press. The `PressableButton` script doesn't even care "where" it is; it could be inside a Canvas, or on a rigidbody. + +To drive visuals, a separate "visual driver" is used to poll the state from the interactable and render the appropriate feedback. `StateVisualizer` is the recommended low-code method for driving common visual feedback effects from interactable state, but developers are free to write their own custom visual drivers. For example, our button components generally use `StateVisualizer` for their advanced 3D + shader-based feedback effects, but we also provide an example `BasicPressableButtonVisuals` that shows how a simple visual driver can be authored in code. + +## Variable selection + +`StatefulInteractable`'s most useful additional feature over the base XRI functionality is support for variable `Selectedness`. While base XRI interactables are either selected or not selected, MRTK's `StatefulInteractable`s can be any floating-point fraction of selected. + +This concept is useful when working in XR, since nearly all forms of input are no longer binary states. Motion controllers often have analog triggers (or analog grips!), hand interactions can provide a variable "pinchedness", and volumetric press interactions can depress a button or pushable surface by a varying amount. You see these variable, analog interactions everywhere in XR, and MRTK is equipped to help developers build delightful interactions on top of these analog inputs. + +A wide range of different interactors and types of interactions can all contribute together to the overall Selectedness of an interactable. Notably, all interactors that implement `IVariableSelectInteractor` contribute their analog selection amount, typically through a `max()` of all participating interactors. This variable amount is combined with the binary, non-variable selections coming from vanilla-style interactors. + +For derived classes like `PressableButton`, the `Selectedness()` function is overridden to add an additional "ingredient" to the selectedness computation. Interactors that implement `IPokeInteractor` can contribute Selectedness based on their physical location and how they're physically pressing down on the interactable. Other derived classes can introduce other, arbitrary forms of selection. + +![Variable selectedness](images/selectedness.svg) + +For the interactables MRTK provides, `Selectedness()` and `isSelected` will always "agree"--in other words, you'll never observe a `Selectedness()` greater than the `SelectThreshold` without a corresponding XRI `isSelected` and an accompanying interactor in `interactorsSelecting`. + +> [!IMPORTANT] +> Your custom interactable subclasses can obviously override `Selectedness` to some other value that's completely disconnected from the XRI `isSelected`. However, our interactables don't do this, and we strongly discourage it. **In general, never write _interactions_ that do not have a corresponding _interactor_.** XRI selection will, in the vast majority of cases, be sufficient, and any custom interactions you build should be written as interactors. + +When you're creating a custom interactable that supports a new method of determining `Selectedness()`, simply override the method and combine your new selectedness with the existing selection amount. If you're using `StateVisualizer` or any other visual layer that listens to variable selection, it will respond accordingly to your new selection type. + +## Map UGUI events to XRI + +In some cases, it's desirable to have interactables respond to UGUI events, such as mouse, gamepad, or touchscreen input. The `UGUIInputAdapter`, which is a UGUI `Selectable`, receives UGUI events and forwards them to a `CanvasProxyInteractor`, if one is present. + +![UGUI adapter flow](images/UGUI.svg) + +When the `CanvasProxyInteractor` is notified of the UGUI events by the `UGUIInputAdapter`, it issues _equivalent_ XRI actions on the relevant interactable. The mapping between UGUI input and XRI actions is somewhat lossy and is an area of active development. + +With this system, existing XRI interactables that are built for immersive platforms, hands, motion controllers, and 3D input can react equally well to accessible 2D controls like mouse and gamepad. diff --git a/docs/mrtk3-overview/architecture/interactors.md b/docs/mrtk3-overview/architecture/interactors.md new file mode 100644 index 000000000..2fd71f2ac --- /dev/null +++ b/docs/mrtk3-overview/architecture/interactors.md @@ -0,0 +1,102 @@ +--- +title: Interactor architecture +parent: Architecture overview +nav_order: 1 +--- + +# Interactor Architecture + +MRTK builds upon the set of interactors offered by Unity's XR Interaction Toolkit. Mixed reality features like articulated hand tracking, gaze, and pinch require more elaborate interactors than the set provided with XRI by default. MRTK defines new interactor interfaces, categorized generally by the input modality, and corresponding implementations. + +## Summary and Review + +For developers new to XRI, we recommend that you first review Unity's [XRI architecture documentation](https://docs.unity3d.com/Packages/com.unity.xr.interaction.toolkit@2.0/manual/architecture.html). MRTK interactors are subclasses of existing XRI interactors or implementations of the XRI interactor interfaces. See Unity's documentation on their interactor architecture which also applies to MRTK. + +### Good Citizens of XRI + +The custom MRTK interactors are well-behaved with respect to the default XRI interactor interfaces; from the perspective of XRI systems, they're indistinguishable from "vanilla" interactors. The inverse is also true; when building advanced interactables in MRTK, the default XRI interactors will still work for basic hover and select. It's part of the MRTK effort to be fully compatible with existing XRI projects. If you have an XRI application, MRTK interactables and UI controls will work with your existing "vanilla" XRI setup. + +### Abstraction of Input Modality + +The input device, the interactor performing the interaction, and the interaction events they generate are all architecturally isolated in XRI. This isolation is critical to the input abstraction strategy in MRTK3, and enables us to write cross-platform and cross-device interactions that function well in all contexts. + +From MRTK v2, there's a common instinct to code interactions specific to a particular input type or device. Many developers are accustomed to writing interactions that react specifically to a near grab, a far ray, or some other specific input type. + +While MRTK3 still allows for the disambiguation and detection of individual input modes, hard-coding interactions to specific individual input types is artificially limiting and reduces the flexibility of your interactions. More on this can be found in the [interactable architecture documentation](interactables.md), but the key for interactors is that they generally don't have to map 1:1 with input devices. + +### AttachTransform and Inversion of Control + +Much of what MRTK v2 did in "move logics" as part of `ObjectManipulator`, `Slider`, and so forth, is now the responsibility of the interactor itself. The interactor now controls its attachTransform to define how a specific type of manipulation behaves. One no longer needs to write complex interaction logic on the interactable that differs between input modalities; instead, your unified manipulation logic can listen to the `attachTransform`'s pose regardless of the input modality or the device driving it. + +For example, a `GrabInteractor`'s `attachTransform` is located at the grabbing point on the hand/controller. An `XRRayInteractor`'s `attachTransform` is located at the hit point at the ray's end. The `CanvasProxyInteractor`'s `attachTransform` is located wherever the mouse has clicked. For all of these different interactors, the interactable **_doesn't have to care about the type of interactor in order to respond appropriately to manipulations._** + +The interactable queries the `attachTransform` and can treat every `attachTransform` the same regardless of the interactor type. + +This approach is critical for compatibility with existing XRI interactors as well as future-proofing your interactions for input modalities that haven't yet been developed. If a new input method is introduced, you don't need to alter existing interactables if the new interactor generates a valid and well-behaved `attachTransform`. + +Thus, philosophically, the `attachTransform` _is_ the interaction logic. For any custom interactions, always give preference to writing a new interactor with new `attachTransform` logic rather than rewriting or extending interactables to be customized for your new interaction. In this way, all existing interactables can enjoy the benefits of your new interaction instead of only the ones you've rewritten or extended. + +### XRControllers and Input Binding + +Most interactors don't bind directly to input actions. Most derive from `XRBaseControllerInteractor`, which requires an `XRController` above the interactor in the hierarchy. The `XRController` binds to input actions and then propagates the relevant actions (select, and so forth) down to all attached interactors. + +Nonetheless, some interactors may need special input bindings or additional input that the `XRController` doesn't provide. In these cases, interactors have the option to bind directly to their own unique input actions or even use other non-Input-System sources for interaction logic. The XRI base classes prefer to listen to the `XRController`'s bindings, but these behaviors can be overridden to use external or alternative input sources. + +## Interfaces + +XRI defines the basic `IXRInteractor`, `IXRHoverInteractor`, `IXRSelectInteractor`, and `IXRActivateInteractor`. MRTK defines additional interfaces for interactors. Some expose additional information about MRTK-specific interactions, and others are simply for categorization and identification. These interfaces are all located within the **Core** package, while the implementations reside in other packages, including **Input**. + +> [!IMPORTANT] +> While these interfaces are helpful if you need to filter for a specific type of interaction, we recommend that you do _not_ hard-code your interactions to listen for these interfaces specifically. _In every situation, always give preference to the generic XRI **isSelected** and **isHovered**, rather than any interaction-specific interface_.

+Unless necessary, you shouldn't reference the concrete MRTK implementations of these interfaces in interactables unless it's absolutely necessary. In all cases, it's better to reference the interfaces. Explicitly referencing the concrete types will restrict your interactables to only work with the current, existing types. By referencing only the interfaces, you ensure compatibility with future implementations that may not subclass the existing implementations. + +### IVariableSelectInteractor + +Interactors implementing this interface can issue variable (that is, analog) selectedness to interactables. The variable select amount can be queried with the `SelectProgress` property. MRTK interactors that implement this interface include the `MRTKRayInteractor` and the `GazePinchInteractor`. Base interactables (the default XRI interactables, and `MRTKBaseInteractable`) won't be affected by the variable selection amount; `StatefulInteractable`, however, listens to this value and computes its `Selectedness` based on the `max()` of all participating variable and non-variable interactors. + +### IGazeInteractor + +Interactors that implement this interface represent the user's passive gaze, separate from any manipulation or intent. The MRTK implementation is `FuzzyGazeInteractor`, which inherits from the XRI `XRRayInteractor`, and adds fuzzy cone-casting logic. `XRBaseInteractable` will flag `IsGazeHovered` when an `IGazeInteractor` is hovering. + +### IGrabInteractor + +Interactors that implement this interface represent a physical near-field grabbing interaction. The `attachTransform` is defined as the grabbing point. The MRTK implementation is `GrabInteractor`, which subclasses XRI's `XRDirectInteractor`. + +### IPokeInteractor + +Interactors that implement this interface represent a poking interaction. Note that this doesn't necessarily imply a finger! Arbitrary interactors can implement this interface and offer poking interactions from non-finger sources. In one of the few instances where checking interactor interfaces is a good idea, interactables like `PressableButton` listen for `IPokeInteractor`s, specifically, to drive volumetric press. Any interactor that implements `IPokeInteractor` will induce 3D presses on buttons. + +`IPokeInteractor` exposes the `PokeRadius` property, which defines the characteristics of the poking object. The poke is considered to be centered on the `attachTransform` and extends outwards from the `attachTransform` by the `PokeRadius`. Interactables like `PressableButton` offset their 3D push distance by this radius, which can be driven by the user's physical finger thickness in the case of finger-based presses. + +The MRTK implementation of this interface is `PokeInteractor`. In our template project, we also provide another example of `IPokeInteractor` that's not finger-driven; `PenInteractor` provides poke interactions rooted on the tip of a virtual 3D stylus. + +### IRayInteractor + +Interactors that implement this interface represent a ray-based pointing interaction. The `attachTransform` represents the hit location of the ray on the surface of the targeted object during a selection. + +The MRTK implementation of this interface is `MRTKRayInteractor`, inheriting directly from the XRI `XRRayInteractor`. + +> [!NOTE] +> The XRI `XRRayInteractor` doesn't implement this MRTK interface. + +### ISpeechInteractor + +Interactors that implement this interface represent speech-driven interactions. The MRTK implementation is `SpeechInteractor`. + +The MRTK `SpeechInteractor`, internally, uses `PhraseRecognitionSubsystem` and subscribes to interactable registration events from the XRI `XRInteractionManager`. However, interactables need not be concerned about what subsystem is performing speech processing; `ISpeechInteractor`s generate the same XRI events (select, and so forth) that any other interactor does. + +### IGazePinchInteractor + +This interface is simply a specialization of the `IVariableSelectInteractor` interface. Interactors that implement this interface are, implicitly, variable-select interactors. `IGazePinchInteractor`s expressly represent an indirectly targeted remote manipulation. A separate gaze-based interactor drives the target of the interaction, and the manipulation is by a hand or controller. `attachTransform` behaves the same way `IRayInteractor`'s `attachTransform` does; it snaps to the hit point on the target when a select is initiated. + +When multiple `IGazePinchInteractor`s participate in a single interaction, their `attachTransform`s are offset by their displacement from the median point between all participating pinch-points. Thus, interactables can interpret these `attachTransform`s in the same way they would for any other multi-handed interaction, like the `attachTransforms` from grab interactions, or ray interactions. + +The MRTK implementation is the `GazePinchInteractor`. + +### IHandedInteractor + +Some interactors can choose to implement `IHandedInteractor` interface to explicitly specify that they're associated with a particular hand on a user. Some interactors aren't associated with handedness and thus don't implement this. The most obvious examples would be ones like `SpeechInteractor` or `FuzzyGazeInteractor`. + +The MRTK interactors that implement this interface are the `HandJointInteractor`, a generic, abstract `XRDirectInteractor` driven by an arbitrary hand joint, the `GazePinchInteractor`, and the `MRTKRayInteractor`. + +Interactables currently use this interface to fire certain effects when selected that must disambiguate between a left or right hand. The most notable example of this is the pulse effect in the UX components library. diff --git a/docs/mrtk3-overview/architecture/subsystems.md b/docs/mrtk3-overview/architecture/subsystems.md new file mode 100644 index 000000000..07e8127c3 --- /dev/null +++ b/docs/mrtk3-overview/architecture/subsystems.md @@ -0,0 +1,93 @@ +--- +title: Subsystems +parent: Architecture overview +nav_order: 3 +--- + +# Subsystems + +MRTK3 leverages the Unity XR Subsystem Management infrastructure for writing extensible modules that can help provide cross-platform support for features like speech and hand tracking. These subsystems are initialized and loaded by Unity alongside the existing Unity-native subsystems like `XRMeshSubsystem` and `XRInputSubsystem`. See [the documentation for how Unity subsystems work](https://docs.unity3d.com/ScriptReference/UnityEngine.SubsystemsModule.html). + +## Philosophy + +In MRTK v2, "services" provided much of the functionality in the scene itself. They would instantiate objects, move objects around, update the scene hierarchy, etc. In MRTK3, the subsystems don't explicitly modify the scene. The MRTK3 subsystems are modular providers of data, information, or events or perform computation for end-users. If something in the scene should change or be acted upon based on data input, there must be a separate scene-based visualizer component to act on the data. This split ensures that the subsystems are non-destructive regarding scene changes and don't cause scene-related side effects. + +While MRTK v2 used systems and services liberally for processing input, MRTK3 generally uses OpenXR and the Unity Input System for cross-platform input. However, some types of data are not yet wrapped by the Input System. In these cases, we provide cross-platform interfaces through our subsystems. + +## MRTK subsystem lifecycle + +The subsystem definitions that are included with Unity's infrastructure offer simple lifecycle methods like `Start`, `Stop`, and `Destroy`. We extend this definition to include helpful "tick" methods, such as `Update`, `LateUpdate`, and `FixedUpdate`. Our `MRTKLifecycleManager` manages subsystems that implement our lifecycle interface. This lifecycle manager is the only MonoBehaviour involved in the subsystem architecture; this can be placed anywhere in the scene, but we tend to leave it somewhere on the Rig. + +## Querying + +Querying for a subsystem implementation is straightforward and performant. + +```c# +// Gets the first valid implementation of T that is started and running. +T mySubsystem = XRSubsystemHelpers.GetFirstRunningSubsystem(); + +// Gets the first valid implementation of T, even if it hasn't been started. +T mySubsystem = XRSubsystemHelpers.GetFirstSubsystem(); + +// If multiple implementations of T are loaded, get all of them. +List allOfThem = new List(); +GetAllRunningSubsystemsNonAlloc(allOfThem); +``` + +## Descriptors + +Different implementations of a subsystem can have different capabilities. For example, the different implementations of the `HandsSubsystem` can specify their capability for reporting physical data or synthesized data. This capability information is stored in the subsystem descriptor, and can be queried for any given implementation. + +```c# +// Get the first running hands subsystem. +var handsSubsystem = XRSubsystemHelpers.GetFirstRunningSubsystem(); + +// If we found one... +if (handsSubsystem != null) +{ + // Read the capability information off the implementation's descriptor. + bool isPhysicalData = handsSubsystem.subsystemDescriptor.IsPhysicalData; +} +``` + +## Profiles + +Not to be confused with MRTK 2.x's profiles, MRTK3 subsystem profiles are a per-deployment-platform asset that defines which subsystems are created and started. + +![Subsystem profiles, as shown in the MRTK project settings view.](images/profiles.png) + +Subsystems that have their corresponding checkbox checked will be created and started by the `MRTKLifecycleManager` and have their lifecycle methods called. Different profiles can be assigned to different deployment targets. + +The subsystems shown here are determined by which packages you've installed. If a package isn't installed, the subsystems associated with that package won't be shown here, and the list auto-refreshes. + +There's a pre-made `MRTKProfile` supplied as part of the MRTK v3 package. It's an immutable asset. However, if you'd like to create a custom selection of subsystems to run, you should create your `MRTKProfile` asset within your project. + +![Create your own MRTK subsystems](images/create-mrtk-asset.png) + +## Configuration + +Subsystems can be assigned configuration objects to customize their behavior. + +![Configuring a subsystem](images/configuration.png) + +These configuration objects are accessible from anywhere through the `XRSubsystemHelpers` API. + +```c# +XRSubsystemHelpers.GetConfiguration() +``` + +Subsystems define which config type is relevant to them in their `MRTKSubsystemAttribute`. Along with this, the attribute also defines several pieces of metadata, along with the concrete types of the implemented provider. For example, this is the attribute that the MRTK Hands Aggregator Subsystem uses. + +```c# +[MRTKSubsystem( + Name = "com.microsoft.mixedreality.hands", + DisplayName = "MRTK Hands Aggregator Subsystem", + Author = "Microsoft", + ProviderType = typeof(MRTKAggregator), + SubsystemTypeOverride = typeof(MRTKHandsAggregatorSubsystem), + ConfigType = typeof(MRTKHandsAggregatorConfig))] +``` + +As with Profiles, default Configuration assets are provided. They're immutable and must be duplicated to your project to be edited. You can also create a new asset through the asset creation menu. + +![New asset creation menu](images/create-new-asset.png) diff --git a/docs/mrtk3-overview/getting-started/exploring-features/mrtk3-sample-scenes.md b/docs/mrtk3-overview/getting-started/exploring-features/mrtk3-sample-scenes.md new file mode 100644 index 000000000..06fd397b7 --- /dev/null +++ b/docs/mrtk3-overview/getting-started/exploring-features/mrtk3-sample-scenes.md @@ -0,0 +1,85 @@ +--- +title: Exploring MRTK3 sample scenes +parent: Getting started with MRTK3 +nav_order: 5 +--- + +# Exploring MRTK3 sample scenes + +Unlike MRTK2, MRTK3 isn't distributed as a Unity project. Instead, MRTK3 consists of a loosely coupled collection of individual UPM packages distributed through our official GitHub repository. + +As a result, we no longer ship our sample scenes inside the MRTK library/package itself. Instead, we maintain the `UnityProjects` folder at the top level of the [GitHub repository](https://github.com/MixedRealityToolkit/MixedRealityToolkit-Unity), which contains any Unity projects we want to ship. Currently, this folder includes the `MRTKDevTemplate` project, which contains all of our example scenes and is configured to align with our recommended best settings. + +We also recommend using the `MRTKDevTemplate` project for local development when submitting fixes or changes. All of the packages are specified as local on-disk dependencies, making editing and submitting changes easy. Clone the repo and open the `MRTKDevTemplate` Unity project. + +Within `MRTKDevTemplate`, you can find all of our sample scenes. Most of the sample scenes are in `UnityProjects/MRTKDevTemplate/Assets/Scenes`, while some experimental or early-preview sample scenes are located in `UnityProjects/MRTKDevTemplate/Assets/Data Binding Example`. + +## Included sample scenes + +A non-exhaustive list can be found below. + +### HandInteractionExamples + +This sample scene offers a wide variety of interaction examples. Despite the name, this scene is a good example of cross-platform input, including hand tracking, controller input, and mouse input. Examples of several different UI controls and interactables are present, including the volumetric UI systems. + +![Hand Menu](../../images/hand-interaction-examples.png) + +### BoundsControlExamples + +Various configurations of BoundsControl, showing both flattened and 3D bounds. + +### CanvasExample + +Shows a collection of UX components built with UnityUI. These UX components are built with a combination of XRI interactables and traditional UGUI event handlers. This combination enables flexibility and responsive design across a wide variety of input methods and contexts. + +### CanvasUITearsheet + +This scene showcases all available UI building blocks and their permutations in MRTK. All controls are based on the new Mixed Reality Design Language. + +### DialogExample + +This scene demonstrates use of the Dialog control. + +### EyeGazeExample + +Example of using the Gaze Interactor to highlight objects within a scene. + +### HandMenuExamples + +Demonstrates using a menu appearing beside the hand. + +### InteractableButtonExamples + +An example of different styles of interactable buttons. + +### NearMenuExamples + +Near interaction menu examples. + +### NonCanvasObjectBarExample + +Demonstrates the Object Bar component, which enables horizontal or vertical arrangement of arbitrary 3D objects. + +### NonCanvasUIBackplateExample + +The scene demonstrates `UIBackplate.prefab`, which you can use to construct various types of UI panels and menus. + +### SampleEmptyMRTKScene + +The sample empty MRTK scene only contains the core MRTK prefab (**MRTK XR Rig**) and the input simulator prefab (**MRTKInputSimulator**). It's intended to give developers an empty scene with only the MRTK essentials necessary to get started. + +### SlateDrawingExample + +A demonstration of using MRTK3 to create a basic drawing application. + +### SpatialMappingExample + +The spatial mapping example scene demonstrates using `ARMeshManager` (**MRTK XR Rig > ARSpatialMeshManager**) in MRTK3 to visualize the spatial mesh. + +### TabViewExample + +Shows a collection of toggles that control the visibility of associated game objects. + +### ToggleCollectionExample + +Demonstrates the `ToggleCollection` script, which allows multiple toggle interactables to be grouped. Only one toggle can be toggled at any given time. diff --git a/docs/mrtk3-overview/getting-started/exploring-features/mrtk3-tutorials.md b/docs/mrtk3-overview/getting-started/exploring-features/mrtk3-tutorials.md new file mode 100644 index 000000000..4e78b55fc --- /dev/null +++ b/docs/mrtk3-overview/getting-started/exploring-features/mrtk3-tutorials.md @@ -0,0 +1,20 @@ +--- +title: MRTK3 tutorials +parent: Getting started with MRTK3 +nav_order: 6 +--- + +# Exploring MRTK3 tutorials + +Several tutorials have been created to help developers learn about MRTK3's various features and capabilities. + +> [!WARNING] +> These tutorials have gone out-of-date and will not be updated. + +## [MRTK3 Aquarium](https://learn.microsoft.com/windows/mixed-reality/develop/unity/mrtk3-aquarium): the in-editor tutorial + +The [MRTK3 Aquarium project](https://learn.microsoft.com/windows/mixed-reality/develop/unity/mrtk3-aquarium) provides a Unity in-editor tutorial that explores various MRTK3 features. Set in an underwater scene, you'll be introduced to the creatures of the aquarium and the objects that make up their habitat. Using MRTK3 features, you'll add interactivity to the aquarium, enabling you to create an aquarium of your very own! + +## [Zappy's Playground](https://learn.microsoft.com/windows/mixed-reality/develop/unity/playground-tutorial) + +[Zappy's Playground](https://learn.microsoft.com/windows/mixed-reality/develop/unity/playground-tutorial) is a cross-platform developer sample project that showcases how to develop intuitive and comprehensive end-to-end experiences for mixed reality. It makes use of many advanced features present in MRTK3, such as Gaze Interaction, Hand Menus, and Spatial Audio. diff --git a/docs/mrtk3-overview/getting-started/overview.md b/docs/mrtk3-overview/getting-started/overview.md new file mode 100644 index 000000000..58a1788de --- /dev/null +++ b/docs/mrtk3-overview/getting-started/overview.md @@ -0,0 +1,16 @@ +--- +title: Getting started with MRTK3 +nav_order: 2 +--- + +# Getting started with MRTK3 + +Welcome to the MRTK3! This guide serves as a starting point for using MRTK to build and experience your app in AR/VR. It includes resources for becoming acquainted with the building blocks of MRTK, and guides users through setting up their project to deploying on device. + +## Where should I go next? + +[Explore MRTK features](./exploring-features/mrtk3-sample-scenes.md): Learn about MRTK's features through exploring our example scenes. + +[Set up an MRTK project](./setting-up/setup-dev-env.md): Learn how to set up your development environment and create an AR/VR ready Unity project using MRTK. + +[Test and deploy your app](../test-and-deploy/overview.md): Learn how to test and deploy your application on a device. diff --git a/docs/mrtk3-overview/getting-started/setting-up/mixed-reality-feature-tool.md b/docs/mrtk3-overview/getting-started/setting-up/mixed-reality-feature-tool.md new file mode 100644 index 000000000..bcedc9b55 --- /dev/null +++ b/docs/mrtk3-overview/getting-started/setting-up/mixed-reality-feature-tool.md @@ -0,0 +1,41 @@ +--- +title: Mixed Reality Feature Tool (Deprecated) +parent: Setting up the development environment +--- + +# Mixed Reality Feature Tool (Deprecated) + +| Software | Version | Notes | +| --- | --- | --- | +| [Mixed Reality Feature Tool for Unity](https://aka.ms/mrfeaturetool) | | Used to acquire MR packages | + +> [!WARNING] +> Older versions of MRTK3 can be found on the Mixed Reality Feature Tool for Unity. The feed that backs the tool and the publishing infrastructure around it have been decommissioned, and new versions will not be published here. + +## Import required dependencies and MRTK3 packages with Mixed Reality Feature Tool + +There are a handful of packages that MRTK3 uses that aren't part of this toolkit. To obtain these packages, use the [Mixed Reality Feature Tool](https://learn.microsoft.com/windows/mixed-reality/develop/unity/welcome-to-mr-feature-tool) and select the latest versions of the following in the **Discover Features** step. + +To run on **HoloLens 2** or to visualize controller models on a **Quest device**, an additional package is required: + +- **Platform Support → Mixed Reality OpenXR Plugin** + +To spatialize audio in your scene, an additional package is required: + +- **Spatial Audio → Microsoft Spatializer** (Optional) + +For MRTK3 packages, we recommend the following two packages to help you get started quickly: + +- **MRTK3 → MRTK Input** (Required for this setup) +- **MRTK3 → MRTK UX Components** + +These two packages, along with their dependencies (automatically added by the Feature Tool), will enable you to explore most of our UX offerings and create projects ready to be deployed to various XR devices. You can always come back to the Feature Tool and add more packages to your project later. + +Be sure to select the `org.mixedrealitytoolkit.*` packages, and not the deprecated packages. The `com.microsoft.mrtk.*` packages have been deprecated and are no longer supported. + +![Selecting the default MRTK3 packages in Microsoft's Mixed Reality Feature Tool](../../images/mrtk3-featuretool-setup-packages.png) + +> [!NOTE] +> For more information on MRTK3 packages, see the [package overview page](../../packages/packages-overview.md). + +When you're finished selecting packages, click **Get Features**, and then follow the instructions in the Mixed Reality Feature Tool to import the selected packages into your Unity project. diff --git a/docs/mrtk3-overview/getting-started/setting-up/setup-dev-env.md b/docs/mrtk3-overview/getting-started/setting-up/setup-dev-env.md new file mode 100644 index 000000000..4003479ba --- /dev/null +++ b/docs/mrtk3-overview/getting-started/setting-up/setup-dev-env.md @@ -0,0 +1,42 @@ +--- +title: Setting up the development environment +parent: Getting started with MRTK3 +nav_order: 1 +--- + +# Setting up your development environment + +Before setting up a Unity Project with MRTK3, make sure you have the following software tools installed. + +| Software | Version | Notes | +| --- | --- | --- | +| Unity | 2022.3 LTS or newer | Recommend using an LTS release
See [Additional tools](#additional-tools) below for recommended modules | + +## Additional tools + +> [!WARNING] +> Older versions of MRTK3 can be found on the [Mixed Reality Feature Tool for Unity](./mixed-reality-feature-tool.md). The feed that backs the tool and the publishing infrastructure around it have been decommissioned, and new versions will not be published here. + +### Android + +If your target platform is an [AOSP-based](https://source.android.com/) device, like Android XR or Quest, your Unity installation needs to include the Android Build Support module and its submodules. + +![Android module installation](../../images/setting-up/MRTK-Development-Setup-AndroidModule.png) + +### HoloLens 2 + +| Software | Version | Notes | +| --- | --- | --- | +| [Microsoft Visual Studio](https://visualstudio.microsoft.com/) | 2022 Community or newer | Add the required workloads as noted in the [Installation Checklist](https://learn.microsoft.com/windows/mixed-reality/develop/install-the-tools) | +| Windows 10 SDK | 10.0.18362.0 or later | | + +If your target platform is a HoloLens device, your Unity installation needs to include the Universal Windows Platform Support module. + +![UWP module installation](../../images/setting-up/MRTK-Development-Setup-UWPModule.png) + +## Next steps + +After setting up the development environment, there are few options for creating a Unity Project with MRTK3. + +- [Starting from the template project](./setup-template.md): This guide walks you through cloning a template project, which is pre-configured to consume all MRTK3 packages. This template project is set up with Unity project settings for running your application on a device. +- [Starting from a new project](./setup-new-project.md): This guide walks you through adding vital MRTK3 packages to a new Unity project. The guide also helps you set up the Unity project settings for running your application on a device. diff --git a/docs/mrtk3-overview/getting-started/setting-up/setup-new-project.md b/docs/mrtk3-overview/getting-started/setting-up/setup-new-project.md new file mode 100644 index 000000000..91cb7f7b1 --- /dev/null +++ b/docs/mrtk3-overview/getting-started/setting-up/setup-new-project.md @@ -0,0 +1,105 @@ +--- +title: Setting up a new project with MRTK3 +parent: Getting started with MRTK3 +nav_order: 3 +--- + +# Starting from a new project + +Since MRTK3 is a collection of loosely coupled packages, consuming MRTK3 is done differently than the way you consume MRTK 2.x. We don't ship MRTK as a Unity project, so you have to manually add MRTK3 packages to your project in order to consume them. + +You're not expected to consume every MRTK package. See [which features are useful to you](../../packages/packages-overview.md) and add only the dependencies that matter. + +## Setting up a new Unity project with MRTK3 + +### Create a new Unity project + +Create a new Unity project with Unity 2021.3.21f1 or newer. Close the Unity project before proceeding to the next step. + +### Import MRTK3 packages + +For MRTK3 packages, we recommend checking for the [latest release on the GitHub repo](https://github.com/MixedRealityToolkit/MixedRealityToolkit-Unity/releases). The package tarballs can be found under the changelogs, under **Assets**: + +![GitHub release assets](../../images/github-release.png) + +We recommend the following packages to help you get started quickly: + +- org.mixedrealitytoolkit.core +- org.mixedrealitytoolkit.uxcore +- org.mixedrealitytoolkit.standardassets +- org.mixedrealitytoolkit.spatialmanipulation +- org.mixedrealitytoolkit.uxcomponents +- org.mixedrealitytoolkit.input + +We'll also need the latest Mixed Reality Graphics Tools package from [its GitHub repo](https://github.com/microsoft/MixedReality-GraphicsTools-Unity/releases), also under **Assets**: + +![MRGT GitHub release assets](../../images/github-release-mrgt.png) + +- com.microsoft.mrtk.graphicstools.unity + +Copy these files somewhere into your project folder. We recommend a subfolder under **Packages**. + +![MRTK Packages folder](../../images/mrtk-packages-folder.png) + +Using UPM's ability to [import local tarball files](https://docs.unity3d.com/6000.0/Documentation/Manual/upm-ui-tarball.html), we'll import the above packages in the following order, to correctly resolve dependencies: + +- com.microsoft.mrtk.graphicstools.unity +- org.mixedrealitytoolkit.core +- org.mixedrealitytoolkit.uxcore +- org.mixedrealitytoolkit.standardassets +- org.mixedrealitytoolkit.spatialmanipulation +- org.mixedrealitytoolkit.uxcomponents +- org.mixedrealitytoolkit.input + +These packages, along with their Unity dependencies, will enable you to explore most of our UX offerings and create projects ready to be deployed to various XR devices. You can always come back and add more packages to your project later. + +> [!NOTE] +> For more information on MRTK3 packages, see the [package overview page](../../packages/packages-overview.md). + +#### Additional dependencies + +There are a handful of optional packages that MRTK3 uses that aren't part of this toolkit. To obtain these packages, use the [Mixed Reality Feature Tool](./mixed-reality-feature-tool.md) and select the latest versions of the following in the **Discover Features** step. + +To run on **HoloLens 2** or to visualize controller models on a **Quest device**, an additional package is required: + +- **Platform Support → Mixed Reality OpenXR Plugin** + +To spatialize audio in your scene, an additional package is required: + +- **Spatial Audio → Microsoft Spatializer** (Optional) + +### Open the Unity project + +Open the Unity project and wait for Unity to finish importing the newly added packages. There may be two pop-up messages in this process: + +1. The first message asks whether you want to enable the new input backend. Select **yes**. +1. The second message asks whether you want to update XR InteractionLayerMask. Select **No Thanks**. + +Unity might restart a few times during this process; wait for it to finish before proceeding. + +### Configure MRTK profile after import + +Once imported, MRTK3 requires a profile to be set for the standalone target platform and each additional target platform. + +1. Navigate to **Edit > Project Settings**. +1. Under **Project Settings**, navigate to **MRTK3** and then switch to the standalone tab. Note that the profile is initially unspecified. +1. Populate the field with the default MRTK profile that ships with the core package. You can click the "Assign MRTK Default" button to auto-populate this field. Alternatively, you can find the profile under `Packages/org.mixedrealitytoolkit.core/Configuration/Default Profiles/MRTKProfile.asset`. + + > [!NOTE] + > Not all of the MRTK subsystems are shown in the screenshot below. The MRTK subsystems that you see may be different depending on the MRTK3 packages you've added to your project. + + ![Assign the default MRTK profile](../../images/mrtk-profile.png) + +1. Switch to the tabs of other build target(s) you want to use (for example, UWP, Android) and check to see if the profile is assigned. If not, repeat the previous step on the current tab. + +### Configure OpenXR-related settings + +Once imported, MRTK3 requires some configuration on OpenXR if you're targeting a specific XR device. Refer to the instructions on the following pages for platform-specific guidance. + +- [Deploy to an Android XR device](../../test-and-deploy/android-xr-deployment.md) +- [Deploy to a Quest device](../../test-and-deploy/quest-deployment.md) +- [Deploy to HoloLens 2](../../test-and-deploy/hololens2-deployment.md) + +## Next steps + +Once you've finished setting up your Unity project, proceed to [creating a new MRTK3 scene](./setup-new-scene.md). diff --git a/docs/mrtk3-overview/getting-started/setting-up/setup-new-scene.md b/docs/mrtk3-overview/getting-started/setting-up/setup-new-scene.md new file mode 100644 index 000000000..39a98ebb9 --- /dev/null +++ b/docs/mrtk3-overview/getting-started/setting-up/setup-new-scene.md @@ -0,0 +1,26 @@ +--- +title: Creating a new scene with MRTK3 +parent: Getting started with MRTK3 +nav_order: 4 +--- + +# Creating a new scene with MRTK3 + +The following will walk through through creating an AR/VR ready scene using MRTK3. + +1. Create a new Unity scene. +1. Add the **MRTK XR Rig** prefab. +1. Remove the **Main Camera** GameObject because **MRTK XR Rig** already contains a camera. + + ![MRTK XR rig screenshot](../../images/mrtk-xr-rig.png) + +1. Add the MRTK Input Simulator prefab to your scene. + + > [!NOTE] + > This step is optional, but required for in-editor input simulation. + + ![MRTK input simulator hierarchy pane](../../images/mrtk-input-simulator.png) + +## Next steps + +Once you've finished setting up your Unity project, learn how to [experience your application on a device](../../test-and-deploy/overview.md). diff --git a/docs/mrtk3-overview/getting-started/setting-up/setup-template.md b/docs/mrtk3-overview/getting-started/setting-up/setup-template.md new file mode 100644 index 000000000..1ac3c3992 --- /dev/null +++ b/docs/mrtk3-overview/getting-started/setting-up/setup-template.md @@ -0,0 +1,25 @@ +--- +title: Starting from the MRTK3 template project +parent: Getting started with MRTK3 +nav_order: 2 +--- + +# Starting from the MRTK3 template project + +The easiest way to acquire and try out MRTK3 is to explore our pre-configured project. This project contains references to all of the current MRTK3 packages and comes pre-configured with the project settings required to deploy to device. + +1. Clone the project from [the MRTK3 GitHub repo](https://github.com/MixedRealityToolkit/MixedRealityToolkit-Unity). + + > [!NOTE] + > If you work with Git using the command line, you can clone the repo with `git clone https://github.com/MixedRealityToolkit/MixedRealityToolkit-Unity.git` + +1. Launch Unity (2021.3.21f1 or newer) on the `MRTKDevTemplate` project under `UnityProjects` and start playing with the sample scenes in the Unity editor by using input simulation, remoting, or deploying them to devices. + +For information on the sample scenes included in the preview, see [Exploring MRTK3 sample scenes](../exploring-features/mrtk3-sample-scenes.md). + +## Next steps + +Once you've finished setting up your Unity project, choose one of the following options: + +* Learn how to [experience your application on a device](../../test-and-deploy/overview.md) +* Proceed to [creating a new MRTK3 scene](./setup-new-scene.md) diff --git a/docs/mrtk3-overview/images/MRDevDays/MRDD-04-GettingStartedMRTK3-1920x1080_w800.png b/docs/mrtk3-overview/images/MRDevDays/MRDD-04-GettingStartedMRTK3-1920x1080_w800.png new file mode 100644 index 000000000..1ff3f16f6 Binary files /dev/null and b/docs/mrtk3-overview/images/MRDevDays/MRDD-04-GettingStartedMRTK3-1920x1080_w800.png differ diff --git a/docs/mrtk3-overview/images/MRDevDays/MRDD-07-MRTK3BuildingBlocks-1920x1080_w800.png b/docs/mrtk3-overview/images/MRDevDays/MRDD-07-MRTK3BuildingBlocks-1920x1080_w800.png new file mode 100644 index 000000000..a1b38f993 Binary files /dev/null and b/docs/mrtk3-overview/images/MRDevDays/MRDD-07-MRTK3BuildingBlocks-1920x1080_w800.png differ diff --git a/docs/mrtk3-overview/images/MRDevDays/MRDD-10-BuildingRichUI-1920x1080_w800.png b/docs/mrtk3-overview/images/MRDevDays/MRDD-10-BuildingRichUI-1920x1080_w800.png new file mode 100644 index 000000000..ec97a0004 Binary files /dev/null and b/docs/mrtk3-overview/images/MRDevDays/MRDD-10-BuildingRichUI-1920x1080_w800.png differ diff --git a/docs/mrtk3-overview/images/MRDevDays/MRDD-12-WorkingWithDynamicData-1920x1080_w800.png b/docs/mrtk3-overview/images/MRDevDays/MRDD-12-WorkingWithDynamicData-1920x1080_w800.png new file mode 100644 index 000000000..6b204b393 Binary files /dev/null and b/docs/mrtk3-overview/images/MRDevDays/MRDD-12-WorkingWithDynamicData-1920x1080_w800.png differ diff --git a/docs/mrtk3-overview/images/MRDevDays/MRDD-15-HashOpenDeploy-1920x1080_w800.png b/docs/mrtk3-overview/images/MRDevDays/MRDD-15-HashOpenDeploy-1920x1080_w800.png new file mode 100644 index 000000000..d618f064c Binary files /dev/null and b/docs/mrtk3-overview/images/MRDevDays/MRDD-15-HashOpenDeploy-1920x1080_w800.png differ diff --git a/docs/mrtk3-overview/images/MRDevDays/MRDD-June8-04-IntroducingMRTK3-1920x1080_w800.png b/docs/mrtk3-overview/images/MRDevDays/MRDD-June8-04-IntroducingMRTK3-1920x1080_w800.png new file mode 100644 index 000000000..c503b32a7 Binary files /dev/null and b/docs/mrtk3-overview/images/MRDevDays/MRDD-June8-04-IntroducingMRTK3-1920x1080_w800.png differ diff --git a/docs/mrtk3-overview/images/MRTK3_Packages.png b/docs/mrtk3-overview/images/MRTK3_Packages.png new file mode 100644 index 000000000..4873ecdd1 Binary files /dev/null and b/docs/mrtk3-overview/images/MRTK3_Packages.png differ diff --git a/docs/mrtk3-overview/images/MRTK_v3_Architecture.png b/docs/mrtk3-overview/images/MRTK_v3_Architecture.png new file mode 100644 index 000000000..150a7d8fa Binary files /dev/null and b/docs/mrtk3-overview/images/MRTK_v3_Architecture.png differ diff --git a/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_Solver_Main.png b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_Solver_Main.png new file mode 100644 index 000000000..c9d18c397 Binary files /dev/null and b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_Solver_Main.png differ diff --git a/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_BoundsControl.png b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_BoundsControl.png new file mode 100644 index 000000000..763588da2 Binary files /dev/null and b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_BoundsControl.png differ diff --git a/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Button.png b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Button.png new file mode 100644 index 000000000..7be235604 Binary files /dev/null and b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Button.png differ diff --git a/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Dialog.png b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Dialog.png new file mode 100644 index 000000000..fbed3faab Binary files /dev/null and b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Dialog.png differ diff --git a/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_HandMenu.png b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_HandMenu.png new file mode 100644 index 000000000..75d13057c Binary files /dev/null and b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_HandMenu.png differ diff --git a/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_NearMenu.png b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_NearMenu.png new file mode 100644 index 000000000..539ff2acc Binary files /dev/null and b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_NearMenu.png differ diff --git a/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_ObjectManipulator.png b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_ObjectManipulator.png new file mode 100644 index 000000000..77bf23a62 Binary files /dev/null and b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_ObjectManipulator.png differ diff --git a/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Slate.png b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Slate.png new file mode 100644 index 000000000..be6fedf78 Binary files /dev/null and b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Slate.png differ diff --git a/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Slider.png b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Slider.png new file mode 100644 index 000000000..d2928521d Binary files /dev/null and b/docs/mrtk3-overview/images/UXBuildingBlocks/MRTK_UX_v3_Slider.png differ diff --git a/docs/mrtk3-overview/images/android-xr-openxr.png b/docs/mrtk3-overview/images/android-xr-openxr.png new file mode 100644 index 000000000..d1bd7f782 Binary files /dev/null and b/docs/mrtk3-overview/images/android-xr-openxr.png differ diff --git a/docs/mrtk3-overview/images/android-xr-plug-in-management.png b/docs/mrtk3-overview/images/android-xr-plug-in-management.png new file mode 100644 index 000000000..cfac97328 Binary files /dev/null and b/docs/mrtk3-overview/images/android-xr-plug-in-management.png differ diff --git a/docs/mrtk3-overview/images/github-release-mrgt.png b/docs/mrtk3-overview/images/github-release-mrgt.png new file mode 100644 index 000000000..d0c89d27b Binary files /dev/null and b/docs/mrtk3-overview/images/github-release-mrgt.png differ diff --git a/docs/mrtk3-overview/images/github-release.png b/docs/mrtk3-overview/images/github-release.png new file mode 100644 index 000000000..49121fec8 Binary files /dev/null and b/docs/mrtk3-overview/images/github-release.png differ diff --git a/docs/mrtk3-overview/images/hand-interaction-examples.png b/docs/mrtk3-overview/images/hand-interaction-examples.png new file mode 100644 index 000000000..ca1dbf035 Binary files /dev/null and b/docs/mrtk3-overview/images/hand-interaction-examples.png differ diff --git a/docs/mrtk3-overview/images/mrtk-input-simulator.png b/docs/mrtk3-overview/images/mrtk-input-simulator.png new file mode 100644 index 000000000..2848e512e Binary files /dev/null and b/docs/mrtk3-overview/images/mrtk-input-simulator.png differ diff --git a/docs/mrtk3-overview/images/mrtk-packages-folder.png b/docs/mrtk3-overview/images/mrtk-packages-folder.png new file mode 100644 index 000000000..a1b68f19a Binary files /dev/null and b/docs/mrtk3-overview/images/mrtk-packages-folder.png differ diff --git a/docs/mrtk3-overview/images/mrtk-profile.png b/docs/mrtk3-overview/images/mrtk-profile.png new file mode 100644 index 000000000..98268ebff Binary files /dev/null and b/docs/mrtk3-overview/images/mrtk-profile.png differ diff --git a/docs/mrtk3-overview/images/mrtk-xr-rig.png b/docs/mrtk3-overview/images/mrtk-xr-rig.png new file mode 100644 index 000000000..05bd1c797 Binary files /dev/null and b/docs/mrtk3-overview/images/mrtk-xr-rig.png differ diff --git a/docs/mrtk3-overview/images/mrtk3-featuretool-setup-packages.png b/docs/mrtk3-overview/images/mrtk3-featuretool-setup-packages.png new file mode 100644 index 000000000..be01b3b55 Binary files /dev/null and b/docs/mrtk3-overview/images/mrtk3-featuretool-setup-packages.png differ diff --git a/docs/mrtk3-overview/images/oculus-openxr.png b/docs/mrtk3-overview/images/oculus-openxr.png new file mode 100644 index 000000000..e9f57cb9a Binary files /dev/null and b/docs/mrtk3-overview/images/oculus-openxr.png differ diff --git a/docs/mrtk3-overview/images/setting-up/MRTK-Development-Setup-AndroidModule.png b/docs/mrtk3-overview/images/setting-up/MRTK-Development-Setup-AndroidModule.png new file mode 100644 index 000000000..3a63d207c Binary files /dev/null and b/docs/mrtk3-overview/images/setting-up/MRTK-Development-Setup-AndroidModule.png differ diff --git a/docs/mrtk3-overview/images/setting-up/MRTK-Development-Setup-UWPModule.png b/docs/mrtk3-overview/images/setting-up/MRTK-Development-Setup-UWPModule.png new file mode 100644 index 000000000..c06a0d21d Binary files /dev/null and b/docs/mrtk3-overview/images/setting-up/MRTK-Development-Setup-UWPModule.png differ diff --git a/docs/mrtk3-overview/images/standalone-openxr.png b/docs/mrtk3-overview/images/standalone-openxr.png new file mode 100644 index 000000000..5197da993 Binary files /dev/null and b/docs/mrtk3-overview/images/standalone-openxr.png differ diff --git a/docs/mrtk3-overview/images/standalone-xr-plug-in-management.png b/docs/mrtk3-overview/images/standalone-xr-plug-in-management.png new file mode 100644 index 000000000..1f25e560f Binary files /dev/null and b/docs/mrtk3-overview/images/standalone-xr-plug-in-management.png differ diff --git a/docs/mrtk3-overview/images/uwp-openxr.png b/docs/mrtk3-overview/images/uwp-openxr.png new file mode 100644 index 000000000..a429a068d Binary files /dev/null and b/docs/mrtk3-overview/images/uwp-openxr.png differ diff --git a/docs/mrtk3-overview/images/uwp-xr-plug-in-management.png b/docs/mrtk3-overview/images/uwp-xr-plug-in-management.png new file mode 100644 index 000000000..9846a2ebe Binary files /dev/null and b/docs/mrtk3-overview/images/uwp-xr-plug-in-management.png differ diff --git a/docs/mrtk3-overview/known-issues.md b/docs/mrtk3-overview/known-issues.md new file mode 100644 index 000000000..cfab42ed0 --- /dev/null +++ b/docs/mrtk3-overview/known-issues.md @@ -0,0 +1,8 @@ +--- +title: Known issues +nav_order: 7 +--- + +# Known issues + +For known issues in MRTK3, refer to [the issues page](https://github.com/MixedRealityToolkit/MixedRealityToolkit-Unity/issues?q=is%3Aopen+is%3Aissue) of our GitHub repo. diff --git a/docs/mrtk3-overview/packages/packages-overview.md b/docs/mrtk3-overview/packages/packages-overview.md new file mode 100644 index 000000000..b1e0021b0 --- /dev/null +++ b/docs/mrtk3-overview/packages/packages-overview.md @@ -0,0 +1,61 @@ +--- +title: Packages +nav_order: 4 +--- + +# Using MRTK3 packages + +Microsoft MRTK3 is distributed as a set of packages that are imported into Unity using the Unity Package Manager (UPM). These packages enable developers to customize the MRTK within their projects. + +## Dependencies + +Some MRTK3 packages require additional packages, some provided by Unity and some by other platform vendors, in order to correctly function. Some of these packages are optional and will enable additional functionality. + +The following diagram illustrates the relationship between MRTK packages and some of the Unity dependencies. + +![MRTK3 Package Graph](../images/MRTK3_Packages.png) + +The following table describes the Mixed Reality Toolkit package dependencies. + +| Display name | Package name | Description | Required | Optional | +| ----------- | ----------- | --------- | -------- | ---------- | +| MRTK Core Definitions | org.mixedrealitytoolkit.core | Shared definitions, utilities and components. | com.unity.xr.interaction.toolkit
com.unity.xr.management | | +| MRTK Accessibility | org.mixedrealitytoolkit.accessibility | Definitions, features and subsystem for building accessible mixed reality experiences. | org.mixedrealitytoolkit.core
org.mixedrealitytoolkit.graphicstools.unity
com.unity.textmeshpro | | +| MRTK Audio Effects | org.mixedrealitytoolkit.audio | Effects and features that enhance the audio in mixed reality experiences. | org.mixedrealitytoolkit.core | | +| MRTK Data Binding and Theming | org.mixedrealitytoolkit.data | Support for data binding and UI element theming. | org.mixedrealitytoolkit.core
com.unity.nuget.newtonsoft-json
com.unity.textmeshpro | | +| MRTK Diagnostics | org.mixedrealitytoolkit.diagnostics | Diagnostics and performance monitoring subsystems and tools. | org.mixedrealitytoolkit.core
com.unity.xr.management | | +| MRTK Environment | org.mixedrealitytoolkit.environment | Environmental features and subsystems, such as Spatial Awareness and boundaries. | org.mixedrealitytoolkit.core
com.unity.xr.management | | +| MRTK Extended Assets | org.mixedrealitytoolkit.extendedassets | Additional audio, font, texture and other assets for use in applications. | org.mixedrealitytoolkit.standardassets
org.mixedrealitytoolkit.graphicstools.unity | | +| MRTK Graphics Tools | org.mixedrealitytoolkit.graphicstools.unity | Shaders, textures, materials and models. | | com.unity.render-pipelines.universal | +| MRTK Input | org.mixedrealitytoolkit.input | Input components including support for articulated hands, offline speech recognition and in-editor input simulation. | org.mixedrealitytoolkit.core
org.mixedrealitytoolkit.graphicstools.unity
com.unity.xr.interaction.toolkit
com.unity.inputsystem
com.unity.xr.management
com.unity.xr.openxr
com.unity.xr.arfoundation | | +| MRTK Spatial Manipulation | org.mixedrealitytoolkit.spatialmanipulation | Spatial positioning and manipulation components and utilities, including solvers. | org.mixedrealitytoolkit.core
org.mixedrealitytoolkit.uxcore
com.unity.inputsystem
com.unity.xr.interaction.toolkit | org.mixedrealitytoolkit.input | +| MRTK Standard Assets | org.mixedrealitytoolkit.standardassets | Standard assets, including materials and textures, for use by applications. | org.mixedrealitytoolkit.graphicstools.unity | | +| MRTK Tools | org.mixedrealitytoolkit.tools | Collection of Unity Editor tools used to extend and optimize MRTK3 applications. | org.mixedrealitytoolkit.core | | +| MRTK UX Components | org.mixedrealitytoolkit.uxcomponents | MRTK UX component library, containing prefabs, visuals, pre-made controls, and everything to get started building 3D user interfaces for mixed reality. | org.mixedrealitytoolkit.uxcore
org.mixedrealitytoolkit.spatialmanipulation
com.microsoft.standardassets | | +| MRTK UX Components (Non-Canvas) | org.mixedrealitytoolkit.uxcomponents.noncanvas | MRTK non-Canvas UX component library, for building 3D UX without Canvas layout. For most production-grade UI, we recommend the dynamic hybrid Canvas-based UX systems, located in org.mixedrealitytoolkit.uxcomponents. However, in some circumstances, static/non-Canvas UI may offer improved performance and batching, and may be desirable in resource-constrained scenarios. | org.mixedrealitytoolkit.uxcore
org.mixedrealitytoolkit.spatialmanipulation
com.microsoft.standardassets | | +| MRTK UX Core | org.mixedrealitytoolkit.uxcore | Core interaction and visualization scripts for building MR user interface components.

Note: this is intended to be consumed in order to build UX libraries. To build MR interfaces with a pre-existing library of components, see org.mixedrealitytoolkit.uxcomponents. | org.mixedrealitytoolkit.core
org.mixedrealitytoolkit.graphicstools.unity
com.unity.inputsystem
com.unity.textmeshpro
com.unity.xr.interaction.toolkit | org.mixedrealitytoolkit.data | +| MRTK Windows Speech | org.mixedrealitytoolkit.windowsspeech | Speech subsystem implementation for native Windows speech APIs. Allows for the use of native Windows speech recognition to fire events and drive XRI interactions. | org.mixedrealitytoolkit.core | | + +## Running package tests + +Some MRTK packages contain tests used to validate the included components. In some cases, these tests require additional MRTK packages not asserted as dependencies. + +> [!NOTE] +> When importing packages into Unity, test assemblies aren't compiled by default. To enable compilation of tests, please use the `testables` element of the project's `manifest.json` file. + +In order to place minimal overhead on applications importing the Mixed Reality Toolkit, dependencies are asserted only for runtime requirements. The following table describes the additional packages required to enable compiling and running the included test assemblies. + +| Display name | Package name | Test requirements | +| ------------ | ------------ | ----------------- | +| MRTK Core Definitions | org.mixedrealitytoolkit.core | | +| MRTK Accessibility | org.mixedrealitytoolkit.accessibility | | +| MRTK Data Binding and Theming | org.mixedrealitytoolkit.data | | +| MRTK Diagnostics | org.mixedrealitytoolkit.diagnostics | | +| MRTK Environment | org.mixedrealitytoolkit.environment | | +| MRTK Extended Assets | org.mixedrealitytoolkit.extendedassets | | +| MRTK Input | org.mixedrealitytoolkit.input | | +| MRTK Spatial Manipulation | org.mixedrealitytoolkit.spatialmanipulation | org.mixedrealitytoolkit.input | +| MRTK Standard Assets | org.mixedrealitytoolkit.standardassets | | +| MRTK UX Components | org.mixedrealitytoolkit.uxcomponents | org.mixedrealitytoolkit.input | +| MRTK UX Core | org.mixedrealitytoolkit.uxcore | org.mixedrealitytoolkit.input | +| MRTK Windows Speech | org.mixedrealitytoolkit.windowsspeech | | diff --git a/docs/mrtk3-overview/test-and-deploy/android-xr-deployment.md b/docs/mrtk3-overview/test-and-deploy/android-xr-deployment.md new file mode 100644 index 000000000..ce90d2b20 --- /dev/null +++ b/docs/mrtk3-overview/test-and-deploy/android-xr-deployment.md @@ -0,0 +1,57 @@ +--- +title: Deploy to an Android XR device +parent: Test and experience overview +nav_order: 2 +--- + +# Deploy to an Android XR device + +This page describes how to deploy your Unity Project with MRTK3 onto an Android XR device. + +> [!NOTE] +> For general Android XR and Unity information, see the [Android XR developer docs](https://developer.android.com/develop/xr/unity). + +## Deployment Prerequisites + +1. Add MRTK to your project and ensure your [project settings](../getting-started/setting-up/setup-new-project.md#configure-openxr-related-settings) are configured correctly to use the OpenXR pipeline and MRTK's feature set. **These features are required to deploy your project onto your Android XR device**. + + > [!NOTE] + > If starting from the [template project](../getting-started/setting-up/setup-template.md), these project settings should already be configured for you. + +1. Navigate to **File > Build Settings**. + +1. Under **Platform**, select **Android**. Switch the platform to **Android**, and wait for the operation to finish. + +1. Navigate to **Edit > Project Settings**. + +1. Under **Project Settings**, navigate to **XR Plug-in Management** and enable **OpenXR** under the **Android** tab. Ensure that **Initialize XR on Startup** is selected and that no feature groups are enabled, and wait for the operation to finish. + + ![Android XR Plug-in Management window](../images/android-xr-plug-in-management.png) + + > [!NOTE] + > A yellow warning icon may appear after checking the **OpenXR** option. Click that icon to open the **OpenXR Project Validation** tool. Click **Fix All** and ignore the interaction profile issue that can't be auto-fixed. The profiles will be added in the step below. + +1. Under **Project Settings**, navigate to **XR Plug-in Management > OpenXR > Interaction Profiles** and ensure the following profiles are listed based on the MRTK features you'd like to use: + + | Profile | MRTK | + |---------|------| + | Hand Interaction Profile | For articulated hand input | + | Oculus Touch Controller Profile | For controller input | + +1. Under **Project Settings**, navigate to **XR Plug-in Management > OpenXR > OpenXR Feature Groups** and ensure the following features are checked under **All Features** based on the MRTK features you'd like to use: + + | Feature | MRTK | + |---------|------| + | Android XR: AR Session
Android XR: Hand Mesh Data | For rendering the system hand mesh | + | Hand Tracking Subsystem | For rendering the articulated hand joints | + + ![Android XR OpenXR](../images/android-xr-openxr.png) + + > [!NOTE] + > You can enable additional features as needed, but in-scene support for them will come from other packages, like AR Foundation. + +1. A yellow warning icon or red error icon may appear during this process. Click that icon to open the **OpenXR Project Validation** tool. Select **Fix All** to address the issues. There may be several items to address. + +## Deploying to Device + +1. After you have the project configured, proceed to [build and run the Unity Project](https://docs.unity3d.com/Manual/xr-run.html). diff --git a/docs/mrtk3-overview/test-and-deploy/hololens2-deployment.md b/docs/mrtk3-overview/test-and-deploy/hololens2-deployment.md new file mode 100644 index 000000000..4b94fe513 --- /dev/null +++ b/docs/mrtk3-overview/test-and-deploy/hololens2-deployment.md @@ -0,0 +1,90 @@ +--- +title: Deploy to HoloLens 2 +parent: Test and experience overview +nav_order: 4 +--- + +# Deploy to HoloLens 2 + +This page describes how to deploy your Unity Project with MRTK3 onto a HoloLens 2. + +> [!NOTE] +> We strongly recommend using [Holographic remoting](streaming.md) for rapid iteration and testing on HoloLens 2, which allows for instant testing on the device without the need for compile + deploy. + +## Deployment Prerequisites + +1. Add MRTK to your project and ensure your [project settings](../getting-started/setting-up/setup-new-project.md#configure-openxr-related-settings) are configured correctly to use the OpenXR pipeline and MRTK's feature set. **These features are required to deploy your project onto your HoloLens**. + + > [!NOTE] + > If starting from the [template project](../getting-started/setting-up/setup-template.md), these project settings should already be configured for you. + +1. Navigate to **File > Build Settings**. + +1. Under **Platform**, select **Universal Windows Platform**. Switch the platform to **Universal Windows Platform**, and wait for the operation to finish. + +1. Navigate to **Edit > Project Settings**. + +1. Under **Project Settings**, navigate to **XR Plug-in Management** and enable **OpenXR** under both the **Standalone** and **UWP** tabs. Under each tab, ensure that **Initialize XR on Startup** is selected and that the **Windows Mixed Reality feature group** under **Standalone** and the **Microsoft HoloLens feature group** under **UWP** are enabled. + + > [!NOTE] + > If you don't see these **feature groups**, ensure the **Mixed Reality OpenXR Plugin** is imported into your project. + + For standalone: + + [![Standalone XR Plug-in Management window](../images/standalone-xr-plug-in-management.png)](../images/standalone-xr-plug-in-management.png) + + For UWP: + + [![UWP XR Plug-in Management window](../images/uwp-xr-plug-in-management.png)](../images/uwp-xr-plug-in-management.png) + + > [!NOTE] + > A yellow warning icon may appear after checking the **OpenXR** option. Click that icon to open the **OpenXR Project Validation** tool. Click **Fix All** and ignore the interaction profile issue that can't be auto-fixed. The profiles will be added in the step below. + +1. Under **Project Settings**, navigate to **XR Plug-in Management > OpenXR > Interaction Profiles** and ensure the following profiles are listed based on the MRTK features you'd like to use: + + | Profile | MRTK | + |---------|------| + | Eye Gaze Interaction Profile | For eye tracking input | + | Hand Interaction Profile | For articulated hand input | + | Microsoft Motion Controller Profile | For controller input | + +1. Under **Project Settings**, navigate to **XR Plug-in Management > OpenXR > OpenXR Feature Groups** and ensure the following features are checked under **All Features** based on the MRTK features you'd like to use (these are likely to be already checked after selecting the **feature groups** above): + + | Feature | MRTK | + |---------|------| + | Hand Tracking Subsystem | For rendering the articulated hand joints | + | Mixed Reality Features | For general HoloLens and WMR support | + | Motion Controller Model | For rendering the motion controller models | + + For standalone: + + [![Standalone OpenXR](../images/standalone-openxr.png)](../images/standalone-openxr.png) + + For UWP: + + [![UWP OpenXR](../images/uwp-openxr.png)](../images/uwp-openxr.png) + + > [!NOTE] + > You can enable additional features as needed, but in-scene support for them will come from other packages, like AR Foundation. + +1. For HoloLens 2, we recommend that you set **Depth Submission Mode** to 16-bit in the settings above. + +1. For immersive headsets, you can use 24-bit depth submission. See the [Microsoft development docs for Unity](https://learn.microsoft.com/windows/mixed-reality/develop/unity/recommended-settings-for-unity?tabs=openxr#enable-depth-buffer-sharing) for more info. + +1. A yellow warning icon or red error icon may appear during this process. Click that icon to open the **OpenXR Project Validation** tool. Select **Fix All** to address the issues. There may be several items to address. For more information about Windows App Capabilities, see [App capability declarations](https://learn.microsoft.com/windows/uwp/packaging/app-capability-declarations) + +## Using platform controller models + +> [!NOTE] +> **Controller models** are stored in a format that is not natively supported by Unity. To use MRTK Controller Visualization on WMR, you will need to make sure you have the following package in your project: +> +> - [glTFast importer](https://github.com/atteneder/glTFast) which enables the use of glTF asset files in Unity and allows the use of MRTK Controller Visualization on WMR +> +> If you started with the MRTK3 template project, this package has already been included in the project. +> If not, an MRTK project validation rule will help you import the package. + +## Deploying to Device + +1. After you have the project configured, proceed to [Build the Unity Project](https://learn.microsoft.com/windows/mixed-reality/develop/unity/build-and-deploy-to-hololens#build-the-unity-project). + +1. Once built, you'll need to deploy the project through [Visual Studio](https://learn.microsoft.com/windows/mixed-reality/develop/advanced-concepts/using-visual-studio?tabs=hl2). diff --git a/docs/mrtk3-overview/test-and-deploy/overview.md b/docs/mrtk3-overview/test-and-deploy/overview.md new file mode 100644 index 000000000..d284e6dd5 --- /dev/null +++ b/docs/mrtk3-overview/test-and-deploy/overview.md @@ -0,0 +1,28 @@ +--- +title: Test and experience overview +nav_order: 3 +--- + +# Test and experience overview + +Now that you have a Unity project with MRTK3, there are several means to test and experience your application. + +## Preview your application + +Compiling and deploying your app can take a significant amount of time, so we recommend using the following instant iteration/preview solutions while developing your application. + +- [In-editor input simulation](../../mrtk3-input/packages/input/input-simulation.md) + - Easily preview your app without any XR device attached. Control the user's head, hands, and hand gestures with traditional WASD controls. + +- [Stream to a device](./streaming.md) + - These solutions allow you to run the app locally in the Unity editor in Play Mode and stream the experience to your device. All inputs from your device are sent to the PC, where the content is then rendered in a virtual immersive view. We highly recommend this solution for instant iteration and for showcasing prototypes + +## Build and deploy + +The following guides will walk you through building and running your application on a device. + +- [Deploy to an Android XR device](./android-xr-deployment.md) +- [Deploy to a Quest device](./quest-deployment.md) +- [Deploy to HoloLens 2](./hololens2-deployment.md) + +If you've deployed a build to your target device of choice, you can debug the build as it runs on device with [Managed debugging](https://learn.microsoft.com/windows/mixed-reality/develop/unity/managed-debugging-with-unity-il2cpp). diff --git a/docs/mrtk3-overview/test-and-deploy/quest-deployment.md b/docs/mrtk3-overview/test-and-deploy/quest-deployment.md new file mode 100644 index 000000000..f07a11841 --- /dev/null +++ b/docs/mrtk3-overview/test-and-deploy/quest-deployment.md @@ -0,0 +1,80 @@ +--- +title: Deploy to a Quest device +parent: Test and experience overview +nav_order: 3 +--- + +# Deploy to a Quest device + +This page describes how to deploy your Unity Project with MRTK3 onto a Quest device. + +> [!NOTE] +> We strongly recommend using [Meta Quest Link](https://www.meta.com/quest/) for rapid iteration and testing on Quest Devices, which allows for instant testing on the device without the need for compile + deploy. + +## Deployment Prerequisites + +These steps are based around OpenXR as your runtime (i.e. XR plugin provider) as we don't recommend using OculusXR due to underlying compatibility issues. + +1. Ensure that your project is ready to deploy on the Quest Device by following [these steps](https://developer.oculus.com/documentation/unity/book-unity-gsg/). + +1. Ensure that [developer mode](https://developer.oculus.com/documentation/native/android/mobile-device-setup/#enable-developer-mode) is enabled on your device (you may need to [join a developer team](https://developers.meta.com/horizon/documentation/native/android/mobile-device-setup/#joining-or-creating-a-team) first). Installing the Oculus ADB Drivers is optional. + +1. Add MRTK to your project and ensure that your [project settings](../getting-started/setting-up/setup-new-project.md#configure-openxr-related-settings) are configured correctly to use the OpenXR pipeline and MRTK's feature set. **These features are required to deploy your project onto your Quest device**. + + > [!NOTE] + > If starting from the [template project](../getting-started/setting-up/setup-template.md), these project settings should already be configured for you. + +1. Navigate to **File > Build Settings**. + +1. Under **Platform**, select **Android**. Switch the platform to **Android**, and wait for the operation to finish. + +1. Navigate to **Edit > Project Settings**. + +1. Under **Project Settings**, navigate to **XR Plug-in Management** and enable **OpenXR** under the **Standalone** and **Android** tabs. Ensure that **Initialize XR on Startup** is selected and that no feature groups are enabled, and wait for the operation to finish. + + ![Android XR Plug-in Management window](../images/android-xr-plug-in-management.png) + + > [!NOTE] + > A yellow warning icon may appear after checking the **OpenXR** option. Click that icon to open the **OpenXR Project Validation** tool. Click **Fix All** and ignore the interaction profile issue that can't be auto-fixed. The profiles will be added in the step below. + +1. Under **Project Settings**, navigate to **XR Plug-in Management > OpenXR > Interaction Profiles** and ensure the following profiles are listed based on the MRTK features you'd like to use: + + | Profile | MRTK | + |---------|------| + | Hand Interaction Profile | For articulated hand input | + | Oculus Touch Controller Profile | For controller input | + +1. Under **Project Settings**, navigate to **XR Plug-in Management > OpenXR > OpenXR Feature Groups** and ensure the following features are checked under **All Features** based on the MRTK features you'd like to use: + + | Feature | MRTK | + |---------|------| + | Hand Tracking Subsystem | For rendering the articulated hand joints | + | Meta Quest Support | For general Quest settings, like Android Manifest permissions | + | Motion Controller Model | For rendering the Touch controller models | + + > [!NOTE] + > If you don't see **Motion Controller Model** under the **OpenXR Feature Groups** panel, ensure the **Mixed Reality OpenXR Plugin** is imported into your project. + + ![Meta Quest OpenXR](../images/oculus-openxr.png) + + > [!NOTE] + > You can enable additional features as needed, but in-scene support for them will come from other packages, like AR Foundation. + +1. A yellow warning icon or red error icon may appear during this process. Click that icon to open the **OpenXR Project Validation** tool. Select **Fix All** to address the issues. There may be several items to address. + +1. If you plan on using the native keyboard, please refer to the [keyboard documentation](../../mrtk3-input/packages/input/System-keyboard.md#meta-quest-specific-setup) for a required `AndroidManifest.xml` modification. + +## Using platform controller models + +> [!NOTE] +> **Controller models** are stored in a format that is not natively supported by Unity. To use MRTK Controller Visualization on Quest, you will need to make sure you have the following packages in your project: +> +> - [glTFast importer](https://github.com/atteneder/glTFast) which enables the use of glTF asset files in Unity and allows the use of MRTK Controller Visualization on Quest +> - [KTX extension](https://github.com/atteneder/KtxUnity) which allows users to load KTX or Basis Universal texture files +> +> If you started with the MRTK3 template project, these packages have already been included in the project. +> If not, an MRTK project validation rule will help you import the packages. + +## Deploying to Device + +After you have the project configured, proceed to [generate, deploy, and run a build](https://developers.meta.com/horizon/documentation/unity/unity-build/#generate-deploy-and-run-a-build). We recommend that you select **Build and Run**. This option lets Unity deploy your project directly to your Quest device. diff --git a/docs/mrtk3-overview/test-and-deploy/streaming.md b/docs/mrtk3-overview/test-and-deploy/streaming.md new file mode 100644 index 000000000..75dded9ee --- /dev/null +++ b/docs/mrtk3-overview/test-and-deploy/streaming.md @@ -0,0 +1,20 @@ +--- +title: Iteration and debugging +parent: Test and experience overview +nav_order: 1 +--- + +# Streaming your application to a device + +These options detail how to stream your application to the device of your choice. Streaming your application allows for rapid iteration and development, as the application runs locally on your machine, without the need to compile and install onto your device. It also allows you to use Unity's plethora of in-editor debugging tools and features. + +- [Holographic remoting (on HoloLens 2)](https://learn.microsoft.com/windows/mixed-reality/develop/unity/preview-and-debug-your-app) + - For development on HoloLens 2 and related platforms (including other OpenXR targets that include hand tracking), we strongly recommend the use of holographic remoting to accelerate your iteration time. Advanced features like hand tracking, eye tracking, and scene reconstruction are available through remoting, and behave the same as if the app were deployed to a device. +- Play-mode testing with the desktop's active OpenXR runtime + - Many popular PC VR platforms now support OpenXR, including [Windows Mixed Reality](https://learn.microsoft.com/windows/mixed-reality/develop/native/openxr-getting-started), [SteamVR](https://www.steamvr.com/), and [Oculus Rift on PC](https://developer.oculus.com/documentation/native/pc/dg-openxr/). +- [Meta Quest Link](https://www.meta.com/quest/) + - Some aspects of hand interactions are still being developed for Quest, and your results may vary. + - Controller interactions should be full parity over Link. + - In **Player Settings** > **OpenXR**, the following must be assigned for the **Windows, Mac, Linux Settings** tab: + - Set **Play Mode OpenXR Runtime** to **Oculus OpenXR**. + - Add the **Oculus Touch Controller Profile** to the list of **Interaction Profiles**. diff --git a/Images/AboutMRTK.png b/images/AboutMRTK.png similarity index 100% rename from Images/AboutMRTK.png rename to images/AboutMRTK.png diff --git a/Images/MRTK3_banner.png b/images/MRTK3_banner.png similarity index 100% rename from Images/MRTK3_banner.png rename to images/MRTK3_banner.png diff --git a/Images/MRTK_Unity_header.png b/images/MRTK_Unity_header.png similarity index 100% rename from Images/MRTK_Unity_header.png rename to images/MRTK_Unity_header.png diff --git a/org.mixedrealitytoolkit.accessibility/LICENSE.md b/org.mixedrealitytoolkit.accessibility/LICENSE.md index f5efea740..6e8fd4a19 100644 --- a/org.mixedrealitytoolkit.accessibility/LICENSE.md +++ b/org.mixedrealitytoolkit.accessibility/LICENSE.md @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Mixed Reality Toolkit Contributors +Copyright (c) 2025, Mixed Reality Toolkit Contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/org.mixedrealitytoolkit.accessibility/README.md b/org.mixedrealitytoolkit.accessibility/README.md new file mode 100644 index 000000000..4938e6b1d --- /dev/null +++ b/org.mixedrealitytoolkit.accessibility/README.md @@ -0,0 +1,6 @@ +# MRTK Accessibility + +Features and subsystem to enable accessibility in MR experiences. + +> [!IMPORTANT] +> This is in early preview and may undergo significant, breaking changes before release. diff --git a/org.mixedrealitytoolkit.accessibility/README.md.meta b/org.mixedrealitytoolkit.accessibility/README.md.meta new file mode 100644 index 000000000..f42fdb7e8 --- /dev/null +++ b/org.mixedrealitytoolkit.accessibility/README.md.meta @@ -0,0 +1,7 @@ +fileFormatVersion: 2 +guid: b73c3a1806e94bb4cba9902b138246da +TextScriptImporter: + externalObjects: {} + userData: + assetBundleName: + assetBundleVariant: diff --git a/org.mixedrealitytoolkit.audio/LICENSE.md b/org.mixedrealitytoolkit.audio/LICENSE.md index f5efea740..6e8fd4a19 100644 --- a/org.mixedrealitytoolkit.audio/LICENSE.md +++ b/org.mixedrealitytoolkit.audio/LICENSE.md @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Mixed Reality Toolkit Contributors +Copyright (c) 2025, Mixed Reality Toolkit Contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/org.mixedrealitytoolkit.audio/README.md b/org.mixedrealitytoolkit.audio/README.md new file mode 100644 index 000000000..90bd2e8e8 --- /dev/null +++ b/org.mixedrealitytoolkit.audio/README.md @@ -0,0 +1,5 @@ +# MRTK Audio Effects + +Features to enhance audio in XR experiences. + +For the audio effects to be spatialized, a spatializer plugin must be imported into the project. Spatializer plugins may be platform specific. diff --git a/org.mixedrealitytoolkit.audio/README.md.meta b/org.mixedrealitytoolkit.audio/README.md.meta new file mode 100644 index 000000000..828d6a432 --- /dev/null +++ b/org.mixedrealitytoolkit.audio/README.md.meta @@ -0,0 +1,7 @@ +fileFormatVersion: 2 +guid: c8ac948d30a45a347bd386135037553b +TextScriptImporter: + externalObjects: {} + userData: + assetBundleName: + assetBundleVariant: diff --git a/org.mixedrealitytoolkit.audio/package.json b/org.mixedrealitytoolkit.audio/package.json index 282f54933..714997930 100644 --- a/org.mixedrealitytoolkit.audio/package.json +++ b/org.mixedrealitytoolkit.audio/package.json @@ -1,7 +1,7 @@ { "name": "org.mixedrealitytoolkit.audio", "version": "3.0.5-development", - "description": "Features to enhance audio in xr experiences.\n\nFor the audio effects to be spatialized, a spatializer plugin must be imported into the project. Spatializer plugins may be platform specific.", + "description": "Features to enhance audio in XR experiences.\n\nFor the audio effects to be spatialized, a spatializer plugin must be imported into the project. Spatializer plugins may be platform specific.", "displayName": "MRTK Audio Effects", "msftFeatureCategory": "MRTK3", "author": "Mixed Reality Toolkit Contributors", diff --git a/org.mixedrealitytoolkit.core/Editor/MRTKProjectValidation.cs b/org.mixedrealitytoolkit.core/Editor/MRTKProjectValidation.cs index 92dfcd404..c563e8c65 100644 --- a/org.mixedrealitytoolkit.core/Editor/MRTKProjectValidation.cs +++ b/org.mixedrealitytoolkit.core/Editor/MRTKProjectValidation.cs @@ -122,7 +122,7 @@ private static BuildValidationRule GenerateProfileRule(BuildTargetGroup buildTar AssetDatabase.LoadAssetAtPath(AssetDatabase.GUIDToAssetPath(DefaultMRTKProfileGuid))), FixItMessage = $"Assign the default MRTK3 profile for the {buildTargetGroup} build target", Error = false, - HelpLink = "https://learn.microsoft.com/windows/mixed-reality/mrtk-unity/mrtk3-overview/getting-started/setting-up/setup-new-project#4-configure-mrtk-profile-after-import" + HelpLink = "https://mixedrealitytoolkit.github.io/MixedRealityToolkit-Unity/mrtk3-overview/getting-started/setting-up/setup-new-project.html#4-configure-mrtk-profile-after-import" }; } diff --git a/org.mixedrealitytoolkit.core/LICENSE.md b/org.mixedrealitytoolkit.core/LICENSE.md index f5efea740..6e8fd4a19 100644 --- a/org.mixedrealitytoolkit.core/LICENSE.md +++ b/org.mixedrealitytoolkit.core/LICENSE.md @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Mixed Reality Toolkit Contributors +Copyright (c) 2025, Mixed Reality Toolkit Contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/org.mixedrealitytoolkit.core/README.md b/org.mixedrealitytoolkit.core/README.md new file mode 100644 index 000000000..6e70ebfc5 --- /dev/null +++ b/org.mixedrealitytoolkit.core/README.md @@ -0,0 +1,3 @@ +# MRTK Core Definitions + +A limited collection of common interfaces and utilities that most MRTK packages share. Most implementations of these interfaces are contained in other packages in the MRTK ecosystem. diff --git a/org.mixedrealitytoolkit.core/README.md.meta b/org.mixedrealitytoolkit.core/README.md.meta new file mode 100644 index 000000000..c2b915daa --- /dev/null +++ b/org.mixedrealitytoolkit.core/README.md.meta @@ -0,0 +1,7 @@ +fileFormatVersion: 2 +guid: 9b06c6cc0db4d3b41abbc19a5f746cc5 +TextScriptImporter: + externalObjects: {} + userData: + assetBundleName: + assetBundleVariant: diff --git a/org.mixedrealitytoolkit.data/Documentation~/DataBinding.md b/org.mixedrealitytoolkit.data/Documentation~/DataBinding.md index 3578337e6..6485636e1 100644 --- a/org.mixedrealitytoolkit.data/Documentation~/DataBinding.md +++ b/org.mixedrealitytoolkit.data/Documentation~/DataBinding.md @@ -1,6 +1,7 @@ -# Data Binding Framework +# Data binding framework -**NOTE: This framework is still under development and APIs may change. Also see Known Limitations section below for more information.** +> [!WARNING] +> This framework is experimental, and APIs may change. Also see the [Known Limitations](#known-limitations-and-missing-features) section below for more information. Welcome to the data binding framework of MRTK. This framework is designed to make it easy to create visual elements that can be populated dynamically at runtime with data being provided from an external @@ -80,7 +81,7 @@ that have registered to receive change notifications. ### Data Source Provider -A simple interface that has a single method to retrieve a data source. This is designed to allow a MonoBehavior scripting component to be auto-discovered in the game object hierarchy by data consumer components, but without the need to implement a data source directly on the game object itself. This is useful when an existing MonoBehaviour must derive from another class and multiple inheritance prevents deriving from DataSourceGOBase. It also allows more code to have no Unity dependencies. +A simple interface that has a single method to retrieve a data source. This is designed to allow a MonoBehavior scripting component to be auto-discovered in the game object hierarchy by data consumer components, but without the need to implement a data source directly on the game object itself. This is useful when an existing MonoBehaviour must derive from another class and multiple inheritance prevents deriving from DataSourceGOBase. It also allows more code to have no Unity dependencies. ### Key Path (string) @@ -97,12 +98,12 @@ which are the two most prevalent means of transferring information from back*end Example key paths: -* temperature -* contacts[10].firstName -* contacts -* contacts[10].addresses[3].city -* [10].title -* kingdom.animal.mammal.aardvark.diet.foodtypes.termites +* `temperature` +* `contacts[10].firstName` +* `contacts` +* `contacts[10].addresses[3].city` +* `[10].title` +* `kingdom.animal.mammal.aardvark.diet.foodtypes.termites` Given that a key path is an arbitrary string with no required taxonomy, the actual data specifiers could be any method of describing what data to retrieve. XML's XPath is an @@ -123,7 +124,7 @@ not matter where in a larger data set hierarchy it actually exists. The most cri use of this ability is to describe the data of a single entry in a list without worrying about which entry in that list the current instance is referencing. -Since a "fully resolved" Key path is always generated and consumed by a DataSource and should never (or at least rarely) be modified by a DataConsumer or other external component, it can have any structure that makes sense to the DataSource. For example, if a prefab to show a list entry for a photo and it's title, date taken and other attributes, the local key path in the prefab might look like this: +Since a "fully resolved" Key path is always generated and consumed by a DataSource and should never (or at least rarely) be modified by a DataConsumer or other external component, it can have any structure that makes sense to the DataSource. For example, if a prefab to show a list entry for a photo and it's title, date taken and other attributes, the local key path in the prefab might look like this: * "photo_url" * "title" @@ -175,23 +176,23 @@ list of products, photos, or contacts. This is accomplished by assigning an item placer to the collection data consumer. This item placer is the logic tha knows how to request list items, accept prefabs that have been populated with variable data, and then present them to the user, typically by inserting them into a list managed by a ux layout component for lists. -# Theming +## Theming -Theming uses all of the plumbing of data sources and data consumers. It is possible to theme any hierarchy of GameObjects whether they are static or are dynamically data bound to other data sources. This allows for both data binding and theming to be applied in combination. It is even possible to theme the data coming from another data source. +Theming uses all of the plumbing of data sources and data consumers. It is possible to theme any hierarchy of GameObjects whether they are static or are dynamically data bound to other data sources. This allows for both data binding and theming to be applied in combination. It is even possible to theme the data coming from another data source. ## Theming UXComponents -The standard UXComponents controls provided in the UXComponents package are all configured to support theming. It is turned OFF by default, but is easy to enable. +The standard UXComponents controls provided in the UXComponents package are all configured to support theming. It is turned OFF by default, but is easy to enable. Each control, typically on the topmost GameObject of the root prefab, has a script called UXBindingConfigurator. This script, if enabled, will pull in the needed data binding scripts to turn on theming. Make sure to import the Data Binding and Theming package as well. -**Note on TextMeshPro StyleSheets**: It is not currently possible to use StyleSheets to style the TextMeshPro *Normal* style. Any other style that is included in TextMeshPro's *Default Style Sheet* can be used. The examples use *Body* to work around this limitation. +**Note on TextMeshPro StyleSheets**: It is not currently possible to use StyleSheets to style the TextMeshPro *Normal* style. Any other style that is included in TextMeshPro's *Default Style Sheet* can be used. The examples use *Body* to work around this limitation. ## Data Consumer Theming Theming is accomplished by Data Consumers, particularly ones that inherit from DataConsumerThemeBase\, DataConsumerTextStyle and custom DataConsumer classes that any developer can implement to enhance the theming support. -The DataConsumerThemeBase\ base class provides logic to use an integer or key datum from a primary data source to then look up the desired final value from a secondary theme database. This is accomplished by mapping the input data to a theme keypath, and then using that theme keypath to retrieve the final value. This allows for any element to be both data bound and themed at the same time. As an example, imagine a status field in a database with statuses of New, Started, and Done represented by values 0, 1 and 2. Each of these can be represented by a Sprite icon. For data binding, a value from 0 to 2 is used to lookup the desired sprite. With theming and data binding, the theme profile points to the correct list of 3 sprites in the theme profile and then the value from 0 to 2 is used to select the correct sprite from that list. This allows the styling of these icons to differ per theme. +The DataConsumerThemeBase\ base class provides logic to use an integer or key datum from a primary data source to then look up the desired final value from a secondary theme database. This is accomplished by mapping the input data to a theme keypath, and then using that theme keypath to retrieve the final value. This allows for any element to be both data bound and themed at the same time. As an example, imagine a status field in a database with statuses of New, Started, and Done represented by values 0, 1 and 2. Each of these can be represented by a Sprite icon. For data binding, a value from 0 to 2 is used to lookup the desired sprite. With theming and data binding, the theme profile points to the correct list of 3 sprites in the theme profile and then the value from 0 to 2 is used to select the correct sprite from that list. This allows the styling of these icons to differ per theme. When both runtime theming and dynamic data binding are used together, a DataConsumerThemeHelper class can be specified in any DataConsumerThemeBase derived class to notify when a theme has changed. @@ -249,7 +250,7 @@ An example for retrieving a themed status icon from a database containing a nume ### TextMeshPro StyleSheets -Theming is able to activate TMPro stylesheets. "TMP Settings" ScriptableObject dictates where stylesheets are expected to be in the Resources. It's the "Default Font Asset => Path" property. +Theming is able to activate TMPro stylesheets. "TMP Settings" ScriptableObject dictates where stylesheets are expected to be in the Resources. It's the "Default Font Asset => Path" property. Make sure to place any app specific StyleSheets in the same sub-path off of Resources. If you wish to organize them differently, make sure to update "TMP Settings" to match. @@ -257,7 +258,7 @@ Make sure to place any app specific StyleSheets in the same sub-path off of Reso If you are developing new UX controls, it is relatively easy to make them themable. To the extent that the control uses Materials, Sprites, and other assets already in use by other UX controls, it is generally a matter of naming the various game objects in a discoverable way. -It's possible to inherit from the MRTK_UXCore_ThemeProfile and add more themable fields, or point your controls to your own ScriptableObject. There is nothing magical about the ones provided other than the organization of the ScriptableObject will determine the keypaths need to access individual data items, via C# Reflection. +It's possible to inherit from the MRTK_UXCore_ThemeProfile and add more themable fields, or point your controls to your own ScriptableObject. There is nothing magical about the ones provided other than the organization of the ScriptableObject will determine the keypaths need to access individual data items, via C# Reflection. By adding a BindingConfigurator.cs script to the top level of the new control, you can then specify your own serialized BindingProfile ScriptableObject to provide the necessary GameObject name to KeyPath mappings needed to associate your themable elements with the data provided in the theme profile. This script will automatically add any needed DataConsumerXXX components at runtime to support the theming you wish to use. @@ -270,7 +271,7 @@ By adding a BindingConfigurator.cs script to the top level of the new control, y ### Sample Scene -For a first step, take a close look at the "Data Binding Test" scene that demonstrates a variety of variable data scenarios. Simply load the scene and play. A few things to notice: +For a first step, take a close look at the "Data Binding Test" scene that demonstrates a variety of variable data scenarios. Simply load the scene and play. A few things to notice: * The Text Input field of TextMeshPro components contain variables that look like this: {{ firstName }} * Game objects for sprites and text have some form of Data Consumer component that manages receiving data and updating views. @@ -289,7 +290,7 @@ Create an empty game object and rename it to "Data Binding". Add a DataSourceJso In the inspector, change the Url to: -Add a UI -> Text - TextMeshPro object to the Data Binding game object. It will add a canvas and then a "Text (TMP)" object. +Add a UI -> Text - TextMeshPro object to the Data Binding game object. It will add a canvas and then a "Text (TMP)" object. Select the Text (TMP) object, and in the inspector change the Text Input to: @@ -297,13 +298,13 @@ Select the Text (TMP) object, and in the inspector change the Text Input to: Select the canvas object and add a Data Consumer Text component to it. -Run the project. Every 15 seconds, a different activity will be shown. +Run the project. Every 15 seconds, a different activity will be shown. Congratulations. You've created your first Data Binding project with MRTK! ### Writing a new Data Source -A data source provides data to one or more data consumers. It's data can be anything: algorithmically generated, in RAM, on disk, or fetched from a central database. +A data source provides data to one or more data consumers. It's data can be anything: algorithmically generated, in RAM, on disk, or fetched from a central database. All Data sources must provide the IDataSource interface. Some of the basic functionality is offered in a base class called DataSourceBase. You most likely want to derive from this class to add the specific data management functionality specific to your need. @@ -317,15 +318,15 @@ A data consumer gets notifications when data has changed and then updates some a All data consumers must provide the IDataConsumer interface. Some of the basic functionality is offered in a base class called DataConsumerGOBase, where GO stands for GameObject. -The majority of the work of a data consumer is to accept new data and then prepare it for presentation. This may be as simple as selecting the right prefab, or it could mean fetching more data from a cloud service such as a content management system. +The majority of the work of a data consumer is to accept new data and then prepare it for presentation. This may be as simple as selecting the right prefab, or it could mean fetching more data from a cloud service such as a content management system. ### Writing a data collection item placer A data collection item placer is responsible for managing which parts of a collection are currently visible and how to present that visible collection, whether the collection is a small static list, or a giant million record database. -All item placers must provide the IDataCollectionItemPlacer interface. Some of the basic functionality is offered in a base class called DataCollectionItemPlacerGOBase. All item placers should derive from this class. +All item placers must provide the IDataCollectionItemPlacer interface. Some of the basic functionality is offered in a base class called DataCollectionItemPlacerGOBase. All item placers should derive from this class. -# Known Limitations and Missing Features +## Known Limitations and Missing Features * Need to verify proper cleanup of resources in all use cases, particularly lists. * Dynamic changes to list data completely refreshes entire list instead of incrementally updating. diff --git a/org.mixedrealitytoolkit.data/LICENSE.md b/org.mixedrealitytoolkit.data/LICENSE.md index f5efea740..6e8fd4a19 100644 --- a/org.mixedrealitytoolkit.data/LICENSE.md +++ b/org.mixedrealitytoolkit.data/LICENSE.md @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Mixed Reality Toolkit Contributors +Copyright (c) 2025, Mixed Reality Toolkit Contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/org.mixedrealitytoolkit.data/README.md b/org.mixedrealitytoolkit.data/README.md new file mode 100644 index 000000000..5d1c3ccb6 --- /dev/null +++ b/org.mixedrealitytoolkit.data/README.md @@ -0,0 +1,3 @@ +# MRTK Data Binding and Theming + +Data binding and theming features contained within this package are experimental and are not recommended for use in production applications and may be changed or removed. diff --git a/org.mixedrealitytoolkit.data/README.md.meta b/org.mixedrealitytoolkit.data/README.md.meta new file mode 100644 index 000000000..a26010ad3 --- /dev/null +++ b/org.mixedrealitytoolkit.data/README.md.meta @@ -0,0 +1,7 @@ +fileFormatVersion: 2 +guid: b6c62464be719cc4092d76ba6554a924 +TextScriptImporter: + externalObjects: {} + userData: + assetBundleName: + assetBundleVariant: diff --git a/org.mixedrealitytoolkit.data/Runtime/Scripts/DataConsumers/README.md b/org.mixedrealitytoolkit.data/Runtime/Scripts/DataConsumers/README.md index bf7af981a..4312ee8a5 100644 --- a/org.mixedrealitytoolkit.data/Runtime/Scripts/DataConsumers/README.md +++ b/org.mixedrealitytoolkit.data/Runtime/Scripts/DataConsumers/README.md @@ -1,19 +1,17 @@ -# DataConsumers folder +# Data Consumers -Data Consumers are objects that implement the IDataConsumer interface. They listen for data change notifications from a Data Source and then retrieve those data changes to update view objects that present the changed data. +Data Consumers are objects that implement the IDataConsumer interface. They listen for data change notifications from a Data Source and then retrieve those data changes to update view objects that present the changed data. -Typical data consumers take variable text or numeric data to populate a user interface, but they can be much more sophisticated. They can take a variable URL, retrieve an image at that URL, then convert it to a Sprite object and assign that to a SpriteRenderer object. +Typical data consumers take variable text or numeric data to populate a user interface, but they can be much more sophisticated. They can take a variable URL, retrieve an image at that URL, then convert it to a Sprite object and assign that to a SpriteRenderer object. ## Data Source -Any one data consumer is designed to communicate with a single data source. For more complex cases, a data source aggregator can be used to combine data sets from multiple data sources. This feature does not exist yet. The default means of associating a data consumer and its data source is to navigate up the game object hierarchy until a data source is found. +Any one data consumer is designed to communicate with a single data source. For more complex cases, a data source aggregator can be used to combine data sets from multiple data sources. This feature does not exist yet. The default means of associating a data consumer and its data source is to navigate up the game object hierarchy until a data source is found. ## Key Paths -A data consumer uses "key paths" to identify which datum is of interest in the overall data set managed by a Data Source. A single data consumer can manage as many of these key paths as it wishes. +A data consumer uses "key paths" to identify which datum is of interest in the overall data set managed by a Data Source. A single data consumer can manage as many of these key paths as it wishes. ## Collections -A data consumer can be designed to manage a collection of data sets where each item in the collection contains data that is relatively similar to other elements in the same list. The data consumer can request from a data source, ranges if items from such a list. The data is actually the fully resolved keypaths of each item that can then further be used to populate each item. In this scenario, each item is typically a Unity Prefab with variable data fields such as TextMeshPro components that then each individually assign listeners for their own data. - - +A data consumer can be designed to manage a collection of data sets where each item in the collection contains data that is relatively similar to other elements in the same list. The data consumer can request from a data source, ranges if items from such a list. The data is actually the fully resolved keypaths of each item that can then further be used to populate each item. In this scenario, each item is typically a Unity Prefab with variable data fields such as TextMeshPro components that then each individually assign listeners for their own data. diff --git a/org.mixedrealitytoolkit.data/Runtime/Scripts/DataSources/README.md b/org.mixedrealitytoolkit.data/Runtime/Scripts/DataSources/README.md index aeaa895de..442ce49fb 100644 --- a/org.mixedrealitytoolkit.data/Runtime/Scripts/DataSources/README.md +++ b/org.mixedrealitytoolkit.data/Runtime/Scripts/DataSources/README.md @@ -1,13 +1,11 @@ -# DataSources folder +# Data Sources -Data Sources are objects that implement the IDataSource interface. They manage a data set and can notify Data Consumers when any data has changed (or upon initial load). These can be as simple as a single number generator, and as complex as very large XML or JSON data sets retrieved from a RESTful web service, including binary data such as images. +Data Sources are objects that implement the IDataSource interface. They manage a data set and can notify Data Consumers when any data has changed (or upon initial load). These can be as simple as a single number generator, and as complex as very large XML or JSON data sets retrieved from a RESTful web service, including binary data such as images. ## Key Paths -A single datum in the data set managed by the Data Source is identified by a key path. A key path is an arbitrary text string that can uniquely identify each datum of interest. A key path or set of key paths can consist of any namespace, any data access scheme such as XPaths, or as is the case with all data sources provided here, can be data accessors consistent with javascript accessing its own data structures created programmatically or via loading JSON. +A single datum in the data set managed by the Data Source is identified by a key path. A key path is an arbitrary text string that can uniquely identify each datum of interest. A key path or set of key paths can consist of any namespace, any data access scheme such as XPaths, or as is the case with all data sources provided here, can be data accessors consistent with javascript accessing its own data structures created programmatically or via loading JSON. ## Key Path Mappers -So that multiple different data sources can populate the same standard view template, key path mappers can be used to map data namespaces to view namespaces and visa versa. This mechanism allows for flexible pairings between standard data sources and standard data consumers. - - +So that multiple different data sources can populate the same standard view template, key path mappers can be used to map data namespaces to view namespaces and visa versa. This mechanism allows for flexible pairings between standard data sources and standard data consumers. diff --git a/org.mixedrealitytoolkit.data/Runtime/Scripts/Helper/README.md b/org.mixedrealitytoolkit.data/Runtime/Scripts/Helper/README.md index c4f6f806e..0db2c291a 100644 --- a/org.mixedrealitytoolkit.data/Runtime/Scripts/Helper/README.md +++ b/org.mixedrealitytoolkit.data/Runtime/Scripts/Helper/README.md @@ -1,3 +1,3 @@ # Helper folder -The classes in this folder provide various miscellaneous services to other classes. They themselves are not concrete implementations of the public interfaces provided for this data framework. \ No newline at end of file +The classes in this folder provide various miscellaneous services to other classes. They themselves are not concrete implementations of the public interfaces provided for this data framework. diff --git a/org.mixedrealitytoolkit.data/Runtime/Scripts/Interfaces/README.md b/org.mixedrealitytoolkit.data/Runtime/Scripts/Interfaces/README.md index c9702115b..70104e262 100644 --- a/org.mixedrealitytoolkit.data/Runtime/Scripts/Interfaces/README.md +++ b/org.mixedrealitytoolkit.data/Runtime/Scripts/Interfaces/README.md @@ -1,5 +1,5 @@ # Interfaces -The C# interfaces in this folder define all of the allowed communication between objects. This ensures maximum flexibility for combining concepts in new combinations through dependency injection. +The C# interfaces in this folder define all of the allowed communication between objects. This ensures maximum flexibility for combining concepts in new combinations through dependency injection. See each interface for more information. diff --git a/org.mixedrealitytoolkit.data/Runtime/Scripts/ItemPlacers/README.md b/org.mixedrealitytoolkit.data/Runtime/Scripts/ItemPlacers/README.md index 18d666ddc..eed5dd0a8 100644 --- a/org.mixedrealitytoolkit.data/Runtime/Scripts/ItemPlacers/README.md +++ b/org.mixedrealitytoolkit.data/Runtime/Scripts/ItemPlacers/README.md @@ -1,10 +1,9 @@ -# ItemPlacers folder +# Item Placers The classes in this folder implement the IDataCollectionItemPlacer interface. -Item placers are used by data consumers that manage collections of data sets. The item placer can request items in a list in the form of game objects, usually a prefab. These prefabs contain their own data consumers which will have been assigned the same data source as the data consumer that manages the collection itself. +Item placers are used by data consumers that manage collections of data sets. The item placer can request items in a list in the form of game objects, usually a prefab. These prefabs contain their own data consumers which will have been assigned the same data source as the data consumer that manages the collection itself. As it is provided with these modified prefabs, it can use any strategy to manage the items and make them visible to the user. Typically, they will be added to a UX view collection with scroll bars, page next and previous, swipe up/down, or other means of navigating the list. Item placers also support virtualization by requesting only those objects that are currently visible. It also supports data pooling, where any list items that go out of visible range can be returned back to the pool for re-use, thus reducing garbage collection and the overhead of instantiating complex prefabs for every item in a large collection. - diff --git a/org.mixedrealitytoolkit.data/package.json b/org.mixedrealitytoolkit.data/package.json index 0dc0608de..515ca25be 100644 --- a/org.mixedrealitytoolkit.data/package.json +++ b/org.mixedrealitytoolkit.data/package.json @@ -1,7 +1,7 @@ { "name": "org.mixedrealitytoolkit.data", "version": "1.0.3-development.pre.20", - "description": "Data binding and theming features contained within this package are experimental, and are not recommended for use in production applications and may be changed or removed.", + "description": "Data binding and theming features contained within this package are experimental and are not recommended for use in production applications and may be changed or removed.", "displayName": "MRTK3 Data Binding and Theming (Experimental)", "msftFeatureCategory": "Experimental", "author": "Mixed Reality Toolkit Contributors", diff --git a/org.mixedrealitytoolkit.diagnostics/LICENSE.md b/org.mixedrealitytoolkit.diagnostics/LICENSE.md index f5efea740..6e8fd4a19 100644 --- a/org.mixedrealitytoolkit.diagnostics/LICENSE.md +++ b/org.mixedrealitytoolkit.diagnostics/LICENSE.md @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Mixed Reality Toolkit Contributors +Copyright (c) 2025, Mixed Reality Toolkit Contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/org.mixedrealitytoolkit.diagnostics/README.md b/org.mixedrealitytoolkit.diagnostics/README.md new file mode 100644 index 000000000..518e73453 --- /dev/null +++ b/org.mixedrealitytoolkit.diagnostics/README.md @@ -0,0 +1,3 @@ +# MRTK Diagnostics + +Subsystems and utilities for common diagnostic and performance monitoring tasks. diff --git a/org.mixedrealitytoolkit.diagnostics/README.md.meta b/org.mixedrealitytoolkit.diagnostics/README.md.meta new file mode 100644 index 000000000..ef5778b98 --- /dev/null +++ b/org.mixedrealitytoolkit.diagnostics/README.md.meta @@ -0,0 +1,7 @@ +fileFormatVersion: 2 +guid: 145056c3cfb79634bb0e5f79f4e1eb1f +TextScriptImporter: + externalObjects: {} + userData: + assetBundleName: + assetBundleVariant: diff --git a/org.mixedrealitytoolkit.extendedassets/LICENSE.md b/org.mixedrealitytoolkit.extendedassets/LICENSE.md index f5efea740..6e8fd4a19 100644 --- a/org.mixedrealitytoolkit.extendedassets/LICENSE.md +++ b/org.mixedrealitytoolkit.extendedassets/LICENSE.md @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Mixed Reality Toolkit Contributors +Copyright (c) 2025, Mixed Reality Toolkit Contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/org.mixedrealitytoolkit.extendedassets/README.md b/org.mixedrealitytoolkit.extendedassets/README.md new file mode 100644 index 000000000..7f02bcb60 --- /dev/null +++ b/org.mixedrealitytoolkit.extendedassets/README.md @@ -0,0 +1,3 @@ +# MRTK Extended Assets + +This package offers additional assets helpful for example scenes or rapid prototyping. These assets are in addition to the more commonly-used assets located in StandardAssets. diff --git a/org.mixedrealitytoolkit.extendedassets/README.md.meta b/org.mixedrealitytoolkit.extendedassets/README.md.meta new file mode 100644 index 000000000..8b3c4c01f --- /dev/null +++ b/org.mixedrealitytoolkit.extendedassets/README.md.meta @@ -0,0 +1,7 @@ +fileFormatVersion: 2 +guid: 9eb8c78ce3eb986448d94217e674d970 +TextScriptImporter: + externalObjects: {} + userData: + assetBundleName: + assetBundleVariant: diff --git a/org.mixedrealitytoolkit.input/LICENSE.md b/org.mixedrealitytoolkit.input/LICENSE.md index f5efea740..6e8fd4a19 100644 --- a/org.mixedrealitytoolkit.input/LICENSE.md +++ b/org.mixedrealitytoolkit.input/LICENSE.md @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Mixed Reality Toolkit Contributors +Copyright (c) 2025, Mixed Reality Toolkit Contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/org.mixedrealitytoolkit.input/README.md b/org.mixedrealitytoolkit.input/README.md new file mode 100644 index 000000000..a32a11f35 --- /dev/null +++ b/org.mixedrealitytoolkit.input/README.md @@ -0,0 +1,3 @@ +# MRTK Input + +This package extends the XR Interaction Toolkit with custom interactors and controllers, hand-joint aggregation, and simulation subsystems. It seamlessly integrates with the Unity Input System. diff --git a/org.mixedrealitytoolkit.input/README.md.meta b/org.mixedrealitytoolkit.input/README.md.meta new file mode 100644 index 000000000..a1b9c7b05 --- /dev/null +++ b/org.mixedrealitytoolkit.input/README.md.meta @@ -0,0 +1,7 @@ +fileFormatVersion: 2 +guid: 535958f31b7700146bf4a50ad8019728 +TextScriptImporter: + externalObjects: {} + userData: + assetBundleName: + assetBundleVariant: diff --git a/org.mixedrealitytoolkit.input/Simulation/InputSimulatorControls.md b/org.mixedrealitytoolkit.input/Simulation/InputSimulatorControls.md index 80da3dead..2a4fde0da 100644 --- a/org.mixedrealitytoolkit.input/Simulation/InputSimulatorControls.md +++ b/org.mixedrealitytoolkit.input/Simulation/InputSimulatorControls.md @@ -1,4 +1,4 @@ -# Mixed Reality Toolkit Input Simulator Default Controls +# MRTK Input Simulator default controls ## Camera @@ -23,7 +23,7 @@ ## Eye Gaze -> ![NOTE] +> [!NOTE] > To better match the behavior of hardware that provides eye tracking support, when enabled, simulated eye gaze is always tracked. ### Look diff --git a/org.mixedrealitytoolkit.input/Visualizers/RiggedHandVisualizer/README.md b/org.mixedrealitytoolkit.input/Visualizers/RiggedHandVisualizer/README.md index e4d7fc92e..5334b12b1 100644 --- a/org.mixedrealitytoolkit.input/Visualizers/RiggedHandVisualizer/README.md +++ b/org.mixedrealitytoolkit.input/Visualizers/RiggedHandVisualizer/README.md @@ -1,3 +1,5 @@ +# FAQ + ## Why are there three different shaders + materials for the rigged hand? URP doesn't support multipass shaders, unfortunately! So we have to split the three passes @@ -15,8 +17,8 @@ render pipelines! It's a model that we've had internally for a while (since the early days of MRTK!) It's been re-rigged and painted with the correct vertex colors for MRTK3. -## I want hands with a different shader/color/material/model/etc! +## I want hands with a different shader/color/material/model/etc Great! You can build your own hand model prefab with your own custom mesh or materials, and still use the RiggedHandMeshVisualizer.cs script. The script expects joints/armatures in the -default Blender format, following OpenXR joint conventions. \ No newline at end of file +default Blender format, following OpenXR joint conventions. diff --git a/org.mixedrealitytoolkit.spatialmanipulation/LICENSE.md b/org.mixedrealitytoolkit.spatialmanipulation/LICENSE.md index f5efea740..6e8fd4a19 100644 --- a/org.mixedrealitytoolkit.spatialmanipulation/LICENSE.md +++ b/org.mixedrealitytoolkit.spatialmanipulation/LICENSE.md @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Mixed Reality Toolkit Contributors +Copyright (c) 2025, Mixed Reality Toolkit Contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/org.mixedrealitytoolkit.spatialmanipulation/README.md b/org.mixedrealitytoolkit.spatialmanipulation/README.md new file mode 100644 index 000000000..8ae7214d4 --- /dev/null +++ b/org.mixedrealitytoolkit.spatialmanipulation/README.md @@ -0,0 +1,3 @@ +# MRTK Spatial Manipulation + +Spatial manipulation features, including ObjectManipulator, BoundsControl, and the Solvers/Constraints systems. diff --git a/org.mixedrealitytoolkit.spatialmanipulation/README.md.meta b/org.mixedrealitytoolkit.spatialmanipulation/README.md.meta new file mode 100644 index 000000000..804a8a6c9 --- /dev/null +++ b/org.mixedrealitytoolkit.spatialmanipulation/README.md.meta @@ -0,0 +1,7 @@ +fileFormatVersion: 2 +guid: 4b9f162f8fe4d264dab92bdf89b5dca6 +TextScriptImporter: + externalObjects: {} + userData: + assetBundleName: + assetBundleVariant: diff --git a/org.mixedrealitytoolkit.standardassets/Fonts/README.md b/org.mixedrealitytoolkit.standardassets/Fonts/README.md index 3de2818af..8a34451b3 100644 --- a/org.mixedrealitytoolkit.standardassets/Fonts/README.md +++ b/org.mixedrealitytoolkit.standardassets/Fonts/README.md @@ -1,11 +1,7 @@ -# Fonts and Icons sources +# Fonts sources ## Selawik* fonts -Selawik* font files taken from products that supply this font as per https://learn.microsoft.com/en-us/typography/font-list/selawik#products-that-supply-this-font -Font source files: https://github.com/microsoft/Selawik +Selawik* font files taken from products that supply this font as per -## Fluent icons - -Fluent icons source: https://github.com/microsoft/fluentui-system-icons/tree/d3bce76153b47755b3390799e446d002de6f9d46 -Specific file: https://github.com/microsoft/fluentui-system-icons/blob/d3bce76153b47755b3390799e446d002de6f9d46/fonts/FluentSystemIcons-Regular.ttf +Font source files: diff --git a/org.mixedrealitytoolkit.standardassets/Icons/README.md b/org.mixedrealitytoolkit.standardassets/Icons/README.md index 3de2818af..e9aeb2311 100644 --- a/org.mixedrealitytoolkit.standardassets/Icons/README.md +++ b/org.mixedrealitytoolkit.standardassets/Icons/README.md @@ -1,11 +1,7 @@ -# Fonts and Icons sources - -## Selawik* fonts - -Selawik* font files taken from products that supply this font as per https://learn.microsoft.com/en-us/typography/font-list/selawik#products-that-supply-this-font -Font source files: https://github.com/microsoft/Selawik +# Icons sources ## Fluent icons -Fluent icons source: https://github.com/microsoft/fluentui-system-icons/tree/d3bce76153b47755b3390799e446d002de6f9d46 -Specific file: https://github.com/microsoft/fluentui-system-icons/blob/d3bce76153b47755b3390799e446d002de6f9d46/fonts/FluentSystemIcons-Regular.ttf +Fluent icons source: + +Specific file: diff --git a/org.mixedrealitytoolkit.standardassets/LICENSE.md b/org.mixedrealitytoolkit.standardassets/LICENSE.md index f5efea740..6e8fd4a19 100644 --- a/org.mixedrealitytoolkit.standardassets/LICENSE.md +++ b/org.mixedrealitytoolkit.standardassets/LICENSE.md @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Mixed Reality Toolkit Contributors +Copyright (c) 2025, Mixed Reality Toolkit Contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/org.mixedrealitytoolkit.standardassets/README.md b/org.mixedrealitytoolkit.standardassets/README.md new file mode 100644 index 000000000..a1f49d21b --- /dev/null +++ b/org.mixedrealitytoolkit.standardassets/README.md @@ -0,0 +1,3 @@ +# MRTK Standard Assets + +Common assets used by the MRTK packages, including common fonts, materials, and models. Relies on the Graphics Tools collection of shaders. diff --git a/org.mixedrealitytoolkit.standardassets/README.md.meta b/org.mixedrealitytoolkit.standardassets/README.md.meta new file mode 100644 index 000000000..252abf2f0 --- /dev/null +++ b/org.mixedrealitytoolkit.standardassets/README.md.meta @@ -0,0 +1,7 @@ +fileFormatVersion: 2 +guid: 61a19797be602144990e9c8555f441bc +TextScriptImporter: + externalObjects: {} + userData: + assetBundleName: + assetBundleVariant: diff --git a/org.mixedrealitytoolkit.tools/LICENSE.md b/org.mixedrealitytoolkit.tools/LICENSE.md index f5efea740..6e8fd4a19 100644 --- a/org.mixedrealitytoolkit.tools/LICENSE.md +++ b/org.mixedrealitytoolkit.tools/LICENSE.md @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Mixed Reality Toolkit Contributors +Copyright (c) 2025, Mixed Reality Toolkit Contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/org.mixedrealitytoolkit.tools/README.md b/org.mixedrealitytoolkit.tools/README.md new file mode 100644 index 000000000..720c430c6 --- /dev/null +++ b/org.mixedrealitytoolkit.tools/README.md @@ -0,0 +1,3 @@ +# MRTK Tools + +A collection of tools, utilities, and wizards that can be used to create and analyze components for use with MRTK3. diff --git a/org.mixedrealitytoolkit.tools/README.md.meta b/org.mixedrealitytoolkit.tools/README.md.meta new file mode 100644 index 000000000..c0b85837a --- /dev/null +++ b/org.mixedrealitytoolkit.tools/README.md.meta @@ -0,0 +1,7 @@ +fileFormatVersion: 2 +guid: 9ef1678e64809b741ac01e5089bcb3ba +TextScriptImporter: + externalObjects: {} + userData: + assetBundleName: + assetBundleVariant: diff --git a/org.mixedrealitytoolkit.uxcomponents.noncanvas/LICENSE.md b/org.mixedrealitytoolkit.uxcomponents.noncanvas/LICENSE.md index f5efea740..6e8fd4a19 100644 --- a/org.mixedrealitytoolkit.uxcomponents.noncanvas/LICENSE.md +++ b/org.mixedrealitytoolkit.uxcomponents.noncanvas/LICENSE.md @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Mixed Reality Toolkit Contributors +Copyright (c) 2025, Mixed Reality Toolkit Contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/org.mixedrealitytoolkit.uxcomponents.noncanvas/README.md b/org.mixedrealitytoolkit.uxcomponents.noncanvas/README.md new file mode 100644 index 000000000..07b22015a --- /dev/null +++ b/org.mixedrealitytoolkit.uxcomponents.noncanvas/README.md @@ -0,0 +1,3 @@ +# MRTK UX Components (Non-Canvas) + +UX component library for 3D UX without Canvas layout. In some cases, non-Canvas UI may offer better performance. diff --git a/org.mixedrealitytoolkit.uxcomponents.noncanvas/README.md.meta b/org.mixedrealitytoolkit.uxcomponents.noncanvas/README.md.meta new file mode 100644 index 000000000..549669ff7 --- /dev/null +++ b/org.mixedrealitytoolkit.uxcomponents.noncanvas/README.md.meta @@ -0,0 +1,7 @@ +fileFormatVersion: 2 +guid: 3fc14fdb416bb55479b26d4e9c273684 +TextScriptImporter: + externalObjects: {} + userData: + assetBundleName: + assetBundleVariant: diff --git a/org.mixedrealitytoolkit.uxcomponents/Button/Prefabs/README.md b/org.mixedrealitytoolkit.uxcomponents/Button/Prefabs/README.md index c9579de08..ab1bc3994 100644 --- a/org.mixedrealitytoolkit.uxcomponents/Button/Prefabs/README.md +++ b/org.mixedrealitytoolkit.uxcomponents/Button/Prefabs/README.md @@ -12,4 +12,4 @@ The Playables graph is constructed at runtime. A future update may implement edi ## Can I still use my own AnimatorController? -Right now, `StateVisualizer` overrides the control data flowing to the Animator. In a future update, it will be configurable to blend with existing AnimatorController behaviors. \ No newline at end of file +Right now, `StateVisualizer` overrides the control data flowing to the Animator. In a future update, it will be configurable to blend with existing AnimatorController behaviors. diff --git a/org.mixedrealitytoolkit.uxcomponents/LICENSE.md b/org.mixedrealitytoolkit.uxcomponents/LICENSE.md index f5efea740..6e8fd4a19 100644 --- a/org.mixedrealitytoolkit.uxcomponents/LICENSE.md +++ b/org.mixedrealitytoolkit.uxcomponents/LICENSE.md @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Mixed Reality Toolkit Contributors +Copyright (c) 2025, Mixed Reality Toolkit Contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/org.mixedrealitytoolkit.uxcomponents/README.md b/org.mixedrealitytoolkit.uxcomponents/README.md new file mode 100644 index 000000000..c8978f6bb --- /dev/null +++ b/org.mixedrealitytoolkit.uxcomponents/README.md @@ -0,0 +1,3 @@ +# MRTK UX Components + +UX library leveraging RectTransform and Canvas for dynamic layout and presentation. Contains prefabs, visuals, controls, and everything to get started building 3D user interfaces for mixed reality. diff --git a/org.mixedrealitytoolkit.uxcomponents/README.md.meta b/org.mixedrealitytoolkit.uxcomponents/README.md.meta new file mode 100644 index 000000000..d5b217a95 --- /dev/null +++ b/org.mixedrealitytoolkit.uxcomponents/README.md.meta @@ -0,0 +1,7 @@ +fileFormatVersion: 2 +guid: 3ee77a885d40a084fa1a7839dddd2b9e +TextScriptImporter: + externalObjects: {} + userData: + assetBundleName: + assetBundleVariant: diff --git a/org.mixedrealitytoolkit.uxcore/LICENSE.md b/org.mixedrealitytoolkit.uxcore/LICENSE.md index f5efea740..6e8fd4a19 100644 --- a/org.mixedrealitytoolkit.uxcore/LICENSE.md +++ b/org.mixedrealitytoolkit.uxcore/LICENSE.md @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Mixed Reality Toolkit Contributors +Copyright (c) 2025, Mixed Reality Toolkit Contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/org.mixedrealitytoolkit.uxcore/LegacyDialog/README.md b/org.mixedrealitytoolkit.uxcore/LegacyDialog/README.md index 7fc9ba386..8a7ed8789 100644 --- a/org.mixedrealitytoolkit.uxcore/LegacyDialog/README.md +++ b/org.mixedrealitytoolkit.uxcore/LegacyDialog/README.md @@ -1,3 +1,3 @@ -## What is this? +# Legacy Dialog -This folder contains the deprecated legacy Dialog implementation ported from MRTK v2. If you'd like to continue using this legacy Dialog implementation, we recommend copying this folder to your local project and maintaining the implementation yourself. Otherwise, we strongly recommend migrating to the new Dialog system located in the uxcore/Dialog folder. \ No newline at end of file +"Legacy Dialog" is the deprecated legacy Dialog implementation ported from MRTK v2. If you'd like to continue using this legacy Dialog implementation, we recommend copying this folder to your local project and maintaining the implementation yourself. Otherwise, we strongly recommend migrating to the new Dialog system located in the uxcore/Dialog folder. diff --git a/org.mixedrealitytoolkit.uxcore/README.md b/org.mixedrealitytoolkit.uxcore/README.md new file mode 100644 index 000000000..d75298bf6 --- /dev/null +++ b/org.mixedrealitytoolkit.uxcore/README.md @@ -0,0 +1,3 @@ +# MRTK UX Core Scripts + +Core interaction and visualization scripts for building MR UI components. Intended to be consumed when building UX libraries. For pre-existing library of components, see the UX Components package. diff --git a/org.mixedrealitytoolkit.uxcore/README.md.meta b/org.mixedrealitytoolkit.uxcore/README.md.meta new file mode 100644 index 000000000..0e18d922f --- /dev/null +++ b/org.mixedrealitytoolkit.uxcore/README.md.meta @@ -0,0 +1,7 @@ +fileFormatVersion: 2 +guid: bd8144f4bfe0e274886ba3265fcbf7f2 +TextScriptImporter: + externalObjects: {} + userData: + assetBundleName: + assetBundleVariant: diff --git a/org.mixedrealitytoolkit.uxcore/package.json b/org.mixedrealitytoolkit.uxcore/package.json index 88e45802c..23ccbd8a2 100644 --- a/org.mixedrealitytoolkit.uxcore/package.json +++ b/org.mixedrealitytoolkit.uxcore/package.json @@ -1,7 +1,7 @@ { "name": "org.mixedrealitytoolkit.uxcore", "version": "3.3.0-development", - "description": "Core interaction and visualization scripts for building MR UI components. Intended to be consumed when building UX libraries. For pre-existing library of components see the UX Components package.", + "description": "Core interaction and visualization scripts for building MR UI components. Intended to be consumed when building UX libraries. For pre-existing library of components, see the UX Components package.", "displayName": "MRTK UX Core Scripts", "msftFeatureCategory": "MRTK3", "author": "Mixed Reality Toolkit Contributors", diff --git a/org.mixedrealitytoolkit.windowsspeech/LICENSE.md b/org.mixedrealitytoolkit.windowsspeech/LICENSE.md index f5efea740..6e8fd4a19 100644 --- a/org.mixedrealitytoolkit.windowsspeech/LICENSE.md +++ b/org.mixedrealitytoolkit.windowsspeech/LICENSE.md @@ -1,6 +1,6 @@ BSD 3-Clause License -Copyright (c) 2023, Mixed Reality Toolkit Contributors +Copyright (c) 2025, Mixed Reality Toolkit Contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/org.mixedrealitytoolkit.windowsspeech/README.md b/org.mixedrealitytoolkit.windowsspeech/README.md index 06533dc10..92010ed61 100644 --- a/org.mixedrealitytoolkit.windowsspeech/README.md +++ b/org.mixedrealitytoolkit.windowsspeech/README.md @@ -1,10 +1,11 @@ -# Mixed Reality Toolkit Speech Package +# MRTK Windows Speech -Author: Max Wang (wangmax) +Speech subsystem implementation for native Windows speech APIs enables native Windows text-to-speech and speech recognition features, producing events to drive XRI interactions using speech. ## How to use -Note: this guide provides steps to enable speech subsystem in a new MRTK project (with other basic non-speech related setup in place). If you are using our sample project you may notice some steps have been performed for you. +> [!NOTE] +> This guide provides steps to enable speech subsystem in a new MRTK project (with other basic non-speech related setup in place). If you are using our sample project you may notice some steps have been performed for you. ### 1. Enable the speech subsystem @@ -12,7 +13,7 @@ Go to Project Settings -> Mixed Reality Toolkit -> Available MRTK Subsystems and ### 2. Configure the profile correctly (for certain subsystems) -For certain subsystems, a profile is required in order for it to perform normally. First check if the Configuration slot is empty. If so create a new profile by Assets -> Create -> MRTK -> Subsystems -> [name of your subsystem] Config and then drag the created config onto the slot. After making sure the config slot is populated, change the settings for your specific project. +For certain subsystems, a profile is required in order for it to perform normally. First check if the Configuration slot is empty. If so create a new profile by Assets -> Create -> MRTK -> Subsystems -> \[name of your subsystem\] Config and then drag the created config onto the slot. After making sure the config slot is populated, change the settings for your specific project. ### 3. Ensure the MRTK Speech GameObject is active