Using MRTK in large projects

This page contains some useful tips for consumers of MRTK that are pulling it into existing large projects, or setting up something new that will be source controlled and have multiple developers.

We recommend reading all of the guidelines below, following them will help avoid some tricky issues when working on larger codebases

gitignore

The following .gitignore file is a recommended base to pull in when consuming MRTK - there parts of MRTK that creates local state that can be safely ignored by source control, which would otherwise dirty local git state.

Note that the beginning parts of this are taken from the default github Unity .gitignore with MRTK-specific additions later. Also note that some of these rules assume certain paths, and can be modified based on where MRTK is located within your project.

# This .gitignore file should be placed at the root of your Unity project directory
#
# Get latest from https://github.com/github/gitignore/blob/master/Unity.gitignore
#
/[Ll]ibrary/
/[Tt]emp/
/[Oo]bj/
/[Bb]uild/
/[Bb]uilds/
/[Ll]ogs/

# MemoryCaptures can get excessive in size.
# They also could contain extremely sensitive data
/[Mm]emoryCaptures/

# Asset meta data should only be ignored when the corresponding asset is also ignored
!/[Aa]ssets/**/*.meta

# Uncomment this line if you wish to ignore the asset store tools plugin
# /[Aa]ssets/AssetStoreTools*

# Autogenerated Jetbrains Rider plugin
/[Aa]ssets/Plugins/Editor/JetBrains*

# Visual Studio cache directory
.vs/

# Gradle cache directory
.gradle/

# Autogenerated VS/MD/Consulo solution and project files
ExportedObj/
.consulo/
*.csproj
*.unityproj
*.sln
*.suo
*.tmp
*.user
*.userprefs
*.pidb
*.booproj
*.svd
*.pdb
*.mdb
*.opendb
*.VC.db

# Unity3D generated meta files
*.pidb.meta
*.pdb.meta
*.mdb.meta

# Unity3D generated file on crash reports
sysinfo.txt

# Builds
*.apk
*.unitypackage

# Crashlytics generated file
crashlytics-build.properties

# NuGet Build Process Generated
# This section covers files that are generated when consuming/using MRTK from NuGet
# May not be relevant if consuming via .unitypackages
/NuGet/*
!/NuGet/BuildSource.proj
/MRTKBuild/
/MSBuild/
/PackagesCopy/
!/scripts/Packaging/NuGetRestoreProject.csproj

# MSBuildForUnity generated
# This section covers files that are generated by the MSBuildForUnity system
# which MRTK uses to consume certain NuGet packages. Useful for when MSBuildForUnity
# is enabled on the project (in the MRTK configurator)
MSBuildForUnity.Common.props
/*.msb4u.csproj.meta
*.msb4u.csproj.meta
/*.msb4u.sln.meta
*.msb4u.sln.meta
Dependencies*
Nuget.config*

# DotNetAdapter specific
# This section covers files that are deployed by the imported DotNetWinRT NuGet package
# This is primarily used for Unity Editor to HoloLens 2 in-editor remoting
!/Assets/MixedRealityToolkit.Providers/WindowsMixedReality/Shared/DotNetAdapter/DotNetAdapter.csproj
Assets/MixedRealityToolkit.Providers/WindowsMixedReality/Shared/DotNetAdapter/.bin/
Assets/MixedRealityToolkit.Providers/WindowsMixedReality/Shared/DotNetAdapter/.obj/

ProjectPreferences.asset file

Project-wide MRTK settings can be found under the Edit -> Project Settings -> Mixed Reality Toolkit location. These settings will be saved to a file at this location in the Assets folder:

Assets/MixedRealityToolkit.Generated/ProjectPreferences.asset

If your project will have multiple collaborators, it is recommended that this asset file be checked in after doing an initial setup of MRTK settings. In particular, consider having the following settings checked:

Lock SDK Profiles - If this is disabled, the default MRTK profiles will be globally editable, which will make MRTK upgrades challenging (it can lead to merge conflicts in the framework itself)

Ignore MRTK project configurator - If this is disabled, the project configurator will show if the current MRTK settings do not match MRTK recommended defaults. Since your project may have explicitly chosen not to have some settings enabled, having this setting checked will prevent other collaborators from seeing this dialog an changing settings inadvertently. These settings should be configured by the person setting up the project and then ignored by the other collaborators.

Auto-enable UWP capabilities - If this is disabled, certain functionality (for example, eye tracking) may silently fail when deployed to a device because Unity won't automatically add the required runtime capabilities to the application manifest. Having this setting checked will safeguard your application deployment experience from this class of issues.