Other Functions and Variables link

This page lists and documents various miscellaneous functions and variables not better listed somewhere else.

Ren'Py Version link

renpy.version(tuple=False) link

If 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 link

The version number of Ren'Py, as a string of the form "Ren'Py 1.2.3.456".

renpy.version_only link

The version number of Ren'Py, without the Ren'Py prefix. A string of the form "1.2.3.456".

renpy.version_tuple link

The version number of Ren'Py, as a tuple of the form (1, 2, 3, 456).

This is a namedtuple with four fields: major, minor, patch, and commit.

renpy.version_name link

A human readable version name, of the form "Example Version."

renpy.license link

A string giving license text that should be included in a game's about screen.

Platform Detection link

Ren'Py includes a number of variables that are set based on which platform it's running on.

renpy.windows link

Has a true value when running on Windows.

renpy.macintosh link

Has a true value when running on macOS.

renpy.linux link

Has a true value when running on Linux or other POSIX-like operating systems.

renpy.android link

Has a true value when running on Android.

renpy.ios link

Has a true value when running on iOS.

renpy.emscripten link

Has a true value when running in the browser.

renpy.mobile link

Has 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.

Memory Profiling link

renpy.diff_memory(update=True, skip_constants=False) link

Profiles 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.

skip_constants

If True, the profiler will skip scanning of large Ren'Py's containers, that are intended to be immutable after startup.

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) link

Profiles 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.

fraction

The fraction of the total memory usage to show. 1.0 will show all memory usage, .9 will show the top 90%.

minimum

If a name is accounted less than minimum bytes of memory, it will not be printed.

skip_constants

If True, the profiler will skip scanning of large Ren'Py's containers, that are intended to be immutable after startup.

As it has to scan all memory used by Ren'Py, this function may take a long time to complete.

renpy.profile_rollback() link

Profiles 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.random link

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.

SDL link

The SDL2 dll can be accessed using renpy.get_sdl_dll(). This allows the use of SDL2 functions directly. However, using them often requires knowledge of the Python ctypes module.

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. It's important to check for a None value before proceeding.

In the following example, the position of the window will be taken from SDL2:

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)

        x = ctypes.c_int()
        y = ctypes.c_int()

        result = sdl.SDL_GetWindowPosition(win, ctypes.byref(x), ctypes.byref(y))

        return result
renpy.get_sdl_dll() link

Returns a ctypes.cdll object that refers to the library that contains the instance of SDL2 that Ren'Py is using. If this fails, None is returned.

renpy.get_sdl_window_pointer() link
Return type

ctypes.c_void_p | None

Returns a pointer to the main window, or None if the main window is not displayed (or some other problem occurs).

Miscellaneous link

renpy.add_python_directory(path) link

Adds 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) link

Adds 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.can_fullscreen() link

Returns True if the current platform supports fullscreen mode, False otherwise.

renpy.capture_focus(name='default') link

If 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.

name

Should be a string. The name "tooltip" is special, as it's automatically captured when a displayable with a tooltip gains focus.

renpy.choice_for_skipping() link

Tells Ren'Py that a choice is coming up soon. This currently has two effects:

  • If Ren'Py is skipping, and the Skip After Choices preferences is set to stop skipping, skipping is terminated.

  • An auto-save is triggered.

renpy.clear_capture_focus(name='default') link

Clear the captured focus with name. If name is None, clear all captured focuses.

renpy.clear_game_runtime() link

Resets the game runtime counter.

renpy.clear_retain(layer='screens', prefix='_retain') link

Clears all retained screens

renpy.confirm(message) link

This causes the a yes/no prompt screen with the given message to be displayed, and dismissed when the player hits yes or no.

Returns True if the player hits yes, and False if the player hits no.

message

The message that will be displayed.

See Confirm() for a similar Action.

renpy.count_dialogue_blocks() link

Returns the number of dialogue blocks in the game's original language.

renpy.count_newly_seen_dialogue_blocks() link

