documentation index ◦ reference manual ◦ function index
The Ren'Py interaction functions are available so that you can customize interactions with the user taking advantage of the same code which the normal interactions use.
Contents |
The following functions either implement new game behavior that didn't merit its own statement, or complement the behavior of statements.
| Function: | renpy.block_rollback | (): |
Prevents the game from rolling back to before the current statement.
| Function: | renpy.checkpoint | (data=None): |
This creates a checkpoint that the user can rollback to. The checkpoint is placed at the statement after the last statement that interacted with the user. Once this function has been called, there should be no more interaction with the user in the current Python block.
data - If not None, this contains data that can be accessed using renpy.roll_forward_info if and when the current statement is re-executed due to the user rolling back and then rolling forward again.
renpy.checkpoint should be called after ui.interact.
| Function: | renpy.choice_for_skipping | (): |
This is called to indicate to the skipping code that we have reached a choice. If we're skipping, and if the skip after choices preference is not True, then this disables skipping. This should only be needed in a custom interaction function.
| Function: | renpy.clear_game_runtime | (): |
Resets the game runtime timer down to 0.
The game runtime counter counts the number of seconds that have elapsed while waiting for user input in the current context. (So it doesn't count time spent in the game menu.)
| Function: | renpy.current_interact_type | (): |
Returns the value of the type parameter supplied to ui.interact() during the current interaction. See renpy.last_interact_type for possible interaction types.
| Function: | renpy.display_menu | (items, window_style='menu_window', interact=True, with_none=None): |
Displays a menu containing the given items, returning the value of the item the user selects.
items - A list of tuples that are the items to be added to this menu. The first element of a tuple is a string that is used for this menuitem. The second element is the value to be returned if this item is selected, or None if this item is a non-selectable caption.
interact - If True, then an interaction occurs. If False, no such interaction occurs, and the user should call ui.interact manually.
with_none - If True, causes a "with None" statement to be run after each interaction. If None (the default), checks config.implicit_with_none to determine if a "with None" should be run.
| Function: | renpy.display_say | (who, what, ...): |
Called by Character to implement the say statement.
| Function: | renpy.full_restart | (transition=config.end_game_transition, label="_invoke_main_menu", target="_main_menu"): |
This causes a full restart of Ren'Py. This resets the state of Ren'Py to what it was when the init blocks finished running, and then restarts the game. After some init code runs, transition will be set to run on the next interaction, and control will be transferred to label. The default label initializes the main menu context, and then invokes target. target can be a screen, like "preferences_screen" or "load_screen".
It generally doesn't make sense to specify both label and target. (changed in 6.9.0)
| Function: | renpy.game_menu | (screen=None): |
Invokes the game menu.
screen is the screen to access, usually one of "load_screen", "save_screen", or "preferences_screen", but the user can define other game menu screens. If None, it defaults to the value of _game_menu_screen.
| Function: | renpy.get_game_runtime | (): |
Returns the number of seconds that have elapsed in gameplay since the last call to clear_game_timer, as a float.
The game runtime counter counts the number of seconds that have elapsed while waiting for user input in the current context. (So it doesn't count time spent in the game menu.)
| Function: | renpy.get_reshow_say | (): |
Gets a function that, when called, will reshow the previous say statement. Does not cause an interaction to occur.
| Function: | renpy.get_roll_forward | (): |
Gets the roll forward info for the current interaction. This function is intended to be used by overlay functions. The overlay function should return the result of this function to cause a roll-forward to happen.
Note that it only makes sense to use this inside of an interaction. See renpy.roll_forward_info for information on how to get the roll forward info outside of an interaction.
| Function: | renpy.get_transition | (layer=None): |
Gets the transition that has been scheduled to occur using renpy.transition.
layer - if not None, finds the transition occuring for that specific layer.
| Function: | renpy.imagemap | (ground, selected, hotspots, unselected=None, overlays=False, style='imagemap', with_none=None, **properties): |
Displays an imagemap. An image map consists of two images and a list of hotspots that are defined on that image. When the user clicks on a hotspot, the value associated with that hotspot is returned. Despite the name, this takes arbitrary displayables, not just image manipulators.
ground - The name of the file containing the ground image. The ground image is displayed for areas that are not part of any hotspots.
selected - The name of the file containing the selected image. This image is displayed in hotspots when the mouse is over them.
hotspots - A list of tuples defining the hotspots in this image map. Each tuple has the format (x0, y0, x1, y1, result). (x0, y0) gives the coordinates of the upper-left corner of the hotspot, (x1, y1) gives the lower-right corner, and result gives the value returned from this function if the mouse is clicked in the hotspot.
unselected - If provided, then it is the name of a file containing the image that's used to fill in hotspots that are not selected as part of any image. If not provided, the ground image is used instead.
overlays - If True, overlays are displayed when this imagemap is active. If False, the overlays are suppressed.
with_none - If True, causes a "with None" statement to be run after each interaction. If None (the default), checks config.implicit_with_none to determine if a "with None" should be run.
| Function: | renpy.input | (prompt, default=, allow=None, exclude='{}', length=None, with_none=None): |
This pops up a window requesting that the user enter in some text. It returns the entered text.
prompt - A prompt that is used to ask the user for the text.
default - A default for the text that this input can return.
length - If given, a limit to the amount of text that this function will return.
allow - If not None, then if an input character is not in this string, it is ignored.
exclude - If not None, then if an input character is in this set, it is ignored.
with_none - If True, causes a "with None" statement to be run after each interaction. If None (the default), checks config.implicit_with_none to determine if a "with None" should be run.
| Function: | renpy.last_interact_type | (): |
Returns the value of the type parameter supplied to ui.interact() during the last interaction. Default types are:
In addition to these, other values can be created by giving the say argument to Character or ui.interact.
| Function: | renpy.pause | (delay=None, music=None): |
When called with no arguments, this pauses and waits for the user to click before advancing the script. If given a delay parameter, then Ren'Py will wait for that amount of time before continuing, unless a user clicks to interrupt the delay. This is useful to, for instance, show an image that will stay on screen for a certain amount of time and then proceed to the next script statement without waiting for a click forever.
delay - The number of seconds to delay.
music - If supplied, and music is playing, this takes precedence over the delay parameter. It gives a time, in seconds, into the currently playing music track. Ren'Py will pause until the music has played up to that point.
Returns True if the pause was interrupted by the user hitting a key or clicking a mouse, or False if the pause was ended by the appointed time being reached.
| Function: | renpy.predict | (img): |
Forces prediction of the supplied image or displayable. This will cause it to be loaded into the image cache during the next (and only the next) interaction, if there's any free time.
| Function: | renpy.predict_display_say | (who, what, ...): |
This is the default function used by Character to predict images that will be used by renpy.display_say.
| Function: | renpy.quit | (): |
This causes Ren'Py to exit entirely.
| Function: | renpy.show_display_say | (who, what, who_args={}, what_args={}, window_args={}, image=False, no_ctc_what=..., **kwargs): |
This is called (by default) by renpy.display_say to add the widgets corresponding to a screen of dialogue to the user. It is not expected to be called by the user, but instead to be called by renpy.display_say, or by a function passed as the show_function argument to Character or renpy.display_say.
who - The name of the character that is speaking, or None to not show this name to the user.
what - What that character is saying. Please note that this may not be a string, as it can also be a list containing both text and displayables, suitable for use as the first argument of ui.text.
who_args - Additional keyword arguments intended to be supplied to the ui.text that creates the who widget of this dialogue.
what_args - Additional keyword arguments intended to be supplied to the ui.text that creates the what widget of this dialogue.
window_args - Additional keyword arguments intended to be supplied to the ui.window that creates the who widget of this dialogue.
image - If True, then who should be interpreted as an image or displayable rather than a text string.
callback - If not None, a function that should be called with no arguments before each time something is shown.
no_ctc_what - The contents of what before the click-to-continue indicator was appended.
kwargs - Additional keyword arguments should be ignored.
This function is required to return the ui.text widget displaying the what text.
| Function: | renpy.shown_window | (): |
This should be called when a window is shown on the screen. Calling this prevents config.empty_window from being called when _window is true. (And hence, prevents the empty window from being shown.)
| Function: | renpy.transition | (trans, layer=None, always=False): |
Sets the transition that will be used for the next interaction. This is useful when the next interaction doesn't take a with clause, as is the case with interactions in the renpy.pause, renpy.input, and renpy.imagemap functions.
trans - The desired transition.
layer - If the layer setting is not None, then the transition will be applied only to the layer named. Please note that only some transitions can be applied to specific layers.
always - If True, forces the transition to be used, potentially overriding the game preference setting for showing all or no transitions.
| Function: | renpy.restart_interaction | (): |
Calling this restarts the current interaction, while keeping any ongoing transitions.
This should be called whenever displayables are added or removed over the course of an interaction, or when the information used to construct the overlay changes.
| Function: | renpy.reshow_say | (): |
Reshows the last say statement. Does not cause an interaction to occur.
| Function: | renpy.roll_forward_info | (): |
When re-executing a statement after rollback, this returns the data stored using renpy.checkpoint the last time this statement was executed. If this statement is not being re-executed due to a rollback, this returns None.
Often, this data is passed as the roll_forward parameter of ui.interact. It's important to check to ensure that the value is valid before using it in this way.
Contexts store the current scene lists and execution location. Ren'Py supports a stack of contexts, but only the top-level context is saved to the save file.
| Function: | renpy.context | (): |
Returns an object that is unique to the current context, that participates in rollback and the like.
| Function: | renpy.call_in_new_context | (label): |
This code creates a new context, and starts executing code from that label in the new context. Rollback is disabled in the new context. (Actually, it will just bring you back to the real context.)
Use this to begin a second interaction with the user while inside an interaction.
| Function: | renpy.invoke_in_new_context | (callable, *args, **kwargs): |
This pushes the current context, and invokes the given python function in a new context. When that function returns or raises an exception, it removes the new context, and restores the current context.
Additional arguments and keyword arguments are passed to the callable.
Please note that the context so created cannot execute renpy code. So exceptions that change the flow of renpy code (like the one created by renpy.jump) cause this context to terminate, and are handled by the next higher context.
If you want to execute renpy code from the function, you can call it with renpy.call_in_new_context.
Use this to begin a second interaction with the user while inside an interaction.
| Function: | renpy.jump_out_of_context | (label): |
Causes control to leave the current context, and then to be transferred in the parent context to the given label.
| Function: | renpy.log | (msg): |
If config.log is not set, this does nothing. Otherwise, it opens the logfile (if not already open), formats the message to 70 columns, and prints it to the logfile.
| Function: | renpy.watch | (expression, style='default', **properties): |
This watches the given python expression, by displaying it in the upper-left corner of the screen (although position properties can change that). The expression should always be defined, never throwing an exception.
A watch will not persist through a save or restart.
| Function: | renpy.get_filename_line | (): |
Returns a pair giving the filename and line number of the current statement.
These functions correspond to the equivalent core Ren'Py language statements.
| Function: | renpy.jump | (label): |
Transfers control to label. Note that this will terminate the python block it's in.
| Function: | renpy.image | (name, img): |
This is used to execute the image statment. It takes as arguments an image name and an image object, and associates the image name with the image object.
Like the image statment, this function should only be executed in init blocks.
name - The image name, a tuple of strings.
img - The displayable that is associated with that name. If this is a string or tuple, it is interpreted as an argument to Image.
| Function: | renpy.scene | (layer='master'): |
This clears out the specified layer, or 'master' by default. This is used in the execution of the `scene` statement, but only to clear out the layer. If you want to then add something new, like the `scene` statement would normally do when an image parameter is given, call renpy.show after this.
| Function: | renpy.show | (name, at_list=[], layer='master', what=None, zorder=0, tag=None, behind=None): |
This is used to execute the show statement, adding the named image to the screen.
name - The name of the image to add to the screen. This may be a tuple of strings, or a single string. In the latter case, it is split on whitespace to make a tuple.
at_list - The at list, a list of functions that are applied to the image when shown. The members of the at list need to be pickleable if sticky_positions is True.
layer - The layer the image will be shown on.
what - If not None, this is expected to be a displayable. That displayable is shown, instead of going through the normal lookup process.
zorder - The zorder of this image.
tag - The tag of this image. If None, the tag is taken from name.
behind - A list of tags this image will be shown behind, if they are present on the same layer at the same zorder, and an image with the same tag is not already present on the layer.
| Function: | renpy.hide | (name, layer='master'): |
This finds items in the given layer (or 'master' if no layer is given) that have the same name as the first component of the given name, and removes them from the layer. This is used to execute the hide statement.
name - The name of the image to hide from the screen. This may be a tuple of strings, or a single string. In the latter case, it is split on whitespace to make a tuple. Only the first element of the tuple is used.
layer - The layer this operates on.
| Function: | renpy.with_statement | (trans, paired=None, always=False, clear=True): |
The programmatic equivalent of a with statement.
trans - The transition caused by the with statement.
paired - The paired transition that is passed into config.with_callback.
always - Causes this transition to always occur, even if the user has transitions turned off.
clear - If True, the transient layer will be cleared at the end of the transition.
These functions let you query the scene lists.
| Function: | renpy.showing | (name, layer='master'): |
Returns True if name is a prefix of an image that's being shown on layer. name may be a tuple of strings, or a single string. In the latter case, it is split on whitespace to make a tuple.
When called during image prediction, this uses the images that are predicted to be shown, rather than the images that are currently being shown.
| Function: | renpy.get_at_list | (name, layer='master'): |
This gets the at_list that was used to show a given image tag. name is parsed to get out the image tag, and the at_list corresponding to that tag is retrieved. If no image with that tag has been shown on the given layer, then None is returned.
| Function: | renpy.layer_at_list | (at_list, layer='master'): |
This sets the layer_at_list, an at_list that is applied to the given layer as a whole. This can be used to do things like moving the layer around, or zooming it in and out.
Note that this interacts poorly with MoveTransition.
| Function: | color | (s): |
This function converts hexcode string s into a color/alpha tuple. Leading # marks are ignored. Colors can be rgb or rgba, with each element having either one or two digits. (So the strings can be 3, 4, 6, or 8 digits long, not including the optional #.) A missing alpha is interpreted as 255, fully opaque.
For example, color('#123a') returns (17, 34, 51, 170), while color('c0c0c0') returns (192, 192, 192, 255).
Note that as of Ren'Py 5.6.0, functions requiring a color accept the hex string form of specification directly, with no need to use this color function.
| Function: | renpy.cache_pin | (*image_manipulators): |
When this is called with one or more image manipulators, it causes those image manipulators to be "pinned" into the image cache. This means that they will be loaded soon after the game begins, and will never be removed from the cache.
The usual use of this function is to preload images used in the game menu. Be careful with it, as it can increase Ren'Py's memory usage.
| Function: | renpy.cache_unpin | (*image_manipulators): |
This may be called with one or more image manipulators. It causes those manipulators to become unpinned and removed from the image cache.
| Function: | renpy.curry | (func): |
Currying is an operation that allows a function to be called using a chain of calls, each providing some of the arguments. In Ren'Py, calling renpy.curry(func) returns a callable object. When this object is called with arguments, a second callable object is returned that stores func and the supplied arguments. When this second callable object is called, the original function is called with the stored arguments and the arguments supplied to the second call.
Positional arguments from the first call are placed before positional arguments from the second call. If a keyword argument is given in both calls, the value from the second call takes priority.
Curry objects can be pickled provided the original function remains available at its original name.
| Function: | renpy.exists | (filename): |
Returns true if the given filename can be found in the searchpath. This only works if a physical file exists on disk. It won't find the file if it's inside of an archive.
| Function: | renpy.file | (filename): |
Returns a read-only file-like object that accesses filename. The file is accessed using Ren'Py's standard search method, and may reside in an archive. The object supports a wide subset of the fields and methods found on python's standard file object. (Basically, all of the methods that are sensible for a read-only object.)
| Function: | renpy.free_memory | (): |
Attempts to free some memory. Useful before running a renpygame-based minigame.
| Function: | renpy.get_all_labels | (): |
Returns the set of all labels defined in the program, including labels defined for internal use in the libraries.
| Function: | renpy.get_placement | (d): |
This gets the placement of displayable d. There's very little warranty on this information, as it might change when the displayable is rendered, and might not exist until the displayable is first rendered.
This returns an object with the following fields, each corresponding to a style property:
| Function: | renpy.loadable | (filename): |
Returns True if the given filename is loadable, meaning that it can be loaded from the disk or from inside an archive. Returns False if this is not the case.
| Function: | renpy.load_module | (name): |
This loads the Ren'Py module named name. A Ren'Py module consists of Ren'Py code 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 init code in the module is 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.
| Function: | renpy.seen_audio | (filename): |
Returns True if the given filename has been played at least once on the current user's system.
| Function: | renpy.seen_image | (name): |
Returns True if the named image has been seen at least once on the user's system. An image has been seen if it's been displayed using the show statement, scene statement, or renpy.show function. (Note that there are cases where the user won't actually see the image, like a show immediately followed by a hide.)
| Function: | renpy.seen_label | (label): |
Returns true if the named label has executed at least once on the current user's system, and false otherwise. This can be used to unlock scene galleries, for example.
| Variable: | renpy.random | = ... |
This object is a random number generator that implements the Python random number generation interface. Randomness can be generated by calling the the various methods this object exposes. See the Python documentation for the full list, but the most useful are:
| Method: | renpy.random.random | (): |
Return the next random floating point number in the range (0.0, #0).
| Method: | renpy.random.randint | (a, b): |
Return a random integer such that a <= N <= b.
| Method: | renpy.random.choice | (seq): |
Return a random element from the non-empty sequence seq.
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'])