--- 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) ``` [![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 craft logo 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/)