Returns the number of dialogue blocks the user has seen for the first time during this session.

renpy.count_seen_dialogue_blocks() link

Returns the number of dialogue blocks the user has seen in any play-through of the current game.

renpy.display_notify(message) link

The default implementation of renpy.notify().

renpy.focus_coordinates() link

This 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) link

Forces a background autosave to occur.

take_screenshot

If True, a new screenshot will be taken. If False, the existing screenshot will be used.

block

If True, blocks until the autosave completes.

renpy.free_memory() link

Attempts to free some memory. Useful before running a renpygame-based minigame.

renpy.full_restart(transition=False, *, save=False) link

Causes Ren'Py to restart, returning the user to the main menu.

transition

If given, the transition to run, or None to not run a transition. False uses config.end_game_transition.

save

If true, the game is saved in _quit_slot before Ren'Py restarts and returns the user to the main menu.

renpy.get_game_runtime() link

Returns 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) link

A generator that yields a log of image loading activity. For the last 100 image loads, this returns:

  • The time the image was loaded (in seconds since the epoch).

  • The filename of the image that was loaded.

  • A boolean that is true if the image was preloaded, and false if the game stalled to load it.

The entries are ordered from newest to oldest.

age

If not None, only images that have been loaded in the past age seconds are included.

The image load log is only kept if config.developer = True.

renpy.get_menu_args() link

Returns a tuple giving the arguments (as a tuple) and the keyword arguments (as a dict) passed to the current menu statement.

renpy.get_mouse_name(interaction=False) link

Returns the name of the mouse that should be shown.

interaction

If true, get a mouse name that is based on the type of interaction occuring. (This is rarely useful.)

renpy.get_mouse_pos() link

Returns 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_on_battery() link

Returns True if Ren'Py is running on a device that is powered by an internal battery, or False if the device is being charged by some external source.

renpy.get_physical_size() link

Returns the size of the physical window.

renpy.get_refresh_rate(precision=5) link

Returns the refresh rate of the current screen, as a floating-point number of frames per second.

precision

The raw data Ren'Py gets is the number of frames per second rounded down to the nearest integer. This means that a monitor that runs at 59.95 frames per second will be reported at 59 fps. The precision argument then further 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() link

Returns a dictionary, giving information about the renderer Ren'Py is currently using. Defined keys are:

"renderer"

A string giving the name of the renderer that is in use.

"resizable"

True if and only if the window is resizable.

"additive"

True if and only if the renderer supports additive blending.

"model"

Present and true if model-based rendering is supported.

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() link

Gets 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() link

Returns "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) link

Gets 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() link

Iconifies the game.

renpy.include_module(name) link

Similar to renpy.load_module(), but instead of loading the module right away, inserts it into the init queue somewhere after the current AST node.

The module may not contain init blocks lower than the block that includes the module. For example, if your module contains an init 10 block, the latest you can load it is init 10.

Module loading may only occur from inside an init block.

renpy.invoke_in_main_thread(fn, *args, **kwargs) link

This runs the given function with the given arguments in the main thread. The function runs in an interaction context similar to an event handler. This is meant to be called from a separate thread, whose creation is handled by renpy.invoke_in_thread().

If a single thread schedules multiple functions to be invoked, it is guaranteed that they will be run in the order in which they have been scheduled:

def ran_in_a_thread():
    renpy.invoke_in_main_thread(a)
    renpy.invoke_in_main_thread(b)

In this example, it is guaranteed that a will return before b is called. The order of calls made from different threads is not guaranteed.

This may not be called during the init phase.

renpy.invoke_in_thread(fn, *args, **kwargs) link

Invokes 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 are calling calling the following functions:

Most other portions of the Ren'Py API are expected to be called from the main thread.

This does not work on the web platform, except for immediately returning without an error.

renpy.is_init_phase() link

Returns True if Ren'Py is currently executing init code, or False otherwise.

renpy.is_mouse_visible() link

Returns True if the mouse cursor is visible, False otherwise.

