novel rpg

---

Why Novel RPG? 为什么选择 Novel RPG？

Most AI role-playing tools are generic — you describe a character and chat. Novel RPG is different: it's grounded in real stories. The AI knows the actual plot, characters, relationships, and turning points of each novel. Your choices diverge from the original story, creating a personal "what-if" timeline.

传统 AI 角色扮演只是自由对话。Novel RPG 不同：它基于真实的小说作品——无论是经典文学还是你自己导入的 PDF 小说。AI 深入分析情节、人物关系和转折点，你的每个选择都可能改写故事走向，创造属于你的"平行时空"。

Think of it as: Choose Your Own Adventure meets classic literature, powered by AI.

---

Quick Demo 快速体验

You: 开始小说冒险

AI: 📚 Available books:
    1. Wuthering Heights (呼啸山庄) - Emily Brontë
    2. Journey to the West (西游记) - 吴承恩

You: Wuthering Heights, I'll play as Heathcliff

AI: Yorkshire, 1801. You stand at the threshold of Wuthering Heights.
    The moor wind howls through the crags as a stranger approaches...

    What do you do?
    1. Greet him with cold indifference
    2. Show a reluctant hint of courtesy
    3. Refuse him entry entirely

    [Stats: wisdom 55 | combat 70 | loyalty 90 | reputation 20]

---

Features 核心功能

Built-in Novels 内置小说

| Novel | Author | Characters | Scenes | Themes | |-------|--------|-----------|--------|--------| | Wuthering Heights 呼啸山庄 | Emily Brontë | Heathcliff, Catherine, Nelly, Edgar | 30 | Love, revenge, class, obsession | | Journey to the West 西游记 | 吴承恩 | 孙悟空, 唐僧, 猪八戒, 沙僧 | 27 | Adventure, loyalty, enlightenment |

PDF Novel Import 导入自定义小说

Import any novel as PDF — the engine auto-detects chapters, extracts character candidates, and generates a playable scene graph. Works with English, Chinese, and other languages.

Multi-Perspective Replay 多视角重玩

Play the same story as different characters. Experience Wuthering Heights as the vengeful Heathcliff, the torn Catherine, the observant Nelly, or the gentle Edgar — each with unique choices and narrative voice.

RPG Stats & Divergence 属性系统与偏离度

• 4 stats: Wisdom, Combat, Loyalty, Reputation — affect available choices
• Divergence score: Track how far you've strayed from the original plot (0–100)
• Achievements: Unlock milestones for both canon and alternate paths

Persistent Save System 持久存档

Save and resume across sessions. Your choices, stats, and relationships persist.

---

Install 安装

npx (recommended)

npx novel-rpg-skill

curl one-liner

curl -fsSL https://raw.githubusercontent.com/kiki123124/novel-rpg/main/install.sh | bash

git clone

git clone https://github.com/kiki123124/novel-rpg.git ~/.openclaw/skills/novel-rpg
python3 ~/.openclaw/skills/novel-rpg/scripts/book_manager.py init-builtins

Update & Uninstall

npx novel-rpg-skill update      # Update to latest version
npx novel-rpg-skill uninstall   # Remove completely

Optional: PDF Import Dependency

pip3 install PyMuPDF    # Required only for importing PDF novels

---

Usage 使用方式

Start a Game 开始游戏

Tell your AI assistant any of these trigger phrases:

• English: "novel rpg", "start adventure", "book rpg"
• 中文: "小说冒险", "开始冒险", "小说闯关", "novel rpg"

Import Your Own Novel 导入你的小说

python3 scripts/pdf_import.py import "my-novel.pdf" --book-id "my-novel" --title "My Novel" --author "Author Name"

After import, ask the AI to enrich the character profiles and add choice points to scenes.

---

How It Works 工作原理

Choose a book → Choose a character → Play through scenes
     ↓                  ↓                    ↓
  Loads scene       Initializes          AI narrates from
  graph (not        your POV,            your perspective,
  full text =       stats, and           presents 2-4
  token efficient)  relationships        choices per scene
                                              ↓
                                    Choices affect stats,
                                    relationships, and
                                    story divergence
                                              ↓
                                    Save progress, replay
                                    as different characters

Token efficient by design: Built-in novels use structured metadata (not full text), so the AI leverages its training knowledge. Only imported PDFs store text chunks.

---

CLI Reference 命令参考

# Book management
python3 scripts/book_manager.py list                              # List all books
python3 scripts/book_manager.py characters wuthering-heights      # Show playable characters
python3 scripts/book_manager.py init-builtins                     # Initialize built-in novels

# Game engine
python3 scripts/game_engine.py new-game wuthering-heights heathcliff  # Start new game
python3 scripts/game_engine.py list-saves                             # List all saves
python3 scripts/game_engine.py load <save-id>                         # Load a save
python3 scripts/game_engine.py delete <save-id>                       # Delete a save

# Scene retrieval
python3 scripts/scene_retriever.py context wuthering-heights ch09_s01     # Get scene context
python3 scripts/scene_retriever.py character wuthering-heights heathcliff # Get character info
python3 scripts/scene_retriever.py lookahead wuthering-heights ch09_s01   # Preview next scenes

# PDF import
python3 scripts/pdf_import.py import "book.pdf" --book-id id --title "Title"
python3 scripts/pdf_import.py status <book-id>                    # Check import status

---

Compatibility 兼容平台

| Platform | Status | Notes | |----------|--------|-------| | Claude Code | Fully supported | Install as skill, trigger with natural language | | OpenClaw (Telegram) | Fully supported | Auto-detected from ~/.openclaw/skills/ | | ChatGPT | Compatible | Copy SKILL.md as custom instructions + run scripts manually | | Any LLM | Compatible | Use SKILL.md as system prompt, scripts as tools |

---

FAQ 常见问题

Q: Do I need the original novel text for built-in books? No. Built-in novels (Wuthering Heights, Journey to the West) use structured metadata only. The AI uses its training knowledge to narrate scenes. This saves tokens and storage.

Q: What languages are supported for PDF import? The chapter detection supports Chinese (第X回/章) and English (Chapter X). Scene splitting works with any language.

Q: Can I add my own books without PDF? Yes. Create meta.json, characters.json, and plot_graph.json in data/books/<book-id>/ following the existing format.

Q: How does the divergence system work? Every non-canon choice adds +5 to your divergence score (0–100). Low divergence = classic experience. High divergence = alternate timeline with unique achievements.

---

Contributing 贡献

PRs welcome! Some ideas:

• Add more built-in novels (三国演义, Harry Potter, Pride and Prejudice...)
• Improve PDF chapter detection for more formats
• Add achievement definitions
• Multi-language narration support

---

License

MIT - Use it however you want.