diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 173 |
1 files changed, 108 insertions, 65 deletions
@@ -2,109 +2,152 @@ > Write your story with Markdown! -> [!WARNING] -> This article is translated from `README_zh_CN.md` +## Some Ramblings + +This is a personal learning project of mine. To quickly achieve the desired effect, the project experimentally uses **Vibe Coding**. + +## Introduction + +MarkDialog is a **paradigm for writing textual narratives**. It defines how to use **Markdown** to describe dialogue for text adventure games. + +It allows you to: + +- Use **level-six headings** to represent characters. +- Use **headings** to represent paragraphs. +- Use **hyperlinks** to represent jumps. +- Use **code blocks** to control speed, visuals, and interact with game content. > [!NOTE] -> This is a project I tinkered with in my spare time, and many aspects are still rough around the edges. +> If you want to learn about MarkDialog syntax, click here. > -> I also experimentally used **Vibe Coding** in it, so you might encounter some unconventional code. Please bear with me. +> [MarkDialog Example Article](#example-article) -## Why MarkDialog? +## Toolchain -The starting point for this project was actually quite simple: I wanted to prototype an AVG visual novel and needed people around me to **be able to start writing the story immediately**. +MarkDialog provides a compilation tool `mdialogc`, which can compile your **Markdown** files into an intermediate language for fast playback or execution on any frontend. -But the reality is: +```bash +# Execution, will output YourMarkdown.dialog +mdialogc -i YourMarkdown.md +``` -- Graphical editors are too heavy. -- Ink and Yarn Spinner are powerful, but both require learning. -- Writing in JSON / XML / custom DSLs isn't "natural" enough. +Currently supported frontends: -What I really wanted was a format that people already know how to write, requires no learning, can be opened and written in immediately, and can be run right after writing. +- [Rust](#rust-example) -Then it suddenly hit me: +## Other -### Isn't Markdown exactly that? +#### Example Article -You can easily write it in **Typora**, **Obsidian**, **VS Code**, or even **Vim/NeoVim**. +```markdown +# Dialogue -> What more could you ask for? +###### Alice -When this idea popped into my head, I got really excited. +Good morning, Bob. -And so, MarkDialog was born. +Have you had breakfast? +- [Of course I have!](#Bob-has-had-breakfast) +- [Not yet.](#Bob-has-not-had-breakfast) +- [I'm not hungry.](#Bob-is-not-hungry) +## Bob-has-had-breakfast -## What is MarkDialog? +###### Bob -It allows you to: +I certainly **had breakfast**! -- Use level-six headings to switch characters. -- Use regular Markdown for dialogue lines. -- Use lists for choices. -- Use links for jumps. -- Use code blocks for rich text controls like speed, color, and actions. -- Use images to change backgrounds. +###### Alice -The Markdown you write is compiled into an IR (Intermediate Representation), which can then be parsed anywhere you want! +*Oh.* I was hoping you'd join me. -For example: +###### Narrator -- Inline it into a Rust project. -- Import it into Unity / Unreal / Godot. -- Convert it to JSON. -- Convert it to anything. +(Story ends) +## Bob-has-not-had-breakfast +###### Bob -## MarkDialog Syntax? +Not yet. -Generally speaking, if you know how to write Markdown, you know how to write MarkDialog. +###### Alice -You can write: +[Great! Want to go get breakfast together?](#Alice-asks-to-eat-breakfast-together) -``` -# Title -> Use blockquotes for comments +## Bob-is-not-hungry -###### Zhang San -Use a level-six heading for **character names**. +###### Bob -Use unordered lists for choices -- Good morning -- Good afternoon -- Good evening +*I'm actually not hungry*? -Ordered lists work too -1. Good morning -2. Good afternoon -3. Good evening +###### Alice -> Use hyperlinks for jumps -What's for lunch? -- Pizza [](#Eat_Pizza) -- Pasta [](#Eat_Pasta) -- Nothing -Or *eat nothing at all*! +Never mind then, what a pity today. (*muttering quietly*) -## Eat_Pizza -Eat pizza +###### Narrator -## Eat_Pasta -Eat pasta +(Story ends) -> Use images to switch backgrounds - +## Alice-asks-to-eat-breakfast-together -> Use the following method to inline other files! -[[branch.md]] -``` +###### Bob -It's that simple! +Let me think... +- Let's go! +- No, I'm [not hungry](#Bob-is-not-hungry) +###### Alice -## Open Source License +Great! Let's go! -Haha, I'm using the MIT License. Feel free to play around with it! +###### Narrator + +(And so Bob and Alice had breakfast together) + +(Story ends) +``` + +#### Rust Example + +```toml +# Cargo.toml +[package] +name = "your_proj" +version = "0.1.0" +edition = "2024" + +[dependencies] +markdialog = { git = "https://github.com/CatilGrass/MarkDialog" } +``` + +```rust +// main.rs +use markdialog::generate::{markdialog, step}; + +markdialog!(my = "alice_and_bob.dialog"); + +fn main() { + let my_step = my::get_step(step!("Bob-has-had-breakfast")).unwrap(); + let sentence = my_step.sentences[0]; + println!( + "{} said : \"{}\"", + sentence.character.unwrap_or_default(), + sentence + .content_tokens + .iter() + .map(|token| match token { + my::Token::Text(t) => t, + my::Token::BoldText(t) => t, + my::Token::ItalicText(t) => t, + my::Token::BoldItalicText(t) => t, + _ => "", + } + .to_string()) + .collect::<Vec<String>>() + .join("") + ) +} +``` |