unifir: A Unifying API for Working with Unity in R

unifir is a unifying API for creating and managing Unity scenes directly from R (without requiring GUI interaction). Users are able to write natural-feeling R code to create “scripts” (C# programs) composed of “props” (C# methods) which produce scenes inside the Unity engine. While it is entirely possible to create fleshed-out Unity scenes through this package, unifir is primarily designed around being easy to wrap in other packages, so that any number of packages interacting with Unity can all share a common framework.

The first function most unifir workflows will call is make_script, which creates a “script” object. In that script, we can tell unifir things like where we want to save our project:

library(unifir)
script <- make_script(project = "path/to/project")

We can then iteratively add props to our project, building up a series of commands that we’ll execute in sequence to create a Unity scene:

script <- add_default_player(script, x_position = 10)
script <- add_light(script)
script <- save_scene(script)

All of these functions are designed with the pipe in mind, letting you easily simplify your code:

script <- make_script(project = "path/to/project") |> 
  add_default_player(x_position = 10) |> 
  add_light() |> 
  save_scene()

Once all your props are set, it’s time to execute the script via the action function! This function will create a new Unity project (if necessary), write your “script” object to a C# file, and execute it inside the Unity project.

action(script)

Open your new project from UnityHub, open the scene you created with save_scene, and you’ll see the outputs from your script right in front of you! To learn more, check out the vignettes that ship with the package – particularly the one for how to use unifir to make scenes and the one for how to extend unifir in your own packages.

Right now, unifir wraps the elements of the Unity API that I’ve found useful in my own work, principally focused around creating GameObjects, lights, player controllers, and terrain surfaces. If you are interested in pieces of the API that haven’t made it into unifir yet, please open an issue or a PR!

Installation

The easiest way to install unifir is to install it directly from R-Universe:

# Enable universe(s) by rOpenSci
options(repos = c(
  mikemahoney218 = 'https://ropensci-universe.dev',
  CRAN = 'https://cloud.r-project.org'))

# Install unifir
install.packages('unifir')

You can also install unifir from GitHub with:

# install.packages("remotes")
remotes::install_github("ropensci/unifir")

Note that right now there is no release version of unifir; all published versions are considered “development” versions. While the unifir API is solidifying, it is not yet solid, and breaking changes may happen at any time.

While unifir can be used by itself, you’ll probably want to install Unity in order to actually make Unity projects.

Why do this?

There’s been a lot of interest in using immersive virtual environments for research on topics including science communication, landscape planning, environmental economics and beyond. This is an incredibly exciting area of research, which looks likely to present new methods for participatory planning, data visualization, and skill training. However, right now, much of the research in this area relies upon closed-source tooling which puts up hurdles in front of the equitability, accessibility, and interoperability of the field. In addition, a challenge when assessing hand-build environments (say to assess participant preferences between two scenes) is that us as researchers might accidentally “tilt the scales” in favor of our preferred option, by putting a little more effort into making the scene we personally prefer look more aesthetically pleasing than the alternative.

unifir is a first step towards an open-source, fully reproducible approach for constructing immersive virtual environments. While it currently only targets Unity, a proprietary source-available game engine, unifir hopes to improve the openness and interoperability of immersive virtual environments by encoding all of the decisions involved in building a scene in standard R and C# code. A partially open system is better than a fully closed one, and if other game engines become more feasible options for large scale immersive virtual environments, unifir may be extended to support those as well.

Citing unifir

To cite unifir in publications please use:

Mahoney M. J., Beier C. M., and Ackerman, A. C. (2022). unifir: A Unifying API for Working with Unity in R. Journal of Open Source Software, 7(73), 4388, https://doi.org/10.21105/joss.04388

A BibTeX entry for LaTeX users is:

  @Article{,
    year = {2022},
    publisher = {The Open Journal},
    volume = {7},
    number = {73},
    pages = {4388},
    author = {Michael J. Mahoney and Colin M. Beier and Aidan C. Ackerman},
    title = {{unifir:} A Unifying {API} for Working with {Unity} in {R}},
    journal = {Journal of Open Source Software},
    doi = {10.21105/joss.04388},
    url = {https://doi.org/10.21105/joss.04388},
  }

Code of Conduct

Please note that the unifir project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

Disclaimer

These materials are not sponsored by or affiliated with Unity Technologies or its affiliates. “Unity” is a trademark or registered trademark of Unity Technologies or its affiliates in the U.S. and elsewhere.