Top Level

The “top level” of a file, which I often refer to as the “leftmost level of indentation”, is where a code is considered to be if it is not nested inside any other code blocks. Consider the following code:

image xia happy = "Characters/Xia/happy.png" # Top level
default xia_points = 0 # Top level

init python: # Top level
    def adjust_points(start, amount): # Not top level
        ## Make sure the provided number doesn't exceed 100
        return min(start+amount, 100) # Not top level

label start(): # Top level
    show xia happy # Not top level
    xia "This is some dialogue!" # Not top level
    return # Not top level

define xia = Character("Xia") # Top level

In the above code, image xia happy = "Characters/Xia/happy.png" on line 1, default xia_points = 0 on line 2, init python: on line 4, label start():on line 9, and define xia = Character("Xia") on line 14 are all considered to be at the “top level”. Colloquially, you can see why I refer to this as the leftmost level of indentation – visually, all of those lines are as far left as possible.

Just because it’s called the “top level” does not mean it’s literally at the top of the file. It just refers to anything at “indentation level 0” so to speak.

There are many things in Ren’Py that should be declared at the top level, like images, default and define, screens, ATL transforms, and more. Though Ren’Py is sometimes lenient on this and doesn’t throw errors when compiling and running your game, it is always preferred to get into the habit of putting these statements and blocks at the correct level of indentation to prevent confusion over when code runs and ensure compatibility with future versions of the engine.