We're in the process of migrating the documentation over to a new tool. As not every page has been migrated yet, this exists to document new functionality that has no other place to go.
renpy.version(tuple=False) linkIf tuple is false, returns a string containing "Ren'Py ", followed by the current version of Ren'Py.
If tuple is true, returns a tuple giving each component of the version as an integer.
renpy.version_string linkThe version number of Ren'Py, as a string of the form "Ren'Py 1.2.3.456".
renpy.version_only linkThe version number of Ren'Py, without the Ren'Py prefix. A string of the form "1.2.3.456".
renpy.version_tuple linkThe version number of Ren'Py, as a tuple of the form (1, 2, 3, 456).
renpy.version_name linkA human readable version name, of the form "Example Version."
renpy.license linkA string giving license text that should be included in a game's about screen.
Ren'Py includes a number of variables that are set based on which platform it's running on.
renpy.windows linkHas a true value when running on Windows.
renpy.macintosh linkHas a true value when running on macOS.
renpy.linux linkHas a true value when running on Linux or other POSIX-like operating systems.
renpy.android linkHas a true value when running on Android.
renpy.ios linkHas a true value when running on iOS.
renpy.emscripten linkHas a true value when running in the browser.
renpy.mobile linkHas a true value when running on Android or iOS or in the browser.
These are only set when running on the actual devices, not when running on in the emulators. These are more intended for use in platform-specific Python. For display layout, use screen variants.
renpy.diff_memory(update=True, skip_constants=False) linkProfiles objects, surface, and texture memory use by Ren'Py and the game. Writes (to memory.txt and stdout) the difference in memory usage from the last time this function was called with update true.
The accounting is by names in the store and in the Ren'Py implementation that the memory is reachable from. If an object is reachable from more than one name, it's assigned to the name it's most directly reachable from.
As it has to scan all memory used by Ren'Py, this function may take a long time to complete.
renpy.profile_memory(fraction=1.0, minimum=0, skip_constants=False) linkProfiles object, surface, and texture memory use by Ren'Py and the game. Writes an accounting of memory use by to the memory.txt file and stdout.
The accounting is by names in the store and in the Ren'Py implementation that the memory is reachable from. If an object is reachable from more than one name, it's assigned to the name it's most directly reachable from.
As it has to scan all memory used by Ren'Py, this function may take a long time to complete.
renpy.profile_rollback() linkProfiles memory used by the rollback system. Writes (to memory.txt and stdout) the memory used by the rollback system. This tries to account for rollback memory used by various store variables, as well as by internal aspects of the rollback system.
renpy.context() linkReturns an object that is unique to the current context. The object is copied when entering a new context, but changes to the copy do not change the original.
The object is saved and participates in rollback.
renpy.context_nesting_level() linkReturns the nesting level of the current context. This is 0 for the outermost context (the context that is saved, loaded, and rolled-back), and is non-zero in other contexts, such as menu and replay contexts.
This object is a random number generator that implements the Python random number generation interface. Randomness can be generated by calling the various methods this object exposes. See the Python documentation for the full list, but the most useful are:
renpy.random.random()Return the next random floating point number in the range (0.0, 1.0).
renpy.random.randint(a, b)Return a random integer such that a <= N <= b.
renpy.random.choice(seq)Return a random element from the non-empty sequence seq.
renpy.random.shuffle(seq)Shuffles the elements of the sequence seq in place. This does not return a list, but changes an existing one.
Unlike the standard Python random number generator, this object cooperates with rollback, generating the same numbers regardless of how many times we rollback. It should be used instead of the standard Python random module.
# return a random float between 0 and 1
$ randfloat = renpy.random.random()
# return a random integer between 1 and 20
$ d20roll = renpy.random.randint(1, 20)
# return a random element from a list
$ randfruit = renpy.random.choice(['apple', 'orange', 'plum'])
renpy.random.Random(seed=None)Returns a new random number generator object separate from the main one, seeded with the specified value if provided.
These functions let you use the Python ctypes module to call functions in the SDL dll. There are no guarantees as to the version of SDL2 that's included with Ren'Py, including which features will or will not be compiled in. These functions may fail on platforms that can otherwise run Ren'Py, and so it's important to check for None before proceeding.
renpy.get_sdl_dll() linkThis returns a ctypes.cdll object that refers to the library that contains the instance of SDL2 that Ren'Py is using.
If this can not be done, None is returned.
renpy.get_sdl_window_pointer() linkReturns a pointer (of type ctypes.c_void_p) to the main window, or None if the main window is not displayed, or some other problem occurs.
init python:
import ctypes
def get_window_position():
"""
Retrieves the position of the window from SDL2. Returns
the (x, y) of the upper left corner of the window, or
(0, 0) if it's not known.
"""
sdl = renpy.get_sdl_dll()
if sdl is None:
return (0, 0)
win = renpy.get_sdl_window_pointer()
if win is None:
return (0, 0)
SDL_GetWindowPosition = sdl.SDL_GetWindowPosition
x = ctypes.c_int()
y = ctypes.c_int()
SDL_GetWindowPosition(win, ctypes.byref(x), ctypes.byref(y))
renpy.add_layer(layer, above=None, below=None, menu_clear=True) linkAdds a new layer to the screen. If the layer already exists, this function does nothing.
One of behind or above must be given.
renpy.add_python_directory(path) linkAdds path to the list of paths searched for Python modules and packages. The path should be a string relative to the game directory. This must be called before an import statement.
renpy.add_to_all_stores(name, value) linkAdds the value by the name to all creator defined namespaces. If the name already exist in that namespace - do nothing for it.
This function may only be run from inside an init block. It is an error to run this function once the game has started.
renpy.call_stack_depth() linkReturns the depth of the call stack of the current context - the number of calls that have run without being returned from or popped from the call stack.
renpy.capture_focus(name=u'default') linkIf a displayable is currently focused, captured the rectangular bounding box of that displayable, and stores it with name. If not, removes any focus stored with name.
Captured focuses are not saved when the game is saveed.
renpy.choice_for_skipping() linkTells Ren'Py that a choice is coming up soon. This currently has two effects:
renpy.clear_capture_focus(name=u'default') linkClear the captured focus with name.
renpy.clear_game_runtime() linkResets the game runtime counter.
renpy.clear_keymap_cache() linkClears the keymap cache. This allows changes to config.keymap to
take effect without restarting Ren'Py.
renpy.context_dynamic(*vars) linkThis can be given one or more variable names as arguments. This makes the variables dynamically scoped to the current context. The variables will be reset to their original value when the call returns.
An example call is:
$ renpy.context_dynamic("x", "y", "z")
renpy.count_dialogue_blocks() linkReturns the number of dialogue blocks in the game's original language.
renpy.count_newly_seen_dialogue_blocks() linkReturns the number of dialogue blocks the user has seen for the first time during this session.
renpy.count_seen_dialogue_blocks() linkReturns the number of dialogue blocks the user has seen in any play-through of the current game.
renpy.display_notify(message) linkThe default implementation of renpy.notify().
renpy.dynamic(*vars, **kwargs) linkThis can be given one or more variable names as arguments. This makes the variables dynamically scoped to the current call. The variables will be reset to their original value when the call returns.
If the variables are given as keyword arguments, the value of the argument is assigned to the variable name.
Example calls are:
$ renpy.dynamic("x", "y", "z")
$ renpy.dynamic(players=2, score=0)
renpy.flush_cache_file(fn) linkThis flushes all image cache entries that refer to the file fn. This may be called when an image file changes on disk to force Ren'Py to use the new version.
renpy.focus_coordinates() linkThis attempts to find the coordinates of the currently-focused displayable. If it can, it will return them as a (x, y, w, h) tuple. If not, it will return a (None, None, None, None) tuple.
renpy.force_autosave(take_screenshot=False, block=False) linkForces a background autosave to occur.
renpy.free_memory() linkAttempts to free some memory. Useful before running a renpygame-based minigame.
renpy.full_restart(transition=False, label=u'_invoke_main_menu', target=u'_main_menu', save=False) linkCauses Ren'Py to restart, returning the user to the main menu.
config.end_game_transition._quit_slot before Ren'Py
restarts and returns the user to the main menu.renpy.get_adjustment(bar_value) linkGiven bar_value, a BarValue, returns the ui.adjustment()
if uses. The adjustment has the following to attributes defined:
value linkThe current value of the bar.
range linkThe current range of the bar.
renpy.get_autoreload() linkGets the autoreload flag.
renpy.get_game_runtime() linkReturns the game runtime counter.
The game runtime counter counts the number of seconds that have elapsed while waiting for user input in the top-level context. (It does not count time spent in the main or game menus.)
renpy.get_image_load_log(age=None) linkA generator that yields a log of image loading activity. For the last 100 image loads, this returns:
The entries are ordered from newest to oldest.
The image load log is only kept if config.developer = True.
renpy.get_mouse_name(interaction=False) linkReturns the name of the mouse that should be shown.
renpy.get_mouse_pos() linkReturns an (x, y) tuple giving the location of the mouse pointer or the current touch location. If the device does not support a mouse and is not currently being touched, x and y are numbers, but not meaningful.
renpy.get_physical_size() linkReturns the size of the physical window.
renpy.get_refresh_rate(precision=5) linkReturns the refresh rate of the current screen, as a floating-point number of frames per second.
The raw data Ren'Py gets is number of frames per second, rounded down. This means that a monitor that runs at 59.95 frames per second will be reported at 59 fps. The precision argument reduces the precision of this reading, such that the only valid readings are multiples of the precision.
Since all monitor framerates tend to be multiples of 5 (25, 30, 60, 75, and 120), this likely will improve accuracy. Setting precision to 1 disables this.
renpy.get_renderer_info() linkReturns a dictionary, giving information about the renderer Ren'Py is currently using. Defined keys are:
"renderer""resizable""additive""model"Other, renderer-specific, keys may also exist. The dictionary should be treated as immutable. This should only be called once the display has been started (that is, after the init phase has finished).
renpy.get_say_attributes() linkGets the attributes associated with the current say statement, or None if no attributes are associated with this statement.
This is only valid when executing or predicting a say statement.
renpy.get_skipping() linkReturns "slow" if the Ren'Py is skipping, "fast" if Ren'Py is fast skipping, and None if it is not skipping.
renpy.get_transition(layer=None) linkGets the transition for layer, or the entire scene if layer is None. This returns the transition that is queued up to run during the next interaction, or None if no such transition exists.
renpy.iconify() linkIconifies the game.
renpy.invoke_in_thread(fn, *args, **kwargs) linkInvokes the function fn in a background thread, passing it the provided arguments and keyword arguments. Restarts the interaction once the thread returns.
This function creates a daemon thread, which will be automatically stopped when Ren'Py is shutting down.
This thread is very limited in what it can do with the Ren'Py API.
Changing store variables is allowed, as is calling the renpy.queue_event()
function. Most other portions of the Ren'Py API are expected to be called from
the main thread.
The primary use of this function is to place accesss to a web API in a second thread, and then update variables with the results of that call, by storing the result in variables and then relying on the interaction restart to cause screens to display those variables.
renpy.is_init_phase() linkReturns True if Ren'Py is currently executing init code, or False otherwise.
renpy.is_mouse_visible() linkReturns True if the mouse cursor is visible, False otherwise.
renpy.is_seen(ever=True) linkReturns true if the current line has been seen by the player.
If ever is true, we check to see if the line has ever been seen by the player. If false, we check if the line has been seen in the current play-through.
renpy.is_skipping() linkReturns True if Ren'Py is currently skipping (in fast or slow skip mode), or False otherwise.
renpy.is_start_interact() linkReturns true if restart_interaction has not been called during the current interaction. This can be used to determine if the interaction is just being started, or has been restarted.
renpy.language_tailor(chars, cls) linkThis can be used to override the line breaking class of a character. For example, the linebreaking class of a character can be set to ID to treat it as an ideograph, which allows breaks before and after that character.
renpy.load_module(name) linkThis loads the Ren'Py module named name. A Ren'Py module consists of Ren'Py script that is loaded into the usual (store) namespace, contained in a file named name.rpym or name.rpymc. If a .rpym file exists, and is newer than the corresponding .rpymc file, it is loaded and a new .rpymc file is created.
All of the init blocks (and other init-phase code) in the module are run before this function returns. An error is raised if the module name cannot be found, or is ambiguous.
Module loading may only occur from inside an init block.
renpy.load_string(s, filename=u'<string>') linkLoads s as Ren'Py script that can be called.
Returns the name of the first statement in s.
filename is the name of the filename that statements in the string will appear to be from.
renpy.maximum_framerate(t) linkForces Ren'Py to draw the screen at the maximum framerate for t seconds. If t is None, cancels the maximum framerate request.
renpy.munge(name, filename=None) linkMunges name, which must begin with __.
renpy.not_infinite_loop(delay) linkResets the infinite loop detection timer to delay seconds.
renpy.notify(message) linkCauses Ren'Py to display the message using the notify screen. By default, this will cause the message to be dissolved in, displayed for two seconds, and dissolved out again.
This is useful for actions that otherwise wouldn't produce feedback, like screenshots or quicksaves.
Only one notification is displayed at a time. If a second notification is displayed, the first notification is replaced.
This function just calls config.notify, allowing its implementation
to be replaced by assigning a new function to that variable.
renpy.pop_call() linkPops the current call from the call stack, without returning to the location.
This can be used if a label that is called decides not to return to its caller.
renpy.predicting() linkReturns true if Ren'Py is currently in a predicting phase.
renpy.queue_event(name, up=False, **kwargs) linkQueues an event with the given name. Name should be one of the event
names in config.keymap, or a list of such names.
The event is queued at the time this function is called. This function will
not work to replace an event with another - doing so will change event order.
(Use config.keymap instead.)
This method is threadsafe.
renpy.quit(relaunch=False, status=0, save=False) linkThis causes Ren'Py to exit entirely.
_quit_slot before Ren'Py
terminates.renpy.quit_event() linkTriggers a quit event, as if the player clicked the quit button in the window chrome.
renpy.reload_script() linkCauses Ren'Py to save the game, reload the script, and then load the save.
This should only be called during development. It works on Windows, macOS, and Linux, but may not work on other platforms.
renpy.reset_physical_size() linkAttempts to set the size of the physical window to the specified values in renpy.config. (That is, screen_width and screen_height.) This has the side effect of taking the screen out of fullscreen mode.
renpy.restart_interaction() linkRestarts the current interaction. Among other things, this displays images added to the scene, re-evaluates screens, and starts any queued transitions.
This only does anything when called from within an interaction (for example, from an action). Outside an interaction, this function has no effect.
renpy.screenshot(filename) linkSaves a screenshot in filename.
Returns True if the screenshot was saved successfully, False if saving failed for some reason.
The config.screenshot_pattern and _screenshot_pattern
variables control the file the screenshot is saved in.
renpy.screenshot_to_bytes(size) linkReturns a screenshot as a bytes object, that can be passed to im.Data(). The bytes will be a png-format image, such that:
$ data = renpy.screenshot_to_bytes((640, 360))
show expression im.Data(data, "screenshot.png"):
align (0, 0)
Will show the image. The bytes objects returned can be stored in save files and persistent data. However, these may be large, and care should be taken to not include too many.
This function may be slow, and so it's intended for save-like screenshots, and not realtime effects.
renpy.scry() linkReturns the scry object for the current statement.
The scry object tells Ren'Py about things that must be true in the future of the current statement. Right now, the scry object has the following fields:
nvl_clearnvl clear statement will execute before the
next interaction.saysay statement will execute before the
next interaction.menu_with_captionmenu statement with a caption will execute
before the next interaction.whosay or menu-with-caption statement will execute
before the next interaction, this is the character object it will use.renpy.set_autoreload(autoreload) linkSets the autoreload flag, which determines if the game will be
automatically reloaded after file changes. Autoreload will not be
fully enabled until the game is reloaded with renpy.utter_restart().
renpy.set_mouse_pos(x, y, duration=0) linkJump the mouse pointer to the location given by arguments x and y. If the device does not have a mouse pointer, this does nothing.
renpy.set_physical_size(size) linkAttempts to set the size of the physical window to size. This has the side effect of taking the screen out of fullscreen mode.
renpy.shown_window() linkCall this to indicate that the window has been shown. This interacts with the "window show" statement, which shows an empty window whenever this functions has not been called during an interaction.
renpy.split_properties(properties, *prefixes) linkSplits up properties into multiple dictionaries, one per prefix. This function checks each key in properties against each prefix, in turn. When a prefix matches, the prefix is stripped from the key, and the resulting key is mapped to the value in the corresponding dictionary.
If no prefix matches, an exception is thrown. (The empty string, "", can be used as the last prefix to create a catch-all dictionary.)
For example, this splits properties beginning with text from those that do not:
text_properties, button_properties = renpy.split_properties(properties, "text_", "")
renpy.substitute(s, scope=None, translate=True) linkApplies translation and new-style formatting to the string s.
Returns the translated and formatted string.
renpy.transition(trans, layer=None, always=False) linkSets the transition that will be used during the next interaction.
renpy.vibrate(duration) linkCauses the device to vibrate for duration seconds. Currently, this is only supported on Android.
layout.yesno_screen(message, yes=None, no=None) linkThis causes the a yes/no prompt screen with the given message to be displayed. The screen will be hidden when the user hits yes or no.