---
title: "Extra functions to control Minecraft"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Extra functions to control Minecraft}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(eval = FALSE)
```

<link rel=stylesheet type="text/css" href="https://kbroman.org/stylesheets/kbroman_vignette.css"></script>

[![R-CMD-check](https://github.com/kbroman/craft/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/kbroman/craft/actions/workflows/R-CMD-check.yaml)
[![r-universe badge](https://kbroman.r-universe.dev/craft/badges/version)](https://kbroman.r-universe.dev/craft)
[![zenodo DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20070587.svg)](https://doi.org/10.5281/zenodo.20070587)

## Introduction <a href="https://github.com/kbroman/craft"><img src="https://kbroman.org/craft/craft_logo.png" align="right" height="138" alt="craft logo"/></a>

The [miner](https://github.com/kbroman/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 [craft](https://github.com/kbroman/craft) includes additional
functions that illustrate and extend the use of
[miner](https://github.com/kbroman/craft), including many of the
examples in our ebook [R Programming with
Minecraft](https://kbroman.org/miner_book/).

## Installation

Install the [miner](https://github.com/kbroman/miner) and
[craft](https://github.com/kbroman/craft) packages from [R
universe](https://r-universe.dev):

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

Alternatively, use the
[remotes](https://remotes.r-lib.org) package to install them from
GitHub. First install [remotes](https://remotes.r-lib.org):

```r
install.packages("remotes")
```

Then use `remotes:install_github()` to install [miner](https://github.com/kbroman/miner) and
[craft](https://github.com/kbroman/craft):

```r
library(remotes)
install_github("kbroman/miner", build_vignettes=TRUE)
install_github("kbroman/craft", build_vignettes=TRUE)
```

_Note_: this should automatically install a number of dependent
packages, including [Rmaze](https://github.com/Vessy/Rmaze),
[igraph](https://r.igraph.org), and
[imager](https://asgr.github.io/imager/). To install imager you may
need to install [Xquartz](https://www.xquartz.org/) on Mac or
`libx11-dev` or similar on Linux.

To use the packages you will need to:

* Install a Minecraft server
* Install a Minecraft client (the Minecraft game)
* Connect to the Minecraft server from R

```r
library(miner)
mc_connect('52.1.2.3') ## use your minecraft server IP address here
```

Note that if your Minecraft server is running locally (on the same
computer as you're running R), you might not have to specify the IP,
or you might try `'127.0.0.1'` or `'localhost'`.
One of these might work:

```r
mc_connect()
mc_connect('127.0.0.1')
mc_connect('localhost')
```

Full installation instructions are provided in the online book, [R
programming with Minecraft](https://kbroman.org/miner_book/).


## Overview of craft commands

The [miner](https://github.com/kbroman/miner) package includes a bunch
of basic commands for interacting with your Minecraft world.
The [craft](https://github.com/kbroman/craft) package combines these
commands to do bigger things, and also provides alternative versions
of the basic functions, for programming convenience.

### Building stuff

There are a number of functions for building stuff:

- [`buildBuilding`](https://kbroman.r-universe.dev/craft/doc/manual.html#buildBuilding) - build a large square building around the player
- [`buildDoor`](https://kbroman.r-universe.dev/craft/doc/manual.html#buildDoor) - build a door in the direction the player is facing
- [`buildFence`](https://kbroman.r-universe.dev/craft/doc/manual.html#buildFence) - build a square fence around the player
- [`buildRlogo`](https://kbroman.r-universe.dev/craft/doc/manual.html#buildRlogo) - render the R logo out of blocks, as in [Chapter 9 of
  our ebook](https://kbroman.org/miner_book/rendering-the-r-logo-in-minecraft.html)
- [`buildStairs`](https://kbroman.r-universe.dev/craft/doc/manual.html#buildStairs) - build a set of stairs (going down or up) in the direction the player is facing
- [`mc_maze`](https://kbroman.r-universe.dev/craft/doc/manual.html#mc_maze) -
  build a maze, as in [Chapter 10 of our
  ebook](https://kbroman.org/miner_book/generate-a-maze-in-minecraft.html)
- [`mc_mazer`](https://kbroman.r-universe.dev/craft/doc/manual.html#mc_mazer) -
  run a chat bot to build a maze from the Minecraft chat

### Useful tools

We've added a number of useful tools:

- [`clearSpace`](https://kbroman.r-universe.dev/craft/doc/manual.html#clearSpace) - clear (ie **destroy**) a bunch of space around the player
- [`mc_whoami`](https://kbroman.r-universe.dev/craft/doc/manual.html#mc_whoami) - figure out your player id by typing "who am i" in the chat
- [`whereami`](https://kbroman.r-universe.dev/craft/doc/manual.html#whereami) - figure out your position
- [`getPlayerCompass`](https://kbroman.r-universe.dev/craft/doc/manual.html#getPlayerCompass) - get your orientation as a compass direction
  with 4, 8, or 16 points (for example north, north-west, or north-northwest)


### Drawing stuff

- [`cube`](https://kbroman.r-universe.dev/craft/doc/manual.html#cube) - Make a solid or hollow cube
- [`sphere`](https://kbroman.r-universe.dev/craft/doc/manual.html#sphere) - Make a solid or hollow sphere with the player at the center
- [`drawLine`](https://kbroman.r-universe.dev/craft/doc/manual.html#drawLine) - Draw a line
- [`mc_plot`](https://kbroman.r-universe.dev/craft/doc/manual.html#mc_plot) - Render a scatterplot within Minecraft
- [`mc_clearplot`](https://kbroman.r-universe.dev/craft/doc/manual.html#mc_clearplot) - Clear the space where you put that scatterplot
- [`write_text`](https://kbroman.r-universe.dev/craft/doc/manual.html#write_text) - Write text in Minecraft


### Games

- [`num_guess`](https://kbroman.r-universe.dev/craft/doc/manual.html#num_guess) - Play the number guessing game in [Chapter 7 of our ebook](https://kbroman.org/miner_book/number-guess-chat-bot-in-minecraft.html)
- [`mc_race`](https://kbroman.r-universe.dev/craft/doc/manual.html#mc_race) -
  Which player will move the farthest in a 10 second race? Based on code
  from [Chapter 11 of our ebook](https://kbroman.org/miner_book/random-walks-in-the-minecraft-world.html)


### Alternate `setBlocks` functions

There are a couple of alternative versions of
[`miner::setBlocks`](https://kbroman.r-universe.dev/miner/doc/manual.html#setBlocks) taking a block style argument, or a
random mixture of blocks

- [`setBlocksStyle`](https://kbroman.r-universe.dev/craft/doc/manual.html#setBlocksStyle) - like `setBlocks` but accepting a block style argument
- [`setBlocksMix`](https://kbroman.r-universe.dev/craft/doc/manual.html#setBlocksMix) - like `setBlocks` but filling a cuboid with randomly
  selected block types


### Vector-based functions

The following are like the corresponding function without the `V`, but
accepting position (or positions) as a vector (or vectors) rather than
three separate coordinates.  For example, you could write
`setBlockV(pos, 46)` rather than `setBlock(pos[1], pos[2], pos[3], 46)`.

- [`setBlockV`](https://kbroman.r-universe.dev/craft/doc/manual.html#setBlockV)
- [`setBlocksV`](https://kbroman.r-universe.dev/craft/doc/manual.html#setBlocksV)
- [`setBlocksStyleV`](https://kbroman.r-universe.dev/craft/doc/manual.html#setBlocksStyleV)
- [`setBlocksMixV`](https://kbroman.r-universe.dev/craft/doc/manual.html#setBlocksMixV)
- [`setPlayerPosV`](https://kbroman.r-universe.dev/craft/doc/manual.html#setPlayerPosV)
- [`setPlayerDirectionV`](https://kbroman.r-universe.dev/craft/doc/manual.html#setPlayerDirectionV)
- [`getBlockV`](https://kbroman.r-universe.dev/craft/doc/manual.html#getBlockV)
- [`getBlocksV`](https://kbroman.r-universe.dev/craft/doc/manual.html#getBlocksV)


### Being Elsa from Frozen

Give your player Elsa powers in Minecraft:

- [`elsafy`](https://kbroman.r-universe.dev/craft/doc/manual.html#elsafy) -
  Water turns to ice when your player steps on it
- [`de_elsafy`](https://kbroman.r-universe.dev/craft/doc/manual.html#de_elsafy) -
  Turn off the [`elsafy`](https://kbroman.r-universe.dev/craft/doc/manual.html#elsafy)) power
- [`ice_towers`](https://kbroman.r-universe.dev/craft/doc/manual.html#ice_towers) -
  Wherever you hit (by right-clicking while holding an iron sword), a
  tower of ice is built


### Random walk

The following are for making your player walk randomly around the
Minecraft world, as in [Chapter 11 of our ebook](https://kbroman.org/miner_book/random-walks-in-the-minecraft-world.html):

- [`initHeading`](https://kbroman.r-universe.dev/craft/doc/manual.html#initHeading)
- [`getHeading`](https://kbroman.r-universe.dev/craft/doc/manual.html#getHeading)
- [`lookForward`](https://kbroman.r-universe.dev/craft/doc/manual.html#lookForward)
- [`moveForward`](https://kbroman.r-universe.dev/craft/doc/manual.html#moveForward)
- [`setHeading`](https://kbroman.r-universe.dev/craft/doc/manual.html#setHeading)
- [`turnLeft`](https://kbroman.r-universe.dev/craft/doc/manual.html#turnLeft)


### Dangerous functions

Finally, you can run R code directly from Minecraft by typing it in
the chat. But enable this feature with great care.

- [`mc_Reval`](https://kbroman.r-universe.dev/craft/doc/manual.html#mc_Reval)


## Acknowledgments and references

Many of the ideas and techniques in the
[miner](https://github.com/kbroman/miner) and
[craft](https://github.com/kbroman/craft) packages were adapted from
or inspired by
["Learn to program with Minecraft" by Craig Richardson (No Starch
Press, 2016)](https://nostarch.com/programwithminecraft),
["Adventures in Minecraft" by Martin O'Hanlon and David Whale (Wiley,
2014)](https://www.wiley.com/en-us/Adventures+in+Minecraft%2C+2nd+Edition-p-9781119439554),
and some work by Alexander Pruss.

---

[![CC BY](https://i.creativecommons.org/l/by/3.0/88x31.png)](https://creativecommons.org/licenses/by/3.0/)