renpy.is_seen(ever=True) link

Returns 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() link

Returns True if Ren'Py is currently skipping (in fast or slow skip mode), or False otherwise.

renpy.is_start_interact() link

Returns 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) link

This can be used to override the line breaking class of a unicode 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.

chars

A string containing each of the characters to tailor.

cls

A string giving a character class. This should be one of the classes defined in Table 1 of UAX #14: Unicode Line Breaking Algorithm.

renpy.last_say() link

Returns an object containing information about the last say statement.

While this can be called during a say statement, if the say statement is using a normal Character, the information will be about the current say statement, instead of the preceding one.

who

The speaker. This is usually a Character() object, but this is not required.

what

A string with the dialogue spoken. This may be None if dialogue hasn't been shown yet, for example at the start of the game.

args

A tuple of arguments passed to the last say statement.

kwargs

A dictionary of keyword arguments passed to the last say statement.

Warning

Like other similar functions, the object this returns is meant to be used in the short term after the function is called. Including it in save data or making it participate in rollback is not advised.

renpy.load_module(name) link

This 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='<string>') link

Loads 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) link

Forces 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) link

Munges name, which must begin with __.

filename

The filename the name is munged into. If None, the name is munged into the filename containing the call to this function.

renpy.not_infinite_loop(delay) link

Resets the infinite loop detection timer to delay seconds.

renpy.notify(message) link

Causes 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.predicting() link

Returns true if Ren'Py is currently in a predicting phase.

renpy.queue_event(name, up=False, **kwargs) link

Queues an event with the given name. Name should be one of the event names in config.keymap, or a list of such names.

up

This should be false when the event begins (for example, when a keyboard button is pressed.) It should be true when the event ends (when the button is released.)

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) link

This causes Ren'Py to exit entirely.

relaunch

If true, Ren'Py will run a second copy of itself before quitting.

status

The status code Ren'Py will return to the operating system. Generally, 0 is success, and positive integers are failure.

save

If true, the game is saved in _quit_slot before Ren'Py terminates.

renpy.quit_event() link

Triggers a quit event, as if the player clicked the quit button in the window chrome.

renpy.reset_physical_size() link

Attempts to set the size of the physical window to the size specified using renpy.config.physical_height and renpy.config.physical_width, or the size set using renpy.config.screen_width and renpy.config.screen_height if not set.

renpy.restart_interaction() link

Restarts 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) link

Saves 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) link

Returns 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.

size

The size the screenshot will be resized to. If None, the screenshot will be resized, and hence will be the size of the player's window, without any letterbars.

This function may be slow, and so it's intended for save-like screenshots, and not realtime effects.

renpy.scry() link

Returns the scry object for the current statement. Returns None if there are no statements executing.

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_clear

Is true if an nvl clear statement will execute before the next interaction.

say

Is true if an say statement will execute before the next interaction.

menu_with_caption

Is true if a menu statement with a caption will execute before the next interaction.

who

If a say or menu-with-caption statement will execute before the next interaction, this is the character object it will use.

The scry object has a next() method, which returns the scry object of the statement after the current one, if only one statement will execute after the this one. Otherwise, it returns None.

Warning

Like other similar functions, the object this returns is meant to be used in the short term after the function is called. Including it in save data or making it participate in rollback is not advised.

renpy.set_mouse_pos(x, y, duration=0) link

Jump the mouse pointer to the location given by arguments x and y. If the device does not have a mouse pointer, this does nothing.

duration

The time it will take to perform the move, in seconds. During this time, the mouse may be unresponsive.

renpy.set_physical_size(size) link

Attempts 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() link

Call 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) link

Splits 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.transition(trans, layer=None, always=False) link

Sets the transition that will be used during the next interaction.

layer

The layer the transition applies to. If None, the transition applies to the entire scene.

always

If false, this respects the transition preference. If true, the transition is always run.

renpy.vibrate(duration) link

Causes the device to vibrate for duration seconds. Currently, this is only supported on Android.