Installation

Table of Contents

• Prerequisites
• Obtaining Astra
  • Locating your Application Configurations
• Supported Platforms
  • Notes
  • macOS Gatekeeper
  • Apple Silicon (M1 arm cpus)
  • Android
  • Unity and C# Requirements
  • Supported Texture Formats
• Installation
• Legacy Configs and Upgrading
• Verifying the SDK Using the Search Tool
• Further Reading

This document will walk you through requirements and configuration of the Astra plugin for first time setup.

Prerequisites

In order to use Astra you will need:

1. An account
2. An Application Id, frequently referred to as an App Id
3. An Application Secret Key, frequently referred to as an App Secret
4. An Application Environment, frequently referred to as an App Environment
5. A customer user login and password
6. A copy of the Unity 2018.4+ and the Astra SDK unity package
7. Optionally a vendor user login and password (for access to the web system)

Obtaining Astra

You can download Astra either through the Unity Asset Store at: http://u3d.as/2VaC or through the SDK Files section in the backend web portal. We provide all published versions of Astra through our portal including both Verified and non-verified options. We also include the latest preview build, currently that build is 2.6.6 while it undergoes verification process.

Locating your Application Configurations

App Id

To locate your App Id, please log into your admin portal provided to you by tafi. On the left hand side click on Apps (found under Company). You will see one or more apps listed, you want to copy the ID field found.

App Secret Key

To locate your App Secret Key, please log into your admin portal provided to you by tafi. On the left hand side click on Apps (found under Company). You will see one or more apps listed. Click the row or edit button for the application you want to use. This will now show you a very large field with your secret key which you can copy out of there.

App Environment

Your app environment will be the protocol + domain. For example if your company is named Acme, your admin portal will likely be located at https://acme.maketafi.com this is the environment. Do not include a trailing slash or the rest of the url query, just the protocol and hostname.

If you are missing any of those please contact Tafi.

Supported Platforms

The native libraries are supported on the following platforms:

1. Windows
   1. Windows 10 64bit x86_64
2. macOS
   1. macOS 10.11+ 64bit x86_64
   2. macOS 10.11+ 64bit *arm (aka M1 or Apple Silicon)
3. Linux
   1. 64bit x86_64
4. iOS
   1. iPhoneOS 10.0+ 64bit arm (arm64)
5. tvOS
   1. tvOS 10.0+ 64bit arm (arm64)
6. Android
   1. * 32bit API 21+ armv7
   2. 64bit API 24+ armv8-a

If your target platform is not in this list please contact jjanz.nosp@m.er@m.nosp@m.aketa.nosp@m.fi.c.nosp@m.om. Currently WebGL is not yet supported but is a planned target in the future.

Notes

• We plan to drop 32bit android arm support (arm-v7a) in the near future due to the adoption rate of 64bit android and requirements from the Google Play Store.
• tvOS is not officially tested by us, if you need official support for this platform please contact us.
• tvOS does not support the Character Editor currently.

macOS Gatekeeper

You may need to resign or provide a security exclusion for Astra's native library on macOS. This library is located in Assets/Astra/Native/Plugins/.../Astra.bundle where ... should be replaced with your specific architecture. We will be working in the future to making this seamless so you don't need to do this yourself.

If you need to clear the quarantine flag you can do something like the following from your root project folder:

xattr -cr ./Assets/Astra/Native/Plugins/macOS/

Apple Silicon (M1 arm cpus)

macOS support on M1 hardware requires you to use either the native M1 build of Astra and use a preview Unity Editor build: https://forum.unity.com/threads/now-available-native-apple-silicon-editor-preview-builds.1122712/ or you can use the x86_64 in translation mode (Rosetta 2) but you need to swap out the x86_64 library for the non_avx version.

Please note that you must set the cpu type to "Any" for the x86_64_non_avx version or your plugin will not be copied into your final build. You must do this step manually due to the fact that Tafi ships this plugin disabled by default.

The non avx version is located at Assets/Astra/Native/Plugins/macOS/x86_64_non_avx/Astra.bundle The avx version is located at Assets/Astra/Native/Plugins/macOS/x86_64_non_avx/Astra.bundle

As a reminder you only want one of these enabled, if you want to support M1 chips you must use the less optimized non avx version (Rosetta 2 does not handle AVX instructions as of the time of this writing). We enable the AVX version by default.

When doing a build with Astra, ensure you target specifically either intel or m1 directly and not both. Ensure you have the right plugin(s) setup. Currently you can only build against one target directly. If choosing one, we recommend using the intel version.

Android

There is a known issue on older versions of unity for 64bit android using IL2CPP you should disable stack traces for your logs or you will have noticeably worse performance in your app. This can greatly impact the performance of Astra.

See: https://issuetracker.unity3d.com/issues/android-performance-regression-in-64-bit-builds

Unity and C# Requirements

Astra supports LTS releases after Unity 2018.4+ (2019.4+ for SRP see below). If there is a specific version of Unity your project needs to use that isn't supported contact jjanz.nosp@m.er@m.nosp@m.aketa.nosp@m.fi.c.nosp@m.om.

Astra will be deprecating 2018 support soon for 2019+, likely for 2.7 release, please be aware if that is your target version.

The managed library in Astra requires the .NET 4.0 runtime, you must ensure you are running against the same or later in unity. You can change this in your Player settings.

