https://github.com/peartreegames/topiary
Dialogue Scripting Language
https://github.com/peartreegames/topiary
dialogue narrative narrative-design narrative-game scripting-games scripting-language video-game video-game-development
Last synced: about 2 months ago
JSON representation
Dialogue Scripting Language
- Host: GitHub
- URL: https://github.com/peartreegames/topiary
- Owner: peartreegames
- License: mit
- Created: 2023-02-19T02:18:47.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-01-10T17:08:39.000Z (6 months ago)
- Last Synced: 2026-01-11T01:45:33.874Z (6 months ago)
- Topics: dialogue, narrative, narrative-design, narrative-game, scripting-games, scripting-language, video-game, video-game-development
- Language: Zig
- Homepage: https://peartree.games/topiary
- Size: 3.77 MB
- Stars: 15
- Watchers: 1
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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](https://ziglang.org).
## 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:
```sh
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](https://github.com/peartreegames/topiary/blob/main/docs/syntax.md) file,
the [CLI reference](https://github.com/peartreegames/topiary/blob/main/docs/cli.md),
and examples in the [example folder](https://github.com/peartreegames/topiary/tree/main/examples).
Here you can see what writing in topi looks like
```topi
=== 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](https://github.com/inkle/ink) and [Yarn Spinner](https://yarnspinner.dev).
Secondly writing my own language would have never been attempted without the wonderfully written books on [Crafting Interpreters](https://craftinginterpreters.com) by Robert Nystrom and [Writing an Interpreter/Complier in Go](https://interpreterbook.com)
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](https://github.com/Luukdegram/luf/tree/master),
and [LoLa](https://github.com/MasterQ32/LoLa/tree/master) both of which are credited in the Licence since their parsers were used as inspiration when starting out.
## Contributing
Download and install [Zig](https://ziglang.org). Currently Topiary uses version `0.16.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.