Program in Minecraft with R and miner

R-CMD-check r-universe badge zenodo DOI

Introduction miner logo

The miner package provides a simple interface to the Minecraft world. Use R functions to connect with a Minecraft server and control the world within.

The purpose of this package is to teach new programmers about R. See the effect of your R programs directly in Minecraft!

Installation

Install the miner and craft packages from R universe:

install.packages(c("miner", "craft"), repos=c("https://kbroman.r-universe.dev", "https://cloud.r-project.org"))

Alternatively, use the remotes package to install them from GitHub:

# install.packages("remotes")
library(remotes)
install_github('kbroman/miner', build_vignettes=TRUE)
install_github('kbroman/craft', build_vignettes=TRUE)

To use the package you will need to:

  • Install a Minecraft server
  • Install a Minecraft client (the Minecraft game)
  • Connect to the Minecraft server from R
library(miner)
mc_connect('52.1.2.3') ## use your server IP address here, or 127.0.0.1 if installed locally

Full installation instructions are provided in the online book, R programming with Minecraft.

About Minecraft

Minecraft is a virtual world, arranged as a 3-D grid of blocks of various materials (air, wood, stone, etc) and populated by players, animals and monsters. The state of the world is maintained by a shared Minecraft server, and players explore and interact with the shared world using a local Minecraft client.

For the server, we installed Spigot, an open-source Minecraft server, on a virtual machine. (See the section “Details on setting up a Minecraft Server”, below.) The R functions in this package connect with the server and modify the game world.

For the client, you will need to purchase and install Minecraft on your local PC or Mac machine. Note: this package will not work with Pocket Minecraft on mobile devices/tablets, or with the Windows 10 version of Minecraft found in the Windows Store.

Your first miner adventure

Once you have a Minecraft server set up, here are some commands you can try. Use your Minecraft client to observe the changes these commands make to the world.

First, connect to the world. For this you will need to know the IP address of your server.

mc_connect("52.168.1.2") # use the IP of your server here

To check you have successfully connected to the world, you can try chatting. You should see this message appear in the feed in the Minecraft client.

chatPost("Hello, Minecraft!")

Each player in the world gets a “player ID”“, and you’ll need to know the player ID to manipulate players. If you’re the only player in the world, the player ID is easy to find. But if there are multiple players, the easiest way to find your ID is to sign out of the server and then sign in again. Your player ID will then be the last one on the list returned by getPlayerIds.

myid <- tail(getPlayerIds(),1)

An alternative way of getting the player ID without the need to log out, using the chat window and an R script, see the mc_whoami function in the related craft package.

Once you have a Player ID, you can move the player around. Note that in Minecraft, “x” is the East/West axis, “z” is the North/South axis, and “y” is the vertical axis.

myloc <- getPlayerPos(myid)
setPlayerPos(myloc[1]+1,myloc[2],myloc[3],player_id=myid)  # move player 1 tile East
setPlayerPos(myloc[1],myloc[2]+50,myloc[3],player_id=myid) # raise player 50 tiles in the air

You can also modify the game world. For example, this adds a diamond block near the player.

myloc <- getPlayerPos(myid)
setBlock(myloc[1]+1, myloc[2], myloc[3], 57, 1)

Overview of miner commands

General functions for connecting to the game world:

  • mc_connect: Connect to a Minecraft server
  • chatPost: Make a chat message appear to players in their clients
  • getChatPosts: Retrieve the most recent chat message
  • mc_close: Close the connection to the Minecraft server

Functions for interacting with player location and direction (the angle of their gaze). Note that in Minecraft, x is East, y is Up and z is South, and the unit is one block. (A block is a 1-unit cube.) The player figure is about 2 units tall.

  • getPlayerIds: Get a list of players in the world
  • getPlayerPos: Find the position of a specified player
  • getPlayerDirection: Get a unit vector representing player direction
  • getPlayerRotation: Return the angle of the player’s direction in the x-z plane
  • getPlayerPitch: Return the up/down angle of the player’s direction
  • setPlayerPos: Teleport a player to a specified location

Functions for interacting with the Minecraft world.

  • getHeight: Find the height of the world (the y value of the highest non-air point) at a given x-z location
  • getBlock: Return the type of block (air, wood etc) in a given location, as a code. See the provided data frame mc_items for a list of blocks and item codes.
  • setBlock: change the block type at a given location. Use this to place items in the world.
  • getBlocks: Return the block types in a rectangular region, as a 3-dimensional array.
  • setBlocks: Fill a rectangular region with a specific block type
  • getBlockHits: Return the locations of blocks recently struck by a player’s iron sword

Additional commands were added in later versions of the API:

  • getPlayerName: get the name of the particular player with a particular ID
  • getPlayerId: get the numeric ID for a player, given their name.
  • getEntityTypes: get a data frame of the available entity types (with columns id and name). See also find_entity for searching for an entity by name.
  • spawnEntity: spawn a particular entity at a specific position.
  • setPlayerRotation, setPlayerPitch, setPlayerDirection: like the corresponding get functions, but for setting a player’s orientation.

Suggestions for writing your own programs with miner

Using the commands above, you can write programs in R to create structures in the game world, manipulate players, or even have the game world react to actions players take. Here are some things you can try (in some cases, with links to examples showing how).

Many of these features have been integrated into the companion package, craft. We are also preparing an ebook, R programming with Minecraft, which discusses these activities, and a few others, in more detail.

Details on Setting up a Minecraft server

We have tested this package using Spigot installed on an Ubuntu 16.04 virtual machine, and created a Docker image after all that you can easily deploy in your environment.

Note, that you may need to open ports on the Minecraft server and firewall to allow R and game clients to connect with it.

You probably want to configure the server to run in Creative mode, so edit the server.properties file as below:

force-gamemode=true
gamemode=1
difficulty=0
motd=My very own minecraft server

Further installation details are provided in the ebook, R programming with Minecraft.

Acknowledgments and References

Many of the ideas and techniques in this package were adapted from “Learn to program with Minecraft” by Craid Richardson (No Starch Press, 2016).

CC BY