Text-engine, a free tool for making Interactive Fiction

Hi, all! :wave: I’m new here. I joined because I wanted to tell you about a project I’ve been working on on-and-off for the last four years.

It’s called text-engine, and like the other amazing tools on this forum, it’s designed to help you make IF (in this case, classic-style text adventure games). Similar to Sadako and ISHML, it’s made using web technologies.

I just released a new version of my engine with a bunch of new features, and I’d love if folks who are interested would check out the demo (link below) and let me know their thoughts. If anyone is interested in making something with the tool, I’m also happy to assist in any way I can!

I’ve worked very hard on this, and I’d like nothing more than to see it used! And if you have ideas about ways it could be improved, I’m all ears.

You can also find the source code and documentation on Github: https://github.com/okaybenji/text-engine

Thanks very much for taking the time to give this a read.



What would you say are the advantages of Text-engine over other systems?

FYI, it doesn’t layout well on mobile.


Hi Dan, thanks for the response!

It’s true, the itch page works best on a desktop computer. If you are on mobile, please try this demo instead: http://benjikay.com/text-engine/

The engine code itself doesn’t actually care what your interface looks like. You can style it however you want with CSS. So if mobile-first is your goal, that would be the way to work toward it.

I can’t speak to advantages versus non-JavaScript-based tools, since JavaScript is my primary programming language. When I set out to make a text game, I looked at other JS options, and then built this tool to meet my needs.

In my opinion, some of its strengths are:

  • Games are just JSON objects; JSON is one of the most popular data formats in the world, and happens to be my favorite
  • Simple exploration games can be made without any programming
  • The scripting language is JavaScript, the most popular programming language in the world; this makes it easy to find help online, and the developer can leverage virtually limitless libraries available for instance on Github and NPM
  • You can style your game any way you like using CSS
  • The engine is highly customizable – you can use or not use virtually any part of it you like; you can, for instance, add custom commands and remove built in commands

I like the aesthetics, but it would make playing easier if it understood the standard command abbreviations:

  • L for LOOK
  • X for LOOK AT
  • I for INV(ENTORY)
  • NORTH/SOUTH/EAST/WEST and N/S/E/W for GO <direction>
  • GET as a synonym for TAKE
  • (sometimes T for TALK TO)
  • (RESTORE as a synonym for LOAD)

Also UNDO would be a useful addition.


Hi Juhana,

Thanks for the response! I appreciate this feedback. The shortcuts for GO already existed, but I went ahead and added the rest of these as well! Except for UNDO, I’ll have to think a bit more about that…

@Juhana a question for you: in your experience, do UNDO commands typically allow you to undo multiple inputs, or just the last input? Would you find a single undo step useful, or would you strongly prefer unlimited undo?

I believe it’s common to have a fixed number of undo’s, 20 or so. Less, and the player may get frustrated; more, and it starts taking up too much memory.

1 Like

“x self” returns “Wow, ten cents.” Am I playing as a dime?
And it’s not JSON if it has JS functions in it, not really.

Games aren’t just JSON, right? It’s JSON with JS mixed in, which is to say, if you’re going to write a game in Text-engine, especially if you’re going to include a way to “win” the game, you’ll have to write some JS, right?

Who would you say is the target audience for this? Are you aiming for authors who don’t know JS, or at authors who know JS and want to write IF in a language with which they’re familiar? Authors who know JS tend not to use other people’s engines… instead, they write their own engine, like you did.

On the other hand, learning JS (and how to debug JS written atop someone else’s library) is a pretty steep climb for authors with no coding experience. You’d want/need your documentation to include a JS tutorial, focusing on the subset of JS that the author would need to write useful code in Text-engine, something wayyy more detailed than what you’ve got right now. (“Just pass a reference to your disk to the loadDisk function” is meaningless to someone with no coding experience.)

Either way, I suggest that your next step be to write an “admirable” game in Text-engine. Most people choose an IF platform by playing a great game and saying, “I really like this game, and I would like to make another game just like it. How did the author(s) make it?”

