Reference Manual: (offline | online) Quickstart: (offline | online)

# Configuration Variables

Much of the the configuration of Ren'Py is done using configuration variable. These variables, when assigned in a python block, change the behavior of the interpreter. As configuration variables aren't saved, and many need to be set before the GUI initializes, it makes sense to set all configuration variable inside init blocks. An example setting of variables is:

    init:
        $ config.screen_width = 640
        $ config.screen_width = 480

Variable: config.afm_bonus = | 25

The number of bonus characters added to every string when auto-forward mode is in effect.

Variable: config.afm_callback = | None

If not None, a python function that is called to determine if it is safe to auto-forward. The intent is that this can be used by a voice system to disable auto-forwarding when a voice is playing.

Variable: config.afm_characters = | 250

The number of characters in a string it takes to cause the amount of time specified in the auto forward mode preference to be delayed before auto-forward mode takes effect.

Variable: config.all_preferences = | dict(...)

This is a map from preference name to the preference object implementing that preference. This variable shouldn't be modified by the user directly, but instead provides a stable source of preferences that can be added to config.preferences.

Variable: config.allow_skipping = | True

If set to False, the user is not able to skip over the text of the game.

Variable: config.always_has_joystick = | False

If True, the joystick interface is always available. This may be used by people without joysticks to see the joystick interface for themeing purposes.

Variable: config.archives = | [ ]

A list of archive files that will be searched for images.

Variable: config.auto_choice_delay = | None

If not None,this variable gives a number of seconds that Ren'Py will pause at an in-game menu before picking a random choice from that menu. We'd expect this variable to always be set to None in released games, but setting it to a number will allow for automated demonstrations of games without much human interaction.

Variable: config.button_properties = | {

}

A map from the (untranslated) name of a button, to additional properties that will be supplied when that button is created.

Variable: config.button_text_properties = | {

}

A map from the (untranslated) name of a button, to additional properties that will be supplied when that button's text is created.

Variable: config.character_callback = | None

The default value of the callback parameter of Character .

Variable: config.debug = | False

Enables some minor debugging functionality (mostly by turning some missing files into errors.) This should always be turned off in a release.

Variable: config.debug_image_cache = | False

If True, Ren'Py will print the contents of the image cache to standard output (wherever that goes) whenever the contents of the image cache change.

Variable: config.debug_sound = | False

Enables debugging of sound functionality. This disables the supression of errors when generating sound. However, if a sound card is missing or flawed, then such errors are normal, and enabling this may prevent Ren'Py from functioning normally. This should always be False in a released game.

Variable: config.default_fullscreen = | None

