simple-ink/README.md

simple-ink

一个用 Python 编写的命令行交互式小说框架：

• 从 YAML 配置加载剧情图
• 节点文本展示 + 选项分支
• 条件过滤与状态变化（简化 DSL）
• 支持存档/读档

快速开始

1. 安装依赖：

pip install -r requirements.txt

2. 运行示例故事：

python main.py --story data/main_story.yaml

配置结构

story_id: demo_story
start: intro
nodes:
  - id: intro
    text: 你的开场文本
    effects:
      - hp = 10
    options:
      - text: 前进
        target: next_node
        condition: hp > 0
        effects:
          - hp -= 1

字段说明：

• story_id: 故事标识
• start: 起始节点 ID
• nodes: 节点列表
• node.id: 节点唯一 ID
• node.text: 显示文本
• node.options: 选项列表
• node.effects: 进入该节点时执行的状态变化
• node.end: true 表示终局
• option.text: 选项文本
• option.target: 目标节点 ID
• option.condition: 选项显示条件
• option.effects: 选择该选项后执行的状态变化

DSL 语法

condition

支持：

• 比较：== != > >= < <=
• 逻辑：and or not
• 变量名直接引用：has_key（不存在变量视为 False）
• 例子：
  • hp > 0 and not is_cursed
  • coins >= 1
  • "lamp" in flags

effect

支持：

• 赋值：hp = 10、is_cursed = false
• 数值增减：hp += 2、coins -= 1
• 标记集合（flags）：flags += lamp、flags -= lamp

交互命令

游戏运行时可输入：

• :help 显示命令
• :state 显示当前状态
• :save [路径] 保存进度（默认 saves/latest.json）
• :load [路径] 读取进度（默认 saves/latest.json）
• :quit 退出

测试

pytest -q