持久化数据

本页属于 GenPy Ren'Py 学习路线。教程内容面向 Ren'Py 8.x，并在页面末尾连接到 GenPy 的对应工作流。

学习目标

• 了解“持久化数据”在 Ren'Py 项目中的用途。
• 能在一个最小项目里验证本章相关语法或工作流。
• 知道发布前需要检查的常见风险，并能在 GenPy 中继续维护。

核心语法

• persistent
• default persistent
• achievement
• renpy.seen_label

可运行示例

# 读写 persistent.<名字>，自动持久化到磁盘
$ persistent.cleared_chapter1 = True

label start:
    if persistent.cleared_chapter1:
        "欢迎回来，老玩家。"

教程正文

persistent 是跨存档、跨周目的全局数据：无论玩家读哪个存档、玩多少遍，它都保留。 适合存“成就、图鉴解锁、通关记录、全局设置、新游戏+标记”等。

1. 基本用法

# 读写 persistent.<名字>，自动持久化到磁盘
$ persistent.cleared_chapter1 = True

label start:
    if persistent.cleared_chapter1:
        "欢迎回来，老玩家。"

• 直接给 persistent.x 赋值即可，引擎自动保存。
• 玩家退出后再进，值依然在。

2. 设默认值（避免 None）

未赋值的 persistent 字段初值是 None。用 default persistent.x 设默认：

default persistent.play_count = 0
default persistent.unlocked = set()

label start:
    $ persistent.play_count += 1
    "这是你第 [persistent.play_count] 次开始游戏。"

3. 典型用途

成就

default persistent.achievements = set()

label get_ending_a:
    $ persistent.achievements.add("ending_a")
    "解锁成就：结局 A"

图鉴 / CG 画廊解锁

default persistent.unlocked_cg = set()
label show_cg_beach:
    $ persistent.unlocked_cg.add("beach")
    scene cg beach

配合 image gallery（第 21 章）只展示已解锁 CG。

新游戏+ / 多周目分支

default persistent.cleared_once = False
label start:
    if persistent.cleared_once:
        menu:
            "进入隐藏路线":
                jump secret_route
            "普通开始":
                jump normal

4. 内置成就 API（Achievements）

Ren'Py 提供成就系统，可对接 Steam 等平台：

init python:
    achievement.register("ending_a")

label get_ending_a:
    $ achievement.grant("ending_a")    # 解锁（同时同步到平台，如已配置）

achievement.* 内部也用 persistent 记录，并可桥接 Steamworks。

5. 持久化的内置项

一些引擎/偏好数据也存在 persistent，例如：

• 玩家的音量、文字速度等偏好（preferences，与 persistent 协同）。
• persistent._seen_images、已读文本记录等（引擎维护，用于“已读快进”“CG 是否看过”）。

可用 renpy.seen_label("x")、renpy.seen_image("y") 查询是否见过。

6. 修改/迁移 persistent 结构

游戏更新后若改了 persistent 结构，用 config.after_load_callbacks 或在 init python 里做迁移：

init python:
    if persistent.unlocked is None:
        persistent.unlocked = set()

default persistent.x 也能优雅处理“老玩家没有该字段”的情况。

7. persistent vs 普通存档变量

维度	普通变量（default/$）	persistent
作用范围	单个存档	全局，跨所有存档/周目
回滚影响	会被回滚还原	不被回滚还原
典型用途	当前剧情状态	成就、图鉴、通关、全局设置

常见坑

• 未初始化的 persistent 字段是 None，先 default persistent.x = ... 再用，避免报错。
• persistent 是全局的：别把“当前周目剧情进度”塞进去，那应放普通存档变量。
• persistent 也用 pickle，别存不可序列化对象。
• 删除测试数据：玩家本地的 persistent 文件在系统的游戏数据目录下（开发期可清掉重测）。

官方参考

• 持久化数据：https://www.renpy.org/doc/html/persistent.html
• 成就：https://www.renpy.org/doc/html/achievement.html

在 GenPy 里怎么做

• 在 GenPy 的代码模式中维护相关 .rpy 文件，先保持语法清晰，再逐步加入本章功能。
• 用故事图谱、变量、校验或演出编辑器把“能运行”提升到“可维护”。
• 导出前结合 Ren'Py Lint 和 GenPy 校验结果，确认脚本、素材和发布路径一致。

推荐继续阅读：

• 变量
• 插件系统
• 脚本校验