Welcome to Ren'Py's documentation!
We're in the process of rewriting Ren'Py's documentation. While what we have here is the most up-to-date documentation, it's also very incomplete. To find out more about Ren'Py, please visit the Ren'Py home page:
http://www.renpy.org/
Much of Ren'Py is only documented in the older documentation, which is stored in the Ren'Py Wiki:
http://www.renpy.org/wiki/
Getting Started
Quickstart
Welcome to the Ren'Py quickstart manual. The purpose of this manual is to demonstrate how you can make a Ren'Py game from scratch, in a few easy steps. We'll do this by showing how to make a simple game, The Question, from scratch. This manual contains a number of examples, which are included as part of the demo game.
The Ren'Py Launcher
Before you begin making a game, you should first take some time to learn how the Ren'Py launcher works. The launcher lets you create, manage, edit, and run Ren'Py projects. Getting Started. To get started you'll want to download Ren'Py.
Once you've downloaded Ren'Py, you'll want to extract it. This can generally be done by right-clicking on the package file, and picking "Extract" if that's an option, or "Open" if it's not. Follow the prompts, and you'll have a working copy of Ren'Py.
Note
Please be sure you've extracted Ren'Py to its own directory or folder on disk. If you try to run it from inside a ZIP file, it won't work properly.
Once you've extracted Ren'Py, you'll need to run it. On Windows, run the renpy or renpy.exe program. On Mac OS X, run the renpy application.
On Linux, run the renpy.sh script.
After running this, the Ren'Py launcher should run.
Choosing and Launching a Project. You should first see what the completed The Question game looks like. To do this, start the Ren'Py launcher, and choose "Select Project". A menu of projects will come up. Choose "the_question" from it. You'll be returned to the main menu, and you can now choose "Launch" to start The Question.
You can get back to the Ren'Py demo by doing the same thing, but choosing "demo" instead of "the_question".
Creating a new Project. Create a new project by choosing "New Project" from the launcher. The launcher will ask you to choose a template. Choose "template". The launcher will then ask you for a project name. Since "the_question" is already taken, you should enter something different, like "My Question". The launcher will then ask you to choose a color theme for the project. It doesn't matter what you pick at this point, just choose something that appeals to you. You'll be returned to the top menu of the launcher with your new game chosen.
A Simple Game
label start:
"I'll ask her..."
"Me""Um... will you..."
"Me""Will you be my artist for a visual novel?" "Silence."
"She is shocked, and then..."
"Sylvie""Sure, but what is a \"visual novel?\""
This is perhaps one of the simplest Ren'Py games. It doesn't include any pictures or anything like that, but it does show a conversation between the two characters.
To try this out, go into the launcher, change to the "My Question" project, and pick "Edit Script". This will open the script files in a text editor. Choose the script.rpy file, and erase everything in it. We're starting from scratch, so you don't need what's there. Copy the example above into script.rpy, and save it.
You're now ready to run this example. Go back to the launcher, and click Run. Ren'Py will start up. Notice how, without any extra work, Ren'Py has given you menus that let you load and save the game, and change various preferences. When ready, click "Start Game", and play through this example game.
This example shows some of the commonly-used Ren'Py statements.
The first line is a label statement. The label statement is used to give a name to a place in the program. In this case, we create a label named start. The start label is special, as it's where Ren'Py scripts begin running when the user clicks "Start Game" on the main menu.
The other lines are say statements. There are two forms of the say statement. The first is a string (beginning with a double-quote, containing characters, and ending with a double-quote) on a line by itself, which is used for narration, and the thoughts of the main character. The second form consists of two strings. It's used for dialogue, with the first string being a character name and the second being what that character is saying.
Note that all the say statements are indented by four spaces. This is because they are a block underneath the label statement. In Ren'Py, blocks must be indented relative to the prior statement, and all of the statements in a block must be indented by the same amount. When strings contain double-quote characters, those characters need to be preceded by a backslash. This is done in the last line of our example.
While this simple game isn't much to look at, it's an example of how easy it is to get something working in Ren'Py. We'll add the pictures in a little bit, but first, let's see how to declare
characters. Characters
One problem with the first example is that it requires you to repeatedly type the name of a character each time they speak. In a dialogue-heavy game, this might be a lot of typing. Also, both character names are displayed in the same way, in fairly boring white text. To fix this, Ren'Py lets you define characters in advance. This lets you associate a short name with a character, and to change the color of the character's name.
define s = Character('Sylvie', color="#c8ffc8") define m = Character('Me', color="#c8c8ff") label start:
"I'll ask her..." m "Um... will you..."
m "Will you be my artist for a visual novel?" "Silence."
"She is shocked, and then..."
s "Sure, but what is a \"visual novel?\""
The first and and second lines define characters. The first line defines a character with the short name of "s", the long name "Sylvie", with a name that is shown in a greenish color. (The colors are red-green-blue hex triples, as used in web pages.)
The second line creates a character with a short name "m", a long name "Me", with the name shown in a reddish color. Other characters can be defined by copying one of the character lines, and changing the short name, long name, and color.
We've also changed the say statements to use character objects instead of a character name string. This tells Ren'Py to use the characters we defined in the init block.
Images
A visual novel isn't much of a visual novel without pictures. Let's add some pictures to our game.
image bg meadow ="meadow.jpg" image bg uni ="uni.jpg"
image sylvie smile ="sylvie_smile.png"
image sylvie surprised ="sylvie_surprised.png" define s = Character('Sylvie', color="#c8ffc8") define m = Character('Me', color="#c8c8ff") label start:
scene bg meadow show sylvie smile "I'll ask her..." m "Um... will you..."
m "Will you be my artist for a visual novel?" show sylvie surprised
"Silence."
"She is shocked, and then..." show sylvie smile
s "Sure, but what is a \"visual novel?\""
The first new thing we needed to do was to declare the images, using image statements on lines 2, 3, 5, and 6, inside the init block. These image statements give an image name, and the filename the image is found in.
For example, line 5 declares an image named "sylvie smile", found in the filename "sylvie_smile.png", with the tag "sylvie".
We have a scene statement on line 12. This statement clears out the screen, and shows the "bg meadow" image. The next line is a show statement, which shows the "sylvie smile" image on the screen.
The first part of an image name is the image tag. If an image is being shown, and another image with the same tag is on the screen, then the image that's on the screen is replaced with the one being shown. This happens on line 19, the second show statement. Before line 19 is run, the image "sylvie smile" is on the screen. When line 19 is run, that image is replaces with "sylvie surprised", since they share the "sylvie" tag.
For Ren'Py to find the image files, they need to be placed in the game directory of the current project. The game directory can be found at "Project-Name/game/", or by clicking the "Game Directory" button in the launcher. You'll probably want to copy the image files from the "the_question/game/" directory into the "my_question/game/" directory, so you can run this example.
Ren'Py does not make any distinction between character and background art, as they're both treated as images. In general, character art needs to be transparent, which means it should be a PNG file. Background art can be JPEG or PNG files. By convention, background images start with the "bg" tag.
Hide Statement. Ren'Py also supports a hide statement, which hides the given image.
label leaving:
s "I'll get right on it!" hide sylvie
"..."
m "That wasn't what I meant!"
It's actually pretty rare that you'll need to use hide. Show can be used when a character is changing emotions, while scene is used when everyone leaves. You only need to use hide when a character leaves and the scene stays the same.
Transitions
Simply having pictures pop in and out is boring, so Ren'Py implements transitions that can make changes to the screen more interesting. Transitions change the screen from what it looked like at the end of the last interaction (dialogue, menu, or transition), to what it looks like after any scene, show, and hide statements.
label start: scene bg uni show sylvie smile
s "Oh, hi, do we walk home together?" m "Yes..."
"I said and my voice was already shaking." scene bg meadow
with fade
"We reached the meadows just outside our hometown." "Autumn was so beautiful here."
"When we were children, we often played here." m "Hey... ummm..."
show sylvie smile with dissolve
"She turned to me and smiled." "I'll ask her..."
m "Ummm... will you..."
m "Will you be my artist for a visual novel?"
The with statement takes the name of a transition to use. The most common one is dissolve which dissolves from one screen to the next. Another useful transition is fade which fades the screen to black, and then fades in the new screen.
When a transition is placed after multiple scene, show, or hide statements, it applies to them all at once. If you were to write:
scene bg meadow show sylvie smile with dissolve
Both the "bg meadow" and "sylvie smiles" would be dissolved in at the same time. To dissolve them in one at a time, you need to write two with statements:
scene bg meadow with dissolve show sylvie smile with dissolve
This first dissolves in the meadow, and then dissolves in sylvie. If you wanted to instantly show the meadow, and then show sylvie, you could write:
scene bg meadow withNone
show sylvie smile with dissolve
Here, None is used to indicate a special transition that updates Ren'Py's idea of what the prior screen was, without actually showing anything to the user.
Positions
By default, images are shown centered horizontally, and with their bottom edge touching the bottom of the screen. This is usually okay for backgrounds and single characters, but when showing more than one character on the screen it probably makes sense to do it at another position. It also might make sense to reposition a character for story purposes.
show sylvie smile at right
and shows the image at that position. Ren'Py includes several pre-defined positions: left for the right side of the screen, right for the right side, center for centered horizontally (the default), and truecenter for centered horizontally and vertically.
A user can define their own positions, and event complicated moves, but that's outside of the scope of this quickstart.
Music and Sound
Most games play music in the background. In Ren'Py, music files automatically loop until they are stopped by the user. Music is played with the play music statement.
play music "illurock.ogg"
When changing music, one can supply a fadeout clause, which is used to fade out the old music when new music is played.
play music "illurock.ogg" fadeout 1.0
Music can be stopped with the stop music statement, which can also optionally take a fadeout clause.
stop music
Sound effects can be played with the play sound statement: playsound"effect.ogg"
Ren'Py support many formats for sound and music, but OGG Vorbis is preferred. Like image files, sound and music files must be placed in the game directory.
Ending the Game
You can end the game by running the return statement, without having called anything. Before doing this, it's best to put something in the game that indicates that the game is ending, and perhaps giving the user an ending number or ending name.
".:. Good Ending." return
That's all you need to make a kinetic novel, a game without any choices in it. Now, we'll look at what it takes to make a game that presents menus to the user.
Menus, Labels, and Jumps
The menu statement lets you present a choice to the user: s "Sure, but what's a \"visual novel?\""
menu:
"It's a story with pictures.": jump vn
"It's a hentai game.": jump hentai
label vn:
m "It's a story with pictures and music." jump marry
label hentai:
m "Why it's a game with lots of sex." jump marry
label marry: scene black with dissolve
"--- years later ---"
This example shows how menus are used with Ren'Py. The menu statement introduces an in-game-menu. The menu statement takes a block of lines, each consisting of a string followed by a colon. These are the menu choices which are presented to the user. Each menu choice should be followed by a block of one or more Ren'Py statements. When a choice is chosen, the statements following it are run.
In our example, each menu choice runs a jump statement. The jump statement transfers control to a label defined using the label statement. The code following that label is run. In our example above, after Sylvie asks her question, the user is presented with a menu containing two choices. If the user picks "It's a story with pictures.", the first jump statement is run, and control is transferred to the vn label. This will cause the pov character to say "It's a story with pictures and music.", after which control is transferred to the marry label.
Labels may be defined in any file that is in the game directory, and ends with .rpy. The
filename doesn't matter to Ren'Py, only the labels contained within it. A label may only appear in a single file.
Python and If Statements
While simple (and even fairly complex) games can be made using only using menus and jump statements, after a point it becomes necessary to store the user's choices in variables, and access them again later. This is what Ren'Py's python support is for.
Python support can be accessed in two ways. A line beginning with a dollar-sign is a single-line python statement, while the keyword "python:" is used to introduce a block of python
statements.
Python makes it easy to store flags in response to user input. Just initialize the flag at the start of the game:
label start:
$ bl_game =False
You can then change the flag in code that is chosen by menus: label hentai:
$ bl_game =True
m "Why it's a game with lots of sex." s "You mean, like a boy's love game?"
s "I've always wanted to make one of those." s "I'll get right on it!"
jump marry And check it later:
"And so, we became a visual novel creating team." "We made games and had a lot of fun making them." if bl_game:
"Well, apart from that boy's love game she insisted on making." "And one day..."
Of course, python variables need not be simple True/False values. They can be arbitrary python values. They can be used to store the player's name, to store a points score, or for any other purpose. Since Ren'Py includes the ability to use the full Python programming language, many things are possible.
Releasing Your Game
Once you've made a game, there are a number of things you should do before releasing it: Edit options.rpy.
The options.rpy file, created when you create a new game, contains a number of settings that you may want to customize. Some of them, like the screen height and screen width, should probably be set before making the game. Others, like the window title, can be set any time.
Add a plug for Ren'Py.
This step is completely optional, but we do ask that if you have credits in your game, you mention Ren'Py in them. We suggest using something like "Made with the Ren'Py visual novel engine.", but that's just a suggestion, and what you write is up to you.
We think that the games people make are the best advertising for Ren'Py, and we hope that by including this, you'll help more people learn how to make visual novels in Ren'Py. Check for a new version of Ren'Py.
New versions of Ren'Py are released on a regular basis, to fix bugs and add new features. You should check the download page to see if a new version has come out. You may also want to see if any bug-fixes are available on that page.
Check the Script.
In the Launcher, you should go to the Tools page, and pick "Check Script (Lint)". This will check your games for errors that may affect some users. These errors can affect users on the Mac and Linux platforms, so it's important to fix them all, even if you don't see them on your computer.
Build Distributions.
From the Tools page, click distribute. The launcher will check your script again, ask you a few questions, and then build the distribution of your game.
Test.
Lint is not a substitute for thorough testing. It's your responsibility to check your game before it is released. Consider asking friends to help beta-test your game, as often a tester can find problems you can't.
Release.
You should post the generated files (for Windows, Mac, and Linux) up on the web somewhere, and tell people where to download them from. Congratulations, you've released a game!
Please also add your released game to our games database, so we can keep track of the Ren'Py games being made.
Script of The Question
You can view the full script of ''The Question'' here. Where do we go from here?
This Quickstart has barely scratched the surface of what Ren'Py is capable of. For simplicity's sake, we've omitted many features Ren'Py supports. To get a feel for what Ren'Py is capable of, we suggest playing through the demo, and having Eileen demonstrate these features to you.
You may also want to read the rest of this (complex) manual, as it's the definitive guide to Ren'Py.
On the Ren'Py website, there's the a FAQ giving answers to common questions, and a
Cookbook giving useful code smippets. If you have questions, we suggest asking them at the Lemma Soft Forums, the official forum of Ren'Py. This is the central hub of the Ren'Py
community, and we welcome new users, and the questions they bring.
Thank you for choosing the Ren'Py visual novel engine. We look forward to seeing what you can create with it!
The Ren'Py Language
Language Basics
Before we can describe the Ren'Py language, we must first describe the structure of a Ren'Py script. This includes how a files are broken into blocks made up of lines, and how those lines are broken into the elements that make up statements.
Files
The script of a Ren'Py game is made up of all the files found under the game directory ending with the .rpy extension. Ren'Py will consider each of these files (in unicode order), and will use the contents of the files as the script.
Generally, there's no difference between a script broken into multiple files, and a script that consists of one big file. Control can be transferred between files by jumping to or calling a label in another file. This makes the division of a script up into files a matter of personal style -some game-makers prefer to have small files (like one per event, or one per day), while others prefer to have one big script.
To speed up loading time, Ren'Py will compile the .rpy files into .rpyc files when it starts up. When a .rpy file is changed, the .rpyc file will be updated when Ren'Py starts up. However, if a .rpyc file exists without a corresponding .rpy file, the .rpyc file will be used. This can lead to problems if a .rpy file is deleted without deleting the .rpyc file.
Comments
A Ren'Py script file may contain comments. A comment begins with a hash mark ('#'), and ends at the end of the line containing the comment. As an exception, a comment may not be
part of a string.
# This is a comment.
show black # this is also a comment.
"# This isn't a comment, since it's part of a string."
Ren'Py ignores comments, so the script is treated like the comment wasn't there. Logical Lines
A script file is broken up into logical lines. A logical line always begins at the start of a line in the file. A logical line ends at the end of a line, unless:
The last character on the line is a backslash ('\').
The line contains an open parenthesis character ('(', '{', or '['), that hasn't been matched by the cooresponding close parenthesis character (')', '}', or ']', respectively).
The end of the line occurs during a string.
Once a logical line ends, the next logical line begins at the start of the next line.
Most statements in the Ren'Py language consist of a single logical line, while some statements consist of multiple lines.
"This is one logical line"
"Since this line contains a string, it continues even when the line ends."
$ a = [ "Because of parenthesis, this line also", "spans more than one line." ]
Empty logical lines are ignored. Indentation and Blocks
Indentation is the name we give to the space at the start of each logical line that's used to line up Ren'Py statements. In Ren'Py, indentation must consist only of spaces.
Indentation is used to group statements into blocks. A block is a group of lines, and often a group of statements. The rules for dividing a file into blocks are:
A block is open at the start of a file.
A new block is started whenever a logical line is indented past the previous logical line. All logical lines inside a block must have the same indentation.
A block ends when a logical line is encountered with less indentation than the lines in the block.
Indentation is very important to Ren'Py, and cause syntax or logical errors when it's incorrect. At the same time, the use of indentation to convey block structure provides us a way of
indicating that structure without overwhelming the script text.
"This statement, and the if statement that follows, is part of a block." ifTrue:
"But this statement is part of a new block." "This is also part of that new block."
"This is part of the first block, again." Elements of Statements
Ren'Py statements are made of a few basic parts. Keyword
A keyword is a word that must literally appear in the source code. They're used to introduce statements and properties.
Names begining with a single underscore (_) are reserved for Ren'Py internal use, unless otherwise documented. When a name begins with __ but doesn't end with __, it is changed to a file-specfic version of that name.
Name
A name begins with a letter or underscore, which is followed by zero or more letters, numbers, and underscores. For our purpose, unicode characters between U+00a0 and U+fffd are considered to be letters.
Image Name
An image name consists of one or more names, separated by spaces. The name ends at the end of the statement, or when a keyword is encountered.
An image name consists of one or more names, separated by spaces. The first component of the image name is called the image tag. The second and later components of the name are the image attributes.
For example, take the image name mary beach night happy. The image tag is mary, while the image attributes are mary, beach, and night.
String
A string begins with a quote character (one of ", ', or `), contains some sequence of characters, and ends with the same quote character.
The backslash character () is used to escape quotes, special characters such as % (written as %) and { (written as {). It's also used to include newlines, using the n sequence.
Inside a Ren'Py string, consecutive whitespace is compressed into a single whitespace character, unless a space is preceded by a backslash.
'Strings can\'t contain their delimiter, unless you escape it.' Simple Expression
A simple expression is a Python expression, used to include Python in some parts of the Ren'Py script. A simple expression begins with:
A name. A string. A number.
Any python expression, in parenthesis. This can be followed by any number of:
A dot followed by a name.
A parenthesised python expression.
As an example, 3, (3 + 4), foo.bar, and foo(42) are all simple expressions. But 3 + 4 is not, as the expression ends at the end of a string.
At List
Python Expression
A python expression is an arbitrary python expression, that may not include a colon. These are used to express the conditions in the if and while statements.
Common Statement Syntax
Most Ren'Py statements share a common syntax. With the exception of the say statement, they begin with a keyword that introduces the statement. This keyword is followed by a parameter, if the statement takes one.
The parameter is then followed by one or more properties. Properties may be supplied in any order, provided each property is only supplied once. A property starts off with a keyword. For most properties, the property name is followed by one of the syntax elements given above. If the statement takes a block, the line ends with a colon (:). Otherwise, the line just ends. Python Expression Syntax
Note
It may not be necessary to read this section thoroughly right now. Instead, skip ahead, and if you find yourself unable to figure out an example, or want to figure out how things actually work, you can go back and review this.
Many portions of Ren'Py take python expressions. For example, defining a new Character involves a call to the Character function. While Python expressions are very powerful, only a fraction of that power is necessary to write a basic Ren'Py game.
Here's a synopsis of python expressions. Integer
An integer is a number without a decimal point. 3 and 42 are integers. Float
A float (short for floating-point number) is a number with a decimal point. .5, 7., and 9.0 are all floats.
String
Python strings begin with " or ', and end with the same character. \ is used to escape the end character, and to introduce special characters like newlines (\n). Unlike Ren'Py strings, python strings can't span lines.
True, False, None
There are three special values. True is a true value, False is a false value. None represents the absence of a value. For example,
Tuple
Tuples are used to represent containers where the number of items is important. For example, one might use a 2-tuple (also called a pair) to represent width and height, or a 4-tuple (x, y, width, height) to represent a rectangle.
Tuples begin with a left-parenthesis (, consist of zero or more comma-separated python expressions, and end with a right-parenthesis ). As a special case, the one-item tuple must have a parenthesis following the item. For example:
() (1,)
(1, "#555")
List
Lists are used to represent containers where the number of items may vary. A list begins with a [, contains a comma-separated list of expressions, and ends with ]. For example:
[ ] [ 1 ] [ 1, 2 ] [ 1, 2, 3 ] Variable
Python expressions can use variables, that store values defined using the define statement or python statements. A variable begins with a letter or underscore, and then has zero or more letters, numbers, or underscores. For example:
name
love_love_points trebuchet2_range
Variables beginning with _ are reserved for Ren'Py's use, and shouldn't be used by user code.
Field Access
Python modules and objects have fields, which can be accessed with by following an expression (usually a variable) with a dot and the field name. For example:
config.screen_width
Consists of a variable (config) followed by a field access (screen_width). Call
Python expressions can call a function which returns a value. They begin with an
expression (usually a variable), followed by a left-parenthesis, a comma-separated list of arguments, and a right-parenthesis. The argument list begins with the position arguments, which are python expressions. These are followed by keyword arguments, which consist of the argument name, and equals sign, and an expression. In the example example:
Character("Eileen", type=adv, color="#0f0")
we call the Character function. It's given one positional argument, the string "Eileen". It's given two keyword argument: type with the value of the adv variable, and color with a string value of "#0f0".
Constructors are a type of function which returns a new object, and are called the same way.
When reading this documentation, you might see a function signature like:
Sample
(
name, delay, position=(0, 0), **properties)
A sample function that doesn't actually exist in Ren'Py, but is used only in documentation. This function:
Has the name "Sample"
Has two positional parameters, a name and a delay. In a real function, the types of these parameters would be made clear from the documentation.
Since the functions ends with **properties, it means that it can take style properties as additional keyword arguments. Other special entries are *args, which means that it takes an arbitrary number of postional parameters, and **kwargs, which means that the keyword arguments are described in the documentation.
Python is a lot more powerful than we have space for in this manual. To learn Python in more detail, we recommend starting with the Python tutorial, which is available from python.org. While we don't think a deep knowledge of Python is necessary to work with Ren'Py, learning about python expressions is helpful.
Dialogue and Narration
Text is fundamental to visual novels, and generally quite important to storytelling-based games. This text may consist of dialogue labeled with the character that is saying it, and narration, which does not have a speaker. (For convenience, we will lump both dialogue and narration together as dialogue, except where the differences are important.) It's also
important that the user be able to customize the look of dialogue to suit their game. In Ren'Py, most dialogue is written using say statements. The look of dialogue may be customized on a per-character basis by using Character objects.
Say Statement
The say statement is used for dialogue and narration. Since it's almost always the most
frequently used statement in Ren'Py scripts, the say statement has a syntax that minimizes the overhead in writing it. Some example say statements are:
"This is narration."
"Eileen""This is dialogue, with an explicit character name." e "This is dialogue, using a character object instead."
The first form of the say statement consists of a string by itself. This form is used for narration, with the narration being the contents of the string.
The second form consists of two strings. The first string is the name of the character who is speaking, and the second is the dialogue being spoken.
The final form is consists of a simple expression followed by a string. The simple expression should evaluate to either a string giving a character name, or a Character object. In the latter case, the character object is used to control how the dialogue is shown.
Although the precise details of what a say statement does is controlled by the character object used, the usual effect of a say statement is to display dialogue on the screen until the user clicks to dismiss it, then to remove that dialogue on the screen.
Certain characters have special meaning to Ren'Py, and so can't be used in dialogue strings. The { character begins a text tag, and the [ character begins a substitution. To use them in dialogue, double them. It may also be necessary to precede a quote with a backslash to prevent it from closing the string. For example:
"I walked past a sign saying, \"Let's give it 100%!\"" Defining Character Objects
By creating a Character object and using it in a say statement, you can customize the look (and to some extent, the behavior) of dialogue. Characters are created by using the define statement to assign a Character to a variable. For example:
define e = Character("Eileen",
who_color="#c8ffc8")
Once this is done, the character can be used in a say statement: e "Hello, world."
Character is a python function, that takes a large number of keyword arguments. These keyword arguments control the behavior of the character.
Character
(
name, kind=adv, **args)
Creates and returns a Character object, which controls the look and feel of dialogue and narration.
name
If a string, the name of the character for dialogue. When name is None, display of the name is omitted, as for narration.
kind
The Character to base this Character off of. When used, the default value of any argument not supplied to this Character is the value of that argument supplied to kind. This can be used to define a template character, and then copy that character with changes.
Linked Image An image tag may be associated with a Character. This allows a say
statement involving this character to display an image with the tag, and also allows Ren'Py to automatically select a side image to show when this character speaks.
image
A string giving the image tag that is linked with this character.
Prefixes and Suffixes. These allow a prefix and suffix to be applied to the name of the character, and to the text being shown. This can be used, for example, to add quotes before and after each line of dialogue.
what_prefix
A string that is prepended to the dialogue being spoken before it is shown. what_suffix
A string that is appended to the dialogue being spoken before it is shown. who_prefix
A string that is prepended to the name of the character before it is shown. who_suffix
A string that is appended to the name of the character before it is shown. Changing Name Display. These options help to control the display of the name. dynamic
If true, then name should be a string containing a python expression. That string will be evaluated before each line of dialogue, and the result used as the name of the
Controlling Interactions. These options control if the dialogue is displayed, if an interaction occurs, and the mode that is entered upon display.
condition
If given, this should be a string containing a python expression. If the expression is false, the dialogue does not occur, as if the say statement did not happen.
interact
If true, the default, an interaction occurs whenever the dialogue is shown. If false, an interaction will not occur, and additional elements can be added to the screen. mode
A string giving the mode to enter when this character speaks. See the section on modes for more details.
callback
A function that is called when events occur while the character is speaking. See the section on character callbacks fore more information.
Click-to-continue. A click-to-continue indicator is displayed once all the text has finished displaying, to prompt the user to advance.
ctc
A Displayable to use as the click-to-continue indicator, unless a more specific indicator is used.
ctc_pause
A Displayable to use a the click-to-continue indicator when the display of text is paused by the {p} or {w} text tags.
ctc_timedpause
A Displayable to use a the click-to-continue indicator when the display of text is paused by the {p=} or {w=} text tags. When None, this takes its default from ctc_pause, use Null() when you want a ctc_pause but no ctc_timedpause. ctc_position
Controls the location of the click-to-continue indicator. If "nestled", the indicator is displayed as part of the text being shown, immediately after the last character. If "fixed", the indicator is added to the screen, and its position is controlled by the position style properties.
Screens. The display of dialogue uses a screen. These arguments allow you to select that screen, and to provide arguments to it.
screen
The name of the screen that is used to display the dialogue.
Keyword arguments beginning with show_ have the prefix stripped off, and are passed to the screen as arguments. For example, the value of show_side_image will become the value of the side_image variable in the screen.
Some useful show_ variables implemented by the default screens are: show_side_image
When given a Displayable, shows that displayable when the dialogue is shown. The position of that displayable is controlled by its position properties. This is often used to show an image of the speaking character to the side of the dialogue.
show_two_window
If true, restructures the layout so that the name of the character is placed in one window, and the dialogue text in a second window.
Styling Text and Windows. Keyword arguments beginning with who_, what_, and
window_` have their prefix stripped, and are used to style the character name, the spoken text, and the window containing both, respectively.
For example, if a character is given the keyword argument who_color="#c8ffc8", the color of the character's name is changed, in this case to green. window_background="frame.png" sets the background of the window containing this character's dialogue.
The style applied to the character name, spoken text, and window can also be set this way, using the who_style, what_style, and window_style arguments, respectively.
Say with Image Attributes
When a character is defined with an associated image tag, say statement involving that character may have image attributes placed between the character name and the second string.
In this form, if an image with the given tag is showing, Ren'Py will issue a show command involving the character tag and the attributes. If the image is not shown, Ren'Py will store the attributes for use by side images, but will not show an image.
For example, the code:
define e = Character("Eileen", image="eileen") label start:
show eileen mad
e "I'm a little upset at you."
e happy "But it's just a passing thing." is equivalent to:
define e = Character("Eileen") label start:
show eileen mad
e "I'm a little upset at you." show eileen happy
e "But it's just a passing thing."
To cause a transition to occur whenever the images are changed in this way, set config.say_attribute_transition to a transition.
Example Characters
Here are a few example characters:
# A character that has its dialogue enclosed in parenthesis.
define e = Character("Eileen", what_prefix='"', what_suffix='"')
# A character that pulls its name from a variable.
define p = Character("player_name", dynamic=True) Special Characters
A few character names are defined by default, and are used automatically in certain
situations. Intentionally redefining these characters can change the behavior of Ren'Py, but accidentally using them can be a problem.
adv
The default kind of character used by Character. This sets up a character such that one line is displayed on the screen at a time.
nvl
A kind of Character that causes dialogue to be displayed in NVL-mode, with multiple lines of text on the screen at once.
narrator
The character that's used to display narration, by say statements without a character name.
name_only
A character that is used to display dialogue in which the character name is given as a string. This character is copied to a new character with the given name, and then that new character is used to display the dialogue.
Displaying Images
The defining aspect of a visual novel, lending its name to the form, are the visuals. Ren'Py contains four statements that control the display of images, and a model that determines the order in which the images are displayed. This makes it convenient to display images in a manner that is suitable for use in visual novels and other storytelling games.
The four statements that work with images are: image - defines a new image.
show - shows an image on a layer.
scene - clears a layer, and optionally shows an image on that layer. hide - removes an image from a layer.
As abrupt changes of image can be disconcerting to the user, Ren'Py has the with statement, which allows effects to be applied when the scene is changed.
Concepts
Image
An image is something that can be show to the screen using the show statement. An image consists of a name and a displayable. When the image is shown on a layer, the displayable associated with it is displayed on that layer.
An image name consists of one or more names, separated by spaces. The first component of the image name is called the image tag. The second and later components of the name are the image attributes.
For example, take the image name mary beach night happy. The image tag is mary, while the image attributes are beach, night, and happy.
A displayable is something that can be shown on the screen. The most common thing to show is a static image, which can be specified by giving the filename of the image, as a string. In the example above, we might use "mary_beach_night_happy.png" as the filename. However, an image may refer to any displayable Ren'Py supports, not just static images. Thus, the same
statements that are used to display images can also be used for animations, solid colors, and the other types of displayables.
Layer
A layer is a list of displayables that are shown on the screen. Ren'Py supports multiple layers, including user-defined layers. The order of the layers is fixed within a game (controlled by the config.layers variable), while the order of displayables within a layer is controlled by the order in which the scene and show statements are called, and the properties given to those statements.
The following layers are defined as part of Ren'Py: master
This is the default layer that is used by the scene, show, and hide statements. It's generally used for backgrounds and character sprites.
transient
The default layer used by ui functions. This layer is cleared at the end of each interaction. screens
This layer is used by the screen system. overlay
The default layer used when a ui function is called from within an overlay function. This layer is cleared when an interaction is restarted.
Additional layers can be defined by updating config.layers, and the various other layer-related config variables. Using renpy.layer_at_list(), one or more transforms can be applied to a layer.
Image Statement
An image statement is used to define an image. An image statement consists of a single logical line beginning with the keyword image, followed by an image name, an equals sign (=), and a displayable. For example:
image eileen happy ="eileen_happy.png" image black ="#000"
image bg tiled = LiveTile("tile.jpg") image eileen happy question = VBox( "question.png",
"eileen_happy.png", )
The image statement must be run at init-time, before game code runs. When not contained inside an init block, image statements are run at init-time, as if they were placed inside an init block of priority 0.
See also the ATL variant of the image statement. Show Statement
The show statement is used to display an image on a layer. A show statement consists of a single logical line beginning with the keyword show, followed by an image name, followed by zero or more properties.
is shown. Otherwise, Ren'Py will attempt to find a unique image that: Has the same tag as the one specified in the show statement. Has all of the attributes given in the show statement.
If an image with the same tag is already showing, shares the largest number of attributes with that image.
If a unique image cannot be found, an exception occurs.
If an image with the same image tag is already showing on the layer, the new image replaces it. Otherwise, the image is placed above all other images in the layer. (That is, closest to the user.) This order may be modified by the zorder and behind properties.
The show statement does not cause an interaction to occur. For the image to actually be displayed to the user, a statement that causes an interaction (like the say, menu, pause, and with statements) must be run.
The show statement takes the following properties: as
The as property takes a name. This name is used in place of the image tag when the image is shown. This allows the same image to be on the screen twice.
at
The at property takes one or more comma-separated simple expressions. Each expression must evaluate to a transform. The transforms are applied to the image in left-to-right order.
If no at clause is given, Ren'Py will retain any existing transform that has been applied to the image. If no transform exists, the image will be displayed using the default transform. behind
Takes a comma-separated list of one or more names. Each name is taken as an image tag. The image is shown behind all images with the given tags that are currently being shown.
onlayer
Takes a name. Shows the image on the named layer. zorder
Takes an integer. The integer specifies the relative ordering of images within a layer, with larger numbers being closer to the user. This isn't generally used in Ren'Py code, but can be useful when porting code from other engines.
Assuming we have the following images defined: image mary night happy ="mary_night_happy.png" image mary night sad ="mary_night_sad.png" image moon ="moon.png"
Some example show statements are:
# Basic show
show mary night sad
# Since 'mary night happy' is showing, the following statement is # equivalent to:
# show mary night happy
show mary happy
show mary night happy at right
# Show the same image twice.
show mary night sad as mary2 at left
# Show an image behind another.
show moon behind mary, mary2
# Show an image on a user-defined layer.
show moon on user_layer
Show Expression. A variant of the show statement replaces the image name with the keyword expression, followed by a simple expression. The expression must evaluate to a displayable, and the displayable is shown on the layer. To hide the displayable, a tag must be given with the as statement.
For example:
showexpression"moon.png"as moon Scene Statement
The scene statement removes all displayables from a layer, and then shows an image on that layer. It consists of the keyword scene, followed by an image name, followed by zero or more properties. The image is shown in the same way as in the show statement, and the scene statement takes the same properties as the show statement.
The scene statement is often used to show an image on the background layer. For example: scene bg beach
Scene Expression. Like the show statement, the scene statement can take expressions instead of image names.
Clearing a layer. When the image name is omitted entirely, the scene statement clears all displayables from a layer without showing another displayable.
Hide Statement
The hide statement removes an image from a layer. It consists of the keyword hide, followed by an image name, followed by an optional property. The hide statement takes the image tag from the image name, and then hides any image on the layer with that tag.
Hide statements are rarely necessary. If a sprite represents a character, then a hide statement is only necessary when the character leaves the scene. When the character changes her emotion, it is preferable to use the show statement instead, as the show statement will automatically replace an image with the same tag.
The hide statement takes the following property: onlayer
Takes a name. Hides the image from the named layer. For example:
e "I'm out of here." hide eileen
You should never write: hide eileen
show eileen happy Instead, just write:
show eileen happy With Statement
The with statement is used to apply a transition effect when the scene is changed, making showing and hiding images less abrupt. The with statement consists of the keyword with, followed by a simple expression that evaluates either to a transition object or the special value None.
The transition effect is applied between the contents of the screen at the end of the previous interaction (with transient screens and displayables hiddden), and the current contents of the scene, after the show and hide statements have executed.
The with statement causes an interaction to occur. The duration of this interaction is controlled by the user, and the user can cause it to terminate early.
For a full list of transitions that can be used, see the chapter on transitions. An example of the with statement is:
show bg washington with dissolve
show eileen happy at left show lucy mad at right with dissolve
This causes two transitions to occur. The first with statement uses the dissolve transition to change the screen from what was previously shown to the washington background. (The dissolve transition is, by default, defined as a .5 second dissolve.)
The second transition occurs after the Eileen and Lucy images are shown. It causes a dissolve from the scene consisting solely of the background to the scene consisting of all three images - the result is that the two new images appear to dissolve in simultaneously.
With None
In the above example, there are two dissolves. But what if we wanted the background to appear instantly, followed by a dissolve of the two characters? Simply omitting the first with statement would cause all three images to dissolve in - we need a way to say that the first should be show instantly.
The with statement changes behavior when given the special value None. The with None statement causes an abbreviated interaction to occur, without changing what the user sees. When the next transition occurs, it will start from the scene as it appears at the end of this abbreviated interaction.
For example, in the code: show bg washington withNone
show eileen happy at left show lucy mad at right with dissolve
Only a single transition occurs, from the washington background to the scene consisting of all three images.
With Clause of Scene, Show, and Hide Statements
The show, scene, and hide statements can take an optional with clause, which allows a
transition to be combined with showing or hiding an image. This clause follows the statements at the end of the same logical line. It begins with the keyword with, followed by a simple expression.
The with clause is equivalent to preceding the line with a with None statement, and following it by a with statement containing the text of the with clause. For example:
show eileen happy at left with dissolve show lucy mad at right with dissolve is equivalent to:
withNone
show eileen happy at left with dissolve
withNone
show lucy mad at right with dissolve
In-Game Menus
In many visual novels, the player is asked to make choices that control the outcome of the story. The Ren'Py language contains a menus statement that makes it easy to present choices to the user.
Here's an example of a menu statement: menu:
"What should I do?" "Drink coffee.":
"I drink the coffee, and it's good to the last drop." "Drink tea.":
$ drank_tea =True
"I drink the tea, trying not to make a political statement as I do." "Genuflect.":
jump genuflect_ending label after_menu:
The menu statement begins with the keyword menu. This may be followed by a label name, in which case it's equivalent to preceding the menu with that label. For example:
menu drink_menu: ...
The menu statement is followed by an indented block. This block may contain a say statement, and must contain at least one menu choice. If the say statement is present, it is displayed on the screen at the same time as the menu.
Menu Choices. A menu choice is an option the user can select from the in-game menu. A menu choice begins with a string. The string may be followed by an if-clause, which makes the choice conditional. The menu choice ends with a colon, and must be followed by a block of Ren'Py statements.
When the choice is selected, the block of code is run. If execution reaches the end of this block of code, it continues with the statement after the end of the menu statement.
An if-clause consists of the keyword if, followed by a python expression. The menu choice is only displayed if the expression is true. In the following menu:
menu:
"Go left.": ... "Go right.": ...
"Fly above."if drank_tea: ...
The third choice will only be presented if the drank_tea variable is true.
Text, Displayables, Transforms, and Transitions
Text
Ren'Py contains several ways of displaying text. The say and menu are primarily concerned with the display of text to the user. The user interface often contains text, displayed using the text, textbutton, and label screen language statements. These functions, along with others, create Text() displayables, and show them on the screen.
The Text displayable is responsible for managing the process of showing the text to the user. The text displayable performs actions in the following order:
1. Translating text.
2. Interpolating data into the text.
3. Styling the text using styles and text tags. 4. Laying out the styled text.
5. Drawing the text to the screen.
This chapter discusses the process of text display in Ren'Py. Escape Characters
There are three special characters that can control the way Ren'Py displays text. A creator needs to be aware of these characters to ensure that their writing is not accidentally
misinterpreted by the engine. (backslash)
The backslash character is used to introduce when writing a Ren'Py or Python string. Some common escape codes are:
\" (backslash-doublequote)
Includes a doublequote in a double-quoted string. \' (backslash-quote)
Includes a single quote in a single-quoted string. \ (backslash-space)
Includes an additional space in a Ren'Py string. By default, Ren'Py script text collapses adjacent whitespace into a single space character.
\n (backslash-n)
Includes a newline character in the text. \\ (backslash-backslash)
Includes a backslash character in the text. [ (left bracket)
The left bracket is used to introduce interpolation of a value into the text. To include a single left bracket in your text, double it - write [[.
{ (left brace)
The left brace is used to introduce a text tag. To include a left brace in your text, double it - write {{.
Interpolating Data
Ren'Py supports interpolating data into the text string before it is displayed. For example, if the player's name is stored in the playername variable, one could write a line of dialogue like:
g "Welcome to the Nekomimi Institute, [playername]!"
Ren'Py will interpolate variables found in the global store. When using a text widget in a screen, Ren'Py will also interpolate screen local variables. (This can be overridden by supplying an explicit scope argument to the Text displayable.)
Ren'Py isn't limited to interpolating simple variables. It can also interpolate fields and components of tuples. So it's possible to have code like:
g "My first name is [player.names[0]]."
It's possible to apply formatting codes when displaying numbers. This code will display a floating point number to two decimal places:
$ percent =100.0* points / max_points g "I like you [percent:.2] percent!"
Ren'Py's string interpolation is taken from the PEP 3101 string formatting syntax. Ren'Py uses [ to introduce string formatting because { was taken by text tags.
Along with the !s and !r conversion flags supported by Python, Ren'Py supports a !q conversion flag. The !q conversion flag ensures that text tags are properly quoted, so that displaying a string will not introduce unwanted formatting constructs. For example:
g "Don't pull a fast one on me, [playername!q]." Styling and Text Tags
In Ren'Py, text gains style information in two ways. The first is from the style that is applied to the entire block of text. Please see the section about the style system for more details,
especially the section on text style properties.
The second way is through text tags. Text tags are suitable for styling a portion of text block, or a small fraction of the text blocks in the program. If you find yourself applying the same text tags to every line of text, consider using a style instead.
There are two text tags. Some text tags are self-closing, while others require a closing tag. When multiple closing tags are used, they should be closed last open, first closed order -Ren'Py will reject incorrect nesting. For example:
# This line is correct.
"Plain {b}Bold {i}Bold-Italic{/i} Bold{/b} Plain"
# This line is incorrect, and will cause an error or incorrect # behavior.
"Plain {b}Bold {i}Bold-Italic{/b} Italic{/i} Plain"
Some text tags take an argument. In that case, the tag name is followed by an equals sign (=), and the argument. The argument may not contain the right-brace (}) character. The meaning of the argument varies based on the text tag.
General Text Tags
Tags that apply to all text are:
a
The anchor tag creates a hyperlink between itself and its closing tag. While the behavior of the hyperlink is controlled by the hyperlink_functions style property, the default handler has the following behavior.
Hyperlinks are rendered using the style.hyperlink_text style.
If the argument begins with the text "http://", clicking on it opens the url in a web browser. Otherwise, the argument is interpreted as a label, which is called in a new context. This allows hyperlinks to be used to define terms.
Apart from the change in style, there is no specific behavior when a hyperlink is hovered.
label test:
e "Why don't you visit {a=http://renpy.org}Ren'Py's home page{/a}?" e "The {a=define_trebuchet}trebuchet{/a} is at the gates."
return
label define_trebuchet:
e "A trebuchet is a kind of siege engine." e "It uses a lever to fling things at targets." e "Like us!"
b
The bold tag renders the text between itself and its closing tag in a bold font. "An example of {b}bold test{/b}."
color
The color text tag renders the text between itself and its closing tag in the specified color. The color should be in #rgb, #rgba, #rrggbb, or #rrggbbaa format.
"{color=#f00}Red{/color}, {color=#00ff00}Green{color}, {color=#0000ffff}Blue{/color}"
cps
The characters per second tag sets the speed of text display, for text between the tag and its closing tag. If the argument begins with an asterisk, it's taken as a multiplier to the current text speed. Otherwise, the argument gives the speed to show the text at, in characters per second.
"{cps=20}Fixed Speed{/cps} {cps=*2}Double Speed{/cps}
font
The font tag renders the text between itself and its closing tag in the specified font. The argument is the filename of the font to use.
"Try out the {font=mikachan.ttf}mikachan font{/font}."
i
The italics tag renders the text between itself and its closing tag in italics. "Visit the {i}leaning tower of Pisa{/i}."
k
The kerning tag is a tag that adjust the kerning of characters between itself and its closing tag. It takes as an argument a floating point number giving the number of pixels of kerning to add to each kerning pair. (The number may be negative to decrease kerning.)
"{k=-.5}Negative{/k} Normal {k=.5}Positive{/k}"
image
The image tag is a self-closing tag that inserts an image into the text. The image should be the height of a single line of text. The argument should be either the image filename, or the name of an image defined with the image statement.
g "Good to see you! {image=heart.png}"
s
The strikethrough tag draws a line through text between itself and its closing tag. g "It's good {s}to see you{/s}."
rb
The ruby bottom tag marks text between itself and its closing tag as ruby bottom text. See the section on Ruby Text for more information.
rt
The ruby top tag marks text between itself and its closing tag as ruby top text. See the section on Ruby Text for more information.
size
The size tag changes the size of text between itself and its closing tag. The argument should be an integer, optionally preceded by + or -. If the argument is just an integer, the size is set to that many pixels high. Otherwise, the size is increased or decreased by that amount.
"{size=+10}Bigger{/size} {size=-10}Smaller{/size} {size=24}24 px{/size}."
space
The space tag is a self-closing tag that inserts horizontal space into a line of text. As an argument, it takes an integer giving the number of pixels of space to add.
"Before the space.{space=30}After the space."
u
The underline tag underlines the text between itself and its closing tag. g "It's good to {u}see{/u} you."
vspace
The vspace tag is a self-closing tag that inserts vertical space between lines of text. As an argument, it takes an integer giving the number of pixels of space to add.
"Line 1{vspace=30}Line 2" Dialogue Text Tags
Text tags that only apply to dialogue are:
fast
If the fast tag is displayed in a line of text, then all text before it is displayed instantly, even in slow text mode. The fast tag is a self-closing tag.
g "Looks like they're{nw}" show trebuchet
g "Looks like they're{fast} playing with their trebuchet again."
nw
The no-wait tag is a self-closing tag that causes the current line of dialogue to automatically dismiss itself once the end of line has been displayed.
g "Looks like they're{nw}" show trebuchet
p
The paragraph pause tag is a self-closing tag that terminates the current paragraph, and waits for the user to click to continue. If it is given an argument, the argument is
interpreted as a number, and the wait automatically ends after that many seconds have passed.
"Line 1{p}Line 2{p=1.0}Line 3"
w
The wait tag is a self-closing tag that waits for the user to click to continue. If it is given an argument, the argument is interpreted as a number, and the wait automatically ends after that many seconds have passed.
"Line 1{w} Line 1{w=1.0} Line 1" User-Defined Text Tags
Ren'Py also supports user-defined text tags. A user-defined text tag is a text tag where the tag name is empty. In this case, the argument is taken to be the name of a style. The text between this tag and the closing tag has the following properties set to those defined in the style:
antialias font size bold italic underline strikethrough color black_color kerning Non-English Languages
The default font for Ren'Py contains characters for English and many other languages. For size reasons, it doesn't contain the characters required to render other languages, including
Chinese, Japanese, and Korean. In order to support these language, a project must first change the default font, using code like:
initpython:
style.default.font="mikachan.ttf"
Ren'Py should then support most world languages without further configuration. However, Korean can be written with or without spacing between words. Ren'Py has a special mode to support Korean with spaces, which can be enabled with the code:
initpython:
style.default.language="korean-with-spaces"
Finally, ideographic languages provide a large number of opportunities for line breaking. To enable a faster line-breaking algorithm, use the code:
initpython:
The faster line-breaking algorithm is not be necessary unless the game is displaying huge amounts of text, such as in NVL-mode.
Ruby Text
Ruby text (also known as furigana or interlinear annotations) is a way of placing small text above a character or word. There are several steps required for your game to support Ruby text.
First, you must set up styles for the ruby text. The following style changes are required: 1. The line_leading property must be used to leave enough vertical space for the ruby
text.
2. A new named style must be created. The properties of this style, such as size should be set in a fashion appropriate for ruby text.
3. The yoffset of the new style should be set, in order to move the ruby text above the baseline.
4. The ruby_style field of the text's style should be set to the newly-created style. For example:
initpython:
style.default.line_leading=12
style.ruby_style= Style(style.default) style.ruby_style.size=12
style.ruby_style.yoffset=-20
style.default.ruby_style=style.ruby_style
Once Ren'Py has been configured, ruby text can be included using the rt and rb text tags. The rt tag is used to mark one or more characters to be displayed as ruby text. If the ruby text is preceded by text enclosed in the rb tag, the ruby text is centered over that text. Otherwise, it is centered over the preceding character.
For example:
e "Ruby can be used for furigana (東{rt}とう{/rt} 京{rt}きょう{/rt})." e "It's also used for translations ({rb}東京{/rb}{rt}Tokyo{/rt})."
It's the creator's responsibility to ensure that ruby text does not leave the boundaries of the text. It may be necessary to add leading or spaces to the left and right of the text to prevent these errors from occurring.
Fonts
Ren'Py supports Truetype and Image-Based fonts.
A Truetype font is specified by giving the name of the font file. The file must be present in the game directory, or one of the archive files.
Ren'Py also supports Truetype collections that define more than one font. When accessing a collection, use the 0-based font index, followed by an at-sign and the file name. For example, "[email protected]" is the first font in a collection, "[email protected]" the second, and so on.
The config.font_replacement_map variable is used to map fonts. The combination of font filename, boldness, and italics is mapped to a similar combination. This allows a font with proper italics to be used instead of the automatically-generated italics.
Once such mapping would be to replace the italic version of the Deja Vu Sans font with the official oblique version. (You'll need to download the oblique font from the web.)
initpython:
config.font_replacement_map["DejaVuSans.ttf", False, True] = ("DejaVuSans-Oblique.ttf" This mapping can improve the look of italic text.
Image-Based Fonts
Image based fonts can be registered by calling one of the following registration functions. Registering an image-based font requires the specification of a name, size, boldness, italicness, and underline. When all of these properties match the registered font, the registered font is used.
renpy.
register_bmfont
(
name=None, size=None, bold=False, italics=False, underline=False, filename=None)
This registers a BMFont with the given details. Please note that size, bold, italic, and underline are all advisory (used for matching), and do not change the appearance of the font.
Please see the BMFont home page for the tool that creates BMFonts. Ren'Py expects that the filename parameter will be to a file in the BMFont text format, that describes a 32-bit font. The Alpha channel should contain the font information, while the Red, Green, and Blue channels should be set to one. The image files, kerning, and other control
information is read out of the BMFont file.
We recommend including Latin and General Punctuation as part of your BMFont, to ensure all of the Ren'Py interface can render.
name
The name of the font being registered, a string. size
The size of the font being registered, an integer. bold
The boldness of the font being registered, a boolean. italics
The italicness of the font being registered, a boolean. underline
An ignored parameter. filename
The file containing BMFont control information.
renpy.
register_mudgefont
(
name=None, size=None, bold=False, italics=False, underline=False, filename=None, xml=None, spacewidth=10, default_kern=0, kerns={})
This registers a MudgeFont with the given details. Please note that size, bold, italic, and underline are all advisory (used for matching), and do not change the appearance of the
