Configuration variables control the behavior of Ren'Py's implementation, allowing Ren'Py itself to be customized in a myriad of ways. These range from the common (such as changing the screen size) to the obscure (adding new kinds of archive files).
Ren'Py's implementation makes the assumption that, once the GUI system has
initialized, configuration variables will not change. Changing configuration
variables outside of init
blocks can lead to undefined behavior.
Configuration variables are not part of the save data.
Configuration variables are often changed in init python
blocks:
init python:
# Use a widescreen resolution.
config.screen_width = 1024
config.screen_height = 600
config.name
= "" linkThis should be a string giving the name of the game. This is included as part of tracebacks and other log files, helping to identify the version of the game being used.
config.save_directory
= "..." linkThis is used to generate the directory in which games and persistent information are saved. The name generated depends on the platform:
Setting this to None creates a "saves" directory underneath the game directory. This is not recommended, as it prevents the game from being shared between multiple users on a system. It can also lead to problems when a game is installed as Administrator, but run as a user.
This must be set with either the define statement, or in a python
early
block. In either case, this will be run before any other
statement, and so it should be set to a string, not an expression.
To locate the save directory, read config.savedir
instead of
this variable.
config.version
= "" linkThis should be a string giving the version of the game. This is included as part of tracebacks and other log files, helping to identify the version of the game being used.
config.window
= None linkThis controls the default method of dialogue window management. If not None, this should be one of "show", "hide", or "auto".
When set to "show", the dialogue window is shown at all times. When set to "hide", the dialogue window is hidden when not in a say statement or other statement that displays dialogue. When set to "auto", the dialogue window is hidden before scene statements, and shown again when dialogue is shown.
This sets the default. Once set, the default can be changed using the
window show
, window hide
and window auto
statements. See
Dialogue Window Management for more information.
These control transitions between various screens.
config.adv_nvl_transition
= None linkA transition that is used when showing NVL-mode text directly after ADV-mode text.
config.after_load_transition
= None linkA transition that is used after loading, when entering the loaded game.
config.end_game_transition
= None linkThe transition that is used to display the main menu after the
game ends normally, either by invoking return with no place to
return to, or by calling renpy.full_restart()
.
config.end_splash_transition
= None linkThe transition that is used to display the main menu after the end of the splashscreen.
config.enter_replay_transition
= None linkIf not None, a transition that is used when entering a replay.
config.enter_transition
= None linkIf not None, this variable should give a transition that will be used when entering the game menu.
config.enter_yesno_transition
= None linkIf not None, a transition that is used when entering the yes/no prompt screen.
config.exit_replay_transition
= None linkIf not None, a transition that is used when exiting a replay.
config.exit_transition
= None linkIf not None, this variable should give a transition that will be performed when exiting the game menu.
config.exit_yesno_transition
= None linkIf not None, a transition that is used when exiting the yes/no prompt screen.
config.game_main_transition
= None linkIf not None, a transition that is used when returning to the main
menu from the game menu, using the MainMenu()
action.
config.intra_transition
= None linkThe transition that is used between screens of the game and main
menu. (That is, when the screen is changed with ShowMenu()
.)
config.nvl_adv_transition
= None linkA transition that is used when showing ADV-mode text directly after NVL-mode text.
config.say_attribute_transition
= None linkIf not None, a transition to use when the image is changed by a say statement with image attributes.
config.say_attribute_transition_callback
= ... linkThis is a function that return a transition to apply and a layer to apply it on
This should be a function that takes four arguments, the image tag being shown, a mode parameter, a set containing pre-transition tags and a set containing post-transition tags. Where the value of the mode parameter is one of:
This should return a 2-component tuple, consisting of:
The default implementation of this returns (config.say_attribute_transition, config.say_attribute_transition_layer).
config.say_attribute_transition_layer
= None linkIf not None, this must be a string giving the name of a layer. (Almost always "master".) The say attribute is applied to the named layer, and Ren'Py will not pause to wait for the transition to occur. This will have the effect of transitioning in the attribute as dialogue is shown.
config.window_hide_transition
= None linkThe transition used by the window hide statement when no transition has been explicitly specified.
config.window_show_transition
= None linkThe transition used by the window show statement when no transition has been explicitly specified.
Ren'Py has a number of variables that set the default values of preferences. Please see the section on preference variables for more information on how to set defaults for various preferences.
config.adjust_attributes
= { } linkIf not None, this is a dictionary. When a statement or function that contains image attributes executes or is predicted, the tag is looked up in this dictionary. If it is not found, the None key is looked up in this dictionary.
If either is found, they're expected to be a function. The function is given an image name, a tuple consisting of the tag and any attributes. It should return an adjusted tuple, which contains and a potential new set of attributes.
As this function may be called during prediction, it must not rely on any state.
config.after_load_callbacks
= [ ... ] linkA list of functions that are called (with no arguments) when a load occurs.
If these callbacks change data (for example, migrating data from an
old version of the game), renpy.block_rollback()
should be
called to prevent the player from rolling back and reverting
the changes.
config.after_replay_callback
= None linkIf not None, a function that is called with no arguments after a replay completes.
config.allow_underfull_grids
= False linkIf True, Ren'Py will not require grids to be full in order to display.
config.always_shown_screens
= [ ] linkA list of names of screens that Ren'Py will always show, even in menus,
and when the interface is hidden. This is mostly used by Ren'Py, which
assumes this will be a list. The config.overlay_screens
list is
usually more appropriate.
config.audio_filename_callback
= None linkIf not None, this is a function that is called with an audio filename, and is expected to return a second audio filename, the latter of which will be played.
This is intended for use when an a games has audio file formats changed, but it's not destired to update the game script.
config.auto_channels
= { "audio" : ( "sfx", "", "" ) } linkThis is used to define automatic audio channels. It's a map the channel name to a tuple containing 3 components:
config.auto_movie_channel
= True linkIf True, and the play argument is give to Movie()
, an
audio channel name is automatically generated for each movie.
config.single_movie_channel
takes precendece over this
variable.
config.auto_load
= None linkIf not None, the name of a save file to automatically load when Ren'Py starts up. This is intended for developer use, rather than for end users. Setting this to "1" will automatically load the game in save slot 1.
config.auto_voice
= None linkThis may be a string, a function, or None. If None, auto-voice is disabled.
If a string, this is formatted with the id
variable bound to the
identifier of the current line of dialogue. If this gives an existing
file, that file is played as voice audio.
If a function, the function is called with a single argument, the identifier of the current line of dialogue. The function is expected to return a string. If this gives an existing file, that file is played as voice audio.
See Automatic Voice for more details.
config.autosave_slots
= 10 linkThe number of slots used by autosaves.
config.cache_surfaces
= False linkIf True, the underlying data of an image is stored in RAM, allowing image manipulators to be applied to that image without reloading it from disk. If False, the data is dropped from the cache, but kept as a texture in video memory, reducing RAM usage.
config.character_id_prefixes
= [ ] linkThis specifies a list of style property prefixes that can be given
to a Character()
. When a style prefixed with one of the given
prefix is given, it is applied to the displayable with that prefix
as its ID.
For example, the default GUI adds "namebox" to this. When a Character
is given the namebox_background property, it sets background
on the displayable in the say screen with the id "namebox".
config.conditionswitch_predict_all
= False linkThe default value of the predict_all argument for ConditionSwitch()
and ShowingSwitch()
, which determines if all possible displayables
are shown.
config.context_callback
= None linkThis is a callback that is called when Ren'Py enters a new context, such as a menu context.
config.context_copy_remove_screens
= [ 'notify' ] linkContains a list of screens that are removed when a context is copied for rollback or saving.
config.context_fadein_music
= 0 linkThe amount of time in seconds Ren'Py spends fading in music when the music is played due to a context change. (Usually, when the game is loaded.)
config.context_fadeout_music
= 0 linkThe amount of time in seconds Ren'Py spends fading out music when the music is played due to a context change. (Usually, when the game is loaded.)
config.debug_image_cache
= False linkIf True, Ren'Py will write information about the image cache to image_cache.txt.
config.debug_prediction
= False linkIf True, Ren'Py will will write information about and errors that occur during prediction (of execution flow, images, and screens) to log.txt and the console.
config.debug_sound
= False linkEnables debugging of sound functionality. This disables the suppression 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.
config.debug_text_overflow
= False linkWhen true, Ren'Py will log text overflows to text_overflow.txt. A text
overflow occurs when a Text
displayable renders to a size
larger than that allocated to it. By setting this to True and setting
the xmaximum
and ymaximum
style properties of the dialogue
window to the window size, this can be used to report cases where the
dialogue is too large for its window.
config.default_attribute_callbacks
= { } linkWhen a statement or function that contains image attributes executes or is predicted, and the tag is not currently being shown, it's looked up in this dictionary. If it is not found, the None key is looked up instead.
If either is found, they're expected to be a function. The function is given an image name, a tuple consisting of the tag and any attributes. It should return an iterable which contains any additional attributes to be applied when an image is first shown.
The results of the function are treated as additive-only, and any explicit conflicting or negative attributes will still take precedence.
As this function may be called during prediction, it must not rely on any state.
config.default_tag_layer
= "master" linkThe layer an image is shown on if its tag is not found in config.tag_layer
.
config.default_transform
= ... linkWhen a displayable is shown using the show or scene statements, the transform properties are taken from this transform and used to initialize the values of the displayable's transform.
The default transform is center
.
config.defer_styles
= False linkWhen true, the execution of style statements is deferred until after
all translate python
blocks have executed. This lets a translate
python
block update variables that are then used in style (not
translate style) statements.
While this defaults to False, it's set to True when gui.init()
is called.
config.developer
= "auto" linkIf set to True, developer mode is enabled. Developer mode gives access to the shift+D developer menu, shift+R reloading, and various other features that are not intended for end users.
This can be True, False, or "auto". If "auto", Ren'Py will detect if the game has been packaged into a distribution, and set config.developer as appropriate.
config.disable_input
= False linkWhen true, renpy.input()
terminates immediately and returns its
default argument.
config.displayable_prefix
= { } linkSee Displayable prefixes.
config.emphasize_audio_channels
= [ 'voice' ] linkA list of strings giving audio channel names.
If the "emphasize audio" preference is enabled, when one of the audio
channels listed starts playing a sound, all channels that are not
listed in this variable have their secondary audio volume reduced
to config.emphasize_audio_volume
over config.emphasize_audio_time
seconds.
When no channels listed in this variable are playing audio, all channels
that are not listed have their secondary audio volume raised to 1.0 over
config.emphasize_audio_time
seconds.
For example, setting this to [ 'voice' ]]
will lower the volume of all
non-voice channels when a voice is played.
config.emphasize_audio_time
= 0.5 linkSee above.
config.emphasize_audio_volume
= 0.5 linkSee above.
config.empty_window
= ... linkThis is called when _window is True, and no window has been shown
on the screen. (That is, no call to renpy.shown_window()
has
occurred.) It's expected to show an empty window on the screen, and
return without causing an interaction.
The default implementation of this uses the narrator character to display a blank line without interacting.
config.enable_language_autodetect
= False linkIf true, Ren'Py will attempt to determine the name of the language to use based on the locale of the player's system. If successful, this language will be used as the default language.
config.enter_sound
= None linkIf not None, this is a sound file that is played when entering the game menu.
config.exit_sound
= None linkIf not None, this is a sound file that is played when exiting the game menu.
config.fix_rollback_without_choice
= False linkThis option determines how the built in menus or imagemaps behave during fixed rollback. The default value is False, which means that menu only the previously selected option remains clickable. If set to True, the selected option is marked but no options are clickable. The user can progress forward through the rollback buffer by clicking.
config.font_replacement_map
= { } linkThis 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:
init python:
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.
If not None, a music file to play when at the game menu.
config.gl_clear_color
= "#000" linkThe color that the window is cleared to before images are drawn. This is mainly seen as the color of the letterbox or pillarbox edges drawn when aspect ratio of the window or monitor in fullscreen mode) does not match the aspect ratio of the game.
config.gl_lod_bias
= -0.5 linkThe default value of the u_lod_bias uniform, which controls the mipmap level Ren'Py uses.
config.gl_test_image
= "black" linkThe name of the image that is used when running the OpenGL performance test. This image will be shown for 5 frames or .25 seconds, on startup. It will then be automatically hidden.
config.has_autosave
= True linkIf true, the game will autosave. If false, no autosaving will occur.
config.history_callbacks
= [ ... ] linkThis contains a list of callbacks that are called before Ren'Py adds a new object to _history_list. The callbacks are called with the new HistoryEntry object as the first argument, and can add new fields to that object.
Ren'Py uses history callbacks internally, so creators should append their own callbacks to this list, rather than replacing it entirely.
config.history_length
= None linkThe number of entries of dialogue history Ren'Py keeps. This is set to 250 by the default gui.
config.hw_video
= False linkIf true, hardware video playback will be used on mobile platforms. This may be faster, but only some formats are supported and only fullscreen video is available. If false, software playback will be used.
config.hyperlink_handlers
= { ... } linkA dictionary mapping a hyperlink protocol to the handler for that protocol. A handler is a function that takes the value (everything after the :) and performs some action. If a value is returned, the interaction ends. Otherwise, the click is ignored and the interaction continues.
config.hyperlink_protocol
= "call_in_new_context" linkThe protocol that is used for hyperlinks that do not have a protocol assigned to them. See the a text tag for a description as to what the possible protocols mean.
config.image_cache_size
= None linkIf not None, this is used to set the size of the image cache, as a multiple of the screen size. This number is multiplied by the size of the screen, in pixels, to get the size of the image cache in pixels.
If set too large, this can waste memory. If set too small, images can be repeatedly loaded, hurting performance.
config.image_cache_size_mb
= 300 linkThis is used to set the size of the image cache, in
megabytes. If config.cache_surfaces
is False, an image takes
4 bytes per pixel, otherwise it takes 8 bytes per pixel.
If set too large, this can waste memory. If set too small, images
can be repeatedly loaded, hurting performance. If not none,
config.image_cache_size
is used instead of this variable.
config.input_caret_blink
= 1.0 linkIf not False, sets the blinking period of the default caret, in seconds.
config.language
= None linkIf not None, this should be a string giving the default language that the game is translated into by the translation framework.
config.lint_character_statistics
= True linkIf true, and config.developer
is true, the lint report will include
statistics about the number of dialogue blocks spoken for each character.
The chanracter statistics are disabled when the game is packaged, to
prevent spoilers.
config.load_failed_label
= None linkIf a string, this is a label that is jumped to when a load fails because the script has changed so much that Ren'Py can't recover. Before performing the load, Ren'Py will revert to the start of the last statement, then it will clear the call stack.
This may also be a function. If it is, the function is called with no arguments, and is expected to return a string giving the label.
config.locale_to_language_function
= ... linkA function that determines the language the game should use, based on the the user's locale. It takes 2 string arguments that give the ISO code of the locale and the ISO code of the region.
It should return a string giving the name of a translation to use, or None to use the default translation.
If not None, a music file to play when at the main menu.
The number of seconds to take to fade in config.main_menu_music
.
If not None, this should be a function that takes positional and/or keyword arguments. It's called whenever a menu statement runs, with the arguments to that menu statement.
This should return a pair, containing a tuple of positional arguments (almost always empty), and a dictionary of keyword arguments.
A list of layer names (as strings) that are cleared when entering the game menu.
When this variable is set, choices disables with the if statement are included as disabled buttons.
The _window_subtitle
variable is set to this value when entering
the main or game menus.
config.minimum_presplash_time
= 0.0 linkThe minimum amount of time, in seconds, a presplash, Android presplash, or iOS LaunchImage is displayed for. If Ren'Py initializes before this amount of time has been reached, it will sleep to ensure the image is shown for at least this amount of time. The image may be shown longer if Ren'Py takes longer to start up.
config.missing_background
= "black" linkThis is the background that is used when config.developer
is True
and an undefined image is used in a scene statement. This should be an image name (a string), not a
displayable.
config.mode_callbacks
= [ ... ] linkA list of callbacks called when entering a mode. For more documentation, see the section on Modes.
The default value includes a callback that implements config.adv_nvl_transition
and config.nvl_adv_transition
.
config.mouse
= None linkThis 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, as it is used when a more specific key is absent.
Each value in the dictionary should be a list of (image, xoffset, yoffset) tuples, representing frames.
The frames are played back at 20Hz, and the animation loops after all frames have been shown.
config.mouse_displayable
= None linkIf not None, this should either be a displayable, or a callable that returns a displayable. The callable may return None, in which case Ren'Py proceeds if the displayable is None.
If a displayable is given, the mouse cursor is hidden, and the
displayable is shown above anything else. This displayable is
responsible for positioning and drawing a sythetic mouse
cursor, and so should probably be a MouseDisplayable()
or something very similar.
If true, narration inside a menu is displayed using the narrator character. Otherwise, narration is displayed as captions within the menu itself.
config.nearest_neighbor
= False linkUses nearest-neighbor filtering by default, to support pixel art or melting players' eyes.
config.notify
= ... linkThis is called by renpy.notify()
or Notify()
with a
single message argument, to display the notification. The default
implementation is renpy.display_notify()
. This is intended
to allow creators to intercept notifications.
config.optimize_texture_bounds
= True linkWhen True, Ren'Py will scan images to find the bounding box of the non-transparent pixels, and only load those pixels into a texture.
config.overlay_functions
= [ ] linkA list of functions. When called, each function is expected to use ui functions to add displayables to the overlay layer.
config.overlay_screens
= [ ... ] linkA list of screens that are displayed when the overlay is enabled, and hidden when the overlay is suppressed. (The screens are shown on the screens layer, not the overlay layer.)
config.pause_after_rollback
= False linkIf False, the default, rolling back will skip any pauses (timed or not) and stop only at other interactions such as dialogues, menus... If True, renpy will include timeless pauses to the valid places a rollback can take the user.
config.preload_fonts
= [ ] linkA list of the names of TrueType and OpenType fonts that Ren'Py should load when starting up. Including the name of a font here can prevent Ren'Py from pausing when introducing a new typeface.
config.preserve_volume_when_muted
= False linkIf False, the default, the volume of channels are shown as 0 and changing it disables mute when the channel is mute. Otherwise, It is shown and adjustable while keeping mute.
config.python_callbacks
= [ ] linkA list of functions. The functions in this list are called, without any arguments, whenever a Python block is run outside of the init phase.
One possible use of this would be to have a function limit a variable to within a range each time it is adjusted.
The functions may be called while Ren'Py is starting up, before the start
of the game proper, and potentially before the variables the
function depends on are initialized. The functions are required to deal
with this, perhaps by using hasattr(store, 'varname')
to check if
a variable is defined.
config.quicksave_slots
= 10 linkThe number of slots used by quicksaves.
config.quit_action
= ... linkThe action that is called when the user clicks the quit button on a window. The default action prompts the user to see if he wants to quit the game.
config.reload_modules
= [ ] linkA list of strings giving the names of python modules that should be reloaded along with the game. Any submodules of these modules will also be reloaded.
config.replace_text
= None linkIf not None, a function that is called with a single argument, a text to be displayed to the user. The function can return the same text it was passed, or a replacement text that will be displayed instead.
The function is called after substitutions have been performed and after the text has been split on tags, so its argument contains nothing but actual text. All displayed text passes through the function: not only dialogue text, but also user interface text.
This can be used to replace specific ASCII sequences with corresponding Unicode characters, as demonstrated by the following:
def replace_text(s):
s = s.replace("'", u'\u2019') # apostrophe
s = s.replace('--', u'\u2014') # em dash
s = s.replace('...', u'\u2026') # ellipsis
return s
config.replace_text = replace_text
config.replay_scope
= { "_game_menu_screen" : "preferences" } linkA dictionary mapping variables in the default store to the values the variables will be given when entering a replay.
config.return_not_found_label
= None linkIf not None, a label that is jumped to when a return site is not found. The call stack is cleared before this jump occurs.
config.save_json_callbacks
= [ ] linkA list of callback functions that are used to create the json object
that is stored with each save and marked accessible through FileJson()
and renpy.slot_json()
.
Each callback is called with a Python dictionary that will eventually be saved. Callbacks should modify that dictionary by adding JSON-compatible Python types, such as numbers, strings, lists, and dicts. The dictionary at the end of the last callback is then saved as part of the save slot.
The dictionary passed to the callbacks may have already have keys
beginning with an underscore _
. These keys are used by Ren'Py,
and should not be changed.
For example:
init python:
def jsoncallback(d):
d["playername"] = player_name
config.save_json_callbacks.append(jsoncallback)
FileJson(slot)
and renpy.slot_json(slot)
will recover the state
of the d
dict-like object as it was at the moment the game was saved.
The value of the player_name
variable at the moment the game was saved
is also accessible by FileJson(slot, "playername")
.
config.say_arguments_callback
= None linkIf not None, this should be a function that takes the speaking character, followed by positional and keyword arguments. It's called whenever a say statement occurs with the arguments to that say statement. This always includes an interact argument, and can include others provided in the say statement.
This should return a pair, containing a tuple of positional arguments (almost always empty), and a dictionary of keyword arguments (almost always with at least interact in it).
For example:
def say_arguments_callback(who, interact=True, color="#fff"):
return (), { "interact" : interact, "what_color" : color }
config.say_arguments_callback = say_arguments_callback
config.screen_height
= 600 linkThe height of the screen. Usually set by gui.init()
to
a much larger size.
config.screen_width
= 800 linkThe width of the screen. Usually set by gui.init()
to a much
larger size.
config.single_movie_channel
= None linkIf not None, and the play argument is give to Movie()
,
this is the name used for the channel the movie is played on.
This should not be "movie", as that name is reserved for
Ren'Py's internal use.
config.skip_sounds
= False linkIf False, non-looping audio will not be played when Ren'Py is skipping.
config.speaking_attribute
= None linkIf not None, this should be a string giving the name of an image attribute. The image attribute is added to the image when the character's image tag when the character is speaking, and removed when the character stops.
This is applied to the image on the default layer for the tag,
which can be set using config.tag_layer
.
config.tag_layer
= { } linkA dictionary mapping image tag strings to layer name strings. When
an image is shown without a specific layer name, the image's tag is
looked up in this dictionary to get the layer to show it on. If the
tag is not found here, config.default_tag_layer
is used.
config.tag_transform
= { } linkA dictionary mapping image tag strings to transforms or lists of transforms. When an image is newly-shown without an at clause, the image's tag is looked up in this dictionary to find a transform or list of transforms to use.
config.tag_zorder
= { } linkA dictionary mapping image tag strings to zorders. When an image is newly-shown without a zorder clause, the image's tag is looked up in this dictionary to find a zorder to use. If no zorder is found, 0 is used.
config.thumbnail_height
= 75 linkThe 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.
This is changed by the default GUI.
config.thumbnail_width
= 100 linkThe 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.
This is changed by the default GUI.
config.tts_voice
= None linkIf not None, a string giving a non-default voice that is used to play back text-to-speech for self voicing. The possible choices are platform specific, and so this should be set in a platform-specific manner. (It may make sense to change this in translations, as well.)
config.webaudio_required_types
= [ "audio/ogg", "audio/mp3" ] linkWhen running on the web platform, Ren'Py will check the browser to see if it can play audio files of these mime types. If the browser can, it is used to play the files. If not, a slower and potentially skip prone wasm decoder is used.
By default, the browser's web audio system is used on Chrome and Firefox, and wasm is used on safari. If your game only uses mp3 audio, this can be changed using
define config.webaudio_required_types = [ "audio/mp3" ]
To used the faster web audio system on Safari as well.
config.window_auto_hide
= [ 'scene', 'call screen', 'menu', "say-centered" ] linkA list of statements that cause window auto
to hide the empty
dialogue window.
config.window_auto_show
= [ 'say', 'menu-with-caption' ] linkA list of statements that cause window auto
to show the empty
dialogue window.
config.window_icon
= None linkIf not None, this is expected to be the filename of an image giving an icon that is used for the game's main window. This does not set the icon used by windows executables and mac apps, as those are controlled by Special Files.
config.window_overlay_functions
= [] linkA list of overlay functions that are only called when the window is shown.
config.window_title
= None linkThe static portion of the title of the window containing the
Ren'Py game. _window_subtitle
is appended to this to get
the full title of the window.
If None, the default, this defaults to the value of config.name
.
config.adjust_view_size
= None linkIf not None, this should be a function taking two arguments, the width and height of the physical window. It is expected to return a tuple giving the width and height of the OpenGL viewport, the portion of the screen that Ren'Py will draw pictures to.
This can be used to configure Ren'Py to only allow certain sizes of screen. For example, the following allows only integer multiples of the original screen size:
init python:
def force_integer_multiplier(width, height):
multiplier = min(width / config.screen_width, height / config.screen_height)
multiplier = max(int(multiplier), 1)
return (multiplier * config.screen_width, multiplier * config.screen_height)
config.adjust_view_size = force_integer_multiplier
config.afm_bonus
= 25 linkThe number of bonus characters added to every string when auto-forward mode is in effect.
config.afm_callback
= None linkIf 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.
config.afm_characters
= 250 linkThe 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.
config.afm_voice_delay
= .5 linkThe number of seconds after a voice file finishes playing before AFM can advance text.
config.all_character_callbacks
= [ ] linkA list of callbacks that are called by all characters. This list is prepended to the list of character-specific callbacks.
config.allow_skipping
= True linkIf set to False, the user is not able to skip over the text of the
game. See _skipping
.
config.allow_screensaver
= True linkIf True, the screensaver may activite while the game is running. If False, the screensaver is disabled.
config.archives
= [ ] linkA list of archive files that will be searched for images and other data. The entries in this should consist of strings giving the base names of archive files, without the .rpa extension.
The archives are searched in the order they are found in this list. A file is taken from the first archive it is found in.
At startup, Ren'Py will automatically populate this variable with
the names of all archives found in the game directory, sorted in
reverse ascii order. For example, if Ren'Py finds the files
data.rpa, patch01.rpa, and patch02.rpa, this variable will be
populated with ['patch02', 'patch01', 'data']
.
config.at_exit_callbacks
= [ ] linkA list of callbacks that are called when Ren'Py quits or restarts the game. These callbacks should not interact with the user.
config.auto_choice_delay
= None linkIf 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.
config.autoreload
= True linkIf True, Shift+R will toggle automatic reloading. When automatic reloading is enabled, Ren'Py will reload the game whenever a used file is modified.
If False, Ren'Py will reload the game once per press of Shift+R.
config.autosave_frequency
= 200 linkRoughly, the number of interactions that will occur before an
autosave occurs. To disable autosaving, set config.has_autosave
to
False, don't change this variable.
config.autosave_on_choice
= True linkIf True, Ren'Py will autosave upon encountering an in-game choice.
(When renpy.choice_for_skipping()
is called.)
config.autosave_on_quit
= True linkIf True, Ren'Py will attempt to autosave when the user attempts to quit, return to the main menu, or load a game over the existing game. (To save time, the autosave occurs while the user is being prompted to confirm his or her decision.)
config.autosave_on_input
= True linkIf True, Ren'Py will autosave when the user inputs text.
(When renpy.input()
is called.)
config.call_screen_roll_forward
= False linkThe value is used when the roll_forward property of a screen is None.
config.character_callback
= None linkThe default value of the callback parameter of Character.
config.choice_empty_window
= None linkIf not None, and a choice menu (usually invoked with the menu
statement) does not have a caption, this function is called with
the arguments ("", interact=False).
The expected use of this is:
define config.choice_empty_window = extend
Doing this displays repeats the last line of dialogue as the caption of the menu, if no other caption is given.
Other implementations are possible, but it's assumed that this will always display a dialogue window.
config.choice_layer
= "screens" linkThe layer the choice screen (used by the menu statement) is shown on.
config.clear_layers
= [] linkA list of names of layers to clear when entering the main and game menus.
config.context_clear_layers
= [ 'screens' ] linkA list of layers that are cleared when entering a new context.
config.controller_blocklist
= [ ... ] linkA list of strings, where each string is matched against the GUID of a game controller. These strings are mached as a prefix to the controller GUID (which cand be found in log.txt), and if matched, prevent the controller from being initialized.
config.exception_handler
= None linkIf not None, this should be a function that takes three arguments:
This function can present the error to a user in any way fit. If it returns True,
the exception is ignored and control is transferred to the next statement. If it
returns False, the built-in exception handler is use. This function may also call
renpy.jump()
to transfer control to some other label.
config.fade_music
= 0.0 linkThis 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.
config.fast_skipping
= False linkSet this to True to allow fast skipping outside of developer mode.
config.file_open_callback
= None linkIf not None, this is a function that is called with the file name when a file needs to be opened. It should return a file-like object, or None to load the file using the usual Ren'Py mechanisms. Your file-like object must implement at least the read, seek, tell, and close methods.
One may want to also define a config.loadable_callback
that
matches this.
config.focus_crossrange_penalty
= 1024 linkThis is the amount of penalty to apply to moves perpendicular to the selected direction of motion, when moving focus with the keyboard.
config.gl_resize
= True linkDetermines if the user is allowed to resize an OpenGL-drawn window.
config.hard_rollback_limit
= 100 linkThis 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.
config.help_screen
= "help" linkThe name of the screen shown by the Help()
action, or by pressing
f1 on the keyboard.
config.hide
= renpy.hide linkA function that is called when the hide statement is executed. This should take the same arguments as renpy.hide.
config.imagemap_auto_function
= ... linkA function that expands the auto property of a screen language imagebutton or imagemap statement into a displayable. It takes the value of the auto property, and the desired image, one of: "insensitive", "idle", "hover", "selected_idle", "selected_hover", or "ground". It should return a displayable or None.
The default implementation formats the auto property with the desired image, and then checks if the computed filename exists.
config.keep_side_render_order
= True linkIf True, the order of substrings in the Side positions will be determine the order of children render.
config.implicit_with_none
= True linkIf True, then by default the equivalent of a with None statement will be performed after interactions caused by dialogue, menus input, and imagemaps. This ensures that old screens will not show up in transitions.
config.interact_callbacks
= ... linkA list of functions that are called (without any arguments) when an interaction is started or restarted.
config.keep_running_transform
= True linkIf True, showing an image without supplying a transform or ATL block will cause the image to continue the previous transform an image with that tag was using, if any. If False, the transform is stopped.
config.keymap
= dict(...) linkThis variable contains a keymap giving the keys and mouse buttons assigned to each possible operation. Please see the section on Keymaps for more information.
config.label_callback
= None linkIf not None, this is a function that is called whenever a label is reached. It is called with two parameters. The first is the name of the label. The second is True if the label was reached through jumping, calling, or creating a new context, and False otherwise.
config.label_overrides
= { } linkThis variable gives a way of causing jumps and calls of labels in Ren'Py script to be redirected to other labels. For example, if you add a mapping from "start" to "mystart", all jumps and calls to "start" will go to "mystart" instead.
config.layer_clipping
= { } linkControls 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.
config.layeredimage_offer_screen
= True linkThis variable sets the default value for the offer_screen
property
of layeredimages. See the related section
for more information.
config.layers
= [ 'master', 'transient', 'screens', 'overlay' ] linkThis 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", "screens", and "overlay" internally, so they should always be in this list.
The renpy.add_layer()
can add layers to this variable without
needing to know the original contents.
config.lint_hooks
= ... linkThis 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).
config.load_before_transition
= True linkIf True, the start of an interaction will be delayed until all images used by that interaction have loaded. (Yeah, it's a lousy name.)
config.loadable_callback
= None linkWhen not None, a function that's called with a filename. It should return
True if the file is loadable, and False if not. This can be used with
config.file_open_callback
or config.missing_image_callback
.
config.log_width
= 78 linkThe width of lines logged when config.log
is used.
config.longpress_duration
= 0.5 linkThe amount of time the player must press the screen for a longpress to be recognized on a touch device.
config.longpress_radius
= 15 linkThe number of pixels the touch must remain within for a press to be recognized as a longpress.
config.longpress_vibrate
= .1 linkThe amount of time the device will vibrate for after a longpress.
config.log
= None linkIf not None, this is expected to be a filename. Much of the text shown to the user by say or menu statements will be logged to this file.
A list of channels that are stopped when entering or returning to the main menu.
config.mipmap_dissolves
= False linkThe default value of the mipmap argument to Dissolve()
,
ImageDissolve()
, AlphaDissolve()
, and AlphaMask()
.
config.mipmap_text
= False linkThe default value of the mipmap argument to Text()
, including
text used in screen statements.
config.missing_image_callback
= None linkIf not None, this function is called when an attempt to load an image fails. It may return None, or it may return an image manipulator. If an image manipulator is returned, that image manipulator is loaded in the place of the missing image.
One may want to also define a config.loadable_callback
,
especially if this is used with a DynamicImage()
.
config.missing_label_callback
= None linkIf not None, this function is called when Ren'Py attempts to access a label that does not exist in the game. The callback should take a single parameter, the name of the missing label. It should return the name of a label to use as a replacement for the missing label, or None to cause Ren'Py to raise an exception.
config.mouse_focus_clickthrough
= False linkIf true, clicks that cause a window to be focused will be processed normally. If false, such clicks will be ignored.
config.mouse_hide_time
= 30 linkThe mouse is hidden after this number of seconds has elapsed without any mouse input. This should be set to longer than the expected time it will take to read a single screen, so mouse users will not experience the mouse appearing then disappearing between clicks.
If None, the mouse will never be hidden.
config.movie_mixer
= "music" linkThe mixer that is used when a Movie()
automatically defines
a channel for video playback.
config.new_translate_order
= True linkEnables the new order of style and translate statements introduced in Ren'Py 6.99.11.
config.new_substitutions
= True linkIf True, Ren'Py will apply new-style (square-bracket) substitutions to all text displayed.
config.old_substitutions
= True linkIf True, Ren'Py will apply old-style (percent) substitutions to text displayed by the say and menu statements.
config.open_file_encoding
= False linkIf not False, this is the encoding that renpy.open_file()
uses
when its encoding parameter is none. This is mostly used when porting
Python 2 games that used renpy.file()
extensively to Python 3,
to have those files open as text by default.
This gets its default value from the RENPY_OPEN_FILE_ENCODING environment variable.
config.overlay_during_with
= True linkTrue if we want overlays to be shown during with statements, or False if we'd prefer that they be hidden during the with statements.
config.overlay_layers
= [ 'overlay' ] linkThis 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.
config.pause_with_transition
= False linkIf false, renpy.pause()
is always, used by the pause
statement.
If true, when given a delay, pause
is equivalent to with Pause(...)
.
config.per_frame_screens
= [ ... ] linkThis is a list of strings giving the name of screens that are updated once per frame, rather than once per interaction. Ren'Py uses this internally, so if you add a screen, append the name rather than replacing the list in its entirety.
config.periodic_callback
= None linkIf not None, this should be a function. The function is called, with no arguments, at around 20Hz.
config.play_channel
= "audio" linkThe name of the audio channel used by renpy.play()
,
hover_sound
, and activate_sound
.
config.predict_statements
= 32 linkThis 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 number of statements is considered, and any image referenced in those statements is potentially predictively loaded. Setting this to 0 will disable predictive loading of images.
config.profile
= False linkIf set to True, some profiling information will be output to stdout.
config.profile_init
= 0.25 linkinit
and init python
blocks taking longer than this amount of time
to run are reported to log file.
config.quit_on_mobile_background
= False linkIf True, the mobile app will quit when it loses focus, rather than
saving and restoring its state. (See also config.save_on_mobile_background
,
which controls this behavior.)
config.rollback_enabled
= True linkShould the user be allowed to rollback the game? If set to False, the user cannot interactively rollback.
config.rollback_length
= 128 linkWhen there are more than this many statements in the rollback log, Ren'Py will consider trimming the log. This also covers how many steps Ren'Py will rollback when trying to load a save when the script has changed.
Decreasing this below the default value may cause Ren'Py to become unstable.
config.rollback_side_size
= .2 linkIf the rollback side is enabled, the fraction of the screen on the rollback side that, when clicked or touched, causes a rollback to occur.
config.say_allow_dismiss
= None linkIf 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.
config.say_layer
= "screens" linkThe layer the say screen is shown on.
If not None, then this is a function that is given the text found in strings in the say and menu statements. It is expected to return new (or the same) strings to replace them.
config.say_sustain_callbacks
= ... linkA 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.
config.save_dump
= False linkIf set to True, Ren'Py will create the file save_dump.txt whenever it saves a game. This file contains information about the objects contained in the save file. Each line consists of a relative size estimate, the path to the object, information about if the object is an alias, and a representation of the object.
config.save_on_mobile_background
= True linkIf True, the mobile app will save its state when it loses focus. The state is saved in a way that allows it to be automatically loaded (and the game to resume its place) when the app starts again.
config.save_physical_size
= True linkIf True, the physical size of the window will be saved in the preferences, and restored when the game resumes.
config.savedir
= ... linkThe complete path to the directory in which the game is
saved. This should only be set in a python early
block. See also
config.save_directory, which generates the default value for this
if it is not set during a python early
block.
config.scene
= renpy.scene linkA function that's used in place of renpy.scene()
by the scene
statement. Note that this is used to clear the screen,
and config.show
is used to show a new image. This should have the same
signature as renpy.scene()
.
config.screenshot_callback
= ... linkA function that is called when a screenshot is taken. The function is called with a single parameter, the full filename the screenshot was saved as.
config.screenshot_crop
= None linkIf not None, this should be a (x, y, height, width) tuple. Screenshots are cropped to this rectangle before being saved.
config.screenshot_pattern
= "screenshot%04d.png" linkThe pattern used to create screenshot files. This pattern is applied (using Python's %-formatting rules) to the natural numbers to generate a sequence of filenames. The filenames may be absolute, or relative to config.renpy_base. The first filename that does not exist is used as the name of the screenshot.
Directories are created if they do not exist.
See also _screenshot_pattern
, which is used in preference to this
variable if not None.
config.script_version
= None linkIf 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.
This is normally set in a file added by the Ren'Py launcher when distributions are built.
config.searchpath
= [ 'common', 'game' ] linkA 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.
config.search_prefixes
= [ "", "images/" ] linkA list of prefixes that are prepended to filenames that are searched for.
config.show
= renpy.show linkA function that is used in place of renpy.show()
by the show and scene statements. This
should have the same signature as renpy.show()
.
config.skip_delay
= 75 linkThe 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.)
config.skip_indicator
= True linkIf True, the library will display a skip indicator when skipping through the script.
config.sound
= True linkIf True, sound works. If False, the sound/mixer subsystem is completely disabled.
config.sound_sample_rate
= 48000 linkThe 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 efficient.
config.start_callbacks
= [ ... ] linkA list of callbacks functions that are called with no arguments after the init phase, but before the game (including the splashscreen) starts. This is intended to be used by frameworks to initialize variables that will be saved.
The default value of this variable includes callbacks that Ren'Py uses internally to implement features such as nvl-mode. New callbacks can be appended to this list, but the existing callbacks should not be removed.
config.start_interact_callbacks
= [ ... ] linkA list of functions that are called (without any arguments) when an interaction is started. These callbacks are not called when an interaction is restarted.
config.quit_callbacks
= [ ... ] linkA list of functions that are called (without any arguments) when Ren'Py terminates. This is intended to free resources, such as opened files or started threads.
config.top_layers
= [ ] linkThis 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.
config.transient_layers
= [ 'transient' ] linkThis 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.
config.transform_uses_child_position
= True linkIf True, transforms will inherit position properties from their child. If not, they won't.
config.transition_screens
= True linkIf True, screens will participate in transitions, dissolving from the old state of the screen to the new state of the screen. If False, only the latest state of the screen will be shown.
config.translate_clean_stores
= [ "gui" ] linkA list of named stores that are cleaned to their state at the end of the init phase when the translation language changes.
config.variants
= [ ... ] linkA list of screen variants that are searched when choosing a screen to display to the user. This should always end with None, to ensure that the default screens are chosen. See Screen Variants.
config.voice_filename_format
= "{filename}" linkA string that is formatted with the string argument to the voice
statement to produce the filename that is played to the user. For
example, if this is "{filename}.ogg", the voice "test"
statement
will play test.ogg.
config.with_callback
= None linkIf 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 two arguments: the transition that is occurring, and the transition it is paired with. The latter is None except in the case of the implicit None transition produced by an inline with statement, in which case it is the inline transition that produced the with None. It is expected to return a transition, which may or may not be the transition supplied as its argument.
These variables allow you to tune the Python garbage collector and the Ren'Py management of the Python garbage collector.
config.manage_gc
= True linkIf True, Ren'Py will manage the GC itself. This means that it will apply the settings below.
config.gc_thresholds
= (25000, 10, 10) linkThe GC thresholds that Ren'Py uses when not idle. These are set to try to ensure that garbage collection doesn't happen. The three numbers are:
(Level-0 collections should be fast enough to not cause a frame drop, level-1 collections might, level-2 will.)
config.idle_gc_count
= 2500 linkThe net number of objects that triggers a collection when Ren'Py has reached a steady state. (The fourth frame or later after the screen has been updated.)
config.gc_print_unreachable
= False linkIf True, Ren'Py will print to its console and logs information about the objects that are triggering collections.
Some other pages of this documentation contain and define other configuration variables. You can locate them there, in their context.