Creating a Custom Main Menu in Ren'Py with Screen Language and ATL

Desired outcome

Replace Ren'Py's built‑in main menu with a custom screen that shows a background image, displays three buttons (Start, Preferences, Quit), and provides smooth hover animations using ATL. After following the guide you will be able to launch the project, see the custom menu, interact with the buttons, and revert to the default menu if needed.

Prerequisites

• Ren'Py 8.x SDK installed (tested with 8.2.2).
• A blank or existing Ren'Py project that launches without errors.
• A text editor that shows indentation (e.g., VS Code, Sublime Text).
• Two image files placed in the game/ folder:
  • menu_background.png – the background for the menu.
  • button_idle.png – optional base image for buttons (can be omitted if using text only).
• Basic familiarity with Ren'Py script syntax.

Focused procedure

1. Prepare the assets. Copy menu_background.png into game/. If you want a simple button background, copy button_idle.png as well. No additional declaration is required; Ren'Py automatically loads images from the game/ directory.

2. Edit or create screens.rpy. Open the file in your editor and add the following screen definition near the top (after any existing screens).

   # screens.rpy
   screen custom_main_menu:
       # Fixed layout positions elements relative to the window.
       fixed:
           # Background image stretched to fill the window.
           add "menu_background.png" xpos 0 ypos 0
   
           # Start button
           textbutton "Start" action Start() xpos 0.5 ypos 0.4 xanchor 0.5 yanchor 0.5:
               atl {
                   idle: alpha 1.0
                   hover: alpha 0.8 linear 0.2
               }
   
           # Preferences button
           textbutton "Preferences" action Preferences() xpos 0.5 ypos 0.5 xanchor 0.5 yanchor 0.5:
               atl {
                   idle: alpha 1.0
                   hover: alpha 0.8 linear 0.2
               }
   
           # Quit button
           textbutton "Quit" action Quit() xpos 0.5 ypos 0.6 xanchor 0.5 yanchor 0.5:
               atl {
                   idle: alpha 1.0
                   hover: alpha 0.8 linear 0.2
               }
   

   Explanation:

   • The fixed layout lets us place items with absolute coordinates.
   • add draws the background image.
   • Each textbutton uses a standard Ren'Py action (Start(), Preferences(), Quit()).
   • The atl block defines two states: idle (normal) and hover (when the mouse cursor is over the button). The alpha property changes opacity, creating a fade effect; you can replace it with zoom, rotate, etc.

3. Replace the default main menu. There are two common ways; choose one.

   • Option A – via label start:: At the very beginning of your script.rpy (or any early label), ensure the game calls your screen before any other content:

     label start:
         call screen custom_main_menu
         return
     

     This overrides the default menu because the start label is the entry point Ren'Py uses when launching.

   • Option B – via configuration: Add the following line to options.rpy (create the file if it doesn’t exist):

     # options.rpy
     config.main_menu_screen = "custom_main_menu"
     

     This tells Ren'Py to use the named screen as the main menu without modifying script.rpy.

4. Run the project. Launch the game using the Ren'Py launcher (Shift+Shift) or by executing renpy.exe from the command line in the project root:

   # From the project directory
   renpy.exe .
   

   You should see the background image and three buttons.

5. Expected checks:

   • The menu appears without any error messages in the console.
   • Hovering over a button triggers the ATL-defined fade (or other transform) smoothly.
   • Clicking Start begins the game (or jumps to your first label).
   • Clicking Preferences opens the preferences screen.
   • Clicking Quit closes the application cleanly.

6. Recovery options (if something goes wrong):

   • Open log.txt in the project directory. Look for lines indicating indentation errors, missing files, or undefined actions.
   • If the screen fails to show, temporarily comment out the custom menu call or configuration:

     # label start:
     #    call screen custom_main_menu
     #    return
     

     or

     # config.main_menu_screen = "custom_main_menu"
     

   • Restart the game; Ren'Py will fall back to its default main menu, allowing you to fix the issue.

Limitations and practical verification

This guide assumes you are using Ren'Py 8.x; older versions may lack certain ATL features or have different default menu handling. The ATL example uses only opacity changes; for more complex animations you can add zoom, rotate, or linear timing functions.

To verify that the custom menu is indeed being used, you can add a temporary diagnostic statement:

screen custom_main_menu:
    text "Debug: custom menu loaded" xpos 0.0 ypos 0.0 size 20 color "#ff0"
    # … rest of the screen as above

If the text appears in the top‑left corner, the screen is active. Remove it once you confirm the menu works.

Summary

By defining a screen in screens.rpy, adding ATL hover transforms, and either calling the screen from label start or setting config.main_menu_screen, you replace Ren'Py's default main menu with a fully customized, animated interface. Verify the result by launching the project, checking hover feedback and button actions, and keep the log.txt handy for quick rollback if needed.