Ren'Py ships with a number of actions, values, and functions intended for use with screens and the screen language.
Actions are invoked when a button (including imagebuttons, textbuttons, and hotspots) is activated, hovered, or unhovered. Actions may determine when a button is selected or insensitive.
Along with these actions, an action may be a function that does not take any arguments. The function is called when the action is invoked. If the action returns a value, then the value is returned from an interaction.
A list of actions can usually be provided in lieu of a single action, in which case the actions in the list are run in order.
These are actions that manage screens, interaction results, and control flow.
Call(label, *args, **kwargs) linkEnds the current statement, and calls label, given as a string.
Arguments and keyword arguments are passed to renpy.call().
Hide(screen=None, transition=None, _layer=None) linkThis causes a screen to be hidden if it is shown.
renpy.hide_screen().
Ignored if screen is None.Jump(label) linkCauses control to transfer to label, given as a string.
NullAction(*args, **kwargs) linkDoes nothing.
This can be used to make a button responsive to hover/unhover events, without actually doing anything.
Return(value=None) linkCauses the current interaction to return the supplied value, which
must not be None. This is often used with menus and imagemaps, to
select what the return value of the interaction is. If the screen
was called using the call screen statement, the return value
is placed in the _return variable.
When in a menu, this returns from the menu. (The value should be None in this case.)
Show(screen, transition=None, *args, **kwargs) linkThis causes another screen to be shown. screen is a string giving the name of the screen. The arguments are passed to the screen being shown.
If not None, transition is used to show the new screen.
This action takes the _layer, _zorder and _tag keyword
arguments, which have the same meaning as in the
renpy.show_screen() function.
ShowTransient(screen, transition=None, *args, **kwargs) linkShows a transient screen. A transient screen will be hidden when the current interaction completes. The arguments are passed to the screen being shown.
If not None, transition is use to show the new screen.
This action takes the _layer, _zorder and _tag keyword
arguments, which have the same meaning as in the
renpy.show_screen() function.
ToggleScreen(screen, transition=None, *args, **kwargs) linkThis toggles the visibility of screen. If it is not currently shown, the screen is shown with the provided arguments. Otherwise, the screen is hidden.
If not None, transition is use to show and hide the screen.
This action takes the _layer, _zorder and _tag keyword
arguments, which have the same meaning as in the
renpy.show_screen() function.
These set or toggle data.
AddToSet(set, value) linkAdds value to set.
RemoveFromSet(set, value) linkRemoves value from set.
SetDict(dict, key, value) linkCauses the value of key in dict to be set to value. This also works with lists, where key is the index at which the value will be set.
SetField(object, field, value) linkCauses the a field on an object to be set to a given value. object is the object, field is a string giving the name of the field to set, and value is the value to set it to.
SetLocalVariable(name, value) linkCauses the variable called name to be set to value in the current local context.
This function is only useful in a screen that has been used by
another screen, as it provides a way of setting the value of a
variable inside the used screen. In all other cases,
SetScreenVariable() should be preferred, as it allows more
of the screen to be cached.
For more information, see Use.
This must be created in the context that the variable is set in - it can't be passed in from somewhere else.
SetScreenVariable(name, value) linkCauses the variable called name associated with the current screen
to be set to value.
In a used screen, this action sets the variable in the context
of the screen containing the used one(s).
To set variables within a used screen, and only in that
case, use SetLocalVariable() instead.
SetVariable(name, value) linkCauses the variable called name to be set to value.
The name argument must be a string, and can be a simple name like "strength", or one with dots separating the variable from fields, like "hero.strength" or "persistent.show_cutscenes".
ToggleDict(dict, key, true_value=None, false_value=None) linkToggles the value of key in dict. It also works on lists, in which case key is the index of the value to toggle. Toggling means to invert the value when the action is performed.
ToggleField(object, field, true_value=None, false_value=None) linkToggles field on object. Toggling means to invert the boolean value of that field when the action is performed.
ToggleLocalVariable(name, true_value=None, false_value=None) linkToggles the value of the variable called name in the current local context.
This function is only useful in a screen that has been used by
another screen, as it provides a way of setting the value of a
variable inside the used screen. In all other cases,
ToggleScreenVariable() should be preferred, as it allows more
of the screen to be cached.
For more information, see Use.
This must be created in the context that the variable is set in - it can't be passed in from somewhere else.
ToggleScreenVariable(name, true_value=None, false_value=None) linkToggles the value of the variable called name in the current screen.
In a used screen, this action accesses and sets the given variable
in the context of the screen containing the used one(s).
To access and set variables within a used screen, and only in that
case, use ToggleLocalVariable() instead.
ToggleSetMembership(set, value) linkToggles the membership of value in set. If the value is not in the set, it's added. Otherwise, it is removed.
Buttons with this action are marked as selected if and only if the value is in the set.
ToggleVariable(variable, true_value=None, false_value=None) linkToggles the variable whose name is given in variable.
The variable argument must be a string, and can be a simple name like "strength", or one with dots separating the variable from fields, like "hero.strength" or "persistent.show_cutscenes".
These actions handle saving, loading, and deleting of files. Many of these take the name and page arguments.
FileAction(name, page=None, **kwargs) link"Does the right thing" with the file. This means loading it if the load screen is showing (current screen is named "load"), and saving otherwise.
Other keyword arguments are passed to FileLoad or FileSave.
FileDelete(name, confirm=True, page=None, slot=False) linkDeletes the file.
FileLoad(name, confirm=True, page=None, newest=True, cycle=False, slot=False) linkLoads the file.
FilePage(page) linkSets the file page to page, which should be one of "auto", "quick", or an integer.
FilePageNext(max=None, wrap=False, auto=True, quick=True) linkGoes to the next file page.
FilePagePrevious(max=None, wrap=False, auto=True, quick=True) linkGoes to the previous file page, if possible.
FileSave(name, confirm=True, newest=True, page=None, cycle=False, slot=False) linkSaves the file.
The button with this slot is selected if it's marked as the newest save file.
config.quicksave_slots slots are
used in the cycle.FileTakeScreenshot(*args, **kwargs) linkTake a screenshot to be used when the game is saved. This can be used to ensure that the screenshot is accurate, by taking a picture of the screen before a file save screen is shown.
QuickLoad(confirm=True) linkPerforms a quick load.
QuickSave(message=u'Quick save complete.', newest=False) linkPerforms a quick save.
The concept of channels and how they work, as well as most information about audio in Ren'Py, is explained at Audio.
PauseAudio(channel, value=True) linkSets the pause flag for channel.
If value is True, the channel is paused. If False, the channel is unpaused. If "toggle", the pause flag will be toggled.
Play(channel, file, selected=None, **kwargs) linkCauses an audio file to be played on a given channel.
Any other keyword arguments are passed to renpy.music.play().
Queue(channel, file, **kwargs) linkCauses an audio file to be queued on a given channel.
Any keyword arguments are passed to renpy.music.queue()
SetMixer(mixer, volume) linkSets the volume of mixer to value.
SetMute(mixer, mute) linkSets the mute status of one or more mixers. When a mixer is muted, audio channels associated with that mixer will stop playing audio.
Stop(channel, **kwargs) linkCauses an audio channel to be stopped.
Any keyword arguments are passed to renpy.music.stop()
ToggleMute(mixer) linkToggles the mute status of one or more mixers.
CaptureFocus(name=u'default') linkIf a displayable is focused when this action is run, the rectangle
containing that displayable is stored with the name name. This
rectangle can then be retrieved with the GetFocusRect() action,
or the focus property of the Nearrect displayable.
If no displayable is focused, the previous capture with that name is removed.
ClearFocus(name=u'default') linkClears a stored focus rectangle captured with CaptureFocus().
GetFocusRect(name=u'default') linkIf a focus rectangle with the given name has been stored (either with
CaptureFocus(), or automatically by a tooltip, returns the
a (x, y, h, w) rectangle. Otherwise, returns None.
ToggleFocus(name=u'default') linkIf the focus rectangle exists, clears it, otherwise captures it.
These are other actions, not found anywhere else.
Confirm(prompt, yes, no=None, confirm_selected=False) linkPrompts the user for confirmation of an action. If the user clicks yes, the yes action is performed. Otherwise, the no action is performed.
The sensitivity and selectedness of this action match those of the yes action.
DisableAllInputValues() linkDisables all active InputValue. This will re-focus the default InputValue, if there is one. Otherwise, no InputValue will be focused.
Function(callable, *args, **kwargs) linkThis Action calls callable with args and kwargs.
This Action takes an optional _update_screens keyword argument, which defaults to true. When it is true, the interaction restarts and the screens are updated after the function returns.
If the function returns a non-None value, the interaction stops and returns that value. (When called using the call screen statement, the result is placed in the _return variable.)
Instead of using a Function action, you can define your own subclass
of the Action class. This lets you name the action, and
determine when it should be selected and sensitive.
Help(help=None) linkDisplays help.
If a screen named help is defined, that screen is displayed
using ShowMenu() and help is ignored.
A string that is used to find help. This is used in the following way:
If help is None, config.help is used as the default
value.
HideInterface(*args, **kwargs) linkCauses the interface to be hidden until the user clicks. This is typically what happens when hitting the H key in a Ren'Py game.
If(expression, true=None, false=None) linkThis returns true if expression is true, and false otherwise. Use this to select an action based on an expression. Note that the default, None, can be used as an action that causes a button to be disabled.
InvertSelected(action) linkThis inverts the selection state of the provided action, while proxying over all of the other methods.
MouseMove(x, y, duration=0) linkMove the mouse pointer to x, y. If the device does not have a mouse pointer or _preferences.mouse_move is False, this does nothing.
Notify(message) linkDisplays message using renpy.notify().
OpenDirectory(directory) linkOpens directory in a file browser. directory is relative to the config.basedir.
OpenURL(url) linkCauses url to be opened in a web browser.
QueueEvent(event, up=False) linkQueues the given event using renpy.queue_event().
RestartStatement(*args, **kwargs) linkThis action causes Ren'Py to rollback to before the current statement, and then re-run the current statement. This may be used when changing a persistent variable that affects how the statement is displayed.
If run in a menu context, this waits until the player exits to a top-level context before performing the rollback.
RollForward(*args, **kwargs) linkThis action causes a rollforward to occur, if a roll forward is possible. Otherwise, it is insensitive.
Rollback(*args, force="menu", **kwargs) linkThis action causes a rollback to occur, when a rollback is possible. Otherwise, nothing happens.
The arguments are given to renpy.rollback(). This includes the
force argument which here defaults to "menu".
RollbackToIdentifier(identifier) linkThis causes a rollback to an identifier to occur. Rollback identifiers are returned as part of HistoryEntry objects.
Screenshot(*args, **kwargs) linkTakes a screenshot.
Scroll(id, direction, amount=u'step') linkCauses a Bar, Viewport, or Vpgrid to scroll.
SelectedIf(expression) linkThis indicates that one action in a list of actions should be used to determine if a button is selected. This only makes sense when the button has a list of actions. For example:
# The button is selected only if mars_flag is True
textbutton "Marsopolis":
action [ SelectedIf(SetVariable("mars_flag", True)), SetVariable("on_mars", True) ]
The action inside SelectedIf is run normally when the button is clicked.
SensitiveIf(expression) linkThis indicates that one action in a list of actions should be used to determine if a button is sensitive. This only makes sense when the button has a list of actions. For example:
# The button is sensitive only if mars_flag is True
textbutton "Marsopolis":
action [ SensitiveIf(SetVariable("mars_flag", True)), SetVariable("on_mars", True) ]
The action inside SensitiveIf is run normally when the button is clicked.
Skip(fast=False, confirm=False) linkCauses the game to begin skipping. If the game is in a menu context, then this returns to the game. Otherwise, it just enables skipping.
With(transition) linkCauses transition to occur.
Additional actions are available in other pages of this documentation, such
as Language, Replay and EndReplay,
gui.SetPreference and gui.TogglePreference,
StylePreference, and the voice actions.
Other actions can be created using the Action class.
Bar values are used with bars, to set the bar value, and to allow the bar
to adjust an underlying property. To create a new bar value, subclass
the BarValue class. All classes that have the step keyword also accept
the force_step keyword whose behavior is described in ui.adjustment().
AnimatedValue(value=0.0, range=1.0, delay=1.0, old_value=None) linkThis animates a value, taking delay seconds to vary the value from old_value to value.
AudioPositionValue(channel=u'music', update_interval=0.1) linkA value that shows the playback position of the audio file playing in channel.
DictValue(dict, key, range, max_is_zero=False, style=u'bar', offset=0, step=None, action=None, force_step=False) linkA value that allows the user to adjust the value of a key in a dict.
FieldValue(object, field, range, max_is_zero=False, style=u'bar', offset=0, step=None, action=None, force_step=False) linkA bar value that allows the user to adjust the value of a field on an object.
If True, then when the field is zero, the value of the bar will be range, and all other values will be shifted down by 1. This works both ways - when the bar is set to the maximum, the field is set to 0.
This is used internally, for some preferences.
MixerValue(mixer) linkThe value of an audio mixer.
ScreenVariableValue(variable, range, max_is_zero=False, style=u'bar', offset=0, step=None, action=None, force_step=False) linkA bar value that adjusts the value of a variable in a screen.
If True, then when the field is zero, the value of the bar will be range, and all other values will be shifted down by 1. This works both ways - when the bar is set to the maximum, the field is set to 0.
This is used internally, for some preferences.
StaticValue(value=0.0, range=1.0) linkThis allows a value to be specified statically.
VariableValue(variable, range, max_is_zero=False, style=u'bar', offset=0, step=None, action=None, force_step=False) linkA bar value that allows the user to adjust the value of a variable in the default store.
If True, then when the field is zero, the value of the bar will be range, and all other values will be shifted down by 1. This works both ways - when the bar is set to the maximum, the field is set to 0.
This is used internally, for some preferences.
XScrollValue(viewport) linkThe value of an adjustment that horizontally scrolls the viewport with the given id, on the current screen. The viewport must be defined before a bar with this value is.
YScrollValue(viewport) linkThe value of an adjustment that vertically scrolls the viewport with the given id, on the current screen. The viewport must be defined before a bar with this value is.
Input values are used with text inputs, to set the default text, to accept
changed text, to respond to the enter key, and to determine if the text is
editable by default. To create a new input value, subclass the InputValue
class.
Ren'Py-defined input values inherit from InputValue, which means that
all values also include Enable(), Disable(), and Toggle() methods that return
actions that enable, disable, and toggle editing, respectively. See also
the DisableAllInputValues() action.
DictInputValue(dict, key, default=True, returnable=False) linkAn input value that updates key in dict.
FieldInputValue(object, field, default=True, returnable=False) linkAn input value that updates field on object.
FilePageNameInputValue(pattern=u'Page {}', auto=u'Automatic saves', quick=u'Quick saves', page=None, default=False) linkAn input value that updates the name of a file page.
ScreenVariableInputValue(variable, default=True, returnable=False) linkAn input value that updates variable.
VariableInputValue(variable, default=True, returnable=False) linkAn input value that updates variable.
These functions and classes are useful in association with screens.
While all preferences can be defined based on the Actions and Values given above, it requires some knowledge of Ren'Py to figure out the correct one to use. The preferences constructor makes this easy, by creation an action or value, as appropriate, based on the names used in the default preferences screen.
Preference(name, value=None, range=None) linkThis constructs the appropriate action or value from a preference. The preference name should be the name given in the standard menus, while the value should be either the name of a choice, "toggle" to cycle through choices, a specific value, or left off in the case of buttons.
Actions that can be used with buttons and hotspots are:
config.emphasize_audio_channels.Values that can be used with bars are:
The range parameter can be given to give the range of certain bars. For "text speed", it defaults to 200 cps. For "auto-forward time", it defaults to 30.0 seconds per chunk of text. (These are maximums, not defaults.)
Actions that can be used with buttons are:
These screens are intended for internal use, and are not customizable.
GetCharacterVolume(voice_tag) linkThis returns the volume associated with voice tag, a number between 0.0 and 1.0, which is interpreted as a fraction of the mixer volume for the voice channel.
These functions and actions work with the gamepad.
GamepadCalibrate() linkAn action that invokes the gamepad calibration routine.
GamepadExists(developer=True) linkA function that returns true if a gamepad is present, and false otherwise.
config.developer
is true.These functions return useful information about files. They use the same default page as the file actions.
FileCurrentPage() linkReturns the current file page as a string.
FileCurrentScreenshot(empty=None, **properties) linkA displayable that shows the screenshot that will be saved with the current
file, if a screenshot has been taken when entering a menu or with
FileTakeScreenshot().
If there is no current screenshot, empty is shown in its place. (If empty is
None, it defaults to Null().)
FileJson(name, key=None, empty=None, missing=None, page=None, slot=False) linkAccesses the Json information associated with name.
This always returns empty if the slot is empty.
If not, and if key is None, returns the entire dictionary containing the Json data.
Otherwise, this returns json[key] if key is defined on the json object of the save, and missing if there is a save with the given name, but it does not contain key.
Such Json data is added to a save slot by callbacks registered using
config.save_json_callbacks.
FileLoadable(name, page=None, slot=False) linkThis is a function that returns true if the file is loadable, and false otherwise.
FileNewest(name, page=None, slot=False) linkReturns True if this is the newest file slot, or False otherwise.
FilePageName(auto=u'a', quick=u'q') linkReturns the name of the current file page, as a string. If a normal page, this returns the page number. Otherwise, it returns auto or quick.
FileSaveName(name, empty=u'', page=None, slot=False) linkReturn the save_name that was in effect when the file was saved, or empty if the file does not exist.
FileScreenshot(name, empty=None, page=None, slot=False) linkReturns the screenshot associated with the given file. If the file is not loadable, then empty is returned, unless it's None, in which case, a Null displayable is created.
The return value is a displayable.
FileSlotName(slot, slots_per_page, auto=u'a', quick=u'q', format=u'%s%d') linkReturns the name of the numbered slot. This assumes that slots on normal pages are numbered in a linear order starting with 1, and that page numbers start with 1. When slot is 2, and slots_per_page is 10, and the other variables are the defaults:
FileTime(name, format=u'%b %d, %H:%M', empty=u'', page=None, slot=False) linkReturns the time the file was saved, formatted according to the supplied format. If the file is not found, empty is returned.
The return value is a string.
FileUsedSlots(page=None, highest_first=True) linkReturns a list of used numeric file slots on the page.
This function returns the side image to use.
SideImage() linkReturns the side image associated with the currently speaking character, or a Null displayable if no such side image exists.
Tooltips can now be accessed by the tooltip property available on all displayables, and the GetTooltip function. The GetTooltip function returns the value of the tooltip property when the displayable gains focus.
Here's an example:
screen tooltip_example():
vbox:
textbutton "North":
action Return("n")
tooltip "To meet a polar bear."
textbutton "South":
action Return("s")
tooltip "All the way to the tropics."
textbutton "East":
action Return("e")
tooltip "So we can embrace the dawn."
textbutton "West":
action Return("w")
tooltip "Where to go to see the best sunsets."
$ tooltip = GetTooltip()
if tooltip:
text "[tooltip]"
The Nearrect displayable can be used to display "popup-style" tooltips, and has support for a special "tooltip" focus name, that is set to the location of the last focus that set a tooltip:
screen tooltip_example2():
frame:
padding (20, 20)
align (.5, .3)
has vbox
textbutton "North":
action Return("n")
tooltip "To meet a polar bear."
textbutton "South":
action Return("s")
tooltip "All the way to the tropics."
textbutton "East":
action Return("e")
tooltip "So we can embrace the dawn."
textbutton "West":
action Return("w")
tooltip "Where to go to see the best sunsets."
# This has to be the last thing shown in the screen.
$ tooltip = GetTooltip()
if tooltip:
nearrect:
focus "tooltip"
prefer_top True
frame:
xalign 0.5
text tooltip
GetTooltip(screen=None, last=False) linkReturns the tooltip of the currently focused displayable, or None if no displayable is focused.
Warning
This has been obsoleted by the above, but you might see it in older projects.
The tooltip class changes the screen when a button is hovered.
Tooltip(default) linkA tooltip object can be used to define a portion of a screen that is updated when the mouse hovers an area.
A tooltip object has a value field, which is set to the default
value passed to the constructor when the tooltip is created. When
a button using an action created by the tooltip is hovered, the
value field changes to the value associated with the action.
Action(value) linkReturns an action that is generally used as the hovered property of a button. When the button is hovered, the value field of this tooltip is set to value. When the button loses focus, the value field of this tooltip reverts to the default.
When using a tooltip with a screen, the usual behavior is to create a tooltip object in a default statement. The value of the tooltip and the action method can then be used within the screen. The order of use within a screen doesn't matter – it's possible to use the value before an action is used.
Tooltips can take on any value. While in the example below we use the text statement to display a string on the screen, it's also possible to use the add statement to add a displayable. More complex behavior is also possible.
screen tooltip_test:
default tt = Tooltip("No button selected.")
frame:
xfill True
has vbox
textbutton "One.":
action Return(1)
hovered tt.Action("The loneliest number.")
textbutton "Two.":
action Return(2)
hovered tt.Action("Is what it takes.")
textbutton "Three.":
action Return(3)
hovered tt.Action("A crowd.")
text tt.value