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

        name: a study room
        description: You're in a study room. There's a desk. That is all.
                name: Pen
                description: Just a pen...
                carryable: yes
                image: pen
        name: the kitchen
        description: It's a kitchen. There's a white marble surface.
                prob: 1.0
                description: You see some keys, you wonder what you're meant to do with them
                name: House keys
                description: Can't get trapped with those in your pocket!
                carryable: yes
                    if: true
                        - add: navigation from outside to hallway direction north
    # ... other locations here ... #
        name: the great outdoors
            prob: 1.0
                if: keys in inventory
                    - say: You have the keys
                    - say: You've locked yourself out!

        east: study
        north: kitchen
        west: bedroom
        south: outside
        west: hallway
        south: hallway
        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.

Built With

+ 6 more
Share this project: