Ren'Py has support for saving game state, loading game state, and rolling back to a previous game state. Although implemented in a slightly different fashion, rollback can be thought of as saving the game at the start of each statement that interacts with the user, and loading saves when the user rolls back.
Note
While we usually attempt to keep save compatibility between releases, this compatibility is not guaranteed. We may decide to break save-compatibility if doing so provides a sufficiently large benefit.
What is Saved
Ren'Py attempts to save the game state. This includes both internal state and python state.
The internal state consists of all aspects of Ren'Py that are intented to change once the game has started, and includes:
The current statement, and all statements that can be returned to.
The images and displayables that are being shown.
The screens being shown, and the values of variables within those screens.
The music that Ren'Py is playing.
The list of nvl-mode text blocks.
The python state consists of the variables in the store that have changed since the game began, and all objects reachable from those variables. Note that it's the change to the variables that matters - changes to fields in objects will not cause those objects to be saved.
In this example:
define a =1
define o =object() label start:
$ b =1
$ o.value=42
only b will be saved. A will not be saved because it does not change once the game begins. O is not saved because it does not change - the object it refers to changes, but the variable itself does not.
What isn't Saved
Python variables that are not changed before the game begins will not be saved. This can be a major problem if a variable that is saved and one that is refer to the same object. (Alias the object.) In this example:
initpython: a =object() a.f =1 label start:
$ b = a $ b.f =2
"a.f=[a.f] b.f=[b.f]"
a and b are aliased. Saving and loading may break this aliasing, causing a and b to refer to different objects. Since this can be very confusing, it's best to avoid aliasing saved and unsaved variables. (This is rare to encounter directly, but might come up when an unsaved variable and saved field alias.)
There are several other kinds of state that isn't saved:
control flow path
Ren'Py only saves the current statement, and the statement it needs to return to. It doesn't remember how it got there. Importantly, if code (like variable assignments) is added to the game, it won't run.
mappings of image names to displayables
Since this mapping is not saved, the image may change to a new image when the game loads again. This allows an image to change to a new file as the game evolves.
configuration variables, styles, and style properties
Configuration variables and styles aren't saved as part of the game. Therefore, they should only be changed in init blocks, and left alone once the game has started.
Where Ren'Py Saves
Saves occur at the start of a Ren'Py statement in the outermost interaction context.
What's important here is to note that saving occurs at the start of a statement. If a load or rollback occurs in the middle of a statement that interacts multiple times, the state will be the state that was active when the statement began.
This can be a problem in python-defined statements. In code like:
python: i =0
while i <10: i +=1
narrator("The count is now [i].")
if the user saves and loads in the middle, the loop will begin anew. Using similar code in Ren'Py - rather than Python - avoids this problem.:
$ i =0
while i <10: $ i +=1
"The count is now [i]."
What Ren'Py can Save
Ren'Py uses the python pickle system to save game state. This module can save:
Basic types, such as True, False, None, int, str, float, complex, str, and unicode objects.
Compound types, like lists, tuples, sets, and dicts.
Creator-defined objects, classes, functions, methods, and bound methods. For pickling these functions to succeed, they must remain available under their original names.
Character, Displayable, Transform, and Transition objects.
There are certain types that cannot be pickled:
Render objects.
Iterator objects.
File-like objects.
Inner functions and lambdas.
By default, Ren'Py uses the cPickle module to save the game. Setting config.use_cpickle will make Ren'Py use the pickle module instead. This makes the game slower, but is better at reporting save errors.
Save Functions and Variables
There is one variable that is used by the high-level save system:
save_name
= ...This is a string that is stored with each save. It can be used to give a name to the save, to help users tell them apart.
There are a number of high-level save actions and functions defined in the screen actions. In addition, there are the following low-level save and load actions.
renpy.
can_load (
filename, test=False)
Returns true if filename exists as a save file, and False otherwise.
renpy.
list_saved_games (
regexp='.', fast=False)
Lists the save games. For each save game, returns a tuple containing:
The filename of the save.
The extra_info that was passed in.
A displayable that, when displayed, shows the screenshot that was used when saving the game.
The time the game was stayed at, in seconds since the UNIX epoch.
regexp
A regular expression that is matched against the start of the filename to filter the list.
fast
If fast is true, the filename is returned instead of the tuple.
renpy.
load (
filename)
Loads the game state from filename. This function never returns.
renpy.
rename_save (
old, new)
Renames a save from old to new.
renpy.
save (
filename, extra_info='')
Saves the game state to a save slot.
filename
A string giving the name of a save slot. Despite the variable name, this corresponds only loosely to filenames.
extra_info
An additional string that should be saved to the save file. Usually, this is the value of save_name.
renpy.take_screenshot() should be called before this function.
renpy.
take_screenshot (
scale=None, background=False)
Causes a screenshot to be taken. This screenshot will be saved as part of a save game.
renpy.
unlink_save (
filename)
Deletes the save with the given filename. Rollback
Rollback allows the user to revert the game to an earlier state in much the same way as undo/redo systems that are available in most modern applications. While the system takes care of maintaining the visuals and game variables during rollback events, there are several things that should be considered while creating a game.
Supporting Rollback and Roll Forward
Most Ren'Py statements automatically support rollback and roll forward. If you call
ui.interact() directly, you'll need to add support for rollback and roll-forward yourself. This can be done using the following structure:
# This is None if we're not rolling back, or else the value that was
# passed to checkpoint last time if we're rolling forward.
roll_forward = renpy.roll_forward_info()
# Set up the screen here...
# Interact with the user.
rv = ui.interact(roll_forward=roll_forward)
# Store the result of the interaction.
renpy.checkpoint(rv)
It's important that your game does not interact with the user after renpy.checkpoint has been called. (If you do, the user may not be able to rollback.)
renpy.
checkpoint (
data=None)
Makes the current statement a checkpoint that the user can rollback to. Once this function has been called, there should be no more interaction with the user in the current
statement.
data
This data is returned by renpy.roll_forward_info() when the game is being rolled back.