Reference Manual: (offline | online) Quickstart: (offline | online)

## Customizing the Preferences Screen

Customizing the preferences screen is accomplished by modifying config.preferences, which is a dictionary mapping from vbox style to a list of preferences to be placed in that vbox. Modifying this dictionary and lists can move preferences around, and eliminate preferences entirely. It may be desirable to create new vbox styles, by using style.create .

Alternative, one can position preferences using config.preference_positions .

To create an entirely new preference, create it with _Preference, _SliderPreference, or _VolumePreference, and then add it to an appropriate list in config.preferences, with a command like `library.preferences['prefs_left'].insert(3, MyNewPreference)`

Function: _Preference( | name, field, values, base=...)

This is a class that's used to represent a multiple-choice preference.

name - The name of this preference. It will be displayed to the user.

field - The field on the base object that will be assigned the selected value. This field must exist.

values - A list of value name, value, condition triples. The value name is the name of this value that will be shown to the user. The value is the literal python value that will be assigned if this value is selected. The condition is a condition that will be evaluated to determine if this is a legal value. If no conditions are true, this preference will not be displayed to the user. A condition of None is always considered to be True.

base - The base object on which the variable is read from and set. This defaults to _preferences, the user preferences object.

Function: _SliderPreference( | name, range, get, set, enable='True')

A class that represents a preference that is controlled by a slider.

set - The name of this preference, that is shown to the user.

range - An integer giving the maximum value of this slider. The slider goes from 0 to range.

get - A function that's called to get the initial value of the slider. It's called with no arguments, and should return an integet between 0 and range, inclusive.

set - A function that's called when the value of the slider is set by the user. It is called with a single integer, in the range 0 to range, inclusive.

enable - A string giving a python expression. If the expression is evaluates to false, this preference is not shown.

Function: _VolumePreference( | name, mixer, enable='True', sound='None', channel=0)

This represents a preference that controls one of the volumes in the system. It is represented as a slider bar, and a button that can be pushed to play a sample sound on a channel.

name - The name of this preference, as shown to the user.

mixer - The mixer this preference controls.

enable - A string giving a python expression. If the expression is evaluates to false, this preference is not shown.

sound - A string that is evaluated to yield another string. The yielded string is expected to give a sound file, which is played as the sample sound. (We apologize for the convolution of this.)

channel - The number of the channel the sample sound is played on.

Function: _remove_preference( | name)

Removes the preference with the given name from the preferences menu.

## From Scratch

One can also write their own preference screen from scratch, as one of the game menu screens. The preferences screen can use the following variables and functions to update the preferences. Preferences take effect as soon as they are set.

Variable: _preferences.fullscreen = | False

True if Ren'Py should run in fullscreen mode, False otherwise.

Variable: _preferences.transitions = | 2

The kinds of transitions to show. 0 for no transitons, 2 for all transitions. A lesser-used value is 1, which shows all transitions except default transitions.

Variable: _preferences.text_cps = | 0

The number of characters per second to show slow text at. 0 means to show infinitely fast. A sensible range is between 1 and 150.

Variable: _preferences.afm_time = | 0

The number of seconds to delay after showing config.afm_characters (default 250) characters in auto-forward mode. A sensible range is between 1 and 40 seconds. If set to 0, auto-forward mode is disabled.

Variable: _preferences.skip_unseen = | False

If True, skipping will skip unseen messages. If False, only seen messages will be skipped.

Variable: _preferences.skip_after_choices = | False

If True, skipping continues past menus. If False, skipping stops a menus.

Function: _preferences.set_volume( | mixer, volume)

Sets the volume of the given mixer to the given volume. mixer is usually 'sfx', 'voice', or 'music', volume ranges between 0 and 1.

Function: _preferences.get_volume( | mixer)

Gets the volume of mixer, which is usually 'sfx', 'voice', or 'music'. The returned volume ranges between 0 and 1.0.

### Joystick Preferences

There are three functions that help in customizing the joystick preferences screen.

Function: _joystick_select_binding( | )

Generates a number of buttons, one for each possible joystick binding. Clicking on these buttons causes ui.interact to return a (label, key) pair, where label is a label indicating the type of binding being customized, and key is the keysym associated with it.

Function: _joystick_get_binding( | )

Calling this prepares Ren'Py to accept a joystick binding. The next call to ui.interact returns the binding when one is selected.

Function: _joystick_take_binding( | binding, key)

This takes a key and binding, and sets Ren'Py up such that that the binding will be translated into the given key.

Skeleton code for the joystick screen looks like:

    label joystick_screen:
       python hide:
           ui.vbox(xalign=0.5, yalign=0.5)
           _joystick_select_binding()
           ui.close()

           label, key = ui.interact()

           ui.text("Setting binding for " + label + ". Click to unset binding.", xalign=0.5, yalign=0.5)
           _joystick_get_binding()

           binding = ui.interact()

           _joystick_take_binding(binding, key)

        jump joystick_screen

Reference Manual: (offline | online) Quickstart: (offline | online)