Interaction Functions
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.
Statement Helper Functions
The following functions either implement new game behavior that didn't merit its own statement, or complement the behavior of statements.
Function: renpy.show_display_say( | who, what, who_args={}, what_args={}, window_args={}, image=False, **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.
kwargs - Additional keyword arguments should be ignored.
This function is required to return the ui.text widget displaying the what text.
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.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.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.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.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.
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.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.
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.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.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.
Function: renpy.block_rollback( | ) |
Prevents the game from rolling back to before the current statement.
Function: renpy.restart_interaction( | ) |
Calling this restarts the current interaction. This will immediately end any ongoing transition, and will call all of the overlay functions again.
This should be called whenever widgets are added or removed over the course of an interaction, or when the information used to construct the overlay changes.
Function: renpy.full_restart( | ) |
This causes a full restart of Ren'Py. This clears the store and configuration, and re-runs init blocks before branching off to the start label. It's very close to what happens when we quit out and re-run the interpreter, except for some caches not being cleared.
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.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.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.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.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: 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.
Context Functions
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.
Debugging Functions
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.
Ren'Py Statement Functions
These functions correspond to the equivalent core Ren'Py language statements.
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. 5.6.5
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.
Miscellaneous Utility Functions
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, 1.0).
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'])