This repository contains packages for the Unity game engine, with an emphasis on supporting animal studies in virtual reality (VR). The packages are meant to be loosely coupled to promote flexible reuse.
Examples of the functionality supported in this toolkit include:
- frame rate management (org.janelia.force-render-rate)
- extensible logging of activity during a session (org.janelia.logging)
- set up of virtual cameras for multiple external displays (org.janelia.camera-utilities, org.janelia.setup-cameras-n-gon)
- multiple external displays when running in the editor (org.janelia.full-screen-view)
- input of kinematic motion from FicTrac (http://rjdmoore.net/fictrac/), a “webcam-based method for tracking spherical motion and generating fictive animal paths” (org.janelia.fictrac, org.janelia.fictrac-collision)
- collision detection and simple sliding response for kinematic motion (org.janelia.collision-handling
- communication with a National Instruments data acquisition (NI DAQ) device using the NI-DAQmx driver (org.janelia.ni-daq-mx)
- background images (org.janelia.background)
- other general capabilities, like making a standalone executable end automatically after running for a specified period (org.janelia.general)
Use Unity’s approach for installing a local package saved outside a Unity project. Start by cloning this repository into a directory (folder) on your computer; it is simplest to use a directory outside the directories of any Unity projects. Note that once a Unity project starts using a package from this directory, the project automatically gets any updates due to a Git pull in the directory.
Some of the packages in this repository depend on other packages (e.g., the package for collision handling uses the package for logging), but the standard Unity Package Manager window does not automatically install such dependencies. To overcome this weakness, use the org.janelia.package-installer package. Once it is installed (as described in the next subsection), use it to install another package as follows:
- Choose “Install Package and Dependencies” from the Unity editor’s “Window” menu.
- In the file chooser that appears, navigate to the directory with the janelia-unity-toolkit repository. Then go down one more level into the subdirectory for the particular package to be installed (e.g., “org.janelia.collision-handling”).
- Select the “package.json” file and press the “Open” button (or double click).
- A window appears, listing the package and other packages on which it depends. Any dependent package already installed appears in parentheses.
- Press the “Install” button to install all the listed packages in order.
- All the listed packages now should be active. They should appear in the Unity editor’s “Project” tab, in the “Packages” section, and also should appear in the editor’s Package Manager window, launched from the “Package Manger” item in the editor’s “Window” menu.
org.janelia.package-installer requires Unity version 2019.3.0 or later.
To install the org.janelia.package-installer package (or to install a package without its dependencies), use the following steps:
- Choose “Package Manager” from the Unity editor’s “Window” menu.
- Press the small “+” button in the upper-left corner of the Package Manager window, and click on the “Add package from disk…” item that appears.
- Use the file chooser to navigate to a package’s directory (e.g., “org.janelia.package-installer”) in the cloned janelia-unity-toolkit repository.
- Select the “package.json” file and press “Open” (or double click).
- Unity should load that package, and it should appear in the Package Manager window and in the “Project” tab.