gudzpoz / brocatel

Embeddable interactive stories in Markdown, made & extended with Lua

brocatel
true

Brocatel

(By the way, you can also run this README file interactively with Brocatel.)

• What is Brocatel?

  Brocatel lets you write interactive stories (choice-based interactive fictions) in Markdown, backed by Lua.

1. Features ¶
2. Why? ¶
3. How to use Brocatel? ¶

Features

1. Markdown-ish.

   Brocatel uses the simple syntax of Markdown, making it easy to learn.

   Here is a snippet taken from the Cloak of Darkness example:

   # bar_light
   There seems to be some sort of message scrawled in the sawdust on the floor.
   1.  Go north.
       [go back to the foyer section](#foyer)
   2.  Examine the message.
       :::if `scuffled < 2`
       -   The message, neatly marked in the sawdust, reads...
           You have won!
       -   The message has been carelessly trampled, making it difficult to read. You can just distinguish the words...
           You have lost.
       The end.

2. Lua Powered.

   Instead of implementing a custom scripting language, Brocatel runs on Lua and uses Lua for scripting purposes. As a proven and robust language, Lua is not only portable and heavily used in the game industry, but also simple and relatively easy to learn.

   Brocatel direcly uses Lua for its variables and conditional branches.

3. Translatable.

   Brocatel is fully translatable, allowing you to write stories in multiple languages. By integrating with GNU gettext, it supports writing stories that handles different pluralities and sentence structures between languages.

   Upon compilation, the Brocatel compiler will automatically generate a context-rich POT file that one may send to a translator for localization.

Navigation

1. Back To Section ¶
2. Back To Top ¶

Why?

There are many tools for writing interactive stories. However, most of them are either too complicated to learn with weird grammar, or too limited in features with little integration or internationalization consideration.

By leveraging the simple syntax of Markdown and the power of Lua, Brocatel aims to balance the ease to create interactive stories and the degree of customizability.

How to use Brocatel?

1. I want to try things out first.

   You can try Brocatel out in our online playground or with an interactive online tutorial.

2. I want to use Brocatel in my own project.

   A Brocatel VS Code extension extension has been published both to the VS Marketplace and the Open VSX Registry. You may use it to aid your story writing by getting syntax error highlights and instant previews.

   The extension will probably support compiling, debugging and exporting Brocatel stories very soon. Before then, if you want to use Brocatel in real games, you will need to use a bit of CLI, i.e., use npx --package @brocatel/[email protected] -- brocatelc YOUR_MARKDOWN_FILE.md to compile your files, which should generate a .lua file (the story) and a .pot file (for translators). To actually get the story out of the .lua file, you will need to use the brocatel Lua library, whose API is available at https://gudzpoz.github.io/brocatel/api/.

Navigation

1. Back To Section ¶
2. Back To Top ¶