diff options
| -rw-r--r-- | README.md | 173 | ||||
| -rw-r--r-- | README_zh_CN.md | 171 |
2 files changed, 216 insertions, 128 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("") + ) +} +``` diff --git a/README_zh_CN.md b/README_zh_CN.md index c7210b2..8ab91ba 100644 --- a/README_zh_CN.md +++ b/README_zh_CN.md @@ -2,109 +2,154 @@ > 用 Markdown 来书写您的剧情！ +## 一些碎碎语 + +这是一个我个人用于学习的项目，为了快速实现我想要的效果，项目中实验性地使用了 **Vibe Coding** + +## 介绍 + +MarkDialog 是 **书写文字剧情的范式**，它定义了如何用 **Markdown** 来描述文字冒险游戏的对话。 + +它允许你： + +- 使用 **六级标题** 表示角色 +- 使用 **标题** 表示段落 +- 使用 **超链接** 表示跳转 +- 使用 **代码块** 来控制速度、画面，与游戏内容互动 + > [!NOTE] -> 这是我闲暇时间折腾出来的项目，很多地方还没打磨好。 +> 如果你想了解 Markdialog 的语法，可以点击此处 > -> 另外我在里面实验性地使用了 **Vibe Coding**，所以你可能会看到一些不太正经的代码，请多包涵。 +> [Markdialog 示例文章](#示例文章) -## 为什么会有 MarkDialog？ +## 工具链 -这个项目的起点其实很简单： 我想做一个 AVG 视觉小说的原型，需要让身边的人**能立刻上手写剧情**。 +MarkDialog 提供了编译工具 `mdialogc`，它可以将您的 **Markdown** 文件编译成中间语言，以快速地在任何前端播放或执行。 -但现实是： +```bash +# 执行，将会输出 YourMarkdown.dialog +mdialogc -i YourMarkdown.md +``` -- 图形化编辑器太重 -- Ink、Yarn Spinner 虽然强大，但都需要学习 -- JSON / XML / 自定义 DSL 写起来都不够 “自然” +目前支持的前端： -我真正想要的是一种大家已经会写、不需要学习、打开就能写、写完就能跑的格式。 +- [Rust](#Rust 示例) -然后我突然想到： +## 其他 -### Markdown 不就是这样的吗？ +#### 示例文章 -你可以在 **Typora**、**Obsidian**、**VS Code** 甚至 **Vim/NeoVim** 里轻松地编写他们 +```markdown +# 对话 -> 还要什么自行车？ +###### 爱丽丝 -当这个念头冒出来的时候，我整个人都兴奋了。 +早上好，鲍勃。 -于是，MarkDialog 就这样诞生了。 +你吃早饭了么？ +- [当然吃了！](#鲍勃吃过了早饭) +- [并没。](#鲍勃还没吃早饭) +- [我还不饿。](#鲍勃并不饿) +## 鲍勃吃过了早饭 -## MarkDialog 是什么？ +###### 鲍勃 -它让你可以： +我当然**吃了早饭**！ -- 用六级标题切换角色 -- 用普通 Markdown 写台词 -- 用列表写选项 -- 用链接写跳转 -- 用代码块写速度、颜色、动作等富文本控制 -- 用图片切换背景 +###### 爱丽丝 -你写的 Markdown 会被编译成一个 IR，然后解析到任何地方，只要你想！ +*哦。*我还想你跟我一起去吃呢。 -比如 +###### 旁白 -- 内联到 Rust 项目 -- 导入 Unity / Unreal / Godot -- 转换为 Json -- 转换为任何东西 +(剧情结束) +## 鲍勃还没吃早饭 +###### 鲍勃 -## MarkDialog 的语法？ +并没吃。 -一般来讲，只要你会写 Markdown，你就会写 Markdialog +###### 爱丽丝 -你可以： +[好啊！一起去吃早饭么？](#爱丽丝询问是否一起吃早饭) -``` -# 标题 -> 使用引用块表示注释 +## 鲍勃并不饿 -###### 张三 -使用六级标题表示**角色名称** +###### 鲍勃 -使用无序列表表示选项 -- 早上好 -- 中午好 -- 晚上好 +*我其实不饿*？ -有序也行 -1. 早上好 -2. 中午好 -3. 晚上好 +###### 爱丽丝 -> 使用超链接表示跳转 -中午吃？ -- 披萨 [](#Eat_Pizza) -- 意面 [](#Eat_Pasta) -- 不吃 -或者 *什么都不吃*！ +那算了，今天太遗憾了。（*小声嘟囔*） -## Eat_Pizza -吃披萨 +###### 旁白 -## Eat_Pasta -吃意面 +(剧情结束) -> 使用图像来切换背景 - +## 爱丽丝询问是否一起吃早饭 -> 使用如下方式来内联其他文件！ -[[branch.md]] -``` +###### 鲍勃 -就是如此简单！ +让我想想。。。 +- 走吧！ +- 算了，我[并不饿](#鲍勃并不饿) +###### 爱丽丝 +好啊！走吧！ +###### 旁白 -## 开源协议 +（于是鲍勃和爱丽丝一起吃了早饭） -哈哈，我采用 MIT License，放心玩去吧！ +（剧情结束） +``` + +#### Rust 示例 + +```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!("鲍勃吃过了早饭")).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("") + ) +} + +``` |