Compiling MirageXR

Developers have to configure a few things before being able to compile, and there are some additional optional settings that are good to know about.

The system utilises several APIs which require API secrets to be configured. This includes IBM Watson and SketchFab.

If these are not configured, the character and the model augmentation will not work properly: characters cannot use AI mode and model search will not work.

The user interface and app presentation can be skinned via config files and mapping tables.

Default server URLs for learning management can be changed.

Terms and conditions of use can be specified via a text file.

API keys
Configure Corporate Design and Identity with the BrandManager
Assets Mapping Table
Default servers
End User License Agreement
Build

API keys

Caution

For all APIs to work when compiling, you will require the keys to be set up accordingly. If you have been invited to contribute, you should have received these keys as files, or should have been granted access to the files.

The API keys need to be set up as follows:

SketchFab: The API id and secret need to be stored. To see how to generate these, see API documentation. You have to copy over three files you can obtain from the project team into this folder (which is in .gitignore and will not be syndicated!): /Assets/MirageXR/Common/Resources/Credentials. The three files are: SketchfabClient.asset, SketchfabClient.json, and SketchfabClientWithPassword.asset. Subsequently, the sketchfab data object and the sketchfab login with password data object need to be assigned:
IBM Watson: you need to put a non-tracked ibm-credentials.env file into the root folder to be able to build the natural language processing capabilities for the character models. You will need to add the API secret key credentials for the following IBM Watson services: Tone Analyzer, Assistant, Speech-to-text, Text-to-speech, and the language translator (optional) services. The file is listed below, just replace the %KEY% values with the according API secrets for each service provided by the IBM Watson dashboard. As with release 2.6 (develop branch from Feb 15 2024 onwards), we have phased out the assistant service and replaced it by openAI chatGPT support.

TONE_ANALYZER_APIKEY=%KEY%
TONE_ANALYZER_IAM_APIKEY=%KEY%
TONE_ANALYZER_URL=https://api.eu-gb.tone-analyzer.watson.cloud.ibm.com/instances/5f989edc-233e-42a0-98c5-9e1cefcf36c5
TONE_ANALYZER_AUTH_TYPE=iam
ASSISTANT_APIKEY=%KEY%
ASSISTANT_IAM_APIKEY=%KEY%
ASSISTANT_URL=https://api.eu-gb.assistant.watson.cloud.ibm.com/instances/7ca75d0a-966f-4350-91b8-06fb0e882de5
ASSISTANT_AUTH_TYPE=iam
SPEECH_TO_TEXT_APIKEY=%KEY%
SPEECH_TO_TEXT_IAM_APIKEY=%KEY%
SPEECH_TO_TEXT_URL=https://api.eu-gb.speech-to-text.watson.cloud.ibm.com/instances/00f5f658-9d9d-4b76-9505-d07885513919
SPEECH_TO_TEXT_AUTH_TYPE=iam
TEXT_TO_SPEECH_APIKEY=%KEY%
TEXT_TO_SPEECH_IAM_APIKEY=%KEY%
TEXT_TO_SPEECH_URL=https://api.eu-gb.text-to-speech.watson.cloud.ibm.com/instances/a597ad6c-b7a1-479f-a592-4fde6d504b2a
TEXT_TO_SPEECH_AUTH_TYPE=iam
LANGUAGE_TRANSLATOR_APIKEY=%KEY%
LANGUAGE_TRANSLATOR_IAM_APIKEY=%KEY%
LANGUAGE_TRANSLATOR_URL=https://api.eu-gb.language-translator.watson.cloud.ibm.com/instances/a1d20d77-8dae-49db-9aa3-5604e9d07753
LANGUAGE_TRANSLATOR_AUTH_TYPE=iam

OpenAI: place file openai.txt into the folder Assets/Resources/ folder which contains the following

OPENAI_KEY=
OPENAI_API_KEY=
OPENAI_ORGANIZATION=

Sentry: place the SentryOptions.asset into the folder Assets/Resources/Sentry/ so that the settings are loaded correctly. If you are creating the Sentry configuration by hand, make sure you set a valid DSN and turn off debug logging, so that no in-editor error messages get tracked through to Sentry. Once the file has been added, you can check that its settings were correctly read by opening Tools>Sentry - if this shows a DSN, then Sentry is correctly configured:

sentry-dsn

Sentry client token: Place the file SentryCliOptions.asset into the folder Assets/Plugins/Sentry/. It seems that you could potentially do a lot with the auth token, depending on the allowed scopes that were checked when generating it, e.g., changing settings in the workspace or reading the error logs (see also https://github.com/expo/sentry-expo/issues/321#issuecomment-1464335081). We therefore have excluded this file as well via the .gitignore and you will have to place it as Assets/Plugins/Sentry/SentryCliOptions.asset manually. Once the file has been added, you can validate that its settings were correctly read by opening Tools>Sentry and checking if it shows an Auth token:

sentry-authtoken

Configure Corporate Design and Identity with the BrandManager

MirageXR supports white labelling. This is implemented via the BrandManager class and the BrandConfiguration Editor window class, which determine key corporate design elements from settings in a configuration file. Most notably, this includes: app name, version number, splash screen image, logo image, a set of primary colours, servers set (Moodle, xAPI LRS), calibration marker file (both for screen and as printable PDF).

These classes allow configuring all key UI elements centrally. The values are stored in Assets/MirageXR/Resources/MirageXRConfig.txt and will be filed in upon start of the app.

companyName:WEKIT ECS
productName:MirageXR
moodleUrl:learn.wekit-ecs.com
xApiUrl:lrs.wekit-ecs.com/data/xAPI
version:$appVersion
splashScreen:Assets/MirageXR/Logo/wekit-logo-v7.png
logo:Assets/MirageXR/Logo/wekit-logo-v7.png
SplashBackgroundColor:#000000FF
primaryColor:#2EC4B6FF
secondaryColor:#FF9F1CFF
textColor:#FFFFFFFF
iconColor:#FFFFFFC8
taskStationColor:#FF9F1CFF
pathColor:#FFFFFFB5
nextPathColor:#00FFE7C8
calibrationMarker:Assets/MirageXR/Player/Resources/CalibrationImage/target.png
pdfCalibrationMarker:Assets/MirageXR/Player/Resources/CalibrationImage/MirageXR_calibration_image_pdf.bytes

Assets Mapping Table

Moreover, there are asset mapping tables to be set up which allow reducing resource load in the application. As a side effect, this allows rapid adaptation of the UI on a deep level. To set up this required mapping table for prefab assets (using the addressable methods), Unity will automatically prompt developers to configure ("build") a mapping table for where to load asset prefabs from.

Default servers

The servers are set via the BrandManager (see above). This includes:

xAPI: The learning record store URL (LRS URL) is set in MirageXRServiceBootstrapper.cs
LMS: The URL to Moodle is set

End User License Agreement

Terms of Use: The end user license agreement is stored in Assets/MirageXR/Resources/TermsOfUseDefault.txt and is filed in by the BrandConfiguration class.