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:
When a a hyperlink is clicked, the callback function defined in config.hyperlink_callback is called with the text of the argument of the hyperlink.
The default hyperlink checks to see if the hyperlink begins with "http:". If it does, the link is opened in the user's web browser. If not, the hyperlink is interpreted as a label, which is called in a new context. This is an appropriate behavior when using hyperlinks to definitions of unfamiliar terms.
Hyperlinks should not be used as a general control-flow tool, as they transfer control to a new context when clicked. If the user saves while inside that context, when he loads the game he will be returned to the screen containing the hyperlink.
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
immediately once the text is fully shown. It only makes sense to use this in dialogue text, where the effect is to cause slow text to dismiss the interaction once it has been fully displayed.
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.
Ren'Py supports rendering text using SFonts as well as TrueType fonts. An SFont is a properly prepared image file, usually a PNG, containing images of the character in the font. Ren'Py has its own implementation of SFonts that supports an arbitrary unicode character set and kerning.
SFonts have several advantages and several disadvantages. One of the advantages is that SFonts 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, as SFonts are images, it's possible to apply effects to them that Ren'Py would not otherwise support. The downsides of SFonts 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 SFont, with white being mapped to the supplied color, and other colors interpolated on a channel-by-channel basis.
For more information about SFonts, see [1].
To use SFonts, they must first be registered with Ren'Py using the renpy.register_sfont function. They can then be used by setting the font property of a style to the name of the SFont. Template:funcdef The default character set for a SFont is:
! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @ A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ ` a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~
Please note that you must register a sfont for each combination of font, size, bold, italic, and underline your game uses.
Legal issues regarding the use of copyrighted outline fonts in creating SFonts are discussed in Bitmap Fonts and Copyright