Back to home
Escaperoom project This project is mainly a system for escaperooms. For those of you who don't know what it is: It is a room you get locked up in with a couple of people, and you search for clues and solve puzzles to escape it.
All escaperooms can have a different theme, but the principle is the same.
Another thing in common is that most have some sort of way to hand hints when it is obvious the players are stuck.
Unfortunately, there is no simple system for this, so you see awfull solutions like handing notes, spoiling the experience a bit.

Enter: this project.

The idea behind it is: it has to be a simple to use system, using mostly cheap commodity hardware and customizable for any room theme.

Unfortunately, only the project is stated here, but no code download. It is entirely developed in a running environment: Mysteryhouse in Valkenburg, the Netherlands.
That way, the project is based on what is needed in real life, not based on theoretical ideas.

The whole package is available for a one-time fee for any escaperoom operator that is interested after reading this post.
please contact Mysteryhouse at:
There you can also request an online demo to evaluate the system.
Project points The points for this project are:
Also in mind are extensions to send other devices like IOT devices signals, but these are not included in the this version of the project. Mainly because it's not clear on what devices will be used.
Once this becomes clear, i will add it to this project page.
The solution to the problem Based on the above, i came up with this solution, it ticks all the boxes and more.
The entire project consists of 5 parts:
The basic system idea is easily explained in a picture:

As is visible, it all runs on a network using standard TCP/IP protocols. This can be expanded to have the hint systems run on a seperate segment from the controllers, but for a basic system this will do.
How to design and set up the network is far beyond the scope of this project but keep in mind that it is by far preferred to use a wired (UTP) network as opposed to wireless networking.
It is best to keep this network just for the hint system so nothing can disrupt the signalling etc. during gameplay! Even an internet connection is not needed.

To keep things simple, absolutely no extra software is installed on the hint and control systems other than a webbrowser! Any up-to-date version supports html5, css and javascripting, so it shouldn't be a problem even using a pad or phone..

On the network, the server dicates the time and when any room started, etc.
In case of any doubt, the rule "the server is always right" is used.
All the hint and control systems are constantly updating their timer etc. In this way, no system will not be more than 2 seconds off from the server time, usually less after some time.

System responses are also within 2 seconds after sending a message to a system which is good enough for the system.
What can it do? An overview of what the system can do:

Well, almost... the biggest limitation will be the server.
You will need storage space for your themes, images, sounds and videos on the server. Also the performance will eventually be an issue with a large setup.
Other than that, there's no real limitation on how big your setup can get.
Server The server will handle all the actions etc. to the controller(s) and hint systems. It is possible to run both on one machine, but it is preferable to have the server running on a solid piece of hardware with good disks in a RAID configuration.
This is the most expensive part of the entire system, but it is well worth investing in because if this fails, the entire system fails.
While at it, it is also good to have a UPS for the server, so any power outages will result in the server shutting down in a controlled fashion instead of simply crashing.

If you have it, you can run the server in a vmware, xen or any other virtual server environment, eliminating a lot of considerations for the server because this is already done when setting up the hypervisor.

It is possible to run the system online on a server in a datacenter, but this would make the system dependent on wether or not the internet connection works and is fast enough. It's better not do so so and run a server yourself on-site.

The resources you will need at the least is around 4GB of RAM, 50GB of storage (mainly for operating system and the images, sounds and videos you store on it, the software itself is only 2MB) and at least one network card capable of 1Gbit/sec
If you get a recent server from somewhere (or buy a new one), it's a multicore CPU and will keep up with a lot of rooms and screens.
If it is an older system, make sure you test things thouroughly before using it in a live environment.

The operating system selection is not critical. Development is done on FreeBSD, but linux and windows will do just fine also. As long as the needed services and modules are available on it, it will work.
I can recommend FreeBSD or linux, since they are available at no cost.

Once the operating system is up and running, a couple of things have to be installed on it: All of the mentioned software is free and setting them up is well documented allover the internet so i won't repeat this here.
The configuration of apache is also a basic vhost setup, so no surprises there either except that you have to make sure you enable either the cgi_module or the cgid_module in httpd.conf.
In some apache distributions this is disabled by default, so check your configuration!

Hint systems As stated, the hint systems should be cheap and easily available. Which they can be.

All hint systems need only one thing to work: an up-to-date webbrowser and a screen.

So any operating system will do (FreeBSD,linux, windows, mac), as long as it can run a browser full-screen that can handle html 5, css and javascripts.
If you would like to send sounds also, it needs a soundcard attached to some speakers.