Texture handling assumes you are in Linear color space, currently Astra does not handle Gamma space well though the libraries will function. You can change this in your Player settings.

Astra supports both Mono and IL2CPP scripting backends and either can be used however Android 64 and iOS require IL2CPP.

Unity SRP Requirements

If you are using Unity's Scriptable Render Pipeline, SRP, you must use 2019.4+ LTS for Unity. Prior versions do not support custom shader function nodes which Astra relies on for it's shaders to work.

Unity HDRP Requirements and Notes

You must add the Assets/Astra/Resources/Shaders/HDRP/Skin Diffusion Profile asset to your Diffusion Profile List in your HDRP asset, Astra will attempt to do this on first launch of Astra in your project. You may also need to manually add this to Assets/Astra/Resource/Shaders/HDRP/Skin.shadergraph manually in the output node under Diffusion Profile.

Green Skin with HDRP

If your characters skin appears green, please confirm your diffusion profiles are setup correctly as above.

Supported Texture Formats

Our pipeline supports dynamically GPU compressed textures done in the cloud upon assets being uploaded to our Vendor Portal. This happens automatically and is finished in a few minutes upon upload. Textures will be uploaded as source PNG (in most cases) in our custom MR package.

The formats we automatically compress to are:

1. Original Texture (PNG RGBA 8bits per channel)
2. DXT5
3. ETC1
4. ETC2
5. PowerVR

Texture resolutions are automatically scaled to:

1. Original Resolution
2. 512
3. 1024
4. 2048
5. 4096

Textures are maintained as a power of 2 resolution.

Additionally DXT1 will be available in the near future. DXT5Crunched may also be supported in the future, but our textures are compressed on disk so textures are heavily optimized already w/o any degradation in image quality.

If your required texture compression format is not in the list above please contact jjanz.nosp@m.er@m.nosp@m.aketa.nosp@m.fi.c.nosp@m.om to discuss support.

Upcoming Texture Support

We have prototyped and released in beta support for:

1. DXT1

1. BC7

1. ASTC

1. BASISU

If you need these texture formats please contact jjanz.nosp@m.er@m.nosp@m.aketa.nosp@m.fi.c.nosp@m.om and we can set you on a preview namespace. These formats are supported internally in 2.6.2 of Astra and are expected to release publicly with 2.7.

Installation

After downloading the Astra unity package, create or choose a Unity project and open it in the Unity Editor. You should ensure that the player settings in Unity have the API Compatibility Level to .NET 4.x or later. For best results we also recommend that you set your Color Space to Linear.

Note: In older versions of Unity the .NET setting will be Scripting Runtime Version to .NET 4.x Equivalent.

Open the Astra_Unity_XYZ.unitypackage, with XYZ being the version you want to use and extract all of the contents from the package. All content will be extracted into the Assets/Astra directory. For Information on folder structure refer to the Astra Project Organization guide.

Now that Astra is installed you will want to create your configuration JSON file. Right click in your Unity Project window and choose "Creates/Astra/JSON Config".

Click on the file created if it's not already selected and fill in the configuration based on your vendor settings. For information on the App Id and others refer to Application Configuration.

From the information provided to you you will need to fill in:

• App Id
• App Secret
• App Environment
• User Login - Provide your customer login
• User Password - Provide your customer password

Optionally you can specify the following:

• Log Enabled if you want the native library to report log events to a log file
• Log Path if logging is enabled where do you want it written to
• Db Path where do you want you Astra database to exist

Default paths for windows are either C:\temp\ or your current project's drive letter instead of C. For unix systems it will exist in /tmp/ or /temp/. If you provide a relative path such as simply using Astra.db and/or Astra.log as the parameter for Db Path or Log Path the file(s) will be located in your Unity project root folder. For a build this will reside in the same location as your output.log. Specifying a absolute path can also be done.

Note: The use of the customer user and password will be going away in the near future and replaced with a developer key instead.

If you want to immediately jump in, click the menu Astra/Prep Scene which will create a new GameObject AstraManagerGO and add the required AstraManager component to it then press Init on your config file now. You should now have a working environment. If you get any errors please report them to Tafi.

Once this is completed all systems of Astra should be operational, you can now assemble an avatar or load assets. We'd encourage you to try the Examples first, located in Assets/Astra/Examples which take you through a more guided tour of how to boot your own app and begin loading assets through code or the runtime interfaces.

Legacy Configs and Upgrading

If using a version of Astra prior to 2.6 you will instead use the non JSON config option (legacy). If you have upgraded to a newer version of Astra there is a helper to convert from the Astra.ProjectConfiguration ScriptableObject which can be found by clicking on the config file and then pressing Export JSON Config. This legacy option will be removed in the future and you should upgrade as soon as possible.

Verifying the SDK Using the Search Tool

The Astra SDK includes a GUI search tool for querying and loading assets. Click the menu option Astra/Asset/Search from the Unity Editor, this will load a search window.

Choose Avatar Item under Type and find an avatar. After choosing an avatar from the result set below you can click on Load to load it into your scene. If this is your first time loading an avatar it may take a few seconds while it fetches the data from the network.

You may also look for various other assets using this search tool or investigate the Astra.Asset.Catalog for the search API instead.

Congratulations you should have a fully working system if you can load a basic App Avatar.

Further Reading

To continue your work with the Astra SDK please see the Programmer's Guide.