Medusa's head from Cellini's Perseus Medusa's head from Cellini's Perseus

Enrico Colombini (Erix)

The Medusa compiler

Macchinario Esente Da Un Significativo Acronimo
(Machinery Expressly Denied Using Significant Acronyms)

What is this?

The Medusa compiler is the key part of the toolchain I built for my Locusta Temporis Italian adventure game-ebook.

It takes an interactive 'book' written as a program with a syntax similar to that used in my old Idra JavaScript framework (note: the page is in Italian) and generates a set of static hyperlinked pages that behave as the original program.

In other words, it makes it easy to generate highly interactive ebooks (or printed books, or static Web sites) from a functional description, automatically generating all needed pages and links. Technically speaking, it produces a book state machine that only uses links and does not need a runtime interpreter to 'execute' the program and keep track of variables.

The Medusa compiler output is a single hyperlinked HTML file that can be read and 'played' with any browser, with limited customization through the configuration file. Transforming the output file into a regular ebook (or PDF document, or printed book, or static Web site) is the job of the rest of the toolchain, that I am not currently publishing.

Interactive ebook authors could be interested in reading my booklet Interactive fiction & ebooks that contains some theory and a list of useful patterns to give as much freedom as possible to the reader while keeping the number of pages under control. It complements the Medusa compiler.

Some notes about the theory behind the Medusa compiler and about its workings can be found in the slides from my talk at the Lua workshop 2014 (Moscow).

From a program to a set of hyperliked pages

A word of warning

Alert sign

I designed this program for my own use and it served me well. However, it has no error handling to speak of and no documentation apart from the samples, a few notes in the source code and the slides mentioned above.

I agree this is not a good thing. I do not usually publish code in this user-unfriendly state. I made an exception here because people asked me to, both from the Interactive fiction and the Lua language communities.

Should enough people wish for it, some documentation could magically appear. Small adventure games and/or other demos could appear too, but I am not promising anything.


The Medusa compiler is written in the wonderful 'little big language' Lua and is system-independent. I tested it under under Windows, Linux and OS X.

Lua language logo

You need a Lua 5.2 (or later) interpreter to run the compiler. You can get it here (just download the executables).
See the readme-medusa.txt file in the distribution package and the readme-samples.txt in the samples folder for details.

As I said, this is not user-friendly software. A minimum of familiarity with the command line is expected.



The Medusa compiler by Enrico Colombini is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.


The Medusa compiler, version 1.5 for all systems, including two tiny samples (17 KB).


  Updated 03/01/19 by Enrico Colombini (