So, when IF platforms successfully take off, they require an admirable story (not just a technology demo) to attract new authors. Historically, the first “admirable” story for each now-successful IF platform was typically either written by the platform authors themselves, or directly funded by them. (Twine’s first admirable story by Anna Anthropy is the only exception I’m aware of.) Admirers don’t seem to directly care about any of the details of the system, except that if it’s too hard for them to learn the system and finish a game, that’s a major factor in achieving true popularity.

I think you’ll either need to write something great or hire a great writer (preferably paid in advance) to launch your platform effectively.

All in all, Text-engine looks like a lot of fun to work with, and I believe you can build the community you want to build if you’re willing to put in the work/money required to write a great game.

P.S. It appears that Text-engine doesn’t work well with screen reader tools like iOS VoiceOver and macOS VoiceOver. It can read the text fine, (except for ASCII art, naturally,) but when you enter a command, a page full of text appears without being announced. You then have to laboriously navigate back up to your previous command and then continue reading the text from there.

I believe you’d want to address this by adding aria-live=polite to the <div id=output> element.


Thanks again for your feedback!

Just like everything else in the engine, this is designed to be flexible. A disk can include JavaScript, or not. JavaScript is not required to make a winnable game. The description of the final room of your game can say “You win,” for instance. Someone has already made a very nice game with text-engine that uses no JavaScript. And FWIW, IMO a game doesn’t need to have a win state.

My target audience is whoever finds the tool useful. I believe the Inform 7 manual says something like “writers who are interesting in programming, and programmers who are interested in writing”. That’s who I would imagine would use a tool like this. I’m personally also interested in collaborating with writers to help them make games.

Perhaps you have a point in that I should move that to a different section of the documentation. This is not a required step for making a game with text-engine, as the source code already does this for you.

I think it would be silly to try to write JavaScript tutorials in my own documentation. There are numerous great places interested folks can learn to write JavaScript already if they are interested. Again, it’s the most popular language in the world, and it is a C-like language. I would guess most folks looking at a repository on Github have at least some experience writing or at least reading JavaScript or similar code.

Well, okay, I’m working on this!

I don’t think it makes sense to hire a writer. This is a free tool I work on in my free time. It’s also open source. I have no designs on making money with it. My interest is only personal. Having spent a lot of time on it, I just want to be sure as many people as possible who might have interest in using it to help them make games are aware it exists, and that they know if they need help with it or have requests for features, I’m here to help.

And maybe it turns out not that many are interested. Well, I had to give it a try.

I appreciate this perspective, and I’m glad to hear you think it looks fun to work with!

Thanks so much, this is really useful feedback. I think there’s a tag I can add to the img class (ASCII art) to be sure screen readers ignore it as well…

x self returns “You don’t see any such thing.” If you can figure out steps to reproduce the issue you say you saw, let me know.

Not super interested in arguing about what is and isn’t JSON.

Okay, it’s x me. The x self command is just broken. Also cute bugs:

  • you can type take me and the game will take the dime (also USE me etc., everything redirects to the dime)
  • > look monstera
    You look monstera.
  • ITEMS returns tall window, but x tall window does not work
  • there’s no verbose mode, if you go north then south you see a blank room

This was one point I forgot to address. Are you speaking about text adventure engines specifically? Or engines broadly?

I’ve been a full-time developer working mostly with JavaScript for the last 8 or so years, and a full-time game developer (again, mostly JavaScript) for 5 years. I’m also a co-organizer of a game development usergroup, and a member of a JS usergroup.

I can say from experience, JS developers tend not to set out to build a game engine each time they start work on a new game. Speaking about not just engines, but tools in general: we first look to see if the specific problem we are trying to solve has already been solved. As I mentioned before, there is a vast library of free and open source software at our disposal. The company I work for has published games made with different engines, but we’ve never bothered to try to build one ourselves. And when I set out to make my own text adventure, the first thing I did was research what already existed for making text adventures with JavaScript. What I found was not flexible enough for my needs, which is one reason text-engine is designed to be very flexible and modular.

An unrelated thing I wanted to say: I hope you will try building something with the engine! If it looks fun to work with, please give it a go when you have some time. I’m sure if you do, you’ll have some great ideas about ways it could be made even more flexible and easy to work with.

Thanks again for your feedback.

