Other Functions and Variables — Ren'Py Documentation (2024)

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

Ren'Py Version link

renpy.version(tuple=False) link

If tuple is false, returns a string containing "Ren'Py ", followed bythe current version of Ren'Py.

If tuple is true, returns a tuple giving each component of theversion 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 ofthe 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'sabout screen.

Platform Detection link

Ren'Py includes a number of variables that are set based on which platformit'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 onin the emulators. These are more intended for use in platform-specificPython. 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 thelast time this function was called with update true.

The accounting is by names in the store and in the Ren'Py implementationthat the memory is reachable from. If an object is reachable from morethan one name, it's assigned to the name it's most directly reachablefrom.

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 along 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 thegame. Writes an accounting of memory use by to the memory.txt file andstdout.

fraction: The fraction of the total memory usage to show. 1.0 will show allmemory usage, .9 will show the top 90%.
minimum: If a name is accounted less than minimum bytes of memory, it willnot 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 along time to complete.

renpy.profile_rollback() link: Profiles memory used by the rollback system. Writes (to memory.txt andstdout) the memory used by the rollback system. This tries to accountfor rollback memory used by various store variables, as well as byinternal aspects of the rollback system.

renpy.random link

This object is a random number generator that implementsthe Python random number generation interface.Randomness can be generated by calling the various methods this objectexposes. See the Python documentation for the full list, but the most usefulare:

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 returna list, but changes an existing one.

Unlike the standard Python random number generator, this object cooperates withrollback, 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, seededwith 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 oftenrequires knowledge of the Python ctypes module.

There are no guarantees as to the version of SDL2 that's includedwith Ren'Py, including which features will or will not be compiled in. Thesefunctions may fail on platforms that can otherwise run Ren'Py. It'simportant 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 containsthe 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

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 becalled 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 namealready exist in that namespace - do nothing for it.

This function may only be run from inside an init block. It is anerror to run this function once the game has started.

renpy.can_fullscreen() link: Returns True if the current platform supports fullscreen mode, Falseotherwise.

renpy.capture_focus(name='default') link

If a displayable is currently focused, captured the rectangular boundingbox of that displayable, and stores it with name. If not, removes anyfocus 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'sautomatically 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 hastwo effects:

If Ren'Py is skipping, and the Skip After Choices preferences is setto 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 messageto 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 timeduring this session.

renpy.count_seen_dialogue_blocks() link: Returns the number of dialogue blocks the user has seen in any play-throughof 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-focuseddisplayable. 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 existingscreenshot 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-basedminigame.

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'Pyrestarts 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 haveelapsed 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 100image 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 thegame 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 ageseconds 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 interactionoccuring. (This is rarely useful.)

renpy.get_mouse_pos() link: Returns an (x, y) tuple giving the location of the mouse pointer or thecurrent touch location. If the device does not support a mouse and is notcurrently 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 internalbattery, 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-pointnumber of frames per second.

precision

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 willbe reported at 59 fps. The precision argument reduces the precisionof this reading, such that the only valid readings are multiples ofthe precision.

Since all monitor framerates tend to be multiples of 5 (25, 30, 60,75, and 120), this likely will improve accuracy. Setting precisionto 1 disables this.

renpy.get_renderer_info() link

Returns a dictionary, giving information about the renderer Ren'Py iscurrently 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 shouldbe treated as immutable. This should only be called once the displayhas been started (that is, after the init phase has finished).

renpy.get_say_attributes() link

Gets the attributes associated with the current say statement, orNone 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 iflayer is None. This returns the transition that is queued upto run during the next interaction, or None if no suchtransition 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 isinit 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 mainthread. The function runs in an interaction context similar to anevent 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 guaranteedthat 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 beforeb is called. The order of calls made from different threads is notguaranteed.

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 theprovided arguments and keyword arguments. Restarts the interactiononce the thread returns.

This function creates a daemon thread, which will be automaticallystopped 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 followingfunctions:

renpy.restart_interaction()
renpy.invoke_in_main_thread()
renpy.queue_event()

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

This does not work on the web platform, except for immediately returningwithout 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 theplayer. If false, we check if the line has been seen in the currentplay-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 currentinteraction. This can be used to determine if the interaction is just beingstarted, or has been restarted.

renpy.language_tailor(chars, cls) link

This can be used to override the line breaking class of a unicodecharacter. Forexample, the linebreaking class of a character can be set to ID totreat it as an ideograph, which allows breaks before and after thatcharacter.

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 Table1 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 usinga 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 thisis not required.
what: A string with the dialogue spoken. This may be None if dialoguehasn'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 usedin the short term after the function is called. Including it in save dataor 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 scriptthat is loaded into the usual (store) namespace, contained in a file namedname.rpym or name.rpymc. If a .rpym file exists, and is newer than thecorresponding .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 runbefore this function returns. An error is raised if the module name cannotbe 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 willappear 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 mungedinto 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. Bydefault, this will cause the message to be dissolved in, displayedfor 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 notificationis displayed, the first notification is replaced.

This function just calls config.notify, allowing its implementationto 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 eventnames in config.keymap, or a list of such names.

up: This should be false when the event begins (for example, when a keyboardbutton is pressed.) It should be true when the event ends (when thebutton is released.)

The event is queued at the time this function is called. This function willnot 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'Pyterminates.

renpy.quit_event() link: Triggers a quit event, as if the player clicked the quit button in thewindow chrome.

renpy.reset_physical_size() link: Attempts to set the size of the physical window to the size specifiedusing renpy.config.physical_height and renpy.config.physical_width,or the size set using renpy.config.screen_width and renpy.config.screen_heightif not set.

renpy.restart_interaction() link

Restarts the current interaction. Among other things, this displaysimages added to the scene, re-evaluates screens, and starts anyqueued transitions.

This only does anything when called from within an interaction (forexample, from an action). Outside an interaction, this function hasno effect.

renpy.screenshot(filename) link

Saves a screenshot in filename.

Returns True if the screenshot was saved successfully, False if savingfailed for some reason.

The config.screenshot_pattern and _screenshot_patternvariables 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 savefiles and persistent data. However, these may be large, and care shouldbe taken to not include too many.

size: The size the screenshot will be resized to. If None, the screenshotwill 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 ifthere are no statements executing.

The scry object tells Ren'Py about things that must be true in thefuture of the current statement. Right now, the scry object has thefollowing fields:

nvl_clear: Is true if an nvl clear statement will execute before thenext interaction.
say: Is true if an say statement will execute before thenext interaction.
menu_with_caption: Is true if a menu statement with a caption will executebefore the next interaction.
who: If a say or menu-with-caption statement will executebefore the next interaction, this is the character object it will use.

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

Warning

Like other similar functions, the object this returns is meant to be usedin the short term after the function is called. Including it in save dataor 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 theside effect of taking the screen out of fullscreen mode.

renpy.shown_window() link: Call this to indicate that the window has been shown. This interactswith the "window show" statement, which shows an empty window wheneverthis functions has not been called during an interaction.

renpy.split_properties(properties, *prefixes) link

Splits up properties into multiple dictionaries, one per prefix. Thisfunction checks each key in properties against each prefix, in turn.When a prefix matches, the prefix is stripped from the key, and theresulting 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 fromthose 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 transitionapplies to the entire scene.
always: If false, this respects the transition preference. If true, thetransition is always run.

renpy.vibrate(duration) link: Causes the device to vibrate for duration seconds. Currently, thisis only supported on Android.