AdvLang: the Adventure Simulation Language
We want to be able to write immersive interactive stories easily, without the hassle of complex game logic, or dealing with I/O.
What it does
AdvLang allows users to describe a set of locations, objects, and events and how they are connected, in a simple format. We parse the input and execute a text-based adventure game based on the specification.
Here's an example input:
start: study locations: study: name: a study room description: You're in a study room. There's a desk. That is all. objects: pen: name: Pen description: Just a pen... carryable: yes image: pen kitchen: name: the kitchen description: It's a kitchen. There's a white marble surface. events: seekeys: prob: 1.0 description: You see some keys, you wonder what you're meant to do with them objects: keys: name: House keys description: Can't get trapped with those in your pocket! carryable: yes conditional: if: true then: - add: navigation from outside to hallway direction north else: # ... other locations here ... # outside: name: the great outdoors description: events: prob: 1.0 description: conditional: if: keys in inventory then: - say: You have the keys else: - say: You've locked yourself out! navigation: hallway: east: study north: kitchen west: bedroom south: outside study: west: hallway kitchen: south: hallway bedroom: east: hallway
How we built it
There are three main parts to our implementation:
- Firstly, we parse the AdvLang input. We use this to create a tree to represent the logic adventure game.
- Secondly, we have the main game loop, which works out what options you have at any point in the game, based on the game tree. For example, we work out where you can move, what objects you can see and/or pick up, and what events should occur automatically.
- Finally, we print these options to the screen, and allow the user to choose. AdvLang games can run in any standard terminal. We developed our interface using curses, and wrote our menu implementation from scratch, which was way more difficult than it really should have been. I'll take a web-interface over curses any day! :P
Challenges we ran into
We had our fair share of challenges on this project:
- Deciding on our idea, and what features we should support took over five hours of our most productive time. We initially tried to implement way too many features, and didn't really get anywhere for a long time. We finally decided on a minimum viable product of having locations, and ways to move between them. This was fairly simple to code and we moved on from there.
- Originally, we used JSON as the base of AdvLang but we quickly realised JSON syntax was not really great for what we were trying to achieve. After trying several different approaches, parser generators, and our own recursive descent parsers, we finally settled on our current approach, which we think maximises simplicity and readability.
- Getting curses to do the "right" thing was a pretty long process. We originally had the user type in their choices, like a proper adventure game, but decided that offering a menu of choices would improve the experience. Little did we realise how much work there'd be to get a menu working inside a terminal!
Accomplishments that we're proud of
We're super proud to have a working engine! There's only two of us, and there were several times when we very close to giving up, especially early on when we had ~3 lines of code after a good 6 hours! :P
Now, we have implemented pretty much everything you need to write a standard text-based adventure game.
What we learned
KISS - "keep it simple, stupid". We really were way too ambitious at the beginning. Once we started working on our "minimum viable product", we started making progress really quickly. From there, it was much easier to extend our project to include the majority of features that we originally hoped for.
What's next for AdvLang
We're actually planning to continue work on this after the hackathon. Firstly, we're really close to adding ASCII art and centering the output to make the interface nicer. We're also planning to create a proper (web-based) GUI for writing and playing adventures, to make it even easier for beginners to get started with AdvLang. Eventually, we'd really like to implement a multiplayer mode.