None of the things you mention are bugs.

Edit: Except for “x tall window” not working, that is now fixed.

I think you’ll find that it’ll be easier to get critical mass if you pick a target audience to start with.

Well, a complete JS tutorial certainly wouldn’t make sense, but you’ll find that it’s easier to recruit coding newbies if you don’t tell them “Learn JavaScript first and then come back and use Text-engine.” A basic one-page intro to JS probably would make sense, if newbies are your target audience, and you’d want to recruit a few coding newbies to engage with your documentation to see if they can make sense of it. (It’s not uncommon for coding newbies not to know how to type curly brackets. {})

Of course, if your target audience is “people who already know JS,” then catering to coding newbies would indeed be extremely silly. But that brings me to the other problem, that people who know JS just write their own engine.

Text adventure engines specifically.

It’s not uncommon for IF enthusiasts to present this forum with alternate IF authoring systems in which authors can develop IF with a “real” programming language, typically one of the top 20 languages on the TIOBE index, or at least a language that ranks highly on StackOverflow’s “most loved languages” list.

But these authoring systems never seem to gain traction. None of the most popular parser-IF systems require authors to use a “real” programming language. All of the most popular systems use a domain-specific language for IF.

Why is the IF community so enamored of DSLs? This isn’t like other parts of the game industry. In the game industry in general, even if people do decide to implement their own engine from time to time, the most popular game engines use popular general-purpose programming languages, the same languages everybody else uses. The IF community must be full of weirdos, right?

Well, yes, but we’re not the only weird ones. Consider querying a database. You could do it in C or in JS, and some people do, but the industry has discovered that using a declarative query language is better, and SQL is by far the most popular language for doing it, despite the fact that SQL doesn’t have much in the way of step-wise debugging support. If you’re querying a database, trust me, you should just use SQL. (At a minimum, you should learn SQL before attempting to query a database in another language.)

Text adventures aren’t like other programs that run step by step from beginning to end; they’re programs to cooperatively generate text, incorporating commands from the player while subtly guiding the player how to use the correct commands to win. Coding a parser-based text adventure is mostly about declaring data (what are the rooms and objects in the game) and a rules engine of events that fire when certain conditions occur.

And, of course, that’s what you see in Text-engine. Text-engine’s “JSON” includes backtick template strings, event-handler functions. But the rules in full-blown text adventures typically aren’t like onLook handlers. They’re more like, “when the dragon is asleep and the player has brought the princess to the same room with the dragon and the princess has her wakizashi or one of the following five weapons…”

The general industry wisdom when it comes to rules engines is that they all kinda suck. It’s easy to get started rolling your own rules engine, but it’s hard to write a good one, so everybody just rolls their own. And this is another area where DSLs often do thrive. (The article I linked above is by Martin Fowler, who concludes, “there’s a lot to be said for avoiding rules engine products.”)

Then, when you add in the fact that most IF authors see themselves as writers first and coders second (if at all), you start to see why a community has formed around DSLs for text-adventure rule engines, and why good programmers keep writing their own IF-rules engines rather than use anybody else’s.

Consider also that a lot of folks appreciate IF due to nostalgia for retro hardware. (I note that you’ve styled your Text-engine demo to look and feel like a machine from the 1980s.) A lot of people who enjoy that sort of thing tend to want their games to actually run on old hardware, or at least run on emulators for old hardware.

You’re not gonna run JavaScript on an Apple IIe. You’re not gonna run Python, there, either. But you absolutely can write Z-machine code today in Inform that works on Apple II out-of-the-box.

I suppose you could write JS that transpiles to Z-machine code, but probably only a subset of JS, at which point what you have is a JS-like DSL.

I’m telling you all this not to be discouraging. I think the world could be a better place with a popular IF engine oriented around a general-purpose programming language, and especially if someone were to implement a rules engine for JS that people love, not just for IF, but for all sorts of rules-engine shaped problems.

The path up this mountain is littered with the frozen corpses of others who have tried and failed to reach the top, but I hope somebody manages to climb it, and I wish you the best of luck.

P.S. One more parting thought. Rather than write your own admirable IF from scratch, you might find it productive to port an existing IF game into Text-engine. Emily Short’s Bronze is available under Creative Commons. Porting it to Text-engine would probably be a valuable exercise.


