Table of Contents

Heru Visual Field

Visual field test application to be built for both the Magic Leap 1 and HoloLens 2 devices.

Built in Unity 2020.3.2f1 LTS.

Installed Main Components

  • Magic Leap Unity SDK v0.25.0
  • Microsoft MRTK 2.6.1
  • Odin Inspector Enterprise 3.0.4
  • UniTask
  • OpenXR v1.0.3
  • Microsoft Mixed Reality OpenXR v0.9.0
  • Heru Visual Fields Models1 1.0.0

Rebuilding of Text Fields and Koreographers to be used in AssetBundles

  • after an alteration of Text Fields, or audio/Koreographers the assetbundles will need to be rebuilt:

  • To add a locale, copy the audio tracks and koreographer.json and customTrack.json (which can be from another locale) to a folder of it's own case-sensitive locale name /Assets/Heru/Audio/xx-XX

    • any enum or logic, like any text-field json additions, might be needed; those can be copied to /Assets/Heru/JsonData with proper naming too.
    • ScriptableObjects/LocalizationSOs/{locale name} files need to be created if they do not exist, the Locale Id and the title just needs to match the locale name
    • modify the Generate editor button to include the new locale, as well as the baker. (see /Assets/Heru/Scripts/Debugging/CustomMenuItems.cs)
    • run the Generate, then run the build assetbundles to solidify it.

  • if there is a change to the koreographer.json from the api-scripts repo please regenerate below after overriding the folders wav files and json file.

  • if there is a change in Locale timing, or a custom track is added to a Koreographer, please add an entry to the locale's customTrack.json within the audio folder.

    • if there is a change to the timing of a Koreographer, hit the "Heru/Localization/Bake Custom Tracks for en-US, de-DE, en-GB, es-ES, es-MX, fr-FR, it-IT Localized Koreographers" button to bake it into the json.
    1. go to the "Heru/Localization/Generate en-US, de-DE, en-GB, es-ES, es-MX, fr-FR, it-IT Localized Koreographers" menu at the top of the Unity Editor.
    • If there was a new Audio file, then the Koreography might need to be converted if it isn't being read in the editor.
    • the rest should be automated
    1. go to the "Heru/Build Assetbundels".
    • this will regenerate some Custom Environment Assetbundles too, like NVI etc. but it won't automatically push to blob storage.
    • The new assetbundles will be in the "Assets/Heru/Assetbundles/" folder in the project and additionally the "Assets/StreamingAssets/Localization" folder for runtime use.

View Creation Process

  • A View consists of:

    • A Unique UIViewId Enum definition in UIViewId.cs.
    • It's own UIViewController extended .cs controller.
    • A Prefab with that script on the root object.
      • (Optionally) There is a platform whitelist which can be set on the controller.
    • A ViewSO instance (Right click in project window within Unity).
      • Which references the Prefab.
      • And is linked to the UIVIewId.
    • A UIManagerSO instance needs to contain a reference to every ViewSO instance, for them to be included in the application for runtime.

  • A UIManagerSO instance is in the project.

    • Technically only need one, it is referenced to in the mandatory Initial Scene.
    • It's purpose is to hold all of the ViewSO instances from the project, and this list can be altered outside of the scene.
      • Merge occur on any scene change, and do not merge, but non-scene objects like the UIManagerSO instance can merge.

Eye Test Creation Process

  • An eye test consists of:

    • A Unique EyeTestType Enum definition synced up with the Portal.
    • A Prefab with a FlowController nested to the root object.
    • A EyeTestSO instance (Right click in project window within Unity).
      • Which References the Prefab.
      • And is linked ot the EyeTestType Enum synced up with the Portal.
      • Additionally an EyeTestSO instance may define some specific views for its experience.
        • An ordered List of Greeting Views may be defined.
        • A training specific view may be defined.
        • A test view may be defined.
          • Which Ideally holds the actual eye test logic/networking/etc.
        • A finish test view may be defined for transitional purposes.
        • A checkbox defining if the eye test will require that eye tracking calibration will be needed in the appointment.

  • A ModalityManagerSO instance is in the project.

    • Technically only need one, it is refrenced to in the mandatory Initial Scene.
    • It's purpose is to hold all of the EyeTestSO instances from the project, and this list can be altered outside of the scene.
      • Merge occur on any scene change, and do not merge, but non-scene objects like the ModalityManagerSO instance can merge.

CLI Setup

Setup terminal

In order to run the command line functionality of this application you will need to do some initial setup. Please use a unix-style terminal e.g. git bash which is installed as part of Git for Windows.

Install dotnet-format

You will also need to install dotnet-format dotnet tool install -g dotnet-format.

Install Node

Before running locally you will need to have node installed. An easy way to install node while having the ability to change versions is to use Node Version Manager for your OS (There is a version specifically for Windows as well).

Install NPM dependencies

Run npm install from the project root

Setup build-configs

To get started copy build-configs.template.json to build-configs.json and fill in the appropriate information.

You will need to specify your unityPath which should be identical to the example provided if you installed through UnityHub.

You will also need to specify the path to various assets based on where you chose to clone the repository on your local machine.

In addition, talk to the Unity engineering team to get the necessary build certificates for different environments.

Run Tests - Command Line

Tests can be run via the appropriate script npm run test-{edit-mode|play-mode|lumin} e.g. npm run test-edit-mode.

When running tests this way a result XML will be populated into TestResults/{EditMode|PlayMode|Lumin}.xml these results should be committed with every PR.

Output logs can be found in Logs/test-{PlayMode|EditMode|Lumin}.txt.

Note: test-lumin is currently not functional.

Build

Local

This project is set up to allow building of the application for a number of scenarios.

Regardless of which way you build you must have a key.cert and key.privkey together in the same folder.

Unity Editor

To create a one off-build within Unity, it is recommended to use the Heru => Build menu item this will generate a build based on the current settings in your ProjectSettings.asset.

Note for Lumin, you must have defined a number of properties. These will automatically be set when using one of the provided build scripts. So it is recommended you start here.

Command Line

This project offers a number of convenience scripts to build for different Heru environments. Run npm run build-local-{dev|qa|stg|bpei|sales|prod} e.g. npm run build-local-dev.

These commands will build for a specific environment based on the configuration in build-configs.json. Output logs can be found in Logs/build-{dev|qa|stg|bpei|sales|prod}.txt.

Git Hooks

This repository is set up with git hooks these hooks will run on specific git actions.

pre-commit

Before each commit husky will run the following:

npm run check-version # Check the current project version and update if necessary if behind `main` and prompt user to update if necessary
npm run lint-changed # Lint any files changed and currently staged
npm run test-edit-mode # Run all EditMode tests and add results to commit 
npm run test-play-mode # Run all PlayMode tests and add results to commit

If you would like to skip these hooks you can pass the --no-verify flag which will skip test, lint, and version check of course do so at your own risk of committing breaking code.

If you get an error

pre-commit hook exited with code 13 (error)

Please re-run your commit from a terminal. It is recommended to use a unix-style terminal to run these commands.

Project Settings

Project settings are specific to each developer environment and are not normally committed. If you want to commit changes to these files please use git add -f ProjectSettings/ProjectSettings.asset

Edit this page