Unity Accelerator
Overview
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.
Contents
Using Accelerator with Unity Teams Advanced
Using Accelerator with Asset Pipeline
Monitoring Accelerators
Stopping and restarting the Accelerator service
Troubleshooting
Requirements
Local hosting requirements
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:
The local host must run one of the following operating systems:
Linux version 2.6.23 or higher (64bit)
Windows Server 2008R2 / Windows 7 or higher (64bit)
Mac OS X 10.12 or higher (64bit)
The local host must have sufficient local storage space to host most of your Project's
files, preferably on a solid-state drive separate from the drive that hosts your operating
system.
The local host must be attached to the same network as your team, or locally routable
with appropriate firewall policies that allow access to the Accelerator's IP address and
port (TCP).
Anyone with access to the host machine has access to your Project’s files, regardless of
permission structures within your Unity Organization. As such, Unity recommends
restricting that machine so that only an Organization Owner or Manager can access and
interact with the Accelerator.
Unity Editor requirements
Your Unity Project must use version 2019.3 or higher of the Unity Engine.
Accelerator with Unity Teams Advanced
Accelerator provides additional benefits with Unity Teams Advanced:
Collaborate integration to ensure recently added or modified source Assets are delivered
on the local network, dramatically reducing download times.
Remote Monitoring on the developer dashboard (see monitoring Accelerators).
Secure transport and access control of source Assets shared between Unity Editors and
the Accelerator (see source Asset security).
In normal Collaborate workflows, users upload and download from Cloud. With an accelerated
Collaborate workflow, uploads are saved to Cloud and the Accelerator, but users download
directly from the Accelerator.
Setup
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:
1. From the Develop tab of the dashboard, select the Project you want to create an
Accelerator for.
2. In the Project view, select Collaborate > Accelerator from the left navigation bar.
3. Click the New Accelerator button.
4. In the New Accelerator prompt, enter an agent name for Unity to use to identify the
Accelerator agent. You can also optionally specify a port number.
Note: The current limit is three Accelerators per Organization.
5. Click Save to confirm your settings.
6. On the following screen, copy the registration token, then click the Download
Accelerator button in the top-right corner, and select the appropriate operating system.
7. Launch the downloaded installer, and follow the installation wizard. Use the registration
token you copied to register the Accelerator with Unity Collaborate. This will allow you to
use the Accelerator for enhanced Collaborate performance.
Source Asset security
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.
Accelerator with Asset Import Pipeline
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.
Setup
If you do not have Unity Teams Advanced, you can download and install Unity Accelerator
directly and uncheck the registration token during installation:
Download for Windows
Download for Mac OS X
Download for Linux
Installing Accelerator on a "headless" machine
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. --have-registration-token false skips registration (if,
for example, you do not have Unity Teams Advanced). Important: Use only one of
these, not both.
Use --mode unattended for automated installations that should not query anything.
This uses default values, or values from other option flags provided.
On Mac OS X, you need to mount the disk image (DMG) and run the binary located in
the installer app's directory (located at Contents/MacOS/installbuilder.sh).
Configuring Editors to use an Accelerator
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:
1. In the Unity Editor, select Edit > Preferences (Windows) or Unity > Preferences (OSX).
2. Select Cache Server from the left menu.
3. Enable Asset pipeline v2, then enter the Accelerator’s IP address from the setup wizard
in the Default IP address field.
Monitoring Accelerators
Developer dashboard (Unity Teams Advanced users only)
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 four 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.
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.
Efficiency
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.
Bytes Removed
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.
Bytes Delivered
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.
Time Saved
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.
Accessing Accelerator metrics directly
If you do not use Unity Teams Advanced, each Accelerator hosts Prometheus metric reports as
/metrics, which you can query from the local network.
Unity Editor log debugging
It might be helpful to view debugging information in the Unity Editor logs. To do so, 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.
Stopping and restarting the Accelerator service
Accelerator runs as a background process for each platform.
Windows
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.
Mac OS X
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/.
Linux
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.
Maintenance
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.
Troubleshooting
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:
Check the Unity Editor versions in use
Each Project contributor must be using an Editor version 2019.3 or higher to use an Accelerator.
Verify users are on the Accelerator’s local network
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.
Test the Accelerator’s connection
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:
1. In the developer dashboard, select Collaborate > Accelerator.
2. Click Details for the Accelerator you want to test.
3. Click the info icon next to the Accelerator’s IP Address to display its health page URL.
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.
Check the Accelerator’s Project configuration
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.
Support
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.