Thanks once again! I really appreciate your thoughtful feedback. I will think about what you’ve said here.

I can’t help but push back a little at the assertion that SQL is the best way to query a database. I used SQL professionally for two and a half years before really getting into the JavaScript world. No JS developer I know uses SQL. Most of us use Mongo. The query language? It’s basically JSON (technically BSON).

This is wayyy off topic now, but IMO the industry consensus is that Mongo has been outmatched by other key-value document DBs, especially DynamoDB.

But also, joins. Joins are really, really nice. You can use Postgres as a pretty solid key-value document DB, but if you want a join, you can just do a join.

:sweat_smile: Indeed

To argue the other side of this: plenty of authors choose Twine because you can write an interactive story without programming and then get sucked into learning a bit of JavaScript when they want to extend what Twine can do. They seem none the worse the wear for it. So, I don’t buy into the idea that authors run away from programming. They’ll do it if the effort/reward ratio is favorable. @okaybenji, I would encourage providing plenty of coding examples in your documentation that people can steal.

While JavaScript can be fairly sophisticated, especially the new features added to ES6, it’s not that difficult to be a copy and paste script kiddie to add a little bit of extra functionality to the world declaration.

For folks who already know a high level language, learning a dedicated DSL, no matter how well constructed, can feel like a waste of time. It’s not like you’re going to have a skill you can go apply in the real world. I know when I looked at TADS, which also has curly braces, my first reaction was that learning it would be as much effort as properly relearning JavaScript and that my time would be better spent doing that. Inform 7 is a truly beautiful language and a great achievement, but again it’s not a skill that transfers outside of Interactive Fiction.

So, I think JavaScript frameworks, engines, APIs, etc. for IF are valuable and of interest. Most JavaScript programmers start their projects by looking for a framework to save them time and jumpstart their projects. If people keep making IF frameworks, perhaps it’s because no one has really cracked the nut and made one that is truly flexible, simple, and deep. That doesn’t mean it’s not possible.

It also doesn’t have to be either/or. A well designed fluent API can function like a DSL. That’s the direction I’m taking with my own project.

@okaybenji, I would say that your text engine bears at least a superficial resemblance to Adventuron. Hard questions you may want to ask yourself is how your product differs and why folks would choose your product over the more established Adventuron. Knowing the answers will help you with marketing to your target audience.

1 Like

That doesn’t seem like an argument for the other side at all: it feels like more of a sunk-cost thing to me. “Authors choose Twine because you can write an interactive story without programming” seems about right. Just as the perceived difference between free and $1 is often bigger than the difference between, say, $1 and $5, I suspect the perceived difference between “you don’t have to learn programming” and “programming isn’t that hard and you only have to learn a little bit” is a big one.

But yeah, once you suck them in, you can sneak in a surprising amount of programming on the “just learn one new little feature!” principle.

Also, the other thing that it took me forever to realize is the sheer amount of time that people have in their games. It seems pretty normal to spend 6 months to 2 years (or more) building a game. So individual authors aren’t starting new ones often. And some of them do like to experiment, but still, it might take a couple weeks or a month to really thoroughly evaluate a new system and figure out how to do all the little things that you already know how to do with your current tools (or if you can even do them at all). So asking someone to start something in your untried system vs. one that has been in use for a decade or three…for many people you’re not asking a small thing, so you need an extremely compelling argument.

And many of them don’t care about general-purpose programming: they’re just trying to make interesting stories. So arguments about ease of finding help and transferability of skills often don’t cut much ice when set against having to learn a whole new language/toolset.

Edit: also, for non-programmers, “ease of finding help” may not even be true. The number of stories I’ve heard, talking to writers these last couple years… From that perspective, it’s not “oh, there are solutions to everything out there, just do a quick search”, you’re asking them to venture into this cultural in-group where almost every posted solution leaves out many of the important bits because “everyone knows that” and you’re as likely to get yelled at and insulted because you violated some unspoken rule and asked the wrong question or asked the question in the wrong way as you are to get the help you came for.

Just my two cents, YMMV, etc.