# Saving, Loading, and Rollback

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:

    init python:
        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, statements (including variable assignments) that are added to the game 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:

    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 Ren'Py script - rather than Python - to loop 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.

## Retaining Data After Load

When a game is loaded, the state of the game is reset (using the rollback system described below) to the state of the game when the current statement began executing.

In some cases, this may not be desirable. For example, when a screen allows editing of a value, we may want to retain that value when the game is loaded. When renpy.retain_after_load is called, data will not be reverted when a game is saved and loaded before the end of the next checkpointed interaction.

Note that while data is not changed, control is reset to the start of the current statement. That statement will execute again, with the new data in place at the start of the statement.

For example:

    screen edit_value:
        hbox:
            text "[value]"
            textbutton "+" action SetVariable("value", value + 1)
            textbutton "-" action SetVariable("value", value - 1)
            textbutton "+" action Return(True)

    label start:
        $ value = 0
        $ renpy.retain_after_load()
        call screen edit_value

## 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.)

## Blocking Rollback

Warning

Blocking rollback is a user-unfriendly thing to do. If a user mistakenly clicks on an unintended choice, he or she will be unable to correct their mistake. Since rollback is equivalent to saving and loading, your users will be forced to save more often, breaking game engagement.

It is possible to disable rollback in part or in full. If rollback is not wanted at all, it can simply be turned off through the `config.rollback_enabled` option.

More common is a partial block of rollback. This can be achieved by the `renpy.block_rollback()` function. When called, it will instruct Ren'Py not to roll back before that point. For example:

    label final_answer:
        "Is that your final answer?"

    menu:
        "Yes":
            jump no_return
        "No":
            "We have ways of making you talk."
            "You should contemplate them."
            "I'll ask you one more time..."
            jump final_answer

    label no_return:
        $ renpy.block_rollback()

        "So be it. There's no turning back now."

When the label no_return is reached, Ren'Py won't allow a rollback back to the menu.

## Fixing Rollback

Fixing rollback provides for an intermediate choice between unconstrained rollback and blocking rollback entirely. Rollback is allowed, but the user is not allowed to make changes to their decisions. Fixing rollback is done with the `renpy.fix_rollback()` function, as shown in the following example:

    label final_answer:
        "Is that your final answer?"
    menu:
        "Yes":
            jump no_return
        "No":
            "We have ways of making you talk."
            "You should contemplate them."
            "I'll ask you one more time..."
            jump final_answer

    label no_return:
        $ renpy.fix_rollback()

        "So be it. There's no turning back now."

Now, after the fix_rollback function is called, it will still be possible for the user to roll back to the menu. However, it will not be possible to make a different choice.

There are some caveats to consider when designing a game for fix_rollback. Ren'Py will automatically take care of locking any data that is given to `checkpoint()`. However, due to the generic nature of Ren'Py, it is possible to write Python that bypasses this and changes things in ways that may have unpredictable results. It is up to the game designer to block rollback at problematic locations or write additional Python to deal with it.

The internal user interaction options for menus, `renpy.input()` and `renpy.imagemap()` are designed to fully work with fix_rollback.

## Styling Fixed Rollback

Because fix_rollback changes the functionality of menus and imagemaps, it is advisable to reflect this in the appearance. To do this, it is important to understand how the widget states of the menu buttons are changed. There are two modes that can be selected through the `config.fix_rollback_without_choice` option.

The default option will set the chosen option to "selected", thereby activating the style properties with the "selected_" prefix. All other buttons will be made insensitive and show using the properties with the "insensitive_" prefix. Effectively this leaves the menu with a single selectable choice.

When the `config.fix_rollback_without_choice` option is set to False, all buttons are made insensitive. This means that the chosen option will use the "selected_insensitive_" prefix for the style properties while the other buttons use properties with the "insensitive_" prefix.

## Fixed Rollback and Custom Screens

When writing custom Python routines that must play nice with the fix_rollback system there are a few simple things to know. First of all the `renpy.in_fixed_rollback()` function can be used to determine whether the game is currently in fixed rollback state. Second, when in fixed rollback state, `ui.interact()` will always return the supplied roll_forward data regardless of what action was performed. This effectively means that when the `ui.interact()`/`renpy.checkpoint()` functions are used, most of the work is done.

To simplify the creation of custom screens, two actions are provided to help with the most common uses. The `ui.ChoiceReturn()` action returns the value when the button it is attached to is clicked. The `ui.ChoiceJump()` action can be used to jump to a script label. However, this action only works properly when the screen is called trough a `call screen` statement.

Example:

    screen demo_imagemap:
        imagemap:
            ground "imagemap_ground.jpg"
            hover "imagemap_hover.jpg"
            selected_idle "imagemap_selected_idle.jpg"
            selected_hover "imagemap_hover.jpg"

            hotspot (8, 200, 78, 78) action ui.ChoiceJump("swimming", "go_swimming", block_all=False)
            hotspot (204, 50, 78, 78) action ui.ChoiceJump("science", "go_science_club", block_all=False)
            hotspot (452, 79, 78, 78) action ui.ChoiceJump("art", "go_art_lessons", block_all=False)
            hotspot (602, 316, 78, 78) action uiChoiceJump("home", "go_home", block_all=False)

Example:

    python:
        roll_forward = renpy.roll_forward_info()
        if roll_forward not in ("Rock", "Paper", "Scissors"):
            roll_forward = None

        ui.hbox()
        ui.imagebutton("rock.png", "rock_hover.png", selected_insensitive="rock_hover.png", clicked=ui.ChoiceReturn("rock", "Rock", block_all=True))
        ui.imagebutton("paper.png", "paper_hover.png", selected_insensitive="paper_hover.png", clicked=ui.ChoiceReturn("paper", "Paper", block_all=True))
        ui.imagebutton("scissors.png", "scissors_hover.png", selected_insensitive="scissors_hover.png", clicked=ui.ChoiceReturn("scissors", "Scissors", block_all=True))
        ui.close()

        if renpy.in_fixed_rollback():
            ui.saybehavior()

        choice = ui.interact(roll_forward=roll_forward)
        renpy.checkpoint(choice)

    $ renpy.fix_rollback()
    m "[choice]!"

## Rollback-blocking and -fixing Functions

## NoRollback

For example:

    init python:

        class MyClass(NoRollback):
            def __init__(self):
                self.value = 0

    label start:
        $ o = MyClass()

        "Welcome!"

        $ o.value += 1

        "o.value is [o.value]. It will increase each time you rolllback and then click ahead."