Ren'Py の GUI はデフォルトでも魅力的 (そうであることを望む) ですが、かなりカスタマイズ可能で、必要ならば完全に置き換えられます。 このページでは簡単なものから中級レベルのものまで GUI カスタマイズの方法を説明します。
ここでは (gui.rpy ファイルにある) 新しいスタイルの Ren'Py GUI を使用することを前提にしています。 (screens.rpy を使用する) 以前の GUI は、このガイドでは高度な GUI カスタマイズとして扱います。
There are a few simple pieces of GUI customization that make sense for all but the simplest visual novels. What these customizations have in common is that they do not require editing gui.rpy. These customizations change the GUI somewhat, but do not drastically change the look of the GUI.
The easiest thing to change about the GUI is to change the size and color of the GUI. Ren'Py will prompt you to make these choices when you first create a project, but choosing "Change/Update GUI" in the launcher will let you change your choice.
When changing the GUI through the launcher, Ren'Py will prompt if you want to simply change the launcher, or update gui.rpy. Both choices will overwrite most image files, and overwriting gui.rpy will get rid of changes to that file.
As a result, you probably want to do this before any other customization.
Ren'Py will prompt for the default resolution of the project, and then also for the color scheme to use. Once you select those, it will update the GUI to match your choices.
There are a couple of variables in options.rpy that are used by the gui code.
Here's an example of these defines:
define config.name = _('Old School High School') define gui.show_name = True define config.version = "1.0" define gui.about = _("Created by PyTom.\n\nHigh school backgrounds by Mugenjohncel.")
For convenience, it might make sense to define gui.about using a triple-quoted string, in which case line endings are respected.
define gui.about = _("""\ Created by PyTom. High school backgrounds by Mugenjohncel.""")
Next, we will demonstrate the intermediate level of GUI customization. At the intermediate level, it's possible to change the colors, fonts, and images used by the game. In general, intermediate customization keeps the screens mostly the same, with buttons and bars in the same places, although modifying the screens to add new functionality is certainly possible.
Many of these changes involve editing variables in gui.rpy. For example, to increase the dialogue font size, find the line that reads:
define gui.font_size = 22
and increase or decrease it, for example, to:
define gui.font_size = 20
Note that the default values are often different than what's found in this documentation. The default values can changed based on size and colors selected for the game, and the values in this file are an example of extensive gui customization. It's best to search gui.rpy for define and the variable in question - for example, "define gui.font_size".
Some of the adjustments below either partially or completely effect image files. As a result, the changes only take effect when the image files themselves are updated, which can be done by choosing "Change GUI" in the launcher, and telling it to regenerate image files. (But note that doing so will overwrite any image files you have already modified.)
You may want to consider waiting until your game is nearly complete before customizing gui.rpy in this way. While old gui.rpys will work in newer Ren'Py versions, newer gui.rpys may have features and fixes that older versions lack. Customizing the gui early may make it harder to take advantage of such improvements.
There are a number of relatively easy customizations that can be performed to change how dialogue is displayed to the player. The first is changing the textbox.
In addition, there are a number of variables that can be customized to change dialogue.
gui.text_color= "#402000" link
This sets the color of the dialogue text.
gui.default_font= "ArchitectsDaughter.ttf" link
This sets the font that is used for dialogue text, menus, inputs, and other in-game text. The font file should exist in the game directory.
gui.text_size= 33 link
Sets the size of the dialogue text. This may need to be increased or decreased to fit the selected font in the space alloted.
gui.name_text_size= 45 link
Sets the size of character names.
By default, the character name label uses the accent color. The color can be easily changed when defining a character:
define e = Character("Eileen", who_color="#104010")
There are also a pair of overlay images. These are used to darken or lighten the background image to make buttons and other user interface components more readable. These images are in the overlay directory:
Here are a pair of example overlay images, and what the game looks like with the overlay images added.
There are a number of gui variables that can be used to change the color, font, and size of text.
These variables should generally be set to hexadecimal color codes, which are strings of the form "#rrggbb", similar to color codes used by web browsers. For example, "#663399" is the code for a shade of purple. There are many tools online that let you create html color codes, such as this one.
In addition to
documented above, the following variables exist:
gui.accent_color= '#000060' link
The accent color is used in many places in the GUI, including titles and labels.
gui.idle_color= '#606060' link
The color used for most buttons when not focused or selected.
gui.idle_small_color= '#404040' link
The color used for small text (like the date and name of a save slot, and quick menu buttons) when not hovered. This color often needs to be a bit lighter or darker than idle_color to compensate for the smaller size of the font.
gui.hover_color= '#3284d6' link
The color used by focused items in the gui, including the text of of buttons and the thumbs (movable areas) of sliders and scrollbars.
gui.selected_color= '#555555' link
The color used by the text of selected buttons. (This takes priority over the hover and idle colors.)
gui.insensitive_color= '#8888887f' link
The color used by the text of buttons that are insensitive to user input. (For example, the rollback button when no rollback is possible.)
gui.interface_text_color= '#404040' link
The color used by static text in the game interface, such as text on the help and about screens.
gui.muted_color= '#6080d0' link
gui.hover_muted_color= '#8080f0' link
Muted colors, used for the sections of bars, scrollbars, and sliders that do not represent the value or visible area. (These are only used when generating images, and will not take effect until images are regenerated in the launcher.)
In additional to
gui.default_font, the following variables selects the
fonts used for text. These fonts should also be placed in the game directory.
gui.interface_font= "ArchitectsDaughter.ttf" link
The font used for text for user interface elements, like the main and game menus, buttons, and so on.
gui.glyph_font= "DejaVuSans.ttf" link
A font used for certain glyphs, such as the arrow glyphs used by the skip indicator. DejaVuSans is a reasonable default for these glyphs, and is automatically included with every Ren'Py game.
gui.interface_text_size= 36 link
The size of static text in the game's user interface, and the default size of button text in the game's interface.
gui.label_text_size= 45 link
The size of section labels in the game's user interface.
gui.notify_text_size= 24 link
The size of notification text.
gui.title_text_size= 75 link
The size of the game's title.
There are a number of GUI components - such as buttons and bars - that use scalable backgrounds confgured using Border objects. Before discussing, how to customize buttons and bars, we'll first describe how this works.
Borders are given to the
A Frame takes an image, and divides it into nine parts - the four corners,
the four sides, and the center. The corners always remain the same size,
the left and right sides are stretched vertically, the top and bottom sides
are stretched horizontally, and the center is stretched in both directions.
A Borders object gives the size of each of the borders, in left, top, right, bottom order. So if the following border image is used:
along with the following borders:
Borders(40, 40, 40, 40)
one possible result is this:
As the child changes size, so will the background.
A Border object can also be given padding, including negative padding that causes the child to overlap the borders. For example, these borders:
Borders(40, 40, 40, 40, -20, -20, -20, -20)
allow the child to overlap the sides. Note that due to this overlap, the result is smaller, since the borders themselves now take up less space.
Borders can also be tiled, rather than scaled. This is invoked by variables, and produces this result.
These example images are a bit ugly, since we need to show what's going on. In practice, this system can produce quite pleasing results. This is the case when a Frame displayable is used as the background of a frame window holding user interface components.
These frame windows can be customized in two ways. The first is by changing the background image file:
And the second is by customizing variables.
gui.frame_borders= Borders(15, 15, 15, 15) link
The borders applied to frame windows.
gui.confirm_frame_borders= Borders(60, 60, 60, 60) link
The borders applied to the fame used in the confirm screen.
gui.frame_tile= True link
If true, the sides and center of the confirm screen are tiled. If false, they are scaled.
Sliders are a type of bar that is used in the preferences screen to allow the player to adjust preference with a large number of values. By default, the gui only uses horizontal sliders, but in-game code may also use vertical sliders.
Sliders are customized with the following images:
The following variables are also used:
gui.slider_size= 64 link
The height of horizontal sliders, and width of vertical sliders.
gui.slider_tile= True link
If true, the frame containing the bar of a slider is tiled. If False, if it scaled.
gui.slider_borders= Borders(6, 6, 6, 6) link
gui.vslider_borders= Borders(6, 6, 6, 6) link
The borders that are used with the Frame containing the bar image.
Here's an example of how we customize the horizontal slider.
Scrollbars are bars that are used to scroll viewports. In the gui, the most obvious place a scrollbar is used is the history screen, but vertical scrollbars can be used on other screens as well.
Sliders are customized with the following images:
The following variables are also used:
gui.scrollbar_size= 24 link
The height of horizontal scrollbars, and width of vertical scrollbars.
gui.scrollbar_tile= True link
If true, the frame containing the bar of a scrollbar is tiled. If False, if it scaled.
gui.scrollbar_borders= Borders(10, 6, 10, 6) link
gui.vscrollbar_borders= Borders(6, 10, 6, 10) link
The borders that are used with the Frame containing the bar image.
gui.unscrollable= "hide" link
This controls what to do if the bar is unscrollable. "hide" hides the bar, while None keeps it shown.
Here's an example of how we customize the vertical scrollbar.
Plain old bars are used to display a number to the player. They're not used in the gui, but can be used in creator-defined screens.
A bar can customized by editing the following images:
There are also the usual variables that control bars:
gui.bar_size= 64 link
The height of horizontal bars, and width of vertical bars.
gui.bar_tile= False link
If true, the bar images are tiled. If false, the images are linearly scaled.
gui.bar_borders= Borders(10, 10, 10, 10) link
gui.vbar_borders= Borders(10, 10, 10, 10) link
The borders that are used with the Frames containing the bar images.
Here's an example of how we customize horizontal bars.
The skip and notify screens both display frames with messages in them. Both use custom frame background images:
The variables that control these are:
gui.skip_frame_borders= Borders(24, 8, 75, 8) link
The borders of the frame that is used by the skip screen.
gui.notify_frame_borders= Borders(24, 8, 60, 8) link
The borders of the frame that is used by the notify screen.
gui.skip_ypos= 15 link
The vertical position of the skip indicator, in pixels from the top of the window.
gui.notify_ypos= 68 link
The vertical position of the notify message, in pixels from the top of the window.
Here is an example of customizing the skip and notify screens.
In addition to the simple customizations given above, there are a number of ways to control how dialogue is presented to the player.
The textbox (or window) is the window the dialogue is displayed in. In addition to changing gui/textbox.png, the following variables control how the textbox is displayed.
The character's name is placed inside a frame that uses gui/namebox.png as it's background. In addition, there are a number of variables that control the presentation of the name. The namebox is only show if the speaking character has a name (an empty name, like " ", counts).
gui.name_xpos= 360 link
gui.name_ypos= 0 link
The horizontal and vertical positions of the name and namebox. These are usually a number of pixels from the left or top side of the textbox. Setting a variable to 0.5 centers the name in the textbox (see below). These numbers can also be negative - for example, setting gui.name_ypos to -22 causes it to be places 22 pixels above the top of the textbox.
gui.name_xalign= 0.0 link
The horizontal alignment of the character's name. This can be 0.0 for left- aligned, 0.5 for centered, and 1.0 for right-aligned. (It's almost always 0.0 or 0.5) This is used for both the position of the namebox relative to gui.name_xpos, and to select the side of of the namebox that is aligned with xpos.
gui.namebox_width= None link
gui.namebox_height= None link
gui.namebox_borders= Borders(5, 5, 5, 5) link
gui.namebox_tile= False link
These variables control the display of the frame containing the namebox.
gui.text_xpos= 402 link
gui.text_ypos= 75 link
The horizontal and vertical positions of the actual dialogue. These are usually a number of pixels from the left or top side of the textbox. Setting a variable to 0.5 centers the dialogue in the textbox (see below).
gui.text_width= 1116 link
This variable gives the maximum width of a line of dialogue, in pixels. When dialogue reaches this width, it will be wrapped by Ren'Py.
gui.text_xalign= 0.0 link
The horizontal alignment of dialogue text. 0.0 is left aligned, 0.5 is centered, and 1.0 is right-aligned.
To center the character's name, use:
define gui.name_xpos = 0.5 define gui.name_xalign = 0.5
To center dialogue text, use:
define gui.text_xpos = 0.5 define gui.text_xalign = 1.0
Our example game uses this code to customize the centered namebox:
define gui.namebox_width = 300 define gui.name_ypos = -22 define gui.namebox_borders = Borders(15, 7, 15, 7) define gui.namebox_tile = True
There are a few variables that control the way the history screen is displayed.
config.history_length= 250 link
The number of blocks of dialogue Ren'Py will keep at history.
gui.history_height= 210 link
The height of a history entry, in pixels. This can be None to allow the height of a history entry to vary at the cost of performance - config.history_length may need to be lowered significantly when this is None.
gui.history_name_xpos= 0.5 link
gui.history_text_xpos= 0.5 link
The horizontal positions of the name label and dialogue text. These can be a number of pixels from the left side of the history entry, or 0.5 to center.
gui.history_name_ypos= 0 link
gui.history_text_ypos= 60 link
The vertical positions of the name label and dialogue text, relative to the top of a history entry, in pixels.
gui.history_name_width= 225 link
gui.history_text_width= 1110 link
The width of the name label and dialogue text, in pixels.
gui.history_name_xalign= 0.5 link
gui.history_text_xalign= 0.5 link
This controls the alignment of text and the side of the text that is aligned with xpos. 0.0 is left-aligned, 0.5 is center-aligned, 1.0 is right-aligned.
The nvl screen displays NVL-mode dialogue. There are a number of ways it can be customized. The first is to customize the NVL-mode background image:
There are also a number of variables that are used to customize the way nvl-mode text is displayed.
gui.nvl_borders= Borders(0, 15, 0, 30) link
The borders around the background of the NVL-mode. Since the background is not a frame, this is only used to pad out the NVL-mode to prevent it from pressing up against the sides of the screen.
gui.nvl_height= 173 link
The height of a single NVL-mode entry. Setting this to a fixed height makes it possible to have NVL-mode without paging, showing a fixed number of entries at once. Setting this to None allows entries to be of a variable size.
gui.nvl_spacing= 15 link
The spacing beween entries when gui.nvl_height is None, and the spacing between NVL-mode menu buttons.
gui.nvl_name_xpos= 0.5 link
gui.nvl_text_xpos= 0.5 link
gui.nvl_thought_xpos= 0.5 link
The positioning of character names, dialogue text, and thought/narration text, relative to the left side of the entry. This can be a number of pixels, or 0.5 to represent the center of the entry.
gui.nvl_name_xalign= 0.5 link
gui.nvl_text_xalign= 0.5 link
gui.nvl_thought_xalign= 0.5 link
The alignment of the text. This controls both the alignment of the text, and the side of the text that is placed at xpos. This can be 0.0 for left, 0.5 for center, and 1.0 for right.
gui.nvl_name_ypos= 0 link
gui.nvl_text_ypos= 60 link
gui.nvl_thought_ypos= 0 link
The position of character names, dialogue text, and thought/narration text, relative to the top of the entry. This should be a number of pixels from the top.
gui.nvl_name_width= 740 link
gui.nvl_text_width= 740 link
gui.nvl_thought_width= 740 link
The width of each kind of text, in pixels.
The position and alignment of NVL-mode menu buttons.
Ren'Py does not use NVL-mode by default. It must be invoked using NVL-mode characters, and by defining a few variables in script.rpy.
define e = Character("Eileen", kind=nvl) define narrator = nvl_narrator define menu = nvl_menu
Here's an example of the NVL screen customized with the code above.
The gui namespace is special, in that it is saved after the init phase, but before any translate python blocks are run. This makes it possible to change any gui variable in a translate python block to accomodate a second language. For example, the following code change the default text font and size.
- translate japanese python:
- gui.default_font = "MTLc3m.ttf" gui.text_size = 24
There is one issue that translators need to be aware of, and that is that in some places in gui.rpy, one variable is assigned the value of another. For example, the default gui.rpy has:
define gui.interface_font = "DejaVuSans.ttf"
and later on:
define gui.button_text_font = gui.interface_font
Since both of these statements run before any translate block runs, both variables need to be changed.
translate japanese python:: define gui.interface_font = "MTLc3m.ttf" define gui.button_text_font = "MTLc3m.ttf"
If the second statement was missing, DejaVuSans would still be used.
More advanced customization is possible by customizing screens.rpy, up to and including deleting it entirely and replacing it with your own code. Here are a few places to get started.
Styles and style properties control how displayables are displayed. To find out what style a displayable is using, put the mouse over it and type shift+I. This invokes the style inspector, which shows style names. Once the style name is known, a style statement can be used to customize it.
For example, say we've lost our minds writing gui documentation, and want to add a bright red outline to the dialogue text. We can hover the text and press shift+I to find out the style used is named say_dialogue. We can then add (to the end of screens.rpy, or somewhere in options.rpy) the style statement:
style say_dialogue: outlines [ (1, "#f00", 0, 0 ) ]
A huge number of customizations are possible using style statements.
A screen we expect to be commonly added is the click to continue screen. This is a screen that is shown when text finishes displaying. Here's a simple example:
screen ctc(): frame: at ctc_appear xalign .99 yalign .99 text _("(click to continue)"): size 18 transform ctc_appear: alpha 0.0 pause 5.0 linear 0.5 alpha 1.0
This particular ctc screen uses a transform to show the frame after 5 seconds. It's a good idea to delay CTC animations for several seconds, to give Ren'Py time to predict and load images.
Advanced creators can replace some or all of screens.rpy in its entirely.
When doing so, some or all of the code in gui.rpy may become redundant.
It's probably a good idea to call
gui.init() to reset styles - but after
that, a creator can do whatever they want. It usually makes sense to include
some or all of the special screens, to make sure
players can have access to all the functionality Ren'Py provides.
There are some Python functions that support gui code.
Given a kind of button, returns a dictionary giving standard style properties for that button. This sets:
(Note that if kind is the string "nvl_button", this will look for the gui.nvl_button_background variable.)
The background is a frame that takes its background picture from the first existing one of:
If a gui variables named gui.kind_borders exists, it's
gui.button_borders is used. If gui.kind_tile
exists, it determines if the borders are tiled, else
For what [prefix_] means, check out the :ref:`style prefix search <style-prefix-search> documentation.
Given a kind of button, returns a dictionary giving standard style properties for that button. This currently sets:
There are also a number of variables that set the text
color style property:
init(width, height) link
Initializes the gui.