Title: | A Unifying API for Calling the 'Unity' '3D' Video Game Engine |
---|---|
Description: | Functions for the creation and manipulation of scenes and objects within the 'Unity' '3D' video game engine (<https://unity.com/>). Specific focuses include the creation and import of terrain data and 'GameObjects' as well as scene management. |
Authors: | Michael Mahoney [aut, cre] |
Maintainer: | Michael Mahoney <[email protected]> |
License: | MIT + file LICENSE |
Version: | 0.2.4.9000 |
Built: | 2024-08-29 23:12:29 UTC |
Source: | https://github.com/ropensci/unifir |
unifir_script
Build and execute a unifir_script
action(script, write = TRUE, exec = TRUE, quit = TRUE)
action(script, write = TRUE, exec = TRUE, quit = TRUE)
script |
The |
write |
Boolean: Write the generated script to a file? |
exec |
Boolean: Execute the script inside of the Unity project? Note
that if |
quit |
Boolean: Quit Unity after execution? |
If exec = FALSE
, the original unifir_script
object passed to
script
. If exec = TRUE
, the same unifir_script
object with its
props replaced by the C# they generate.
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver() ) # Then add any number of props to it: script <- add_light(script) # Then call `action` to execute the script! if (interactive()) { action(script) }
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver() ) # Then add any number of props to it: script <- add_light(script) # Then call `action` to execute the script! if (interactive()) { action(script) }
These functions add assets available at https://github.com/mikemahoney218/unity_assets/ to a Unity scene.
add_default_player( script, controller = c("Player", "FootstepsPlayer", "JetpackPlayer", "Third Person"), asset_directory = NULL, lazy = TRUE, method_name = NULL, destination_scene = NULL, x_position = 0, y_position = 0, z_position = 0, x_scale = 1, y_scale = 1, z_scale = 1, x_rotation = 0, y_rotation = 0, z_rotation = 0, exec = TRUE ) add_default_tree( script, tree, asset_directory = NULL, lazy = TRUE, method_name = NULL, destination_scene = NULL, x_position = 0, y_position = 0, z_position = 0, x_scale = 1, y_scale = 1, z_scale = 1, x_rotation = 0, y_rotation = 0, z_rotation = 0, exec = TRUE )
add_default_player( script, controller = c("Player", "FootstepsPlayer", "JetpackPlayer", "Third Person"), asset_directory = NULL, lazy = TRUE, method_name = NULL, destination_scene = NULL, x_position = 0, y_position = 0, z_position = 0, x_scale = 1, y_scale = 1, z_scale = 1, x_rotation = 0, y_rotation = 0, z_rotation = 0, exec = TRUE ) add_default_tree( script, tree, asset_directory = NULL, lazy = TRUE, method_name = NULL, destination_scene = NULL, x_position = 0, y_position = 0, z_position = 0, x_scale = 1, y_scale = 1, z_scale = 1, x_rotation = 0, y_rotation = 0, z_rotation = 0, exec = TRUE )
script |
A |
controller |
Which controller to use. "Player", the default, is a simple first-person controller. "FootstepsPlayer" adds footsteps to this controller, while "JetpackPlayer" adds a "jetpack" with limited fuel. ""Third Person" lets you control a small cylinder in third person. |
asset_directory |
A file path to the directory containing the asset,
or alternatively, to which the default assets should be saved.
Defaults to |
lazy |
Boolean: if TRUE, unifir will attempt to only copy the files once per run of a script; if FALSE, unifir will copy the files as many times as requested, overwriting pre-existing files each time. |
method_name |
The internal name to use for the C# method created. Will be randomly generated if not set. |
destination_scene |
Optionally, the scene to instantiate the prefabs in. Ignored if NULL, the default. |
x_position , y_position , z_position
|
The position of the GameObject in world space. |
x_scale , y_scale , z_scale
|
The scale of the GameObject (relative to its parent object). |
x_rotation , y_rotation , z_rotation
|
The rotation of the GameObject to create, as Euler angles. |
exec |
Logical: Should the C# method be included in the set executed by MainFunc? |
tree |
Which tree to use. There are currently 12 generic tree objects available, named "tree_1" through "tree_12". The number of a tree (1-12) can be specified instead of the full name. |
In effect, these functions provide a thin wrapper across instantiate_prefab and import_asset. By providing the directory an asset is stored in, and the path to the prefab file once that directory has been copied into Unity, these files will add prefabs to specified locations throughout the scene. This function will also download the necessary assets and handles specifying file paths.
add_default_player adds "player" controllers to a Unity scene. add_default_tree adds tree GameObjects.
The unifir_script
object passed to script
, with props for adding
assets appended.
Other props:
add_light()
,
add_prop()
,
add_texture()
,
create_terrain()
,
import_asset()
,
instantiate_prefab()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
Other utilities:
add_prop()
,
create_unity_project()
,
find_unity()
,
get_asset()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
,
waiver()
if (interactive()) { # First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver()) # Now add props: script <- add_default_player(script) script <- add_default_tree(script, 1) script <- save_scene(script) } # Lastly, execute the script via the `action` function
if (interactive()) { # First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver()) # Now add props: script <- add_default_player(script) script <- add_default_tree(script, 1) script <- save_scene(script) } # Lastly, execute the script via the `action` function
This function creates light objects within a Unity scene. This function can only add one light at a time – call the function multiple times to add more than one light.
add_light( script, light_type = c("Directional", "Point", "Spot", "Area"), method_name = NULL, light_name = "Light", x_position = 0, y_position = 0, z_position = 0, x_scale = 1, y_scale = 1, z_scale = 1, x_rotation = 50, y_rotation = -30, z_rotation = 0, exec = TRUE )
add_light( script, light_type = c("Directional", "Point", "Spot", "Area"), method_name = NULL, light_name = "Light", x_position = 0, y_position = 0, z_position = 0, x_scale = 1, y_scale = 1, z_scale = 1, x_rotation = 50, y_rotation = -30, z_rotation = 0, exec = TRUE )
script |
A |
light_type |
One of "Directional", "Point", "Spot", or "Area". See https://docs.unity3d.com/Manual/Lighting.html for more information. |
method_name |
The internal name to use for the C# method created. Will be randomly generated if not set. |
light_name |
The name to assign the Light object. |
x_position , y_position , z_position
|
The position of the GameObject in world space. |
x_scale , y_scale , z_scale
|
The scale of the GameObject (relative to its parent object). |
x_rotation , y_rotation , z_rotation
|
The rotation of the GameObject to create, as Euler angles. |
exec |
Logical: Should the C# method be included in the set executed by MainFunc? |
The unifir_script
object passed to script
, with props for adding
lights appended.
Other props:
add_default_player()
,
add_prop()
,
add_texture()
,
create_terrain()
,
import_asset()
,
instantiate_prefab()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver()) # Now add props: script <- add_light(script) # Lastly, execute the script via the `action` function
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver()) # Now add props: script <- add_light(script) # Lastly, execute the script via the `action` function
This function is exported so that developers can add their own props in new packages, without needing to re-implement the prop and script classes themselves. It is not expected that end users will need this function.
add_prop(script, prop, exec = TRUE)
add_prop(script, prop, exec = TRUE)
script |
A script object (from make_script) to append the prop to. |
prop |
A |
exec |
Logical: Should the method created by the prop be called in the MainFunc method? |
Other props:
add_default_player()
,
add_light()
,
add_texture()
,
create_terrain()
,
import_asset()
,
instantiate_prefab()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
Other utilities:
add_default_player()
,
create_unity_project()
,
find_unity()
,
get_asset()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
,
waiver()
script <- make_script("example_script", unity = waiver()) prop <- unifir_prop( prop_file = waiver(), # Must be a file that exists or waiver() method_name = NULL, # Auto-generated if NULL or NA method_type = "ExampleProp", # Length-1 character vector parameters = list(), # Not validated, usually a list build = function(script, prop, debug) {}, using = character(0) ) script <- add_prop(script, prop)
script <- make_script("example_script", unity = waiver()) prop <- unifir_prop( prop_file = waiver(), # Must be a file that exists or waiver() method_name = NULL, # Auto-generated if NULL or NA method_type = "ExampleProp", # Length-1 character vector parameters = list(), # Not validated, usually a list build = function(script, prop, debug) {}, using = character(0) ) script <- add_prop(script, prop)
This function adds a helper method, AddTexture
, to the
C# script. This function is typically used to add textures to
heightmaps in a Unity scene, for instance by functions
like create_terrain. It requires some arguments be provided
at the C# level, and so is almost always called with exec = FALSE
.
add_texture(script, method_name = NULL, exec = FALSE)
add_texture(script, method_name = NULL, exec = FALSE)
script |
A |
method_name |
The internal name to use for the C# method created. Will be randomly generated if not set. |
exec |
Logical: Should the C# method be included in the set executed by MainFunc? |
The unifir_script
object passed to script
, with an AddTexture
method appended.
Other props:
add_default_player()
,
add_light()
,
add_prop()
,
create_terrain()
,
import_asset()
,
instantiate_prefab()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver() ) # Now add props: script <- add_texture(script) # Lastly, execute the script via the `action` function
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver() ) # Now add props: script <- add_texture(script) # Lastly, execute the script via the `action` function
Unity uses a left-handed coordinate system, which is effectively "flipped"
from our normal way of thinking about spatial coordinate systems. It also
can only import terrain as square tiles of side 2^x + 1, for x between 5 and
12. As a result, importing objects into a Unity scene so that they align
with terrain surfaces is trickier than you'd expect.
This function "associates" the XY coordinates from some sf
object, likely a
point data set, with some raster object.
associate_coordinates(object, raster, side_length = 4097)
associate_coordinates(object, raster, side_length = 4097)
object |
The |
raster |
A raster or file path to a raster to associate coordinates with. Note that different rasters will produce different coordinate outputs; you should run this function with the same raster you plan on bringing into Unity. Any file or object that can be read via terra::rast can be used. |
side_length |
The side length of terrain tiles, in map units, you intend to bring into Unity. Must be a value equal to 2^x + 1, for x between 5 and 12. All functions in the unifir family default to 4097. |
A data.frame with two columns, X and Y, representing the re-aligned
coordinates. If object
is point data (or anything object that
sf::st_coordinates returns a single row for each row of), these rows will
be in the same order as object
(and so can be appended via cbind).
## Not run: if (!isTRUE(as.logical(Sys.getenv("CI")))) { simulated_data <- data.frame( id = seq(1, 100, 1), lat = runif(100, 44.04905, 44.17609), lng = runif(100, -74.01188, -73.83493) ) simulated_data <- sf::st_as_sf( simulated_data, coords = c("lng", "lat"), crs = 4326 ) output_files <- terrainr::get_tiles(simulated_data) temptiff <- tempfile(fileext = ".tif") terrainr::merge_rasters(output_files["elevation"][[1]], temptiff) associate_coordinates(simulated_data, temptiff) } ## End(Not run)
## Not run: if (!isTRUE(as.logical(Sys.getenv("CI")))) { simulated_data <- data.frame( id = seq(1, 100, 1), lat = runif(100, 44.04905, 44.17609), lng = runif(100, -74.01188, -73.83493) ) simulated_data <- sf::st_as_sf( simulated_data, coords = c("lng", "lat"), crs = 4326 ) output_files <- terrainr::get_tiles(simulated_data) temptiff <- tempfile(fileext = ".tif") terrainr::merge_rasters(output_files["elevation"][[1]], temptiff) associate_coordinates(simulated_data, temptiff) } ## End(Not run)
This object contains the set of assets unifir is able to download and import (through get_asset and import_asset). These objects are all released under permissive open-source licenses (currently, either CC-0 1.0 or MIT). More information on the assets may be found at https://github.com/mikemahoney218/unity_assets .
available_assets
available_assets
A character vector with 13 elements, each representing an asset which can be imported.
https://github.com/mikemahoney218/unity_assets
When running in debug mode, unifir will write nothing to disk.
check_debug()
check_debug()
Create directory if it doesn't exist
create_if_not(path, recur = FALSE)
create_if_not(path, recur = FALSE)
path |
The path to be created |
recur |
Boolean: create directories recursively? |
Create a terrain tile with optional image overlay
create_terrain( script, method_name = NULL, heightmap_path, x_pos, z_pos, width, height, length, heightmap_resolution, texture_path = "", exec = TRUE )
create_terrain( script, method_name = NULL, heightmap_path, x_pos, z_pos, width, height, length, heightmap_resolution, texture_path = "", exec = TRUE )
script |
A |
method_name |
The internal name to use for the C# method created. Will be randomly generated if not set. |
heightmap_path |
The file path to the heightmap to import as terrain. |
x_pos , z_pos
|
The position of the corner of the terrain. |
width , height , length
|
The dimensions of the terrain tile, in linear units. |
heightmap_resolution |
The resolution of the heightmap image. |
texture_path |
Optional: the file path to the image to use as a terrain overlay. |
exec |
Logical: Should the C# method be included in the set executed by MainFunc? |
Other props:
add_default_player()
,
add_light()
,
add_prop()
,
add_texture()
,
import_asset()
,
instantiate_prefab()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
if (requireNamespace("terra", quietly = TRUE)) { raster <- tempfile(fileext = ".tiff") r <- terra::rast(matrix(rnorm(1000^2, mean = 100, sd = 20), 1000), extent = terra::ext(0, 1000, 0, 1000) ) terra::writeRaster(r, raster) script <- make_script("example_script", unity = waiver() ) create_terrain( script, heightmap_path = raster, x_pos = 0, z_pos = 0, width = 1000, height = terra::minmax(r)[[2]], length = 1000, heightmap_resolution = 1000 ) }
if (requireNamespace("terra", quietly = TRUE)) { raster <- tempfile(fileext = ".tiff") r <- terra::rast(matrix(rnorm(1000^2, mean = 100, sd = 20), 1000), extent = terra::ext(0, 1000, 0, 1000) ) terra::writeRaster(r, raster) script <- make_script("example_script", unity = waiver() ) create_terrain( script, heightmap_path = raster, x_pos = 0, z_pos = 0, width = 1000, height = terra::minmax(r)[[2]], length = 1000, heightmap_resolution = 1000 ) }
Create a new Unity project.
create_unity_project(path, quit = TRUE, unity = NULL)
create_unity_project(path, quit = TRUE, unity = NULL)
path |
The path to create a new Unity project at. |
quit |
Logical: quit Unity after creating the project? |
unity |
The path to the Unity executable on your system (importantly,
not the UnityHub executable). If |
TRUE, invisibly.
Other utilities:
add_default_player()
,
add_prop()
,
find_unity()
,
get_asset()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
,
waiver()
if (interactive()) create_unity_project(file.path(tempdir(), "project"))
if (interactive()) create_unity_project(file.path(tempdir(), "project"))
If the path to Unity is not provided to a function, this function is invoked to attempt to find it. To do so, it goes through the following steps:
Attempt to load the "unifir_unity_path" environment variable.
Attempt to load the "unifir_unity_path" option.
Assuming that neither points to an actual file, this function will then check the default installation paths for Unity on the user's operating system. If not found, this function will error.
find_unity(unity = NULL, check_path = TRUE)
find_unity(unity = NULL, check_path = TRUE)
unity |
Character: If provided, this function will quote the provided string (if necessary) and return it. |
check_path |
Logical: If |
The path to the Unity executable on the user's machine, as a length-1 character vector.
Other utilities:
add_default_player()
,
add_prop()
,
create_unity_project()
,
get_asset()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
,
waiver()
if (interactive()) { try(find_unity()) }
if (interactive()) { try(find_unity()) }
This is a simple helper function downloading the assets stored at https://github.com/mikemahoney218/unity_assets .
get_asset(asset, directory = NULL)
get_asset(asset, directory = NULL)
asset |
The asset to download. Available asset names are provided in available_assets. |
directory |
Optionally, the directory to extract the downloaded models
in. If NULL, the default, saves to |
Other utilities:
add_default_player()
,
add_prop()
,
create_unity_project()
,
find_unity()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
,
waiver()
if (interactive()) { get_asset(asset = "tree_1", directory = tempdir()) }
if (interactive()) { get_asset(asset = "tree_1", directory = tempdir()) }
Import assets into Unity.
import_asset(script, asset_path, lazy = TRUE)
import_asset(script, asset_path, lazy = TRUE)
script |
A |
asset_path |
The file path to the asset to import. If a directory, the
entire directory will be recursively copied. Note that this function doesn't
have a |
lazy |
Boolean: if TRUE, unifir will attempt to only copy the files once per run of a script; if FALSE, unifir will copy the files as many times as requested, overwriting pre-existing files each time. |
script
with a new prop.
Other props:
add_default_player()
,
add_light()
,
add_prop()
,
add_texture()
,
create_terrain()
,
instantiate_prefab()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver() ) # CRAN also doesn't have any props to install, # so we'll make a fake prop location: prop_directory <- file.path(tempdir(), "props") dir.create(prop_directory) # Now add props: script <- import_asset(script, prop_directory) # Lastly, execute the script via the `action` function
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver() ) # CRAN also doesn't have any props to install, # so we'll make a fake prop location: prop_directory <- file.path(tempdir(), "props") dir.create(prop_directory) # Now add props: script <- import_asset(script, prop_directory) # Lastly, execute the script via the `action` function
This function creates objects (specifically, prefabs) within a Unity scene.
This function is vectorized over all functions from prefab_path
through
z_rotation
; to add multiple objects, simply provide vectors to each
argument. Note that all arguments will be automatically recycled if not the
same length; this may produce undesired results. This function is only
capable of altering a single scene at once – call the function multiple
times if you need to manipulate multiple scenes.
instantiate_prefab( script, method_name = NULL, destination_scene = NULL, prefab_path, x_position = 0, y_position = 0, z_position = 0, x_scale = 1, y_scale = 1, z_scale = 1, x_rotation = 0, y_rotation = 0, z_rotation = 0, exec = TRUE )
instantiate_prefab( script, method_name = NULL, destination_scene = NULL, prefab_path, x_position = 0, y_position = 0, z_position = 0, x_scale = 1, y_scale = 1, z_scale = 1, x_rotation = 0, y_rotation = 0, z_rotation = 0, exec = TRUE )
script |
A |
method_name |
The internal name to use for the C# method created. Will be randomly generated if not set. |
destination_scene |
Optionally, the scene to instantiate the prefabs in. Ignored if NULL, the default. |
prefab_path |
File path to the prefab to be instantiated. This should be relative to the Unity project root directory, and likely begins with "Assets". Alternatively, if this is one of the elements in |
x_position , y_position , z_position
|
The position of the GameObject in world space. |
x_scale , y_scale , z_scale
|
The scale of the GameObject (relative to its parent object). |
x_rotation , y_rotation , z_rotation
|
The rotation of the GameObject to create, as Euler angles. |
exec |
Logical: Should the C# method be included in the set executed by MainFunc? |
Other props:
add_default_player()
,
add_light()
,
add_prop()
,
add_texture()
,
create_terrain()
,
import_asset()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver()) # Now add props: script <- instantiate_prefab(script, prefab_path = "Assets/some.prefab") # Lastly, execute the script via the `action` function
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver()) # Now add props: script <- instantiate_prefab(script, prefab_path = "Assets/some.prefab") # Lastly, execute the script via the `action` function
This function adds a helper method, LoadPNG
, to the
C# script. This function is typically used by other C# methods
to bring in textures into a Unity scene, for instance by functions
like create_terrain. It requires some arguments be provided
at the C# level, and so is almost always called with exec = FALSE
.
load_png(script, method_name = NULL, exec = FALSE)
load_png(script, method_name = NULL, exec = FALSE)
script |
A |
method_name |
The internal name to use for the C# method created. Will be randomly generated if not set. |
exec |
Logical: Should the C# method be included in the set executed by MainFunc? |
Other props:
add_default_player()
,
add_light()
,
add_prop()
,
add_texture()
,
create_terrain()
,
import_asset()
,
instantiate_prefab()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
Other utilities:
add_default_player()
,
add_prop()
,
create_unity_project()
,
find_unity()
,
get_asset()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
,
waiver()
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver()) # Then add any number of props to it: script <- load_png(script) # Then call `action` to execute the script!
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver()) # Then add any number of props to it: script <- load_png(script) # Then call `action` to execute the script!
Load a scene in a Unity project.
load_scene(script, scene_name, method_name = NULL, exec = TRUE)
load_scene(script, scene_name, method_name = NULL, exec = TRUE)
script |
A |
scene_name |
The name of the scene to load. |
method_name |
The internal name to use for the C# method created. Will be randomly generated if not set. |
exec |
Logical: Should the C# method be included in the set executed by MainFunc? |
Other props:
add_default_player()
,
add_light()
,
add_prop()
,
add_texture()
,
create_terrain()
,
import_asset()
,
instantiate_prefab()
,
load_png()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
Other utilities:
add_default_player()
,
add_prop()
,
create_unity_project()
,
find_unity()
,
get_asset()
,
load_png()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
,
waiver()
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver()) # Now add props: script <- load_scene(script, scene_name = "some_scene") # Lastly, execute the script via the `action` function
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver()) # Now add props: script <- load_scene(script, scene_name = "some_scene") # Lastly, execute the script via the `action` function
unifir_script
object.unifir relies upon "script" objects, which collect "prop" objects (C# methods) which then may be executed within a Unity project via the action function.
make_script( project, script_name = NULL, scene_name = NULL, unity = find_unity(), initialize_project = NULL )
make_script( project, script_name = NULL, scene_name = NULL, unity = find_unity(), initialize_project = NULL )
project |
The directory path of the Unity project. |
script_name |
The file name to save the script at. The folder location and file extensions will be added automatically. |
scene_name |
The default scene to operate within. If a function requires a scene name and one is not provided, this field will be used. |
unity |
The location of the Unity executable to create projects with. |
initialize_project |
If TRUE, will call create_unity_project to create
a Unity project at |
A unifir_script
object.
# Create an empty script file # In practice, you'll want to set `project` to the project path to create # and `unity` to `NULL` (the default) make_script(project = waiver(), unity = waiver())
# Create an empty script file # In practice, you'll want to set `project` to the project path to create # and `unity` to `NULL` (the default) make_script(project = waiver(), unity = waiver())
Create a new scene in a Unity project.
new_scene( script, setup = c("EmptyScene", "DefaultGameObjects"), mode = c("Additive", "Single"), method_name = NULL, exec = TRUE )
new_scene( script, setup = c("EmptyScene", "DefaultGameObjects"), mode = c("Additive", "Single"), method_name = NULL, exec = TRUE )
script |
A |
setup |
One of "EmptyScene" ("No game objects are added to the new Scene.") or "DefaultGameObjects" ("Adds default game objects to the new Scene (a light and camera).") |
mode |
One of "Additive" ("The newly created Scene is added to the current open Scenes.") or "Single" ("All current open Scenes are closed and the newly created Scene are opened.") |
method_name |
The internal name to use for the C# method created. Will be randomly generated if not set. |
exec |
Logical: Should the C# method be included in the set executed by MainFunc? |
Other props:
add_default_player()
,
add_light()
,
add_prop()
,
add_texture()
,
create_terrain()
,
import_asset()
,
instantiate_prefab()
,
load_png()
,
load_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
Other utilities:
add_default_player()
,
add_prop()
,
create_unity_project()
,
find_unity()
,
get_asset()
,
load_png()
,
load_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
,
waiver()
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver() ) # Now add props: script <- new_scene(script) # Lastly, execute the script via the `action` function
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver() ) # Now add props: script <- new_scene(script) # Lastly, execute the script via the `action` function
This function adds a helper method, ReadRaw
, to the
C# script. This function is typically used to bring in
heightmaps into a Unity scene, for instance by functions
like create_terrain. It requires some arguments be provided
at the C# level, and so is almost always called with exec = FALSE
.
read_raw(script, method_name = NULL, exec = FALSE)
read_raw(script, method_name = NULL, exec = FALSE)
script |
A |
method_name |
The internal name to use for the C# method created. Will be randomly generated if not set. |
exec |
Logical: Should the C# method be included in the set executed by MainFunc? |
Other props:
add_default_player()
,
add_light()
,
add_prop()
,
add_texture()
,
create_terrain()
,
import_asset()
,
instantiate_prefab()
,
load_png()
,
load_scene()
,
new_scene()
,
save_scene()
,
set_active_scene()
,
validate_path()
Other utilities:
add_default_player()
,
add_prop()
,
create_unity_project()
,
find_unity()
,
get_asset()
,
load_png()
,
load_scene()
,
new_scene()
,
save_scene()
,
set_active_scene()
,
validate_path()
,
waiver()
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver()) # Now add props: script <- read_raw(script) # Lastly, execute the script via the `action` function
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver()) # Now add props: script <- read_raw(script) # Lastly, execute the script via the `action` function
Save a scene in a Unity project.
save_scene(script, scene_name = NULL, method_name = NULL, exec = TRUE)
save_scene(script, scene_name = NULL, method_name = NULL, exec = TRUE)
script |
A |
scene_name |
The name to save the scene to. |
method_name |
The internal name to use for the C# method created. Will be randomly generated if not set. |
exec |
Logical: Should the C# method be included in the set executed by MainFunc? |
Other props:
add_default_player()
,
add_light()
,
add_prop()
,
add_texture()
,
create_terrain()
,
import_asset()
,
instantiate_prefab()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
set_active_scene()
,
validate_path()
Other utilities:
add_default_player()
,
add_prop()
,
create_unity_project()
,
find_unity()
,
get_asset()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
set_active_scene()
,
validate_path()
,
waiver()
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver() ) # Now add props: script <- save_scene(script, scene_name = "some_scene") # Lastly, execute the script via the `action` function
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver() ) # Now add props: script <- save_scene(script, scene_name = "some_scene") # Lastly, execute the script via the `action` function
Set a single scene to active.
set_active_scene(script, scene_name = NULL, method_name = NULL, exec = FALSE)
set_active_scene(script, scene_name = NULL, method_name = NULL, exec = FALSE)
script |
A |
scene_name |
The name of the scene to set as the active scene. |
method_name |
The internal name to use for the C# method created. Will be randomly generated if not set. |
exec |
Logical: Should the C# method be included in the set executed by MainFunc? |
Other props:
add_default_player()
,
add_light()
,
add_prop()
,
add_texture()
,
create_terrain()
,
import_asset()
,
instantiate_prefab()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
validate_path()
Other utilities:
add_default_player()
,
add_prop()
,
create_unity_project()
,
find_unity()
,
get_asset()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
validate_path()
,
waiver()
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver() ) # Now add props: script <- set_active_scene(script, scene_name = "some_scene") # Lastly, execute the script via the `action` function
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver() ) # Now add props: script <- set_active_scene(script, scene_name = "some_scene") # Lastly, execute the script via the `action` function
Fill in plot holes in a script
set_script_defaults(script, debug)
set_script_defaults(script, debug)
script |
The unifir_script to fill elements of |
debug |
Boolean: run in debug mode? |
This function is exported so that developers can add their own props in new packages, without needing to re-implement the prop and script classes themselves. It is not expected that end users will need this function.
unifir_prop(prop_file, method_name, method_type, parameters, build, using)
unifir_prop(prop_file, method_name, method_type, parameters, build, using)
prop_file |
The system location for the C# template file |
method_name |
The name of the method, in C# code |
method_type |
The type of the method (usually matches its file name); scripts can have multiple versions of the same method, each with different method_name values, all sharing the same method_type. |
parameters |
Method-specific parameters, typically used in the build stage. |
build |
A function that takes three arguments, |
using |
A character vector of imports required for the method. |
This function will check each argument for correctness. To be specific, it performs the following checks:
prop_file
must be either a waiver
object (created by waiver)
or a file path of length 1 pointing to a file that exists
method_name
will be automatically generated if not existing. If
it exists, it must be a character vector of length 1
method_type
must be a character vector of length 1
build
must be a function with the arguments script
, prop
,
and debug
(in that order, with no other arguments). Any other
arguments needed by your build function should be passed as prop
parameters.
using
must be a character vector (of any length, including 0)
If your prop needs data or arguments beyond these, store them as a
list in parameters
, which is entirely unchecked.
An R6 object of class unifir_prop
When Sys.getenv(unifir_debugmode)
returns anything other than ""
,
action runs in "debug mode". In addition to setting exec
and write
to FALSE
in action, this mode also attempts to disable any prop
functionality that would make changes to the user's disk – no files
or directories should be altered. In this mode, action will pass
debug = TRUE
as an argument to your prop; your prop should respect
the debug mode and avoid making any changes.
unifir_prop( prop_file = waiver(), # Must be a file that exists or waiver() method_name = NULL, # Auto-generated if NULL or NA method_type = "ExampleProp", # Length-1 character vector parameters = list(), # Not validated, usually a list build = function(script, prop, debug) {}, using = character(0) )
unifir_prop( prop_file = waiver(), # Must be a file that exists or waiver() method_name = NULL, # Auto-generated if NULL or NA method_type = "ExampleProp", # Length-1 character vector parameters = list(), # Not validated, usually a list build = function(script, prop, debug) {}, using = character(0) )
Print the version of the Unity Editor in use.
unity_version(unity = NULL)
unity_version(unity = NULL)
unity |
The path to the Unity executable on your system (importantly,
not the UnityHub executable). If |
A character vector of length 1 containing the version of Unity in use.
try( unity_version() )
try( unity_version() )
validate_path creates a generic C# method which takes a single argument and checks to make sure it exists. Your C# code calling the method must provide the path to validate. validate_single_path hard-codes the path to check in the C# code. This allows you to specify the path to check from R.
validate_path(script, method_name = NULL, exec = FALSE) validate_single_path(script, path, method_name = NULL, exec = TRUE)
validate_path(script, method_name = NULL, exec = FALSE) validate_single_path(script, path, method_name = NULL, exec = TRUE)
script |
A |
method_name |
The internal name to use for the C# method created. Will be randomly generated if not set. |
exec |
Logical: Should the C# method be included in the set executed by MainFunc? |
path |
The file path to validate |
Other props:
add_default_player()
,
add_light()
,
add_prop()
,
add_texture()
,
create_terrain()
,
import_asset()
,
instantiate_prefab()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
Other utilities:
add_default_player()
,
add_prop()
,
create_unity_project()
,
find_unity()
,
get_asset()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
waiver()
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver()) # Now add props: script <- validate_path(script) # Don't specify the path in R script <- validate_single_path( # Specify the path in R script, "file_that_exists.txt" )
# First, create a script object. # CRAN doesn't have Unity installed, so pass # a waiver object to skip the Unity-lookup stage: script <- make_script("example_script", unity = waiver()) # Now add props: script <- validate_path(script) # Don't specify the path in R script <- validate_single_path( # Specify the path in R script, "file_that_exists.txt" )
This function is borrowed from ggplot2. It creates a "flag" object indicating
that a value has been intentionally left blank (because it will be filled in
by something else). Often, a function argument being missing or NULL
will
result in an error, while passing waiver()
will cause the function to look
elsewhere in the script for an acceptable value.
waiver()
waiver()
An empty list of class waiver
.
H. Wickham. ggplot2: Elegant Graphics for Data Analysis. Springer-Verlag New York, 2016.
Other utilities:
add_default_player()
,
add_prop()
,
create_unity_project()
,
find_unity()
,
get_asset()
,
load_png()
,
load_scene()
,
new_scene()
,
read_raw()
,
save_scene()
,
set_active_scene()
,
validate_path()
waiver()
waiver()