MarkVenture 創作者指南

Version: 2.0 Date: 2026-03-31 Language: zh-TW

歡迎來到 MarkVenture！這份指南將教你如何使用簡單的 Markdown 語法創作互動式小說。

📚 目錄

  1. 快速開始
  2. 基礎語法
  3. 場景設計
  4. 互動系統
  5. 道具與物品
  6. 條件與變數
  7. 場景圖片
  8. 顯示模式
  9. 最佳實踐
  10. 常見問題
  11. 範例模板
  12. 錯誤排查與警告

1. 快速開始

1.1 你的第一個故事

讓我們創作一個簡單的互動故事：

---
title: 我的第一個冒險
author: 你的名字
language: zh-TW
---

## 起點

你站在一個十字路口。左邊是森林，右邊是山脈。

- @here
    - [進入森林](#森林)
    - [爬上山脈](#山脈)

## 森林

你走進茂密的森林，陽光透過樹葉灑下斑駁的光影。

這裡很安靜，只聽得到鳥叫聲。

## 山脈

你開始攀爬陡峭的山路。視野越來越開闊。

從山頂可以看到整個山谷的美景。

就是這麼簡單！ 這個故事包含：

1.2 文件結構

所有 MarkVenture 故事都遵循這個結構：

---
[配置設定]
---

## 場景 1
[場景內容]
- @here [互動選項]

## 場景 2
[場景內容]

2. 基礎語法

2.1 Frontmatter（配置區）

Frontmatter 必須放在文件最開頭，用 --- 包圍：

---
title: 故事標題
author: 作者名稱
language: zh-TW

variables:
  player_name: ""
  health: 100
  has_key: false
---

必填欄位：

選填欄位：

2.2 場景標題

使用 ## 定義主場景：

## 書房

## 陽台

## 密室

使用 ### 定義子場景（不會顯示在導航中）：

## 書房

### 書架
這是書房裡的書架...

### 書桌
這是書房裡的書桌...

2.3 場景描述

場景標題後的文字就是場景描述：

## 圖書館

你走進一間巨大的圖書館。高聳的書架延伸到看不見的天花板，
無數古老的書籍散發著歷史的氣息。

遠處傳來翻書的聲音。

支援的 Markdown 格式：

3. 場景設計

3.1 基本場景跳轉

使用 - @ 創建互動選項，用 #場景名稱 連結到其他場景：

## 大廳

你站在豪宅的大廳。有三扇門。

- @here
    - [左邊的門](#書房)
    - [中間的門](#廚房)
    - [右邊的門](#臥室)

## 書房
你進入了書房...

## 廚房
你進入了廚房...

## 臥室
你進入了臥室...

3.2 子場景

子場景不會顯示在場景列表中，適合用於小地點：

## 書房

寬敞的書房裡擺滿了書架。

- @here
    - [檢查書桌](#書桌)
    - [看看窗外](#窗戶)
    - [離開](#大廳)

### 書桌
書桌上放著一本日記。

- @here
    - [閱讀日記]() show "日記記載著..."
    - [返回](#書房)

### 窗戶
從窗戶可以看到花園。

- @here
    - [返回](#書房)

3.3 同場景互動

使用空連結 () 在同一場景內互動：

## 神秘房間

房間裡有一個寶箱。

- @here
    - [打開寶箱]()
        - show "你獲得了一把鑰匙！"
        - set has_key = true
    - [離開](#走廊)

3.4 場景屬性

為場景添加特殊屬性：

## 密室 {display: expand, preview: 2}

第一段（顯示）...

第二段（顯示）...

第三段（收合，需要點「繼續閱讀」）...

## 最終章 {img: "epic final battle scene"}

帶有 AI 生成圖片的場景...

4. 互動系統

4.1 基本互動

語法：

- @here
    - [選項文字](#目標場景或空)

範例：

## 十字路口

- @here
    - [向左走](#森林)
    - [向右走](#山脈)
    - [原地等待]() show "時間慢慢過去..."

4.2 實體互動

定義可互動的物品或角色：

## 書房

桌上有一本[古書][]和一支[鋼筆][]。

[古書]: book "厚重的皮革裝訂古書"
[鋼筆]: pen "精緻的黑色鋼筆"

- book
    - [翻開]() show "書頁泛黃，寫滿了難懂的文字。"
    - [收起來](/item) show "你把古書收進背包。"
- pen
    - [拿起來](/item) show "你拿起了鋼筆。"

實體定義格式：

[顯示名稱]: id "懸停描述"

4.3 道具互動

玩家在背包中點選道具，再點選場景中的目標來使用，不會在選項清單中看到「使用 XX」的選項。道具互動定義在被使用的目標實體下：

## 上鎖的門

這扇門被鎖住了。

- @here
    - [嘗試推開]() show "門紋絲不動。"
    - [離開](#走廊)
- locked-door
    - use golden-key
        - [進入密室](#密室) show "鎖打開了！"

只要 golden-key 在背包中，玩家就能點選它再點選「locked-door」來觸發互動。

4.4 條件選項

根據變數顯示不同選項：

## 守衛

- @here
    - if has_pass
        - [出示通行證](#進入城堡)
    - if persuasion >= 5
        - [說服守衛](#進入城堡) set persuaded_guard = true
    - else
        - [偷偷溜進去](#嘗試潛入)
    - [離開](#城門外)

4.5 輸入互動

讓玩家輸入文字：

## 神秘石碑

石碑上刻著：「說出你的名字，勇者。」

- @here
    - [說出名字]()
        - prompt player_name

---

## 歡迎

石碑發光了。一個聲音響起：「歡迎你，{player_name}！」

- @here
    - [繼續](#冒險開始)

4.6 條件分支

根據前面的選擇決定結果：

## 神秘寶箱

你打開了寶箱...

- @here
    - if chest_searched
        - [再次查看]() show "寶箱已經空了。"
    - if not chest_searched
        - [打開]() set chest_searched = true
            - if has_treasure_map
                - show "地圖指引你找到了藏在夾層的金幣！"
                - set gold += 100
            - if not has_treasure_map
                - show "裡面有一把生鏽的劍。"
                - set has_sword = true

5. 道具與物品

5.1 定義物品

[物品名稱]: id "描述文字" {img: "AI 圖片提示詞"}

範例：

[金鑰匙]: golden-key "閃閃發光的金色鑰匙" {img: "golden ornate key"}
[治療藥水]: potion "紅色的治療藥水" {img: "red healing potion bottle"}
[古老地圖]: map "泛黃的羊皮紙地圖"

5.2 收集物品

在互動目標行加上 /item 旗標，玩家點選後即自動加入背包：

- key /item

加了 /item 的實體，玩家在尚未取得時會看到「撿起」選項；取得後可在背包中使用。也可以在互動區塊中定義取得後的額外行為（例如顯示訊息）：

- key /item
- locked-door
    - use key
        - show "鎖打開了！"
        - [進入密室](#密室)

5.3 使用物品

玩家在背包點選道具 → 點選場景中的目標，觸發互動。互動邏輯定義在目標實體下，不在道具本身：

## 廢棄倉庫

生鏽的鐵門擋住了去路。

- iron-door
    - use_fallback: "這個東西對門好像沒什麼用。"
    - use crowbar
        - set door_forced = true
        - show "你用撬棍硬撬開了門。"
        - [進入倉庫](#倉庫內部)

use_fallback：當玩家用了未定義的道具時顯示的訊息。Fallback 優先順序：

  1. Entity 層級 use_fallback（定義在互動區塊內）
  2. 故事層級 use_fallback（定義在 frontmatter）
  3. 平台預設：「Nothing happens.」

故事全域 fallback（在 frontmatter 設定，與 entity 層級同名）：

---
title: 廢棄倉庫
use_fallback: "這樣做沒有任何效果。"
---

5.4 合成物品

用一個道具對另一個道具使用，產生新道具。合成邏輯定義在「目標」道具的互動區塊中。合成結果道具（如火把）需要在某個場景中定義 entity，讓背包知道它的顯示名稱：

[木棍]: stick "一根普通的木棍"
[破布]: cloth "一塊破爛的布"
[火把]: torch "用布纏繞木棍製成的火把"

- stick /item
- cloth /item
    - use stick
        - remove stick
        - remove cloth
        - give torch
        - show "你用布纏住木棍，做出了火把！"

5.5 消耗物品

道具使用後若需消耗，在命令中加上 remove：

- character
    - use_fallback: "對方沒有什麼反應。"
    - use potion
        - remove potion
        - set health += 50
        - show "你給對方喝下了藥水，對方的氣色好多了。"

5.6 自用道具（@self）

玩家想對自己使用道具（例如喝藥水），用 @self 作為目標，定義一次即可全場景生效：

- @self
    - use potion
        - remove potion
        - set health += 50
        - show "你喝下藥水，感覺好多了。"
    - use armour
        - remove armour
        - set defence += 10
        - show "你穿上了盔甲。"

玩家在選中道具後，畫面會出現「對自己使用」的按鈕，點擊即觸發 @self 互動。

5.7 道具檢視描述（examine）

在道具上加上 examine，讓玩家單擊道具時可以查看詳細說明，不會進入使用模式：

- key /item
    - examine: "一把沉重的鐵鑰匙，上面刻著奇怪的符文。"
- locked-door
    - use key
        - set door_open = true
        - show "鎖打開了。"

不定義 examine 的話，單擊只顯示道具名稱。雙擊（或手機長按）才進入使用模式。

5.8 道具狀態

若道具有多種狀態（如「生鏽的劍」→「鋒利的劍」），建議用變數追蹤狀態，在場景描述中根據條件顯示不同文字，而非更改道具名稱：

---
variables:
  sword_sharpened: false
---

## 書房

你的[劍][]`{if sword_sharpened}`鋒利無比。`{else}`有些生鏽。`{/if}`

[劍]: sword "一把劍"

- @here
    - if not sword_sharpened
        - [磨劍]()
            - set sword_sharpened = true
            - show "劍磨好了！"
- sword /item

5.9 道具數量

MarkVenture 的道具不支援堆疊——同一個道具 ID 在背包中只能有一個。若需要追蹤數量（金幣、箭矢等），請用數值變數：

set gold += 1        ✓ 正確：用變數追蹤數量
give gold-coin       ✗ 避免：道具不能堆疊

在場景文字中可以直接顯示數量：

你目前有 {gold} 金幣。

6. 條件與變數

6.1 定義變數

在 frontmatter 初始化：

---
title: RPG 冒險

variables:
  health: 100
  gold: 0
  level: 1
  has_sword: false
  player_name: ""
---

6.2 設定變數

使用 set 指令：

- [撿起金幣]()
    - set gold += 10
    - show "你獲得了 10 金幣！"
- [受傷]() set health -= 20
- [升級]() set level += 1
- [裝備劍]() set has_sword = true

支援的運算：

6.3 條件判斷

使用 if-else 控制流程：

- @here
    - if health > 50
        - [繼續探索](#深處)
    - else
        - [太虛弱了，休息一下](#休息處)

比較運算子：

6.4 複合條件

使用 and 和 or：

- @here
    - if has_sword and health > 30
        - [戰鬥](#戰鬥場景)
    - if gold >= 100 or has_key
        - [進入寶庫](#寶庫)
    - else
        - [逃跑](#安全區域)

6.5 場景內容中的條件顯示

在場景描述文字中，可以使用 inline condition 根據條件顯示不同內容。語法為在同一行用反引號包住條件標記：

## 書房

你站在書房中。`{if door_open}`門是開著的。`{/if}``{if not door_open}`門是關著的。`{/if}`

帶有 else 分支：

你站在書房中。`{if door_open}`門是開著的。`{else}`門是關著的。`{/if}`

7. 場景圖片

7.1 設定圖片場景

在場景標題下一行加上 {img: "提示詞"} 來標記這個場景需要圖片：

## 神秘森林
{img: "dark mysterious forest with glowing mushrooms"}

你進入了一片神秘的森林...

也可以用 {img: auto} 讓系統自動以場景標題作為提示詞：

## 神秘森林
{img: auto}

圖片比例： 16:9（建議尺寸 1792×1024）

7.2 上傳圖片（推薦）

最簡單的方式是自行準備圖片後上傳：

  1. 用任何免費工具生成圖片，例如 ChatGPT、Gemini、Ideogram、Canva
  2. 儲存圖片（建議 16:9 比例，否則會自動裁切；上傳時會自動壓縮至合適大小）
  3. 在編輯頁面的「場景圖片」區塊，點擊場景旁的「上傳圖片」

圖片上傳後會快取在平台，所有玩家都能看到。

7.3 AI 自動生成（需 API Key）

若有付費的 AI API Key，可以在編輯頁面直接批次生成所有場景圖片，不需要手動上傳。

支援的服務：

服務 provider 值 API Key 來源
Google Gemini gemini aistudio.google.com
OpenAI DALL-E 3 dall-e-3 platform.openai.com
Stability AI stable-diffusion platform.stability.ai

在平台設定頁填入 API Key 後，編輯頁面會出現「生成缺少的圖片」按鈕。

在 frontmatter 指定服務與風格：

---
title: 我的故事
ai_image:
  provider: gemini
  style: "soft watercolor illustration, warm light"
---

不指定 provider 時，系統會依照已填入的 Key 自動選擇（順序：Gemini → OpenAI → Stability AI）。

提示詞技巧：

8. 顯示模式

8.1 模式類型

MarkVenture 提供 5 種內容顯示模式：

模式 適用情境 行為
auto 自動判斷（預設） 根據內容長度自動選擇
standard 短內容（< 3 段） 直接顯示全部
scroll 中長內容（3-8 段） 可滾動，顯示漸層
expand 長內容（> 8 段） 顯示前幾段，「繼續閱讀」
paginate 超長內容 分頁顯示

8.2 全域設定

在 frontmatter 設定整個故事的預設模式：

---
title: 我的故事
display:
  description_mode: scroll
---

8.3 場景級設定

為特定場景覆寫顯示模式：

## 短場景 {display: standard}
簡短的內容...

## 中等場景 {display: scroll}
中等長度的內容...
多個段落...

## 長場景 {display: expand, preview: 3}
第一段（顯示）...
第二段（顯示）...
第三段（顯示）...
第四段（收合）...
更多內容...

## 超長場景 {display: paginate, per_page: 2}
非常長的內容會被分成多頁...

8.4 最佳實踐

短場景（< 150 字）：

## 轉角 {display: standard}
你轉過街角，看到一間小店。

中等場景（150-500 字）：

## 圖書館 {display: scroll}
你走進圖書館。高聳的書架...（3-5 段）

長場景（> 500 字）：

## 回憶 {display: expand, preview: 2}
長篇回憶描述...（顯示前 2 段）
更多回憶...（收合）

超長場景（> 1000 字）：

## 史詩序章 {display: paginate, per_page: 3}
非常長的開場敘述...（每頁 3 段）

9. 最佳實踐

9.1 故事結構

好的開場：

## 序幕

{img: "mysterious tavern at night"}

你推開酒館的門，嘈雜的聲音撲面而來。
角落裡，一個神秘的人向你招手。

- @here
    - [走過去](#與神秘人對話)
    - [先點杯酒](#吧台)
    - [觀察一下環境]() show "你注意到牆上掛著懸賞令..."

清晰的選項：

- @here
    - [勇敢地踏入](#危險區域)  ← 明確動作
    - [小心翼翼前進](#謹慎探索)  ← 不同風格
    - [放棄離開](#回到安全區)  ← 提供退路

9.2 變數命名

好的命名：

variables:
  player_health: 100
  has_magic_sword: false
  gold_coins: 0
  talked_to_wizard: false

避免：

variables:
  h: 100          ← 太短，不清楚
  生命值: 100     ← 避免中文變數名
  HasSword: false ← 使用底線而非駝峰

9.3 場景設計

一個場景一個重點：

❌ 太擁擠：

## 房間

房間裡有[書桌][]、[椅子][]、[書架][]、[窗戶][]、[地毯][]、[門][]...

✅ 適當：

## 書房

寬敞的書房，最引人注目的是巨大的書架。
角落有一張書桌。

- @here
    - [檢查書架](#書架)
    - [坐到書桌前](#書桌)
    - [離開](#走廊)

9.4 互動設計

提供有意義的選擇：

❌ 假選擇：

- @here
    - [向左]() show "路不通。"
    - [向右]() show "路不通。"
    - [向前](#唯一出路)  ← 只有這個有用

✅ 真選擇：

- @here
    - [戰鬥](#戰鬥) ← 高風險高回報
    - [談判](#談判) ← 需要技能
    - [逃跑](#逃跑) ← 安全但錯失機會

9.5 回饋設計

即時回饋：

- [開門]()
    show "門打開了。"
    set door_open = true
    ← 立即告訴玩家發生了什麼

狀態顯示：

## 當前狀態

生命值：{health}/100 `{if health < 30}`⚠️`{/if}`
金幣：{gold}

9.6 難度曲線

逐步引入概念：

## 教學 - 第一步
最基本的選擇...

## 教學 - 第二步
引入物品系統...

## 教學 - 第三步
引入條件判斷...

## 正式開始
現在可以自由探索了！

9.7 測試檢查清單

創作完成後檢查：

10. 常見問題

Q1: 如何製作多結局？

方法 1：使用變數追蹤

---
variables:
  good_deeds: 0
  bad_deeds: 0
---

# 在故事中累積點數
- [幫助老人]() set good_deeds += 1
- [搶劫商人]() set bad_deeds += 1

# 最終場景
## 結局

- @here
    - if good_deeds > bad_deeds
        - [正面結局](#好結局)
    - if bad_deeds > good_deeds
        - [負面結局](#壞結局)
    - else
        - [中立結局](#普通結局)

方法 2：關鍵選擇

## 最終決定

你必須做出選擇...

- @here
    - [拯救村莊](#英雄結局)
    - [保護自己](#生存結局)
    - [什麼都不做](#悲劇結局)

Q2: 如何實現戰鬥系統？

用變數追蹤雙方狀態，讓玩家選擇策略：

---
variables:
  player_health: 100
  enemy_health: 50
  player_defending: false
---

## 戰鬥

敵人生命值：{enemy_health}
你的生命值：{player_health}

- @here
    - if enemy_health > 0 and player_health > 0
        - [強攻]()
            - set enemy_health -= 25
            - set player_defending = false
            - show "你猛力一擊，敵人受到 25 點傷害！"
            - if not player_defending
                - set player_health -= 15
                - show "敵人反擊，你受到 15 點傷害。"
        - [防禦反擊]()
            - set player_defending = true
            - set enemy_health -= 10
            - show "你格擋後反擊，敵人受到 10 點傷害。敵人的攻擊被格擋。"
    - if enemy_health <= 0
        - [勝利！](#戰鬥勝利)
    - if player_health <= 0
        - [失敗...](#戰鬥失敗)

Q3: 如何實現計時器/時間系統？

---
variables:
  is_day: true
---

## 旅店

`{if is_day}`現在是白天。`{else}`現在是夜晚。`{/if}`

- @here
    - if is_day
        - [休息到夜晚]() set is_day = false
    - if not is_day
        - [等到白天]() set is_day = true
    - [探索城鎮](#城鎮)

Q4: 如何製作商店系統？

---
variables:
  gold: 100
  has_sword: false
  has_armor: false
---

## 商店

你有 {gold} 金幣。

- @here
    - if not has_sword and gold >= 50
        - [購買劍（50 金）]()
            - set gold -= 50
            - set has_sword = true
            - show "你買了一把劍！"
    - if not has_armor and gold >= 80
        - [購買盔甲（80 金）]()
            - set gold -= 80
            - set has_armor = true
            - show "你買了盔甲！"
    - if gold < 50
        - show "你的錢不夠。"
    - [離開](#城鎮廣場)

Q5: 如何實現謎題？

密碼鎖謎題：

---
variables:
  password_tries: 3
  password_correct: false
---

## 密碼鎖

剩餘嘗試次數：{password_tries}

- @here
    - if password_tries > 0 and not password_correct
        - [輸入密碼]()
            - prompt password_input
            - if password_input = "1234"
                - set password_correct = true
                - show "密碼正確！"
                - [解鎖](#解鎖)
            - else
                - set password_tries -= 1
                - show "密碼錯誤！"
    - if password_tries = 0
        - [放棄](#走廊)
    - if password_correct
        - [打開門](#密室)

### 解鎖
門開了！

- @here
    - [進入](#密室)

Q6: 如何追蹤玩家探索進度？

---
variables:
  visited_library: false
  visited_garden: false
  visited_tower: false
---

## 城堡大廳

已探索：
`{if visited_library}`✓ 圖書館`{/if}` `{if visited_garden}`✓ 花園`{/if}` `{if visited_tower}`✓ 塔樓`{/if}`

- @here
    - [圖書館](#圖書館)
    - [花園](#花園)
    - [塔樓](#塔樓)
    - if visited_library and visited_garden and visited_tower
        - [離開城堡](#結局)

## 圖書館
...
- @here
    - set visited_library = true

## 花園
...
- @here
    - set visited_garden = true

## 塔樓
...
- @here
    - set visited_tower = true

11. 範例模板

11.1 簡單選擇冒險

---
title: 森林探險
author: 你的名字
language: zh-TW
---

## 森林入口 {img: "mysterious forest entrance"}

你站在森林入口。路分成兩條。

- @here
    - [走左邊的路](#左路)
    - [走右邊的路](#右路)

## 左路 {img: "dark forest path"}

你走在陰暗的小路上。突然聽到奇怪的聲音。

- @here
    - [繼續前進](#深林)
    - [返回](#森林入口)

## 右路 {img: "sunny forest clearing"}

陽光透過樹葉灑下。這裡很平靜。

- @here
    - [坐下休息]() show "你恢復了體力。"
    - [繼續前進](#山頂)

## 深林

森林越來越密。你找到了一個寶箱！

- @here
    - [打開寶箱](#找到寶藏)

## 山頂 {img: "mountain top view"}

你爬到了山頂。景色壯麗！

- @here
    - [完成](#結局)

## 找到寶藏

你獲得了神秘的寶物！

- @here
    - [完成](#結局)

## 結局

冒險結束！謝謝遊玩。

11.2 密室逃脫

---
title: 午後的書房
author: 你的名字
language: zh-TW

variables:
  has_letter: false
  door_unlocked: false
---

## 書房 {img: "cozy study room with afternoon light"}

你醒來發現自己在一間陌生的書房。[鎖著的門][]緊鎖著。

房間裡有[書桌][]、[書架][]和通往[陽台][]的門。

[書桌]: desk "老舊的木製書桌"
[書架]: bookshelf "裝滿書籍的書架"
[陽台]: balcony "半開的陽台門"
[鎖著的門]: locked-door "緊鎖的房門"
[鑰匙]: key "生鏽的銅鑰匙"

- desk
    - [檢查抽屜]()
        - show "抽屜裡有一封信，上面寫著：『鑰匙藏在知識之後』"
        - set has_letter = true
    - [檢查桌面]() show "桌上放著一個茶几。"
- bookshelf
    - if has_letter
        - [尋找線索]()
            - show "你記起信上說『鑰匙藏在知識之後』，仔細翻找後發現了鑰匙！"
            - give key
    - if not has_letter
        - [尋找線索]() show "書架上都是書，沒有特別的東西。"
- balcony
    - [走到陽台](#陽台)
- locked-door
    - use_fallback: "這樣做沒有任何效果。"
    - use key
        - set door_unlocked = true
        - show "鑰匙插入鎖孔，發出清脆的喀噠聲。"
        - [逃出書房](#逃脫)

## 陽台 {img: "balcony view"}

陽台上有一個小桌子，放著一個[打火機][]。

[打火機]: lighter "銀色的打火機"

- @here
    - [返回書房](#書房)
- lighter /item

## 逃脫

你用鑰匙打開了門！

恭喜你逃出了書房！

- @here
    - end

11.3 RPG 冒險

---
title: 勇者之路
author: 你的名字
language: zh-TW

variables:
  health: 100
  gold: 0
  level: 1
  has_sword: false
---

## 起點 {img: "small village"}

你是一名年輕的冒險者。村長找你有事。

生命值：{health}/100
金幣：{gold}
等級：{level}

- @here
    - [與村長對話](#村長)
    - [探索村莊](#村莊)

## 村長

村長：「勇者啊，惡龍威脅著我們的村莊。你願意幫助我們嗎？」

- @here
    - [接受任務]() show "任務接受！擊敗惡龍。"
    - [拒絕]() show "村長失望地看著你..."
    - [詢問獎勵]() show "村長：『我會給你 500 金幣。』"
    - [前往村莊](#村莊)

## 村莊

村莊廣場。有[商店][]和通往[森林][]的路。

[商店]: shop "武器商店"
[森林]: forest "通往惡龍巢穴的森林"

- shop
    - [進入](#商店)
- forest
    - [進入](#森林)
- @here
    - [休息]()
        - set health = 100
        - show "你恢復了生命值！"

## 商店

商人：「歡迎！」

- @here
    - if not has_sword and gold >= 50
        - [購買劍（50金）]() set gold -= 50
            - set has_sword = true
            - show "你獲得了劍！攻擊力 +20"
    - if has_sword
        - show "你已經有劍了。"
    - if gold < 50
        - show "金幣不夠。"
    - [離開](#村莊)

## 森林 {img: "dark forest"}

森林很危險。你遇到了一隻哥布林！

- @here
    - if has_sword
        - [戰鬥](#戰鬥哥布林)
    - else
        - [逃跑](#村莊) show "你逃回了村莊。"

## 戰鬥哥布林

哥布林在你面前！

- @here
    - [用劍攻擊](#哥布林落敗)
        - set gold += 20
        - set level += 1
        - show "你揮劍擊敗了哥布林！獲得 20 金幣，升至 {level} 級。"
    - [逃跑](#森林)

## 哥布林落敗

你擊敗了哥布林！

- @here
    - [繼續前進](#惡龍巢穴)

## 惡龍巢穴 {img: "dragon lair"}

巨大的惡龍在你面前！

- @here
    - if level >= 2 and has_sword
        - [挑戰惡龍](#擊敗惡龍)
    - else
        - show "你還沒準備好..."
        - [撤退](#村莊)

## 擊敗惡龍

經過激烈的戰鬥，你擊敗了惡龍！

村莊得救了！你成為了傳說中的勇者！

獲得 500 金幣獎勵！

- @here
    - end

12. 錯誤排查與警告

12.1 常見錯誤

錯誤 1：場景連結失效

❌ 錯誤：

## 書房
- @here
    - [去廚房](#Kitchen)  ← 英文場景名

## 廚房  ← 中文場景名

✅ 修正：

## 書房
- @here
    - [去廚房](#廚房)  ← 名稱必須完全一致

## 廚房

錯誤 2：變數名稱不一致

❌ 錯誤：

set hasKey = true  ← 駝峰命名
...
if has_key:  ← 底線命名

✅ 修正：統一使用底線命名

set has_key = true
...
if has_key:

錯誤 3：Frontmatter 格式錯誤

❌ 錯誤：

--  ← 少一個破折號
title: 我的故事
---

✅ 修正：

---  ← 必須是三個破折號
title: 我的故事
---

錯誤 4：縮排錯誤

❌ 錯誤：

- @here
  - [選項 1](#場景)  ← 2 空格
    - [選項 2](#場景)  ← 4 空格（不一致）

✅ 修正：統一使用 4 空格

- @here
    - [選項 1](#場景)
    - [選項 2](#場景)

12.2 除錯技巧

技巧 1：使用測試場景

## 測試

當前變數狀態：
- health = {health}
- gold = {gold}
- has_key = {has_key}

- @here
    - [繼續測試](#下一個場景)

技巧 2：分段測試

先完成主線，確保可以跑通：

## 開始 → ## 中間 → ## 結局

再加入支線和細節。

技巧 3：檢查清單

12.3 語法警告

儲存故事時，平台可能會顯示語法警告。警告不會阻止儲存，但代表故事邏輯可能有問題，建議修正。

警告：場景無法到達

場景「結局B」無法到達

原因：沒有任何選項連結到這個場景。
修正：加入連結，或刪除該場景。

警告：連結目標不存在

場景「書房」：連結目標「書房2F」不存在

原因：[前往](#書房2F) 指向的場景名稱不存在。
修正：確認目標場景名稱完全一致（含大小寫、空格）。

警告：物件未在場景定義

場景「入口」：物件「old_door」未在此場景定義

原因：interaction 裡用了 old_door，但這個場景沒有 [舊門]: old_door "..." 的定義。
修正：加入實體定義，或更正 ID。

警告：道具未定義

場景「書房」：道具「key」未定義

原因：give key 或 remove key，但整個故事找不到 key 的實體定義。
修正：在某個場景加入 [鑰匙]: key "一把舊鑰匙"。

12.4 效能優化

優化 1：避免過深的巢狀

❌ 不推薦：

- @here
    - if condition1
        - if condition2
            - if condition3
                - if condition4
                    - [選項](#場景)

✅ 推薦：使用複合條件

- @here
    - if condition1 and condition2 and condition3 and condition4
        - [選項](#場景)

優化 2：重複使用場景

❌ 不推薦：為每個狀態創建新場景

## 房間_有鑰匙
## 房間_沒鑰匙
## 房間_門開了

✅ 推薦：使用條件顯示

## 房間

`{if has_key}`你有鑰匙。`{/if}`

`{if door_open}`門開著。`{/if}`

13. 進階技巧

13.1 動態文字

根據變數改變文字：

## 對話

NPC：`{if health > 50}`「你看起來還不錯！」`{else}`「天啊！你需要治療！」`{/if}`

13.2 計數器與成就

---
variables:
  enemies_defeated: 0
  secrets_found: 0
---

## 成就追蹤

- @here
    - [擊敗敵人]() set enemies_defeated += 1
        if enemies_defeated >= 10:
            show "成就解鎖：『屠龍勇士』"
    - [發現秘密]() set secrets_found += 1
        if secrets_found >= 5:
            show "成就解鎖：『探險家』"

13.3 時間限制

---
variables:
  moves_left: 10
---

## 計時挑戰

剩餘行動次數：{moves_left}

- @here
    - if moves_left > 0
        - [行動]() set moves_left -= 1
    - if moves_left = 0
        - [時間到](#失敗)
    - if puzzle_solved
        - [成功](#勝利)

13.4 分支探索

用條件控制不同探索路線：

## 森林探索

- @here
    - if has_map
        - [按地圖深入](#寶藏地點) show "地圖帶領你找到了正確的路。"
    - if not has_map
        - [隨意探索](#迷路) show "沒有地圖，你在森林中迷失了方向。"
    - [原路返回](#村莊)

14. 資源與支援

14.1 學習資源

14.2 工具

14.3 獲取幫助

遇到問題？

  1. 查看本指南的常見問題
  2. 搜尋社群論壇
  3. 查閱技術文件
  4. 聯繫支援團隊

15. 發布檢查清單

準備發布你的故事了嗎？確保：

內容

元數據

視覺

技術

測試

🎉 開始創作！

恭喜你完成了 MarkVenture 創作者指南！現在你已經掌握了所有必要的知識。

記住：

準備好了嗎？

👉 開始創作你的第一個故事

需要更多幫助？

祝你創作順利！✨

更新歷史