An Org-Mode based text adventure game for learning the basics of Emacs, inside Emacs, written in Emacs Lisp

Chung-hong Chan (he/his/him, er/sein/ihn/ihm, 佢/他)

Format: 6-min talk; Q&A: Etherpad
Status: All done

00:00.000 Introduction 01:01.200 Demo 03:33.360 emi-escape-12 04:47.040 The rest of the game

Duration: 05:58 minutes


I am experimenting with using org-mode as a HyperCard-like text adventure game engine. In this talk, I am going to demonstrate a text adventure game for learning the basics of Emacs. Through solving puzzles and programming your companion robot, Emi, you will learn how to use the built-in Emacs help system, the mechanic of emacs customization and the basics of programming Emacs Lisp. I believe this game is ideal as a light-hearted complement to the C-h t tutorial.

About the speaker:

Dr Chung-hong Chan is a senior researcher at GESIS Leibniz Institute for the Social Sciences, Germany.


  • Q: Maybe the Emacs tutorial could be adapted to this game flow?
    • A: Unfortunately, that would be quite difficult. The Emacs tutorial is more about the basics (cursor movement, buffer management etc). And those bits are quite difficult to demo in the current text adventure format. I think a game format like vim-adventuresvim-adventures would be better.
  • Q: What was something that you learned about Org-Mode/Emacs in working on this tutorial?
    • A: ~(eval (car (read-from-string string)))~
  • Q: Could you please elaborate what's the background of this game? What's the motivation why you choose this game as introduction for a newbie ton enter the Emacs world?
    • A: The background of this game is a bit silly. It’s actually my wife wanted to create a (general) video game last year and I told her I can create a puzzle game as well. I have no experience in programming any video game, but I enjoy playing niche video games such as Tetris and TIS-100. I have tried to create educational material for R programmers to learn emacs, e.g. this and this. Actually, the game presented so far is covering the same material of the latter tutorial. But I don’t think the written tutorial is as effective as this game. There are so many introductory emacs tutorials. C-h t, for example, is quite good. If the path to emacs is from 0 to 100, those tutorials are good for going from 0 to maybe 20. It is nice to get the feet wet. I think that the gateway to really enjoy emacs, i.e. beyond 20, is to customize emacs so that emacs becomes your own tool. However, there is a huge perceived knowledge barrier of “learning emacs lisp” and “learning emacs internal”. From my own experience, the trick is stop “learning” (from an educational perspective, one can’t learn something for the sake of learning something.), but to “do.” The best way to immediately do something, is to play a game.
  • Q: Thank you for the talk! Really cool project! How many planes are you planning to make and what more will you teach the players? + Q: Do you have an end goal for this game? That is, what information do you want it to cover or will it be never ending?
    • A: I am going to answer both questions jointly. The plan is to at least allow the users to write a 10-LOC function in emacs lisp.
  • Q: What is plane? Is that something like a question set in the game?
    • A: I am not a D&D player. But my wife told me a Plane) is one parallel universe. But you are right, one Plane in this game is basically one question set, or one puzzle.
  • Q: Is it for programmers? Non-programmers? Or general?
    • A: I really hope that this is for everyone. But given the emacs userbase is like 90% programmers, I don’t mind this game is geared towards the programmer type wanting to “go beyond 20”
  • Q: What is the link to your GitHub repository?
  • Q: Is (find-file org-file-name)  [skip-to-plane] a effective way to load information from your org-files? 
    • A: Probably not. The original idea was to have one giant org file and jump between headlines. But the current approach is easier to implement.
  • I love this idea of using emacs to teach emacs! It is a good continuation of C-h t. The adventure should not replace C-h t but be its next step after finishing C-h t. Good job!
  • Q: i am wondering what is the naming scheme of the planes, since there are large spaces between the numbering which i guess could be like how you leave space in between basic lines?
    • A:
  • with how simple the system seems it would be interesting if people forked it and add their own tutorials for their projects
  • neat idea for learning about emacs!
  • that was actually my first thought - it is good template for tutorial of complicated custom functions.
  • Yeah, that sounds pretty interesting as an idea
  • I mean, it is beautiful presentation of fun hacking, but I don't see it as real text adventure... But great intro and wish you good luck with it.
  • so good thank you i will check this game out
  • interesting idea
  • i will definitely keep this game in mind since i have mostly just started my emacs journey


[00:00:00.000] Introduction

Hi, I'm going to give you a little demo of a project that I'm working on which is called the orgdungeon. As you can see here, they are just a bunch of Org files and also an Emacs Lisp file. What I found is that if you have these Org files and then you have an Emacs Lisp file as a source to control how to progress from one file to another, it will give you a game-like experience. It's like the old game Myst. It was developed with the technology HyperCard for the Macintosh. Basically, it uses a similar technology, so a similar interface to the developer who was using that technology to develop the game.

[00:01:01.200] Demo

Concretely, I'm going to give you a demo of how the game looks like. So, this is a very vanilla Emacs setup. Then I open up the first Org file. The Org file is just a bunch of text, but it tells you a story. So you wake up somewhere, and then there is a dog-like robot called Emi around you. And then it tells you what you should do. Following the instructions... For example, here it tells you down there is one thing called "code block," and then you can evaluate it by pressing C-c C-c. Then we can just go there and then just evaluate the code block. So technically it just runs the Emacs Lisp file, because you can see here, if you load Emacs Lisp... It just evaluates that Emacs Lisp file. I can just say C-c C-c. Then for this one, I just say yes, and then it will jump to another file. But in the game, I call it the plane. So it jumps to another plane. Yeah, so... In the other one, it's just saying that there is a function called emi-escape-10. Assuming that you don't have any experience how to use Emacs, so you have no idea how to do that, but down there, it's saying that there is a key combination called C-h f, and it will bring up the help system. Then you can read the help file of emi-escape-10. So you can just do that. For example, C-h f and then describe-function emi-escape-10 here. It will show you the help file. Then it's just saying that you can press M-x, and Meta usually mapped to Alt, and then yeah. Then you can just close this help file using C-x 1. I'm just going to do that. And then yeah... I'm just try that. M-x and then emi-escape-10. All right.

[00:03:33.360] emi-escape-12

So I will jump to another file. Or in the game, you jump to another plane. And now you know that there is a function called emi-escape-12. And yeah, you can just do that emi, because you learned it previously, right. emi-escape-12. But this time, it asks you for a password, which you probably don't know, right? If you just type in anything, it will just say incorrect password. But yeah, it's part of the learning experience because previously you learned that you should use the help file, help system to read the help file of a function, so you can just use the help file to look for the help of emi-escape-12. Then, yeah, the help file will say that you should enter a password, and the password is emi. Right. So you can just do that. Write emi-escape-12, and then now you know the password is emi. Right.

[00:04:47.040] The rest of the game

So you can progress along these different files, and then if you... Okay, it's like a game, but at the same time, it also teaches you something about how Emacs works. For example, like the previous one, you know how to use the help file, for example, but in the later part, you will learn how to evaluate some Emacs Lisp code and also how to write some Emacs Lisp code as well, and then you will learn the difference between interactive commands and also just ordinary functions, for example. Now, I just created a few Org files, but I'm actively adding more Org files so that we can have a complete kind of educational experience. If you want to follow along [with] this project, you can just go to my Github repository. I hope you enjoyed this little demo. Thank you.

Captioner: sachac

Questions or comments? Please e-mail