Ren'Py Variable Strategy: When to Use `define` vs `default` for Game State

The Problem: Variables That Break Saves

When you’re mid‑development and need to add a new story flag, you face a critical choice: define or default? The wrong choice can make old saves unopenable or cause mysterious state loss during rollback. I’ve seen teams waste days debugging why a simple new variable caused everything to break.

The Core Difference

In Ren'Py’s store system, define runs during init phase—before the game starts and re‑evaluates from script on every run. It’s meant for constants: character objects, colors, transforms. Think of it as Python module‑level code that executes once per session.

default is lazy‑evaluated. It only assigns when that name doesn’t already exist in the current game state. This means it naturally handles save compatibility: if a save lacks the variable, default fills it in. If the save has it, default respects the saved value.

Worked Example: Adding a Trust Flag

Imagine you’re adding relationship tracking mid‑project:

# game/script.rpy - BEFORE adding the flag
label start:
    # ... existing story ...
    return

# Add this line anywhere in the file (not inside labels):
default trust = 0

label after_first_date:
    if trust >= 5:
        # ... happy ending branch ...
    else:
        # ... neutral branch ...
    return

Why this works: A save made before trust existed will load without error. When the branch evaluates, trust gets initialized to 0 if missing from the save. No NameError, no broken saves.

Testing Your Setup

Verify this locally with a minimal project:

1. default test_flag = 0 at file top level
2. Create a save from a point where test_flag exists
3. Add a new default new_var = "hello" used later in script
4. Load the old save—confirm no errors
5. Open developer console (Shift+O) and print(new_var) to verify value
6. Test rollback—confirm default-declared values revert properly

The Trade‑off: Value Migration

Limitation: Changing a default value later won’t update existing saves. If you initially set default coins = 10 and later change it to default coins = 5, players with existing saves keep their original 10 coins.

Solution: Use migration hooks for critical changes:

label after_load:
    if coins == 10:
        $ coins = 5  # Migrate old value
    return

Key Takeaways

• Use default for mutable story state: flags, counters, inventory
• Use define for constants: characters, colors, config values
• Avoid mutating defined values—they’re not save‑aware
• Test save compatibility after adding any variable
• Consider persistent for cross‑playthrough data: gallery unlocks, preferences

Check your Ren'Py version against official docs—behavior can shift between major branches. The in‑game developer console is invaluable for inspecting state after load and rollback operations.