documentation index ◦ reference manual ◦ function index
Contents |
This section covers aspects of text in Ren'Py. It first covers interpolation, supported by the say and menu statements, which allows values to be substituted into text. It next discusses text tags, which allow the style of portions of strings of text to be customized. Finally, it covers how Ren'Py handles fonts.
Interpolation is supported by the `say` and `menu` statements. These statements support python string interpolation over the contents of the store. The strings used by the statements support conversion specifiers of the form `%(variable)s`, where `variable` is the name of a variable and `s` is a conversion. Useful conversions include 's', which interpolates a string; 'd', which interpolates an integer; and 'f', which interpolates a floating point number. Conversions may also include characters that modify how the string is converted. More information about conversions can be found at the Python string formatting operations reference.
In strings where interpolation is supported, percent characters (%) must be duplicated (to %%) to prevent them from being interpreted as introducing interpolation.
$ name = 'Samantha' $ age = 19 $ withyou = 110 girl "My name is %(name)s, and I am %(age)d years old. I'm with you %(withyou)d%%"
When interpolation is not supported, the effect can often be faked by formatting a string against the result of calling the globals() function.
ui.text("%(name)s's Vital Statistics" % globals())
Text tag processing is performed after interpolation, so it's important to ensure interpolation does not introduce text tags.
Text displayed by Ren'Py supports text tags. While styles can only be applied to an entire Text displayable, allow only a portion of the text in the displayable to be customized. As text tags are part of the Text displayable, they may be used in any string that is displayed on the screen. However, some of the text tags will only have effect if used in the appopriate context.
Text tags should be used fairly sparingly. If you find you're using text tags on every line of the game, it's quite possible text tags are not the right solution for the problem at hand. Investigate text styles as a possible alternative to text tags.
Text tags start with a left brace ({), and continue to the matching right brace (}). Immediately following the left brace is the tag name. The name may be followed by an argument, which is separated from the tag name by an equals sign (=). Some tags require an argument, while others require that the argument be omitted. Text tags are sensitive to case and white space.
Some tags require a corresponding closing tag. A closing tag is any text tag where the name begins with a slash (/). Closing tags should be properly nested: "{b}{i}this is okay{/i}{/b}", while "{b}{i}this is wrong{/b}{/i}". While improper nesting of text tags will generally not cause an error, this problem may cause undesirable rendering results. The text between a tag and the corresponding closing tag is called the enclosed text. All tags must be closed by the end of the text string.
To include a single left brace in text, two left braces ({{) musty be included instead.
Ren'Py supports the following text tags:
init: $ definition = Character(None, window_yfill=True, window_xmargin=20, window_ymargin=20, window_background=Solid((0, 0, 0, 192))) label start: "A game that instructs on how to make a game? Isn't that a sort of {a=define_quine}Quine{/a}?" # ... label define_quine: definition "Quine:\n\nA program that prints itself to its output." return
The last {fast} tag is the one that is used. {nw}, {p}, and {w} tags only take effect if they are after the last {fast} tag in the text.
The following is an example of a say statement that uses many text tags. Use of this many text tags is not recommended in a high-quality game.
"Using text tags, we can make text {size=+12}bigger{/size} or {size=-8}smaller{/size}. We can make it {b}bold{/b}, {i}italic{/i}, or {u}underlined{/u}. We can even change its {color=#f88}color{/color}."
The Text displayable attempts to find an an appropriate font using information about the font name, boldness, italics, underline and size. This information is supplied to the Text displayable using style properties, but may then be modified using text tags. Ren'Py translates this into a font using the following algorithm.
The truetype font loading code will automatically scale and underline the font as required. If you have not provided bold and italic font mappings, it will also artificially thicken and slant the font when necessary.
For best results, fonts should be truetype files that ship with the game. This ensures that required fonts are always present on the user's system.
We support TrueType collections "0@font.ttc" is the first font in the collection, "1@font.ttc" the second, and so on. (new in 6.10.0)
Along with the usual TrueType fonts, Ren'Py supports image-based SFonts, MudgeFonts, and BMFonts.
Image-based fonts have several advantages and several disadvantages. One of the advantages is that these fonts are bitmap-based, which means it is easy to create custom fonts and to find free examples (in contrast, the licenses of high quality TrueType fonts rarely permit redistribution). Also, since the fonts are images, it's possible to apply effects to them that Ren'Py would not otherwise support. The downsides of image-based fonts come from the fact that Ren'Py doesn't render them, but instead merely copies characters out of them. Because of this, one needs to supply another image to Ren'Py if one wants the font to be scaled, made bold, made italic, or underlined. Ren'Py will recolor the image fonts, with white being mapped to the supplied color, and other colors interpolated on a channel-by-channel basis.
Please note that you must register an image-based font for each combination of font, size, bold, italic, and underline your game uses. They can then be used by setting the font property of a style to the name of the font.
To use SFonts, they must first be registered with Ren'Py using the renpy.register_sfont function. For more information about SFonts, see [1].
To use MudgeFonts, they must be registered with the renpy.register_mudgefont function. For more information about MudgeFonts, see [2].
To use BMFonts, they must be registered with the renpy.register_bmfont function. For more information about BMFonts, see [3]. We recommend BMFont for bitmap fonts, as BMFonts support unicode and proper kerning.
Legal issues regarding the use of copyrighted outline fonts in creating image-based fonts are discussed in Bitmap Fonts and Copyright.