topiary

Topiary is a dialogue scripting tool which uses the Topi language to write interactive stories. It is designed to be integrated into video games which require a large amount of state and control flow in their dialogue.

Think of Topiary as programming a screenplay for your video game.

It is written in Zig.

Usage

The CLI tool is a very simple runner that can be used as a starting point. It will compile a file, and run your story in the terminal. It is recommended to start there to see how you can use topiary in your projects.

To run the CLI:

zig build // or download from release page
./zig-out/bin/topi run ./examples/hello.topi

You can then press enter for the next line, and select a choice with 0-9 then enter

Writing in Topi

You can view a full breakdown in the syntax file, the CLI reference, tips & tricks for writing patterns, and examples in the example folder.

Here you can see what writing in topi looks like

=== START {
    :User: "How does this work?"
    :Author: "You write your dialogue like this, then you can use the compiler and virtual matchine to run it in game."
    fork TOPIC {
        ~ "What does the compiler do?" {
            :Author: "The compiler will take your source code and convert it into bytecode."
            :Author: "With that you can either pass it directly to the virtual machine, or serialize it to save to a file."
            => TOPIC
        }
        ~ "What does the virtual machine do?" {
            :Author: "The virtual machine will take the bytecode and a runner and process each line of code, dialogue, and choices."
            :Author: "The runner has two functions, onLine, and onChoice. Which will be called and used to call your game code."
            => TOPIC
        }
        ~ "Okay, thanks." :Author: "Let me know in the issues if you have any questions!"
    }
}

Future

Topiary is in early development and still has a long way to go. Please check the Issues tab on the repo to see features I'd like to implement.

Credits

First off this project never would have been attempted without first being inspired by Ink and Yarn Spinner.

Secondly writing my own language would have never been attempted without the wonderfully written books on Crafting Interpreters by Robert Nystrom and Writing an Interpreter/Complier in Go by Thorsten Ball.

Lastly when I started on this project I was fairly new to Zig, so I have to thank two other projects Luf, and LoLa both of which are credited in the Licence since their parsers were used as inspiration when starting out.

Contributing

Download and install Zig. Currently Topiary uses version 0.17.0

git clone https://github.com/peartreegames/topiary
cd topiary
zig build

I'm confident there are many areas of improvement so please feel free to submit pull requests. This is my first time writing a compiler, and I'm definitely don't understand everything.