Other than that, the system should: It sometimes takes a bit of trial and error to get the system to work like it should, but it shouldn't be hard to figure things out.

The home screen URL for the browser can be either one of:
1 - the direct url for the screen. This way, the screen will start up and immediately get the correct theme etc.
2 - a general url in which the screen identifies itself, receives the correct url from the server and will redirect to that theme etc.

Option 1 is mainly for any system that you know will only use that particular theme in a room. It allows for faster startup of your system.
This url is visible in the controller screen after you have added a screen in the room. You can copy it and set it as the home screen for the browser.
Using this setup, it is not possible for the server to send WOL or shutdown commands to the system.

Option 2 is for the spare system you might have or when you want your screens to get WOL and shutdown commands.
The URL will identify the hint system to the server. Once it is registered you can assign a screen to that system.
This URL is set in the home screen settings of the browser.
Because the screen is registered and identified, it is possible also to send it a wakeup command when you reset a room and shutdown all screens in a room when you click that function in the controller screen.

On linux and freebsd it is even possible to set things up so that after startup it will automatically send the correct information to the server, thereby registering it and receiving the correct homescreen for the browser.
This can then be set up in the browser after which the X system and the browser is started using the correct screen url.

If you employ only option 2 on all hint systems, any system can be used in any room simply by changing the assigned screen to it. This also saves on spare hint systems, you will only need 1 or 2 on the shelf!
Control station The control station can be any system you prefer, up to and including a pad or even phone. All that's needed is a recent browser supporting HTML5, css and javascript.
No extra add-ons are needed in the browser at all!
You can use your regular office pc for this, but is is preferred to have a dedicated system for it in your control room.
Software Last but not least: the software that runs the system.
It handles everything needed for the hintsystem, communicates with everything and keeps track of the time etc.
For the hint systems, it will send the correct screen template etc.
For the controller stations it will present the page to setup, maintain and control the system and run the hint systems.

The layout is kept pretty simple because (for one), there is no need to have flashy screens and buttons. Besides, i am a tech-guy, not a designer and a fan of the KISS principle.
Once the software is installed, you are free to change things as you like.

Themes As mentioned before, each hint screen can have it's own theme. A theme is simply a folder with a template and folders holding files.
Creating a theme is simple. All that is needed is a folder in the themes folder where you store a file theme.tpl in.
As an example, an simple template that will work with tekst, sound, image and video hints, having the hint tekst show at the top and the countdown time at the bottom:
<!DOCTYPE html>
<title>black video screen
<div id="wrapper">
	<div id="contentwrap">
		<div id="tipvak"><div id="tiptekst">Welcome to this escape room!</div></div>
		<div id="imagelayer">{$corehintimage}</div>
		<div id="tijdvak"><div id="roomtime"></div></div>
		<div id="logovak"><civ id="logo">Escape<br>Room</div></div>
Note some things in this template:

Adding your own files is easy and you will not have to change the template file even!
There are special folders in the template folder, used for different tings:
Folder namePurpose
jsStore all your javascripts in this folder
cssStore all your css files in this folder
imagesStore all your images in this folder. Supported formats: jpg and png
images/tipsA subfolder in the images folder. Any images in this folder will show up as hint image in the system
soundsStore all your hint sounds in this folder. Supported format: mp3
videoStore all your hint videos in this folder. Supported format: mp4
The system will automatically pick up all the allowed files in these folders and insert the correct links to it in the template.

Ontop of these files, the system will always add the files in the default theme in all rooms. So if you have a particular sound you would always want available, just store it in the sounds folder in the default theme folder.
This is in fact where the css comes from that makes the above example work!

To be able to link to images for your template (like a background image etc.), you can get the correct url to it by using the available directives in the template:
{$httpbase}The absolute base url for the system
{$themepath}The absolute url to the theme folder
{$themedefault}The absolute url to the default theme folder
Obtaining the software/licensing Because of the time and effort that went into the system i decided to ask for a small fee for the software of 200 euro.
You can however play with it online before deciding it's worth the money. Please contact me if you would like to have a testdrive!

You buy the software as-is at the time you buy it and you can use it for as long as you need. You are allowed to run it on one live server/system with an installation on a backup system.
There is no licensing checking, call-home system, timed options or any of it. I trust everybody's fairness to use the software within reason and not make copies for everybody, supporting me a little by having other people also pay the fee so i can continue improving and expanding this system.

If you would like additions or changes to the software done, please contact me about it. I do like a challenge every now and then!
Also, if you need help setting things up at your site contact me about it.