documentation index

## Branching & Recombining the Story

Short branches can be accomplished entirely with the menu statement by including the entire branch indented after the menu option. For longer branches, however, this will get cumbersome. The solution is to use labels and the jump statement or the call statement.

The first thing that you'll have to decide is whether you're going to use call or jump. Jump simply changes where in the script Ren'Py is executing, and that's it. The new place of execution in the script can only move forward; there's no such thing as returning from a jump, though you could always jump to a label after the original jump. Thus you can't easily re-use jump-branches from multiple places in your script. For a visual novel, jump will probably be sufficient.

Call, by contrast, saves information about where you were, so that the branch being called can automatically return to the right place. With call, you can easily re-use branches. Dating sims will probably want to use call.

You can, of course, use both types of branching in the same visual novel (or dating sim). Mixing and matching is fine, so long as any single branch is only either a call-branch or a jump-branch..

### Branching with Jump

The first step of branches using jump is to mark places in your script using the label statement:

    label jewelry_store:
    b "Let's go to the jewelry store. I'd like to buy you something."

    s "You're so sweet!"

Next, you add the jump to the branch:

    s "What do you want to do?"

    menu:
        "Let's go to the jewelry store":
            jump jewelry_store
            #we'll never go past the jump statement, since it doesn't return
        "Let's do nothing":
            s "This is boring."

Congratulations, you've branched with jump!

Unless this branch runs to the end of the game, you will probably want your branch to jump to other places in the script. This is done in the same way; branches are not special and you can jump to anywhere you want even though you're in a branch. For example, suppose that in the above example you want to go back to after the menu from the branch. First, you add a label after the menu so that you have somewhere to jump to:

    s "What do you want to do?"

    menu:
        "Let's go to the jewelry store":
            jump jewelry_store
            #we'll never go past the jump statement, since it doesn't return
        "Let's do nothing":
            s "This is boring."

    label what_to_do:
    b "Well, now what?"

Then you add a jump to the end of the branch:

    label jewelry_store:
    b "Let's go to the jewelry store. I'd like to buy you something."

    s "You're so sweet!"

    b "I am."

    s "Well, that's enough. Let's go back."

    jump what_to_do

Please note that labels have to be unique within a Ren'Py script.

### Branching with Call

The first step of branches using call is to mark a branch in your script using the label statement and the return statement:

    label jewelry_store:
        b "Let's go to the jewelry store. I'd like to buy you something."

        s "You're so sweet!"

        etc.

        return

(NOTE: it's very important that a call-branch should never be entered either with a jump or by normal script flow. If it is, the return statement at the end of the branch will cause the game to immediately end. A return statement outside of a call is actually the correct way to end the game: the metaphore is that since the game came from the starting menu, a return statement in the main story would go back to the starting menu.)

Next, you add the jump to the branch:

    s "What do you want to do?"

    menu:
        "Let's go to the jewelry store":
            call jewelry_store
            s "That was fun"
        "Let's do nothing":
            pass

Congratulations, you've branched with call! Unfortunately, you're not done.

You don't need to do anything while you're still writing your game, but when you're ready to release your game, you'll need to run the "Add From to Calls" tool in the Ren'Py launcher to add labels below your call statement and from clauses to all of your call statements.

### A Note on Organization

There is no consensus on the best way to organize branches. It is, however, recommended that you come up with some way to organize your branches and stick to it.

If you use multiple files to organize your script, please bear in mind that labels are visible from any file, so jumping to a label in a different file is exactly the same as jumping to a label in the same file. Since labels have to be unique in a Ren'Py script, this means that you can't re-use labels in different files of the same Ren'Py game.

Previous: Remembering User Choices | Ren'Py Web Tutorial | Next: Adding Music & Sound Effects

documentation index