Make your own room: a simple coursework guide

The short version

Start with the example below and save it as a .R file.
Change it into your own ecological puzzle.
Play it and check a wrong answer, the hints, and the correct answer.
Upload the .R file to the coursework submission on Moodle.

The rest of this guide walks you through those four steps. You can use the same R and RStudio setup you use for practical classes.

1. Start with a working example

In RStudio, choose File > New File > R Script. Copy the following code into the script and save it. For example, a student with number 19549 might name the file 19549_snail_room.R. Use your own number and a short name for your topic. Keep the .R ending.

This is a complete example. First try it unchanged so you can see how it works; then make your own version for submission.

# Author: replace with your name
# Student number: replace with your student number
# Course topic: means of ecological counts
# Data source: invented counts for this teaching example
# Teacher's solution: mean(c(2, 4, 6)) gives 4 snails per quadrat
# Change the example into your own puzzle before submitting it.

library(escapeR)

my_room <- new_room(
  id = "s19549a",
  module = "Ecological summaries",
  title = "The Snail Garden",
  learning_goal = "Create a vector and calculate a mean.",
  introduction = "A garden gate is locked. Three quadrat counts are written on its sign.",
  challenge = "Three equal-area quadrats contain 2, 4, and 6 snails. Use R to calculate the mean number of snails per quadrat. Submit that mean.",
  hints = c(
    "The mean is the sum of the counts divided by the number of quadrats.",
    "Use c() to put the three counts into a vector, then use mean().",
    "Try mean(c(2, 4, 6))."
  ),
  correct_result = 4,
  success = "The gate opens. You can take your field notebook into the garden!",
  failure = "Check that you included all three quadrats, then calculate their mean."
)

# This makes the room available for playing in this R session.
# replace = TRUE lets you source the file again after editing your own room.
register_rooms(my_room, replace = TRUE)

You can also copy the supplied template into your working folder by running these lines in the Console:

file.copy(
  system.file("templates", "student-room.R", package = "escapeR"),
  "my-room.R"
)

Open my-room.R in RStudio and save your edited version with your student number in its filename. If file.copy() returns FALSE, check whether a file with that name already exists and choose a new filename.

What those lines mean

library(escapeR) makes the game’s tools available. new_room(...) creates a room from the information between its brackets. my_room <- gives the room an object name, so R can refer to it later. The final register_rooms(...) line makes the room available to play in the current R session.

Most of your editing will be ordinary text between quotation marks. Lines beginning with # are comments: notes for you and your teacher. R does not run them.

2. Make the example yours

Choose the question first. Solve it yourself in R before writing the story. Here are a few manageable ideas:

Calculate the mean length of a small sample of fish.
Find the proportion of nests containing eggs.
Count how many quadrats have more than five plants.
Compare an observed count with a model prediction.
Find a particular value in a small table of species counts.

Pick an idea related to something you have practised in class. Keep one main task per room. The challenge should give another student enough information to solve it without asking you for the data or guessing your intention.

Edit these parts of the template:

Part	What to put there
Comments at the top	Your name, student number, course topic, data source, and worked R solution
`id`	A short code for your room, starting with a letter and at most 8 characters
`module`	The topic, such as `"Probability"` or `"Ecological summaries"`
`title`	A short name for the room
`learning_goal`	One sentence saying what someone will practise
`introduction`	A short story explaining the locked door
`challenge`	The ecological question, its data, units, and the answer to submit
`hints`	Three clues, from a small nudge to a clear R suggestion
`correct_result`	The answer you calculated yourself
`success`	A message for someone who solves the puzzle
`failure`	A helpful message for someone who tries a wrong answer

For an ID, you could use s followed by the last five digits of your student number and a letter: s19549a, then s19549b for a second room. Use your own number. Keep this ID different from existing rooms; en01 to en25 already belong to the course. You can inspect existing IDs with list_rooms().

