Screen Actions, Values, and Functions

Ren'Py ships with a number of actions, values, and functions intended for use with screens and the screen language.

Actions

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.

Control Actions

These are actions that manage screens, interaction results, and control flow.

Hide(screen, transition=None)

This causes the screen named screen to be hidden, if it is shown.

transition

If not None, a transition that occurs when hiding the screen.

Jump(label)

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.

Return(value=None)

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.

Show(screen, transition=None, **kwargs)

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.

ShowTransient(screen, **kwargs)

Shows a transient screen. A transient screen will be hidden when the current interaction completes.

Data Actions

These set or toggle data.

SetDict(dict, key, value)

Causes the value of key in dict to be set to value.

SetField(object, field, 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.

SetVariable(variable, value)

Causes variable to be set to value.

ToggleDict(dict, key, true_value=None, false_value=None)

Toggles the value of key in dict. Toggling means to invert the value when the action is performed.

true_value

If not None, then this is the true value we use.

false_value

If not None, then this is the false value we use.

ToggleField(object, field, true_value=None, false_value=None)

Toggles field on object. Toggling means to invert the boolean value of that field when the action is performed.

true_value

If not None, then this is the true value we use.

false_value

If not None, then this is the false value we use.

ToggleVariable(variable, true_value=None, false_value=None)

Toggles variable.

true_value

If not None, then this is the true value we use.

false_value

If not None, then this is the false value we use.

Menu Actions

These actions invoke menus, or are primarily useful while in the main or game menus.

MainMenu(confirm=True)

Causes Ren'Py to return to the main menu.

confirm

If true, causes Ren'Py to ask the user if he wishes to return to the main menu, rather than returning directly.

Quit(confirm=True)

Quits the game.

confirm

If true, prompts the user if he wants to quit, rather than quitting directly.

ShowMenu(screen=None)

Causes us to enter the game menu, if we're not there already. If we are in the game menu, then this shows a screen or jumps to a label.

screen is usually the name of a screen, which is shown using the screen mechanism. If the screen doesn't exist, then "_screen" is appended to it, and that label is jumped to.

• ShowMenu("load")
• ShowMenu("save")
• ShowMenu("preferences")

This can also be used to show user-defined menu screens. For example, if one has a "stats" screen defined, one can show it as part of the game menu using:

• ShowMenu("stats")

ShowMenu without an argument will enter the game menu at the default screen, taken from _game_menu_screen.

Start(label='start')

Causes Ren'Py to jump out of the menu context to the named label. The main use of this is to start a new game from the main menu. Common uses are:

• Start() - Start at the start label.
• Start("foo") - Start at the "foo" label.

File Actions

These actions handle saving, loading, and deleting of files. Many of these take the name and page arguments.

name

The name of the file to save to. This can be a string or an integer. It's combined with the page to create the filename.

page

The page that this action acts on. This is one of "auto", "quick", or a positive integer. If None, the page is determined automatically, based on a persistent page number.

FileAction(name, page=None)

"Does the right thing" with the file. This means loading it if the load screen is showing, and saving to it otherwise.

FileDelete(name, confirm=True, page=None)

Deletes the file.

confirm

If true, prompts before deleting a file.

FileLoad(name, confirm=True, page=None)

Loads the file.

confirm

If true, prompt if loading the file will end the game.

FilePage(page)

Sets the file page to page, which should be one of "auto", "quick", or an integer.

FilePageNext(max=None)

Goes to the next file page.

max

If set, this should be an integer that gives the number of the maximum file page we can go to.

FilePagePrevious(self)

Goes to the previous file page, if possible.

FileSave(name, confirm=True, newest=True, page=None)

Saves the file.

The button with this slot is selected if it's marked as the newest save file.

confirm

If true, then we will prompt before overwriting a file.

newest

If true, then this file will be marked as the newest save file when it's saved. (Set this to false for a quicksave, for example.)

page

The name of the page that it will be saved to.

FileTakeScreenshot()

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.

Audio Actions

Play(channel, file, **kwargs)

Causes an audio file to be played on a given channel.

channel

The channel to play the sound on.

file

The file to play.

Any keyword arguments are passed to renpy.music.play()

Queue(channel, file, **kwargs)

Causes an audio file to be queued on a given channel.

channel

The channel to play the sound on.

file

The file to play.

Any keyword arguments are passed to renpy.music.queue()

Stop(channel, **kwargs)

Causes an audio channel to be stopped.

channel

The channel to play the sound on.

file

The file to play.

Any keyword arguments are passed to renpy.music.play()

Other Actions

These are other actions, not found anywhere else.

Help(help=None)

Displays help.

help

If this is a string giving a label in the programe, then that label is called in a new context when the button is chosen. Otherwise, it should be a string giving a file that is opened in a web browser. If None, the value of config.help is used in the same wayt.

If(expression, true=None, false=None)

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.

InvertSelected(action)

This inverts the selection state of the provided action, while proxying over all of the other methods.

Notify(message)

Displays message using renpy.notify().

Screenshot()

Takes a screenshot.

Skip()

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.

With(transition)

Causes transition to occur.

Values

Values are used with bars, to set the bar value, and to allow the bar to adjust an underlying property.

AnimatedValue(value=0.0, range=1.0, delay=1.0, old_value=None)

This animates a value, taking delay seconds to vary the value from old_value to value.

value

The value itself, a number.

range

The range of the value, a number.

delay

The time it takes to animate the value, in seconds. Defaults to 1.0.

old_value

The old value. If this is None, then the value is taken from the AnimatedValue we replaced, if any. Otherwise, it is initialized to value.

FieldValue(object, field, range, max_is_zero=False, style='bar')

A value that allows the user to adjust the value of a field on an object.

object

The object.

field

The field, a string.

range

The range to adjust over.

max_is_zero

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.

style

The styles of the bar created.

MixerValue(mixer)

The value of an audio mixer.

mixer

The name of the mixer to adjust. This is usually one of "music", "sfx", or "voice", but user code can create new mixers.

StaticValue(value=0.0, range=1.0)

This allows a value to be specified statically.

value

The value itself, a number.

range

The range of the value.

XScrollValue(viewport)

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.

YScrollValue(viewport)

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.

Functions

These functions are useful in association with screens.

Preferences

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)

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:

