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.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
142
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
143
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.
144
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.
145
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:
"say" - Normal say statements.
"nvl" - NVL-mode say statements.
"imagemap" - renpy.imagemap
"pause" - renpy.pause
"input" - renpy.input
"menu" - Menus.
"misc" - Other interactions.
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.
146
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.
147
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.
148
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. 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