To install ABREngine in a Unity Project

The first sections refer to the ABREngine Unity Package. For install instructions on the ABR Server, see the ABR Server section below.

Install via the Unity Package Manager

To use the package in a read-only mode, the same way you would for packages downloaded directly from Unity:

  1. In Unity, open Window -> Package Manager.
  2. Click the + button
  3. Select Add package from git URL
  4. Paste https://github.com/ivlab/ABREngine-UnityPackage.git for the latest package
  5. After ABREngine is installed, close and reopen your Unity project. Click "Ignore" when it prompts you about compile errors in the project.
  6. Now, there should be a new "ABR" menu tab that has appeared on the top bar (next to "Window"). Click ABR > Import ABR Dependencies.
  • This will install all of ABR's dependencies automatically.
  • Installing all the dependencies will take some time.
  • If you get a permission denied error, try clicking "Import ABR Dependencies" again.

Once you've set up the ABREngine package, there are a couple more steps to make sure your editor is set up correctly. We recommend using either Visual Studio Code or Visual Studio to develop, since they are both well-supported by Unity.

Tip

Ensure that your external script editor is set up correctly, and that under "Generate .csproj files for:", "Embedded Packages", "Local Packages", and "Local Tarball" are all checked.

Additionally, make sure you have the latest .NET SDK installed. Avoid using dotnet versions installed from places besides this official installer, e.g., homebrew on MacOS.

Editing with Visual Studio Code

  1. In Package Manager, uninstall the "Visual Studio Code Editor" package (it is outdated, and now uses the same package as Visual Studio)
  2. Install or update the "Visual Studio Editor" package to the latest version (you will likely need to periodically keep this up to date).
  3. In Unity preferences / External Tools, set the editor to "Visual Studio Code", and make sure Generate .csproj files is checked for at least "Embedded" and "Local" packages.
  4. In the Project tab, right-click anywhere in the open space and click "Open C# Project". If all is configured correctly, VS Code should now open.

Editing with Visual Studio

  1. In Package Manager, uninstall the "Visual Studio Code Editor" package
  2. Install or update the "Visual Studio Editor" package to the latest version (you will likely need to periodically keep this up to date).
  3. In Unity preferences / External Tools, set the editor to "Visual Studio", and make sure Generate .csproj files is checked for at least "Embedded" and "Local" packages.
  4. In the Project tab, right-click anywhere in the open space and click "Open C# Project". If all is configured correctly, Visual Studio should now open.

Next steps: Get started creating a visualization

We recommend that you read the Introduction and Overview before going any further, and also checking out the Core Concepts!

After you've read the introduction, to get started creating a visualization:

  1. Follow the instructions below to start the ABR server.
  2. Import the ABR Vis App example by opening the package manager and navigating to the ABR package, twirling down "Samples", and clicking "Import" for the "ABR Vis App" sample.
  3. Follow the ABR Vis App tutorial.

If you're looking to make additions or changes to the ABREngine package itself, head to Development Mode for more information.

ABR Server

This folder contains the code for the ABR server and the ABR Compose Design Interface. This is how you create visualizations quickly and visually in ABR!

Installation

Before you begin, this tutorial assumes that you have a modern version of Python (>= 3.10) installed; the commands shown here are NOT guaranteed to work with other versions of Python.

In this tutorial, we set up the Python configuration for the ABR Server app, which enables you to create visualizations with the ABR Compose design interface.

Effectively, we are setting up a "local" copy of each package the ABR Server depends on to reduce the chance of conflicts. If you're interested in learning more, check out the pipenv project for more information. If you're on Windows, replace python3 with py.

Tip

Run all these commands from a terminal in the ABRServer~ folder (/Packages/ABREngine-UnityPackage/ABRServer~). If you have the read-only Unity package (i.e., you just installed ABR from the Unity Package Manager), use the menu option ABR > Open ABRServer~ folder to open the ABRServer folder. After you've opened the folder, follow the instructions for your operating system to open a terminal.

To get started, first make sure you have the pipenv package installed in Python. We are using python3 -m pip instead of pip directly to ensure we have the correct pip/Python version pairing.

python3 -m pip install --user pipenv

Then, install the local dependencies:

python3 -m pipenv install
Note

The first time you run this command, you may need to provide Python path. You can usually get the Python path with a command like which python3 or where python3. Again, on Windows, replace python3 with py. For example:

py -m pipenv --python=/c/Python311/python.exe install

Then, to get ready to run the server, "activate" the Pipenv by entering a shell:

python3 -m pipenv shell
Note

If you reboot or close the terminal, you will need to re-run the above command.

Running the server

The server can be run local-only (on localhost:8000 by default):

python3 manage.py runserver

The server can also be broadcast to other devices (i.e., if you want to run the server on a desktop and use the design interface with a tablet):

python manage.py runserver 0.0.0.0:8000

After this command is running, test it but opening http://localhost:8000 in a web browser! You should see the ABR design interface appear:

A screenshot of the ABR design interface loaded in a web browser.

Development with the server

This step is optional, and only recommended if you are editing the Python or JavaScript files for the Server or Design Interface. To enable live-reloading (automatically refresh browser when a file is changed), run these commands in separate terminals (the settings_dev enables live-reloading to work):

python manage.py livereload

python manage.py runserver --settings=abr_server.settings_dev

Development Mode

Collectively, the lab now recommends a development process where you start by adding the package to your project in read-only mode, as described above. This way, your Unity project files will always maintain a link to download the latest version of the package from git whenever the project is loaded, and all users of the package will be including it the same way. If/when you have a need to edit the package, the process is then to "temporarily" switch into development mode by cloning a temporary copy of the package. Then, edit this source as needed, test your edits for as long as you like, etc. When you get to a good stopping point, commit and push the changes to github from within this temporary clone inside the Packages directory. Once the latest version of your package is on github, you can then "switch out of development mode" by deleting the cloned repo. This will cause Unity to revert to using the read-only version of the package, which it keeps in its internal package cache, and we can trigger Unity to update this version to the latest by removing the packages-lock.json file. In summary:

  1. Follow the read-only mode steps above.
  2. Navigate your terminal or Git tool into your Unity project's main folder and clone this repository into the packages folder, e.g., cd Packages; git clone git@github.com:ivlab/ABREngine-UnityPackage.git edu.umn.cs.ivlab.abrengine. This will create a folder that contains all the sourcecode in the package.
  3. Go for it. Edit the source you just checked out; add files, etc. However, BE VERY CAREFUL NOT TO ADD THE ABREngine-UnityPackage FOLDER TO YOUR PROJECT'S GIT REPO. We are essentially cloning one git repo inside another here, but we do not want to add the package repo as a submodule or subdirectory of the project's repo, we just want to temporarily work with the source.
  4. When you are ready to commit and push changes to the package repo, go for it. JUST MAKE SURE YOU DO THIS FROM WITHIN THE Packages/edu.umn.cs.ivlab.abrengine DIRECTORY!
  5. Once these changes are up on github, you can switch out of "development mode" by simply deleting the ABREngine-UnityPackage directory. The presence of that directory is like a temporary override. Once it is gone, Unity will revert back to using the cached version of ABREngine that it originally downloaded from git.
  6. The final step is to force a refresh of the package cache so that Unity will pull in the new version of the package you just saved to github. In Unity 2021+, you can open the Package Manager, select the ABREngine Package, and click "Update". In earlier versions of Unity, you must manually delete the packages-lock.json file inside your project's Packages folder to update the package.