-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
179 lines (143 loc) · 7.46 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# unifir: A Unifying API for Working with Unity in R <img src='man/figures/logo.png' align="right" height="138" />
<!-- badges: start -->
[](https://doi.org/10.21105/joss.04388)
[](https://choosealicense.com/licenses/mit/)
[](https://www.repostatus.org/#active)
[](https://lifecycle.r-lib.org/articles/stages.html#maturing-1)
[](https://cran.r-project.org/package=unifir)
[](https://github.com/ropensci/unifir/actions)
[](https://app.codecov.io/gh/ropensci/unifir?branch=main)
[](https://github.com/ropensci/software-review/issues/521)
<!-- badges: end -->
unifir is a unifying API for creating and managing [Unity](https://unity.com/)
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:
```{r}
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:
```{r}
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:
```{r}
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.
```{r eval = FALSE}
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](https://docs.ropensci.org/unifir/articles/unifir-user-guide.html)
and
[the one for how to extend unifir in your own packages](https://docs.ropensci.org/unifir/articles/unifir-dev-guide.html).
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:
```{r eval = FALSE}
# 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](https://github.com/) with:
``` r
# 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](https://unity.com/download) 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](https://doi.org/10.1080/13658816.2020.1830997),
[landscape planning](https://doi.org/10.1016/j.apgeog.2019.102102),
[environmental economics](https://doi.org/10.1016/j.jeem.2008.08.002)
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:
```{bibtex}
@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](https://docs.ropensci.org/unifir/CODE_OF_CONDUCT.html). 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.
[](https://ropensci.org)