• Preference("display", "fullscreen") - displays in fullscreen mode.
• Preference("display", "window") - displays in windowed mode.
• Preference("display", "toggle") - toggle display mode.
• Preference("transitions", "all") - show all transitions.
• Preference("transitions", "none") - do not show transitions.
• Preference("transitions", "toggle") - toggle transitions.
• Preference("text speed", 0) - make test appear instantaneously.
• Preference("text speed", 142) - set text speed to 142 characters per second.
• Preference("joystick") - Show the joystick preferences.
• Preference("skip", "seen") - Only skip seen messages.
• Preference("skip", "all") - Skip unseen messages.
• Preference("skip", "toggle") - Toggle skipping.
• Preference("begin skipping") - Starts skipping.
• Preference("after choices", "skip") - Skip after choices.
• Preference("after choices", "stop") - Stop skipping after choices.
• Preference("after choices", "toggle") - Toggle skipping after choices.
• Preference("auto-forward time", 0) - Set the auto-forward time to infinite.
• Preference("auto-forward time", 10) - Set the auto-forward time (unit is seconds per 250 characters).
• Preference("auto-forward", "enable") - Enable auto-forward mode.
• Preference("auto-forward", "disable") - Disable auto-forward mode.
• Preference("auto-forward", "toggle") - Toggle auto-forward mode.
• Preference("music mute", "enable") - Mute the music mixer.
• Preference("music mute", "disable") - Un-mute the music mixer.
• Preference("music mute", "toggle") - Toggle music mute.
• Preference("sound mute", "enable") - Mute the sound mixer.
• Preference("sound mute", "disable") - Un-mute the sound mixer.
• Preference("sound mute", "toggle") - Toggle sound mute.
• Preference("voice mute", "enable") - Mute the voice mixer.
• Preference("voice mute", "disable") - Un-mute the voice mixer.
• Preference("voice mute", "toggle") - Toggle voice mute.

Values that can be used with bars are:

• Preference("text speed")
• Preference("auto-forward time")
• Preference("music volume")
• Preference("sound volume")
• Preference("voice volume")

File Functions

These functions return useful information about files. They use the same default page as the file actions.

FileLoadable(name, page=None)

This is a function that returns true if the file is loadable, and false otherwise.

FilePageName(auto='a', quick='q')

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.

FileSaveName(name, empty='', page=None)

Return 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)

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.

FileSlotName(slot, slots_per_page, auto='a', quick='q', format='%s%d')

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:

• When the first page is slowing, this returns "2".
• When the second page is showing, this returns "12".
• When the auto page is showing, this returns "a2".
• When the quicksave page is showing, this returns "q2".

slot

The number of the slot to access.

slots_per_page

The number of slots per page.

auto

A prefix to use for the auto page.

quick

A prefix to use for the quick page.

format

The formatting code to use. This is given two arguments: A string giving the page prefix, and an integer giving the slot number.

FileTime(name, format='%b %d, %H:%M', empty='', page=None)

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.