Plugin Introduction¶
EasyAR Sense Unity Plugin exposes EasyAR Sense features into Unity as a plugin. It provides rich features of EasyAR Sense and easy to use interfaces designed delicately for Unity users. It can work with or without AR Foundation and supports use on AR/VR/MR headsets such as Nreal.
EasyAR Sense Unity Plugin is a very thin wrapper build above EasyAR Sense C# API to expose EasyAR Sense features into Unity. It is always a good practice to read EasyAR Sense Documentation to understand how EasyAR Sense works.
How to Use¶
EasyAR Sense Unity Plugin now require Unity 2019.4 or later.
The plugin use Unity’s package to organize itself. It is distributed as a tarball file. The release package is a zip file, and you will get readme files and a tgz file after extracting the zip file. Do not extract the tgz file.
It is suggested to put above tgz file inside the project, like in the Packages folder. Use Unity’s Package Manager window to install the plugin from a local tarball file.
Choose the com.easyar.sense-*.tgz file in the popup dialogue.
NOTE: The tgz file cannot be deleted or moved to another place after import, so it is always a good practice to find a suitable place for the file before import. If you want to share the project with others, you can put the file inside the project and your version control system.
Versioning¶
EasyAR Sense Unity Plugin is designed to work with only the same version of EasyAR Sense, so the plugin uses the same version rule as EasyAR Sense.
NOTICE: EasyAR does not follow semantic versioning required by Unity package. The major difference in general, is the minor version change may introduce breaking changes, but not always.
Inside the Plugin¶
EasyAR Sense¶
Release packages of the plugin has EasyAR Sense libraries inside, so a separate EasyAR Sense package is not required when using the plugin.
The EasyAR Sense binaries inside the plugin are always the same with the EasyAR Sense in the same version. In case when you are trying to make the plugin work on a different EasyAR Sense version, you must make sure the csapi comes together with the libraries.
Scripts¶
The plugin is designed to be a thin Unity wrapper of EasyAR Sense, so most scripts are controllers of EasyAR Sense components in the 3D scene providing a few extensions in the Unity environment. It helps to organize and connect EasyAR Sense components.
The plugin use as much Unity features as possible, like start/stop in OnEnable/OnDisable, most EasyAR Sense features can work without writing scripts. The plugin does not wrap all functions from EasyAR Sense, all functionalities are exposed to Unity directly through C# API (csapi.cs), which is accessible from MonoBehaviours.
The plugin also implements one typical assemble strategy for all EasyAR Sense components in ARAssembly and controls data flow from ARSession. But that is not all of EasyAR Sense. You can always rewrite these two scripts to make a customized AR workflow to use the powerful flexibility of EasyAR Sense API.
The plugin is open sourced. All public types and members are documented in the scripts in both English and Chinese. You are free to change the scripts to make custom workflows.
You can use the plugin directly to create AR experience within short time. You can also reference the source code to create more custom usages of EasyAR Sense or even a Unity Plugin of your own.
All interface description can be found in the plugin scripts. There are both English and Chinese documents for all the interfaces in the code. But Unity does not generate XML documentation file for DLLs. Even worse, it removes the file after compilation if -doc is used in compiler options. So, we have made a hack to copy pre-generate XML document when script reload to make IntelliSense for API document work. If Unity changes its behavior in some version, or the hack is causing some problems in your project, disable Generate XML Doc option.
Editors¶
The plugin provides a few editor features to help development, including
Menu items to create AR Session and other AR components
Script input parameters before start on the Inspector
Runtime control like CenterMode and HorizontalFlipMode
Menu entry for license key and cloud service configurations
Gizmos for image targets
Tools for image target data generation
Samples¶
The plugin release comes with a few samples to demonstrate features and combination of different algorithms from EasyAR Sense.
The samples are distributed within the plugin package. You can import samples into your project using Unity’s Package Manager window. See How to Use Samples for more details.
Samples has a launcher; you can start most samples from the launcher. To use the launcher, you must add the launcher scene and all other scenes referenced by the launcher into the build settings.
Samples are designed to be straight forward of showing how API can be used and how EasyAR Sense work. Feel free to build your application on top of the sample or copy sample code for your projects, but remember the sample is NOT the plugin itself, and all codes in the sample are not guaranteed to be reusable in any condition without change.
EasyAR Sense and the plugin has rich APIs. Although important features and usages are demonstrated, the samples still would not cover all API callings and feature usages. If you find the sample do not satisfy the needs of your project, try read API Reference to learn all interfaces and the corresponding features of EasyAR Sense first.
Start with samples, they will help you understand how EasyAR Sense and the Unity Plugin work.