Keep the question and answer in agreement

In the example, the counts are 2, 4, and 6. Check their mean in the Console:

mean(c(2, 4, 6))
#> [1] 4

That is why the template says correct_result = 4. If you change the counts, calculate the new answer and update correct_result, the hints, and the worked solution in your comments. Updating only the question leaves the lock checking the old answer.

For a number, write the number without quotes: correct_result = 4. For a word, use quotes: correct_result = "wetland". Text answers ignore case and spaces at the beginning or end.

If your question requests rounding, state it clearly, for example: “Submit the mean in cm, rounded to two decimal places.” Calculate that rounded answer with round(...) and put it in correct_result. For this simple template, students should submit the requested rounded value; the default numeric checker uses a small numerical tolerance.

Use data everyone can access

For a first room, put a few values directly in the challenge. Invented data are fine for a teaching puzzle: say they are invented in your comments. For real data, record their source and include any permission or licence information needed to share them.

If you need a separate data file, include it with the submission and explain how to read it. Use a relative filename such as "snails.csv" so your teacher can put the files in one folder and run the example. Include units and explain what each column represents. Small self-contained examples are easier to review and reuse.

3. Play your room

Save the script after editing. In the Console, run the following commands, using the actual name of your saved file:

source("19549_snail_room.R")
escape(player = "my_room_test", reset = TRUE, escape = my_room$id)

source() runs the saved script. The second line starts a new test game containing your one room. The room should appear on screen.

If R cannot find the script, use RStudio’s Source button with the script open, then run the escape(...) line in the Console. This avoids having to type its location.

For the unchanged snail example, try these commands in order:

submit(5)       # A wrong answer should leave the door locked.
hint()         # The first clue should appear.
hint()         # The second clue should appear.
hint()         # The final clue should help you solve the task in R.
submit(4)       # The correct answer should open the door.

For your own puzzle, choose a wrong answer and your calculated correct answer. For a word answer, use quotes, for example submit("wetland").

After another edit, save and source the file again, then repeat the test. replace = TRUE lets your newly edited definition replace your own previously registered room with the same ID. Registration lasts for the current R session; source your file again after restarting R.

If R reports an error

Check that every quoted sentence has both an opening and a closing quote.
Keep commas between the entries in new_room(...) and between hints.
Keep the closing brackets from the template.
Check that you saved the file before sourcing it.
Check the Console’s error message for the line or object to inspect.

If a sentence contains a quote, use single quotes inside the sentence, as in "The sign says 'Count the snails'.". Change one part at a time and rerun the script; it is easier to find a small mistake that way.

Ask a classmate to play the room without seeing your solution. If they cannot tell which quantity or units to submit, clarify the question before submitting.

4. Submit through Moodle

Upload your saved .R file to the coursework submission indicated by your teacher. For a self-contained room, that one file is enough. Your teacher can read the code, source the file, and play your room.

Before uploading, check:

The filename identifies you, and the comments include your name and number.
The room practises a course idea and has an ecological question with clear units.
The comments include your worked R solution and explain where the data came from.
The wrong answer fails, the correct answer works, and all three hints make sense.
You included any separate data files and instructions they need.

You can also write a short note in Moodle describing what the room teaches and anything you would like feedback on. Follow the assignment’s instructions for any additional explanation or reflection.

Optional: contribute through GitHub

If you already use GitHub and want the room considered for inclusion in the package, the contribution route is a pull request: a proposal that the maintainer can review before adding your changes.

The package’s existing room-authoring guide explains how to put rooms into a pack, add that pack to the package catalogue, and check that it works. Open it in R with:

vignette("creating-themed-escape-rooms", package = "escapeR")

Use that route when you want to prepare a package contribution. The Moodle .R file route is sufficient for submitting this coursework; your teacher can help adapt a submitted room into a package contribution later. Follow the course’s submission instructions so your contribution can be matched to you for assessment.