Ren'Py ships with a number of actions, values, and functions intended for use with screens and the screen language.
Actions are be 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.
An action may also be a list of actions, the actions in the list are run in order.
These are actions that manage screens, interaction results, and control flow.
This causes the screen named screen to be hidden, if it is shown.
Causes control to transfer to the given label. This can be used in conjunction with renpy.run_screen to define an imagemap that jumps to a label when run.
Causes the current interaction to return the supplied value. This is often used with menus and imagemaps, to select what the return value of the interaction is.
When in a menu, this returns from the menu.
This causes another screen to be shown. screen is a string giving the name of the screen. The keyword arguments are passed to the screen being shown.
If not None, transition is use to show the new screen.
Shows a transient screen. A transient screen will be hidden when the current interaction completes.
These set or toggle data.
Causes the value of key in dict to be set to value.
Causes 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.
Causes the variable name associated with the current screen to be set to value.
Causes variable to be set to value.
Toggles the value of key in dict. Toggling means to invert the value when the action is performed.
Toggles field on object. Toggling means to invert the boolean value of that field when the action is performed.
Toggles the value of the variable name in the current screen.
Toggles variable.
These actions handle saving, loading, and deleting of files. Many of these take the name and page arguments.
"Does the right thing" with the file. This means loading it if the load screen is showing, and saving to it otherwise.
Deletes the file.
Loads the file.
Sets the file page to page, which should be one of "auto", "quick", or an integer.
Goes to the next file page.
Goes to the previous file page, if possible.
Saves the file.
The button with this slot is selected if it's marked as the newest save file.
Take a screenshot to be used when the game is saved. This can be used to ensure that the screenshot is accurate, by taking a pictue of the screen before a file save screen is shown.
Performs a quick load.
Performs a quick save.
Causes an audio file to be played on a given channel.
Any keyword arguments are passed to renpy.music.play()
Causes an audio file to be queued on a given channel.
Any keyword arguments are passed to renpy.music.queue()
Sets the volume of mixer to value.
Causes an audio channel to be stopped.
Any keyword arguments are passed to renpy.music.play()
These are other actions, not found anywhere else.
Displays help.
This 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.
This inverts the selection state of the provided action, while proxying over all of the other methods.
Changes the language of the game to language. A language change causes the current statement to be restarted, and all contexts but the outermost being exited.
Displays message using renpy.notify().
This action causes a rollforward to occur, if a roll forward is possible. Otherwise, it is insensitive.
This action causes a rollback to occur, when a rollback is possible. Otherwise, nothing happens.
Takes a screenshot.
This allows an expression to control if a button should be marked as selected. It should be used as part of a list with one or more actions. For example:
# The button is selected if mars_flag is True
textbutton "Marsopolis":
action [ Jump("mars"), SelectedIf(mars_flag) ]
Causes the game to begin skipping. If the game is in a menu context, then this returns to the game. Otherwise, it just enables skipping.
Causes transition to occur.
Values are used with bars, to set the bar value, and to allow the bar to adjust an underlying property.
This animates a value, taking delay seconds to vary the value from old_value to value.
A 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.
The value of an audio mixer.
This allows a value to be specified statically.
The value of an adjustment that horizontally scrolls the the viewport with the given id, on the current screen. The viewport must be defined before a bar with this value is.
The value of an adjustment that vertically scrolls the the viewport with the given id, on the current screen. The viewport must be defined before a bar with this value is.
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.
This constructs the approprate 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:
Values that can be used with bars are:
These functions return useful information about files. They use the same default page as the file actions.
This is a function that returns true if the file is loadable, and false otherwise.
Returns 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.
Return the save_name that was in effect when the file was saved, or empty if the file does not exist.
Returns 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.
Returns 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 defauts:
Returns 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.
This function returns the side image to use.
Returns the side image associated with the currently speaking character, or a Null displayable if no such side image exists.
The tooltip class changes the screen when a button is hovered.
A 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 creadted by the tooltip is hovered, the value field changes to the value associated with the action.
Returns 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 buttton 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