This page is out of date

You've reached a page on the Ren'Py wiki. Due to massive spam, the wiki hasn't been updated in over 5 years, and much of the information here is very out of date. We've kept it because some of it is of historic interest, but all the information relevant to modern versions of Ren'Py has been moved elsewhere.

Some places to look are:

Please do not create new links to this page.


Style Customization Tutorial

By default, Ren'Py games are made with a usable but relatively generic style. The purpose of this tutorial is to teach you how to customize the Ren'Py style system to make your game more attractive.

Before we start, we should note that the style system is only one way to customize your game, and may not be able to accomplish all customizations.

This tutorial is divided into two parts. The first part gives canned recipes for the most common style customizations. The second part explains how to customize any style and style property in the system, using the style inspector and style tree tools.

Common Style Customizations

Customize Any Style

The first thing one needs to do to when customizing styles is to determine which style it is you really want to customize. The easiest way to do this is to use the style inspector. It's also possible to use the style heirarchy tool to determine styles.

Style Inspector

To use the style inspector, place the mouse over any element in the game, and press shift+I. If nothing happens, then set to True, and restart your game. Otherwise, a screen similar to the following will pop up, showing the styles and Displayables underneath the mouse.

Style Inspector.png
Style Inspector.png

This screenshot was created by hovering over the "Start Game" button on the demo game main menu, and pressing shift+I.

Each line contains the following three fields:

  1. The kind of displayable that is being shown.
  2. The name of the style that is being used by that displayable.
  3. The size of the displayable.

The lines are arrange in the order that things are drawn on the screen, so that the first line is the farthest from the user, and the last line is closest to the user. Indentation is used to represent nesting of displayables. Such nesting may affect the positioning of the various displayables.

Style Hierarchy

Styles may inherit from each other. The precise nature of style inheritance varies based on the layouts and themes that are being used. For a full accounting of styles the system knows about, hit shift+D and choose "Style Hierarchy". This will display a list of styles that the system knows about.

The styles that can be expected by all games to exist are:

layout.button_menu

Invoking , as the default game template does, makes a couple of changes to the default style hierarchy.

This makes menu choices look like buttons.

Style Indexing and Inheritance

Some styles used by the game may be index. For example, the style mm_button[u"Start Game"] is the style mm_button indexed with the string u"Start Game". Indexing is used to specifically customize a single button or label.

According to the style hierarchy tool, the default inheritance hierarchy for the mm_button style is:

  1. mm_button
  2. button
  3. default

When indexed with u"Start Game", it becomes.

  1. mm_button[u"Start Game"]
  2. mm_button
  3. button[u"Start Game"]
  4. button
  5. default[u"Start Game"]
  6. default

Ren'Py will look at styles in this order until it finds the first style in which a value for the property is defined.

Setting Style Properties

Each displayable is in one of two roles, selected or unselected. The selected role is used, for example, to indicate the page that is being shown, or the current value of a preference. The unselected role is used for all other displayables.

Each displayable is in one of four states:

The roles and states correspond to prefixes that are applied to style properties. The role prefixes are:

The state prefixes are:

To set a property, one assigns a value to the python expression:

style.<style name>.<role prefix><state prefix><property>

For example:

init python:
    style.mm_button.background = "#f00"
    style.mm_button.hover_background = "#ff0"
    style.mm_button.selected_hover_background = "#00f"
    style.mm_button[u"Start Game"].background = "#0f0"

The first line sets the background of all main menu buttons to be red. The second changes the background of hovered main menu buttons to be yellow. The third changes selected and hovered main menu buttons to be blue - this doesn't actually do anything, since main menu buttons are never selected. Finally, the last one changes the index style to have a green background. Since the indexed style is hire in the inheritance order, it will take precedence over all other styles.

Note that the order of statements matters. The code:

init python:
    style.mm_button.hover_background = "#ff0"
    style.mm_button.background = "#f00"

Will cause hovered main menu buttons to have a red background. This is because the second statement, which sets all roles and states, takes precedence over the first statement. Generally, it makes sense to set the unprefixed properties first, and the prefixed properties second.