Choose Your Own Adventure Engine

While tutoring someone in Java, I put together a simple little Choose Your Own Adventure tool for them to play with, which allowed you to define your own CYOA story and play through it via the command prompt. Afterwards I decided I wanted to make a graphical interface to improve the gameplay and ability to follow the story, so I worked on making a GUI version, and also a better way to create stories.

The result is this CYOA Engine, which lets you load stories you write and play through them like a classic CYOA book. It's a pretty lightweight utility which I churned out in just a few hours, but it's kinda fun and I'll add more stories if I get a chance.

Writing Stories

Out of the box this only comes with two stories, neither of which are very entertaining, so the whole idea here is to be writing your own stories, which is a fairly straightforward process. The stories are CSV (comma separated) text files, (with the exception of the first two) each line is an event in the plot, and consists of the following parts:

  • A word to identify the event (like 'storyStart' or 'monster')
  • A brief text which will be the choice the player sees
  • A longer text, which is the plot continuing, and is displayed when the user selects this choice
  • A space separated list of events the player can chose from from this pont.

The first line is the title of the story, which is displayed in the list of stories on the left, this is followed by a blank line. The choices can be in any order you find easiest to organize by, however the first event in the list is what starts the story off.

You can have cycles (sets of choices that go in a circle) and multiple different events can share choices. An event with no choices marks the end of the story.

If you write a story that you'd like to share, send it to me and I'll include it in the release, with credit of course!


I originally made this (the command line version anyways) as an example application for someone I was tutoring. In the course of making this relatively simple application I realized I was integrating quite a lot of key Java / Programming concepts from basic I/O to Object Oriented Programming in a short and intuitive but complex program. I'm releasing the source code primarily in the hope that someone else may be able to use this as well to teach these key concepts with an application that is more interesting than, say, a bank simulation, and likely to click with lots of people of all ages.

Additionally, the end result of this project is a program which can help kids write stories - they provide the creative energy, and the CYOA Engine provides the nuts and bolts to bring their stories together. While the structure of the story files is not easy, it is fairly straightforward, and I imagine kids could pick it up quite well with a little guidance. If any teachers find this program and it appeals to them at all, I'd be more than happy to help you and your students use it.


Launch: CYOA Engine
Launches Java Web Start

Download: Example Stories
Size: 1.29kb

Download: Source Code
Size: 20.5kb