The Unity Accelerator is a software agent that allows you to share Unity Editor content faster. An Accelerator coordinates Asset sharing when your team is working on the same local network, so that you don’t need to rebuild portions of your Project. When used with Unity Teams Advanced, the Accelerator also shares source Assets. This significantly reduces download time from the Collaborate service.
When you install an Accelerator on your local network, the Unity Editor (version 2019.3 or higher; see Unity Editor requirements below) communicates with it to retrieve Assets that other team members have changed or built. The Accelerator keeps temporary copies of these Assets on the network to avoid wasting time and bandwidth retrieving or rebuilding them.
Install an Accelerator on each network your team regularly works on. You must have a machine running on your local network that can host an Accelerator. When selecting a host, consider the following requirements:
Your Unity Project must use version 2019.3 or higher of the Unity Engine.
Accelerator provides additional benefits with Unity Teams Advanced:
If you have Unity Teams Advanced, one of your Organization’s Owners or Managers can create an Accelerator from the developer dashboard by following these steps:
Note: If installing Accelerator on a Linux system, see Verifying your Accelerator version.
When used with Unity Teams Advanced, each Accelerator receives its own security certificate to prove it has permission to access your Organization. Before an Accelerator uploads or downloads any content, the Unity Editor making the request uses SSL/TLS to securely connect to the Accelerator and verifies its authenticity. When Unity Editors discover and connect to an Accelerator, instead of passing a normal Unity user token, they receive a special token from the Unity Identity service. These tokens verify the user’s identity and access to a single Project within your Organization, thereby protecting access to any other Organizations and Projects while using an Accelerator.
Asset Import Pipeline provides an API for accessing Project Assets via script, and uses Accelerators as a caching mechanism. When you or a member of the team imports an Asset, Asset Import Pipeline first checks whether the Asset already exists in an imported state in an Accelerator’s store. If it does, Asset Import Pipeline skips the import step and downloads the Asset from the Accelerator instead. If it doesn’t, Asset Import Pipeline imports the Asset, then uploads the result to the Accelerator.
Using Asset Import Pipeline with an Accelerator reduces initial startup time for large Projects significantly. Instead of doing resource-intensive importing, this combination only downloads the imported results and stores them locally for the Project. Users on the same local network can share each other’s imports, reducing the need for multiple people to do heavy importing work.
If you do not have Unity Teams Advanced, you can download and install Unity Accelerator directly and uncheck the registration token during installation:
Note: If installing Accelerator on a Linux system, see Verifying your Accelerator version.
On each platform, you can run the installer from the command line. If you execute the installer with an argument of --help
, it displays the various options available. To run a full install without any prompts, you should provide values for the following:
--storagedir
sets the directory for the Accelerator to store files and configurations.--registration-token
specifies the token provided in the developer dashboard after creating the Accelerator. This is required to use Accelerator with Collaborate.--mode unattended
for automated installations that should not query anything. This uses default values, or values from other option flags provided.Contents/MacOS/installbuilder.sh)
.When installing an Accelerator, the final step of the setup wizard displays the IP address and Port to reference in your Editor, in the following format:
[IP]:[Port]
To configure your Editor to use that Accelerator as an Asset pipeline version 2 Cache Server, follow these steps:
Alternatively you can provide the Accelerator Cache Server configuration details using command line arguments when launching the Unity Editor.
To specify that you want to use the Accelerator Cache Server, use the -EnableCacheServer
argument, and to specify the address and port number, use -cacheServerEndpoint Address:Port
, replacing Address and Port with the your Cache Server’s details.
Note: The Accelerator Cache Server requires that your project uses Asset Database V2 (ADB2). You can force an upgrade to ADB2 when launching Unity from the commandline by using the -adb2
argument.
See command line arguments for more information.
If you are a Unity Teams Advanced user, you can monitor Accelerator metrics from the developer dashboard. These metrics only apply to source Assets, and do not apply to generated (imported) Assets.
To view a summary of your Project’s Accelerators, select that Project, then select Collaborate > Accelerators from the left navigation bar. In this menu, you can view the following information:
Property | Description |
---|---|
Name | The name you provided when you created the Accelerator. |
Avg. Efficiency | The average efficiency of the Accelerator over the past 24 hours. |
Editors | The number of Unity Editors connected to the Accelerator. |
Latest Activity | The most recent use of the Accelerator. |
Status | The Accelerator can be in one of the following states: - Available indicates that the Accelerator is not installed or registered with the Collaborate service. - Ready indicates that the Accelerator is registered with the Collaborate service, but no Unity Editors are connected to it. - In use indicates that Unity Editors are connected, or have recently connected to the Accelerator. - Idle indicates that Unity Editors have used the Accelerator previously, but there has been no recent activity. - Not Listening indicates that the Accelerator could not connect to the configured port (most likely because another service is already using it). - Disconnected indicates that the Accelerator is no longer connected to the service for usage reporting, or receiving configuration changes. |
Enabled | Indicates whether Unity Editors can discover and attempt to use the Accelerator. Unity Editors do not use disabled Accelerators, regardless of whether they’re running. |
Click Details for an Accelerator to view the following in-depth information about its usage. This data updates every 10 minutes.
This shows the average performance of the Accelerator for the past 24 hours. The values range from 0 to 100, measuring the percentage of content downloads provided locally from the Accelerator, rather than remotely from the Collaborate service. A value of 0 indicates that the Accelerator is not actively helping with content downloads. A value of 100 indicates that the Accelerator is providing all content downloads.
Periodically, the Accelerator clears space to store new Assets. When it does, the dashboard reports the number of bytes allocated to older Assets that the Accelerator removed from local storage.
Note: This is a normal operation to help maintain a healthy Accelerator. However, if this value seems to be adversely affecting the Accelerator’s efficiency, you might need to add more storage space to accommodate your team’s usage. Ideally, the file system running the Accelerator should use a solid-state hard drive with enough free disk space to house all files in the most recent version of active Projects, but this is not a requirement. If insufficient storage is available, the overall efficiency of the Accelerator declines.
Distributed teams might have local contributors working with an Accelerator, as well as remote contributors using the Collaborate service. In these cases, the Accelerator listens for remote publish events, and proactively downloads the affected content for users on its local network.
When you use an Accelerator, it reports on the overall number of bytes it has requested and downloaded from the remote Collaborate service, rather than those it has delivered from the local network. More bytes delivered locally is better for your team, because it places less load on your network gateway.
The Accelerator tracks bandwidth when it delivers locally stored Assets instead of downloading them from the Collaborate service, and reports the difference in time the Unity Editor would have waited to download Assets remotely as time saved.
Note: The aforementioned metrics apply only to source Assets. They do not apply to generated (imported) Assets.
If you do not use Unity Teams Advanced, each Accelerator hosts Prometheus metric reports as /metrics
, which you can query from the local network. The following is a full list of metrics that you can access:
Metric | Description |
---|---|
process_resident_memory_bytes |
The amount of memory used by the Accelerator. |
uta_agent_sys_cpu_percent |
The amount of CPU used by the system. |
uta_agent_sys_mem_bytes_used |
The amount of memory used by the system. |
uta_agent_protobuf_connects |
The number of times Unity Editors have connected to the service for the Asset Import Pipeline. |
uta_agent_protobuf_bytes_in |
The number of bytes received from the Asset Import Pipeline. |
uta_agent_protobuf_bytes_out |
The number of bytes sent to the Asset Import Pipeline. |
uta_agent_protobuf_requests{code="0",method="get"} |
The number of items sent to the Asset Import Pipeline. |
uta_agent_protobuf_requests{code="1",method="get"} |
The number of errors occurring from items sent to the Asset Import Pipeline. |
uta_agent_protobuf_requests{code="2",method="get"} |
The number of namespace errors occurring from items sent to the Asset Import Pipeline. |
uta_agent_protobuf_requests{code="3",method="get"} |
The number of requests made from the Asset Import Pipeline for items that have not been cached. |
uta_agent_protobuf_requests{code="0",method="put"} |
The number of items received from the Asset Import Pipeline. |
uta_agent_protobuf_requests{code="1",method="put"} |
The number of errors occurring from items received from the Asset Import Pipeline. |
uta_agent_protobuf_requests{code="2",method="put"} |
The number of namespace errors occurring from items received from the Asset Import Pipeline. |
uta_agent_protobuf_requests{code="0",method="delete"} |
The number of requests made from Asset Import Pipeline to remove items. |
uta_agent_protobuf_requests{code="1",method="delete"} |
The number of errors occurring from the Asset Import Pipeline removing items. |
uta_agent_protobuf_requests{code="2",method="delete"} |
The number of namespace errors occurring from requests to remove items by the Asset Import Pipeline. |
uta_agent_protobuf_requests{code="3",method="delete"} |
The number of requests to remove items made from the Asset Import Pipeline for items that have not been cached. |
uta_agent_protobuf_cache_hits |
Number of Asset Import Pipeline requests that were served from cache. |
uta_agent_protobuf_cache_misses |
Number of Asset Import Pipeline requests that could not be served from cache. |
uta_agent_protobuf_cache_bytes_out |
Number of bytes served from cache to the Asset Import Pipeline. |
uta_agent_protobuf_cache_bytes_in |
Number of bytes stored into the cache received from the Asset Import Pipeline. |
The Unity Editor logs are useful for viewing debugging information. To view logs for Collaborate events, run your Unity Editor (or the Unity Hub) with an environment variable set to enableCollabEventLogs=true
. Logs marked with [collab-accelerator]
can help provide insight to your Accelerator’s performance.
The block below shows an example log output for the Accelerator using Asset Import Pipeline v2. This does not require enableCollabEventLogs=true
because it’s not for Collaborate.
2019-10-07T11:34:51-0700 Using Asset Import Pipeline V2.
...
2019-08-08T09:04:03-0700 Start importing Assets/Scenes/tame-the-unicorn.png guid(07a0d449dcaef4d2ba104e9d9b350de6)
2019-08-08T09:04:05-0700 Done importing asset: 'Assets/Scenes/tame-the-unicorn.png' (target hash: 'd5fddd470dd9beedcd7261b6455e436a') in 1.082988 seconds
2019-08-08T09:04:05-0700 RemoteAssetCache::AddArtifactToCacheServer - artifactKey='Guid(07a0d449dcaef4d2ba104e9d9b350de6) Importer(-1,)' Target hash='d5fddd470dd9beedcd7261b6455e436a'
Accelerator runs as a background process for each platform.
Open the Services Panel by searching the term “Services” in the Settings menu, or running “services.msc” in the Run dialogue (WIN + R). Next, locate the “Unity Accelerator” service in the resulting list. The option to Stop the service or Restart the service appears on the left panel.
Run the launchctl
command from the terminal to control the “com.unity.accelerator” service from the LaunchControl utility. For more information, visit https://www.launchd.info/.
Use the service
console utility to control the “unity-accelerator” service. For more information, visit http://manpages.ubuntu.com/manpages/bionic/man8/service.8.html.
The Accelerator service automatically updates itself during a maintenance period, currently set for 01:00 - 02:00 AM local time according to the machine running the Accelerator. This only occurs if the Accelerator discovers a newer version available.
Accelerator’s installation and uninstallation logs are saved in the operating system’s standard temp directory as unity-accelerator-*install.log
. Accelerator’s logs are saved in the storage directory as unity-accelerator.log.
If you’ve installed an Accelerator, but some Unity Editors are not using it, several things could cause this issue. The following troubleshooting options might help you fix it:
Each Project contributor must be using an Editor version 2019.3 or higher to use an Accelerator.
Make sure the Accelerator is running on the same local area network as the Project contributors experiencing issues. Accelerator does not affect contributors who are working remotely.
Check if the machine experiencing issues can reach the Accelerator. If you use Unity Teams Advanced, follow these steps to access an Accelerator’s health page in your browser:
If you do not use Unity Teams Advanced, enter the Accelerator’s host IP address into the following URL path to display its health page:
[AcceleratorIP]:[AcceleratorPort]/api/agent-health
If the test fails, make sure all host and network firewalls allow access to the Accelerator’s listening IP address and port (TCP). You might need to coordinate with your network administrator to allow access to this port.
If you use Unity Teams Advanced, verify that the Accelerator is configured for the Project in question. Navigate to the Project in the developer dashboard, and select Collaborate > Accelerator from the left navigation bar. You should see the Accelerator listed for that Project.
For Accelerator installations on Linux systems, all Linux executables have signature files that you can verify to ensure that no malicious entities have tampered with your downloaded Accelerator version. You can verify the signature files with a trusted version of GnuPG. The key below signs the current release. The public key block with the key is available at https://collab-accelerator.cloud.unity3d.com/.
pub rsa4096 2019-12-02
Key fingerprint = 9BC4 B04D F2E8 74E5 64AA 47E7 6D44 3B8B 002C F61F
uid Unity Technologies ApS (Accelerator signing key) <sst-ops@unity3d.com>
To download the key to your GPG store, use one of the following commands:
$ gpg --keyserver https://collab-accelerator.cloud.unity3d.com/ --search-key "sst-ops@unity3d.com"
$ gpg --keyserver https://collab-accelerator.cloud.unity3d.com/ --recv-key 9BC4B04DF2E874E564AA47E76D443B8B002CF62F
To check the version of Accelerator that you installed is original and unmodified, verify the file’s signature.
The Accelerator installation file comes with a signature file that is available at https://storage.googleapis.com/unity-accelerator-prd/unity-accelerator-installer.sig. Use this signature file to verify the Accelerator installer:
$ gpg --verify unity-accelerator-installer.sig unity-accelerator-linux-x64-installer.run
Before trusting the key, compare the fingerprint with what is shown in Forged or untrusted keys. After trusting the key, you will see something like:
gpg: Signature made Thu Jan 16 12:29:14 2020 PST
gpg: using RSA key 9BC4B04DF2E874E564AA47E76D443B8B002CF61F
gpg: Good signature from "Unity Technologies ApS (Accelerator signing key) <sst-ops@unity3d.com>" [ultimate]
This means the signature is valid and that you trusted this key.
If you do not have the correct distribution key, the output of the above commands will look as follows:
gpg: Signature made Thu Jan 16 12:29:14 2020 PST
gpg: using RSA key 9BC4B04DF2E874E564AA47E76D443B8B002CF61F
gpg: Can't check signature: No public key
In this case, you must get the key using the instructions above.
If you have a copy of the key with a valid signature, but either the key was not marked as trusted or the key is a forgery, the output will look as follows:
gpg: Signature made Thu Jan 16 12:29:14 2020 PST
gpg: using RSA key 9BC4B04DF2E874E564AA47E76D443B8B002CF61F
gpg: Good signature from "Unity Technologies ApS (Accelerator signing key) <sst-ops@unity3d.com>" [unknown]
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: 9BC4 B04D F2E8 74E5 64AA 47E7 6D44 3B8B 002C F61F
If the key has been forged, you must verify the fingerprint using the signature file. If the key has not been marked as trusted, edit it to mark it as trusted. For more information, see https://www.gnupg.org/gph/en/manual/x334.html.
For help regarding Accelerator with Unity Teams, email support or submit a help ticket from the developer dashboard. To submit a ticket for a Unity Teams Advanced Project, select your Project, then select Collaborate > Support from the left navigation bar.
For help regarding Accelerator with Asset Import Pipeline, please visit the Accelerator forums.