Creating a new Extension

Extensions

Extensions are components within the MRTK that enrich mixed reality experiences but aren't needed as fundamental components for using the MRTK platform.

• Extensions may or may not be usable without the rest of the MRTK.
• Extensions should adequately document any dependencies on other MRTK components.
• Extensions may or may not require external dependencies, but all code added to the MRTK repo should conform to the MRTK repo's license. Any external dependencies should be adequately documented so that users of the MRTK can understand what licensing changes or service subscriptions they are subject to when using an extension. Any external dependencies should be publicly available.

Getting Started

1. Assess the licenses required for your extension. What dependencies does your extension take? Does it require any plugins/native dlls?
2. Create an issue for the MixedRealityToolkit-Unity repo proposing your new extension.
   • Please call out that you would like to contribute this enhancement.
   • Please note your extension's licenses and any external dependencies.
   • Please note if your extension will have any plugins or non-Unity Assets.
3. Begin work in a feature branch within your own fork of the MixedRealityToolkit-Unity repo.
4. Assess that your completed extension aligns with the different coding practices/file locations called out below.
5. Create a pull request to merge your extension's feature branch into the official MRTK repo development branch.

Unity Assets

• Unity assets needed for an MRTK extension should be placed within an extension specific folder:

MixedRealityToolkit-Unity\Assets\MixedRealityToolkit.Extensions\ExtensionName

• Script namespaces should have the following prefix:

Microsoft.MixedReality.Toolkit.Extensions.ExtensionName

Plugins

The success of an extension/its adoption in the community will be influenced by how easy it is to consume. That going said, its preferred to avoid adding any precompiled binaries directly to the MRTK repo. The correct mechanism for distributing each binary will likely be handled case by case. But some general practices for distributing plugin binaries are the following:

Open Source Binaries

If a component requires open source binaries, add instructions for obtaining the associated project, building the components and bringing the needed binaries into Unity to a ReadMe.md file within the extension asset directory. Also prepare to help with issues related to regressions in this process. Many of the MRTK community members would prefer to avoid compiling non-Unity code, so creating and posting a NuGet package containing these dll's would still be preferred (see below).

Closed Source Binaries

Some plugins may have to be distributed through closed source binaries. For MRTK, we suggest using NuGet packages to distribute closed source binaries (see below).

NuGet Packages

NuGet packages are currently generated for a variety of components in the MRTK. Instructions outlining the tool setup for this process can be found here. For more information on setting up nuget packages/nuspec files see here. For consuming NuGet packages in unity see NuGet for Unity. For hosting created nuget packages, see NuGet.org as well as other hosting solutions.

If for some reason, your specific dependency can't be distributed through NuGet, please call it out in the initial issue you opened when starting on your MRTK extension. Conversations in this issue can likely determine the best distribution story for your various components.

More information is coming for the MRTK NuGet story. Stay tuned for a more detailed overview of creating/consuming NuGet packages with the MRTK.