This sets the default value of the fullscreen preference. This should be True or False. If None, this is ignored, allowing other code to set the default value. (It's usually set to False in options.rpy.)

The file saves/persistent in the game directory must be deleted for this to take effect.

Variable: config.default_text_cps = | None

If not None, this sets the default number of characters per second to show. 0 is special cased to mean an infinite number of characters per second. (It's usually set to 0 in options.rpy.)

The file saves/persistent in the game directory must be deleted for this to take effect.

Variable: config.developer = | False

If set to True, developer mode is enabled.

Variable: config.disable_file_pager = | False

If True, there will be only a single page of file in the file picker.

Variable: config.disable_thumbnails = | False

If True, the file picker will not show thumbnails.

Variable: config.editor = | None

If not None, this is expected to be a command-line for an editor that is invoked when the launch_editor (normally shift-E) key is pressed. There are two subsitutions that make sense here. %(filename)s is replaced with the filename of the currently-executing line of Ren'Py code. %(line)d is replaced with the line number of the currently-executing line of Ren'Py code.

Variable: config.enable_fast_dissolve = | True

Setting this to False can fix a potential bug in the dissolve transition when used with an overlay layer that has an alpha channel that is not fully transparent or opaque, at the cost of 25% of the performance of dissolve. It usually can be kept at True with no ill effects.

Variable: config.enter_sound = | None

If not None, this is a sound file that is played when entering the game menu without clicking a button. (For example, when right-clicking during the game.)

Variable: config.enter_transition = | None

If not None, this variable should give a transition that will be used when entering the game menu.

Variable: config.exit_sound = | None

If not None, this is a sound file that is played when exiting the game menu without clicking a button. (For example, when right-clicking inside the game menu.)

Variable: config.exit_transition = | None

If not None, this variable should give a transition that will be performed when exiting the game menu.

Variable: config.fade_music = | 0.0

This is the amount of time in seconds to spend fading the old track out before a new music track starts. This should probably be fairly short, so the wrong music doesn't play for too long.

Variable: config.fast_skipping = | False

Set this to True to allow fast skipping outside of developer mode.

Variable: config.file_page_cols = | 2

This is the number of columns of save slots that are show in the picker that's used in the load and save screens of the game menu.

Variable: config.file_page_rows = | 5

This is the number of rows of save slots that are show in the picker that's used in the load and save screens of the game menu.

Variable: config.file_picker_positions = | None

If not None, elements of the file picker are rendered at the top level of the game menu, at the specified positions. Elements are named as follows

- nav_Previous - The previous page button.
- nav_Next - The next page button.

- nav_number - The quick access button to page number (nav_1, nav_2, etc.).

- entry_number - File picker entry number number. (entry_1, entry_2).

Positions are specified as a dict of position properties.

Variable: config.file_quick_access_pages = | 5

The number of pages of the file picker to provide quick access to. Quick access is provided by number buttons which are at the top of the file picker.

Variable: config.focus_crossrange_penalty = | 1024

This is the amount of penalty to apply to moves perpendicular to the selected direction of motion, when moving focus with the keyboard.

Variable: config.font_replacement_map = | dict()

This is a map from (font, bold, italics) to (font, bold, italics), used to replace a font with one that's specialized as having bold and/or italics. For example, if you wanted to have everything using an italic version of "Vera.ttf" use "VeraIt.ttf" instead, you could write config.font_replacement_map["Vera.ttf", False, True] = ("VeraIt.ttf", False, False). Please note that these mappings only apply to specific variants of a font. In this case, requests for a bold italic version of vera will get a bold italic version of vera, rather than a bold version of the italic vera.

Variable: config.game_menu = | [ ... ]

This is used to customize the choices on the game menu. Please read Customizing the Main and Game Menus for more details on the contents of this variable.

Variable: config.game_menu_music = | None

If not None, a music file to play when at the game menu.

Variable: config.game_menu_positions = | None

If not None, this is a map between the default label for buttons on the game menu, and a dictionary containing properties that are applied to that button. This provides a simple way of customizing the game menu by changing where buttons are located on the screen. Please note that this disables the usual button-placement algorithm, so if one button is positioned this way, all must be.

Variable: config.hard_rollback_limit = | 10

This is the number of steps that Ren'Py will let the user interactively rollback. Set this to 0 to disable rollback entirely, although we don't recommend that, as rollback is useful to let the user see text he skipped by mistake.

Variable: config.has_afm = | True

If True, the preference for auto-forward mode is shown to the user.

Variable: config.has_cps = | True

If True, the preference for changing the text speed is shown to the user.

Variable: config.has_music = | True

If True, the preference for enabling and disabling music will be presented to the user. This should be set to False if the game does not play any music.

Variable: config.has_skip_after_choices = | True

If True, the preference enabling skip after choices will be shown to the user.

Variable: config.has_skipping = | True

If True, the preference controlling what TAB and CTRL skip will be shown to the user.

Variable: config.has_sound = | True

If True, the preference for enabling and disabling sound effects is presented to the user. This should be set to False if the game does not have any sound effects.

Variable: config.has_transitions = | True

If True, the preference for enabling and disabling transitions is presented to the user. This should be set to False if the game does not have any transitions (that is, never uses the with statement or clause).

Variable: config.hbox_pref_choices = | False

If True, the choice buttons in a preference will be placed together in an hbox.

Variable: config.hyperlink_callback = | ...

A function that is called with the argument to a hyperlink when that hyperlink is clicked. Defaults to a function that inteprets the argument as a label, which is called in a new context when the hyperlink is clicked.

Variable: config.image_buttons = | { }

A map from button labels to 5 tuples giving the (idle, hover, selected idle, selected hover, disabled) images used for main and game menu buttons with the given label. If a label isn't present in the dictionary, text buttons are used instead. New in 5.6.5.

Variable: config.image_cache_size = | 8

This is used to set the size of the image cache, as a multiple of the screen size. This is mostly a suggestion, as if Ren'Py ever needs to display more than this amount of images at once, it will cache them all. But it will stop predictively loading images when the cache is filled beyond this, and it will try to drop images from the cache until it shrinks below this size. If this is too small, there will be more disk access as images are loaded and re-loaded. If this is too large, memory usage will be increased as images are kept in memory.

Variable: config.image_labels = | { }

A map from a game or main menu label to an image that is used for that label. If a label isn't present here, it's rendered as text. New in 5.6.5.

Variable: config.implicit_with_none = | True

If True, then by default the equivalent of a "with None" statement will be performed after interactions caused by dialogue (through the Character object), menus (and renpy.display_menu ), renpy.input , and renpy.imagemap .

All of the above functions take a with_none parameter, which will override this variable.

Variable: config.interact_callbacks = | ...

A list of functions that are called (without any arguments) when an interaction is started or restarted.

Variable: config.joystick = | True

Governs if joystick support is enabled. If False, Joystick detection is disabled.

Variable: config.joystick_keys = | [ ... ]

This is a listing of all the joystick synthetic keys known to Ren'Py. It's a list of visible name, keysym pairs. Ren'Py uses this to populate the joystick preferences. See Customizing the Keymap for more information.

Variable: config.joystick_preference_positions = | None

If not None, this should be a dictionary mapping preferences to positions, similar to config.preference_positions . The only key that's sensible to use here is 'Joystick Configuration'.

Variable: config.keymap = | dict(...)

This variable contains a keymap giving the keys and mouse buttons assigned to each possible operation. Please see the section on Keymaps for more information.

Variable: config.label_properties = | {

}

A map from the (untranslated) name of a label, to additional properties that will be supplied when that label is created.

Variable: config.layer_clipping = | {

}

Controls layer clipping. This is a map from layer names to (x, y, height, width) tuples, where x and y are the coordinates of the upper-left corner of the layer, with height and width giving the layer size.

If a layer is not mentioned in config.layer_clipping, then it is assumed to take up the full screen.

Variable: config.layers = | [ 'master', 'transient', 'overlay' ]

This variable gives a list of all of the layers that Ren'Py knows about, in the order that they will be displayed to the screen. (The lowest layer is the first entry in the list.) Ren'Py uses the layers "master", "transient", and "overlay" internally, so they should always be in this list.

Variable: config.lint_hooks = | ...

This is a list of functions that are called, with no arguments, when lint is run. The functions are expected to check the script data for errors, and print any they find to standard output (using the python print statement is fine in this case).

Variable: config.load_before_transitions = | True

If True, the start of transitions will be delayed until the images used by said transitions have finished loading.

Variable: config.log = | None

If not None, this is expected to be a filename. Much of the text shown to the user by say or menu statements will also be logged to this file.

Variable: config.main_menu = | [ ( "Start Game", "start", "True" ), ("Continue Game", ... ), ("Preferences", ... ), ("Quit Game", ...) ]

This is used to give the main menu that is shown to the user when the game first starts. It is a list of tuples, where the first element of each tuple is the title of the menu button, and the second element is a label that we jump to when that button is selected. (This jump exits the context in which the start menu executes.) The second element may also be a function, in which case it is called when the item is selected, in the menu context. The third element in each tuple is an expression, which is evaluated each time the main menu is displayed. If the expression evaluates to false, the menu choice is disabled.

Variable: config.main_menu_music = | None

If not None, a music file to play when at the main menu.

Variable: config.main_menu_positions = | None

If not None, this is a map between the default label for buttons on the main menu, and a dictionary containing properties that are applied to that button. This provides a simple way of customizing the main menu by changing where buttons are located on the screen. Please note that this disables the usual button-placement algorithm, so if one button is positioned this way, all must be.

Variable: config.mouse = | None

This variable controls the use of user-defined mouse cursors. If None, the system mouse is used, which is usually a black-and-white mouse cursor. Otherwise, this should be a dictionary giving the mouse animations for various mouse types. Keys used by the default library include "default", "say", "with", "menu", "prompt", "imagemap", "pause", "mainmenu", and "gamemenu". The "default" key should always be present. The values in the dictionary should be list of frames making up the mouse cursor. Each frame is an (image, x-offset, y-offset) tuple. Image is a filename of an image, while x- and y- offset are the offsets of the hotspot within the image. The frames are played back at 20hz, and the animation loops after all frames have been shown. Please note that to show a frame more than once, it must be repeated in a frame list. That is implemented efficiently.

Variable: config.overlay_during_with = | True

True if we want overlays to be shown during with statements, or False if we'd prefer that they be hidden during the with statements.

Variable: config.overlay_functions = | [ ]

A list of functions. When called, each function is expected to return a list of displayables, which are added to the overlay list. See the section on overlays for more.

Variable: config.overlay_layers = | [ 'overlay' ]

This is a list of all of the overlay layers. Overlay layers are cleared before the overlay functions are called. "overlay" should always be in this list.

Variable: config.periodic_callback = | None

If not None, this should be a function. The function is called, with no arguments, at around 20hz.

Variable: config.predict_statements = | 10

This is the number of statements, including the current one, to consider when doing predictive image loading. A breadth-first search from the current statement is performed until this many statements is considered, and any image referenced in those statements is potentially predictively loaded. Setting this to 0 will disable predictive loading of images.

Variable: config.preferences = | dict(...)

This is used to customize the preferences. Please read the section on customizing the main and game menus for more details on the contents of this variable.

Variable: config.preference_positions = | None

If not None, this is should be a dictionary mapping preference name to the position of that preference on the screen.

Variable: config.profile = | False

If set to True, some profiling information will be output to stdout (wherever that may go to).

Variable: config.rollback_enabled = | True

Should the user be allowed to rollback the game? If set to False, the user cannot interactively rollback. (The feature still works for loading savegames when the script changes.)

Variable: config.rollback_length = | 128

When there are more than this many statements in the rollback log, Ren'Py will consider trimming the log.

Variable: config.sample_sound = | None

If not None, this variable should give a sample sound that is played when the "Test" button on the volume slider is clicked. If None, then the "Test" button is not shown.

Variable: config.say_allow_dismiss = | None

If not None, this should be a function. The function is called with no arguments when the user attempts to dismiss a say statement. If this function returns true, the dismissal is allowed, otherwise it is ignored.

Variable: config.say_sustain_callbacks = | ...

A list of functions that are called, without arguments, before the second and later interactions caused by a line of dialogue with pauses in it. Used to sustain voice through pauses.

Variable: config.screen_height = | 600

This sets the height of the screen.

Variable: config.screen_width = | 800

This sets the width of the screen.

Variable: config.script_version = | None

If not None, this is interpreted as a script version. The library will use this script version to enable some compatibility features, if necessary. If None, we assume this is a latest-version script.

Variable: config.searchpath = | [ 'common', 'game' ]

A list of directories that are searched for images, music, archives, and other media, but not scripts. This is initialized to a list containing "common" and the name of the game directory, which changes depending on the name of the exe file. This variable is not used to load scripts, as scripts will be loaded before it can be set.

Variable: config.skip_delay = | 75

The amount of time that dialogue will be shown for, when skipping statements using ctrl, in milliseconds. (Although it's nowhere near that precise in practice.)

Variable: config.skip_indicator = | True

If True, the library will display a skip indicator when skipping through the script.

Variable: config.sound = | True

If True, sound works. If False, the sound/mixer subsystem is completely disabled.

Variable: config.sound_sample_rate = | 44100

The sample rate that the sound card will be run at. If all of your wav files are of a lower rate, changing this to that rate may make things more efficent.

Variable: config.start_interact_callbacks = | ...

A list of functions that are called (without any arguments) when an interaction is started. These callbacks are not called when an interaction is restarted.

Variable: config.sticky_positions = | False

Sticky positions causes the at clause of a show or scene statement to be remembered for as long as that character is on the screen. Future show statements without at clauses will be given the remembered at clause. This lets us easily change the character's expression without changing their position on the screen. Sticky positions does not interact well with multiple layers, when they are used with the show, hide, and scene statements via an onlayer clause.

Variable: config.text_tokenizer = | ...

This is used to set an alternate text-tokenizing function.

The function is called when laying out a Text widget, and is given the string that is the text of the widget, and the style associated with the widget.

It's expected to yield some number of pairs. In each pair, the first element is the kind of token found, and the second element is the text corresponding to that token. The following token types are defined:

- "newline" -- A newline, which when encountered starts a new line.
- "word" -- A word of text. A line will never be broken inside of a word.
- "space" -- A space. Spaces are always placed on the current line, and will never be placed as the start of a line.
- "tag" -- A text tag. If encountered, the second element should be the name of the tag, without any enclosing braces.

Variable: config.thumbnail_height = | 75

The height of the thumbnails that are taken when the game is saved. These thumbnails are shown when the game is loaded. Please note that the thumbnail is shown at the size it was taken at, rather than the value of this setting when the thumbnail is shown to the user.

Variable: config.thumbnail_width = | 100

The width of the thumbnails that are taken when the game is saved. These thumbnails are shown when the game is loaded. Please note that the thumbnail is shown at the size it was taken at, rather than the value of this setting when the thumbnail is shown to the user.

Variable: config.top_layers = | [ ]

This is a list of names of layers that are displayed above all other layers, and do not participate in a transition that is applied to all layers. If a layer name is listed here, it should not be listed in config.layers.

Variable: config.transient_layers = | [ 'transient' ]

This variable gives a list of all of the transient layers. Transient layers are layers that are cleared after each interaction. "transient" should always be in this list.

Variable: config.translations = | dict(...)

This is a map used to translate text in the game menu into your language. See Localizing Ren'Py for how to use it, and /renpy/doc/cookbook/Translations for a list of available translations.

Variable: config.window_icon = | None

If not None, this is expected to be the filename of an image giving an icon that is used for the window. Any image can be used, but most systems want a smaller image around 32x32. The image can have colorkey transparency which will be passed to the system.

Variable: config.with_callback = | None

If not None, this should be a function that is called when a with statement occurs. This function can be responsible for putting up transient things on the screen during the transition. The function is called with a single argument, which is the transition that is occuring. It is expected to return a transition, which may or may not be the transition supplied as its argument.

Reference Manual: (offline | online) Quickstart: (offline | online)