Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/gudzpoz/brocatel
Embeddable interactive stories in Markdown, made & extended with Lua
https://github.com/gudzpoz/brocatel
choice-based-game interactive-fiction interactive-storytelling lua
Last synced: 22 days ago
JSON representation
Embeddable interactive stories in Markdown, made & extended with Lua
- Host: GitHub
- URL: https://github.com/gudzpoz/brocatel
- Owner: gudzpoz
- License: mit
- Created: 2023-08-30T09:34:19.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-04-13T08:43:44.000Z (10 months ago)
- Last Synced: 2024-04-14T04:55:27.661Z (10 months ago)
- Topics: choice-based-game, interactive-fiction, interactive-storytelling, lua
- Language: TypeScript
- Homepage: https://gudzpoz.github.io/brocatel/
- Size: 2.28 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
- Roadmap: docs/roadmap.md
Awesome Lists containing this project
README
---
brocatel: true
---
# Brocatel
[](https://www.npmjs.com/package/@brocatel/mdc)
[](https://luarocks.org/modules/gudzpoz/brocatel)
[](https://github.com/gudzpoz/brocatel/blob/main/LICENSE.txt)
[](https://marketplace.visualstudio.com/items?itemName=gudzpoz.vscode-brocatel)
[](https://open-vsx.org/extension/gudzpoz/vscode-brocatel)
[](https://gudzpoz.github.io/brocatel/)
[](https://github.com/gudzpoz/brocatel/issues)
[](https://github.com/gudzpoz/brocatel/wiki)
[](https://rvlt.gg/P66DcpnQ)
(By the way, you can also [run this README file interactively with Brocatel](https://gudzpoz.github.io/brocatel/playground.html?url=https://cdn.jsdelivr.net/gh/gudzpoz/brocatel@main/README.md).)
* What is Brocatel?
Brocatel lets you write interactive stories (choice-based interactive fictions) in [Markdown](https://en.wikipedia.org/wiki/Markdown), backed by [Lua](https://www.lua.org/).
1. Features
[¶](#features)
2. Why?
[¶](#why)
3. How to use Brocatel?
[¶](#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](https://gudzpoz.github.io/brocatel/cloak.html) example:
```markdown
# 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](https://www.lua.org/) 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](https://www.gnu.org/software/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
[¶](#features)
2) Back To Top
[¶](#brocatel)
## 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.
[](#brocatel)
## How to use Brocatel?
1. I want to try things out first.
You can try Brocatel out in [our online playground](https://gudzpoz.github.io/brocatel/playground.html) or with [an interactive online tutorial](https://gudzpoz.github.io/brocatel/tutorial.html).
2. I want to use Brocatel in my own project.
A [Brocatel VS Code extension](https://marketplace.visualstudio.com/items?itemName=gudzpoz.vscode-brocatel) 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`](https://luarocks.org/modules/gudzpoz/brocatel) Lua library, whose API is available at [https://gudzpoz.github.io/brocatel/api/](https://gudzpoz.github.io/brocatel/api/).
Navigation
1) Back To Section
[¶](#how-to-use-brocatel)
2) Back To Top
[¶](#brocatel)