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 rightclicking 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 r e n p yor r e n p y . e x eprogram. On Mac OS X, run the r e n p yapplication. On Linux, run the r e n p y . s hscript. 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
l a b e ls t a r t : " I ' l la s kh e r . . . " " M e "" U m . . .w i l ly o u . . . " " M e "" W i l ly o ub em ya r t i s tf o rav i s u a ln o v e l ? " " S i l e n c e . " " S h ei ss h o c k e d ,a n dt h e n . . . " " S y l v i e "" S u r e ,b u tw h a ti sa\ " v i s u a ln o v e l ? \ " "

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 s t a r t . 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.
d e f i n es=C h a r a c t e r ( ' S y l v i e ' ,c o l o r = " # c 8 f f c 8 " ) d e f i n em=C h a r a c t e r ( ' M e ' ,c o l o r = " # c 8 c 8 f f " ) l a b e ls t a r t : " I ' l la s kh e r . . . " m" U m . . .w i l ly o u . . . " m" W i l ly o ub em ya r t i s tf o rav i s u a ln o v e l ? " " S i l e n c e . " " S h ei ss h o c k e d ,a n dt h e n . . . " s" S u r e ,b u tw h a ti sa\ " v i s u a ln o v e l ? \ " "

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.
i m a g eb gm e a d o w=" m e a d o w . j p g " i m a g eb gu n i=" u n i . j p g " i m a g es y l v i es m i l e=" s y l v i e _ s m i l e . p n g " i m a g es y l v i es u r p r i s e d=" s y l v i e _ s u r p r i s e d . p n g " d e f i n es=C h a r a c t e r ( ' S y l v i e ' ,c o l o r = " # c 8 f f c 8 " ) d e f i n em=C h a r a c t e r ( ' M e ' ,c o l o r = " # c 8 c 8 f f " ) l a b e ls t a r t : s c e n eb gm e a d o w s h o ws y l v i es m i l e " I ' l la s kh e r . . . " m" U m . . .w i l ly o u . . . " m" W i l ly o ub em ya r t i s tf o rav i s u a ln o v e l ? " s h o ws y l v i es u r p r i s e d " S i l e n c e . " " S h ei ss h o c k e d ,a n dt h e n . . . " s h o ws y l v i es m i l e

s" S u r e ,b u tw h a ti sa\ " v i s u a ln o v e l ? \ " "

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 "P r o j e c t N a m e /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.
l a b e ll e a v i n g : s" I ' l lg e tr i g h to ni t ! " h i d es y l v i e " . . . " m" T h a tw a s n ' tw h a tIm e a n t ! "

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.
l a b e ls t a r t : s c e n eb gu n i s h o ws y l v i es m i l e s" O h ,h i ,d ow ew a l kh o m et o g e t h e r ? " m" Y e s . . . "

" Is a i da n dm yv o i c ew a sa l r e a d ys h a k i n g . " s c e n eb gm e a d o w w i t hf a d e " W er e a c h e dt h em e a d o w sj u s to u t s i d eo u rh o m e t o w n . " " A u t u m nw a ss ob e a u t i f u lh e r e . " " W h e nw ew e r ec h i l d r e n ,w eo f t e np l a y e dh e r e . " m" H e y . . .u m m m . . . " s h o ws y l v i es m i l e w i t hd i s s o l v e " S h et u r n e dt om ea n ds m i l e d . " " I ' l la s kh e r . . . " m" U m m m . . .w i l ly o u . . . " m" W i l ly o ub em ya r t i s tf o rav i s u a ln o v e l ? "

The with statement takes the name of a transition to use. The most common one is d i s s o l v e which dissolves from one screen to the next. Another useful transition is f a d ewhich 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:
s c e n eb gm e a d o w s h o ws y l v i es m i l e w i t hd i s s o l v e

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:
s c e n eb gm e a d o w w i t hd i s s o l v e s h o ws y l v i es m i l e w i t hd i s s o l v e

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:
s c e n eb gm e a d o w w i t hN o n e s h o ws y l v i es m i l e w i t hd i s s o l v e

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.
s h o ws y l v i es m i l ea tr i g h t

To do this repositioning, add an at-clause to a show statement. The at clause takes a position,

and shows the image at that position. Ren'Py includes several pre-defined positions: l e f tfor the right side of the screen, r i g h tfor the right side, c e n t e rfor centered horizontally (the default), and t r u e c e n t e rfor 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.
p l a ym u s i c" i l l u r o c k . o g g "

When changing music, one can supply a fadeout clause, which is used to fade out the old music when new music is played.
p l a ym u s i c" i l l u r o c k . o g g "f a d e o u t1 . 0

Music can be stopped with the stop music statement, which can also optionally take a fadeout clause.
s t o pm u s i c

Sound effects can be played with the play sound statement:

p l a ys o u n d" e f f e c t . o g g "

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.
" . : .G o o dE n d i n g . " r e t u r n

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" S u r e ,b u tw h a t ' sa\ " v i s u a ln o v e l ? \ " " m e n u : " I t ' sas t o r yw i t hp i c t u r e s . " : j u m pv n " I t ' sah e n t a ig a m e . " : j u m ph e n t a i

l a b e lv n : m" I t ' sas t o r yw i t hp i c t u r e sa n dm u s i c . " j u m pm a r r y l a b e lh e n t a i : m" W h yi t ' sag a m ew i t hl o t so fs e x . " j u m pm a r r y l a b e lm a r r y : s c e n eb l a c k w i t hd i s s o l v e " -y e a r sl a t e r"

This example shows how menus are used with Ren'Py. The menu statement introduces an ingame-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:
l a b e ls t a r t : $b l _ g a m e=F a l s e

You can then change the flag in code that is chosen by menus:
l a b e lh e n t a i : $b l _ g a m e=T r u e m" W h yi t ' sag a m ew i t hl o t so fs e x . " s" Y o um e a n ,l i k eab o y ' sl o v eg a m e ? " s" I ' v ea l w a y sw a n t e dt om a k eo n eo ft h o s e . " s" I ' l lg e tr i g h to ni t ! " j u m pm a r r y

j u m pm a r r y

And check it later:

" A n ds o ,w eb e c a m eav i s u a ln o v e lc r e a t i n gt e a m . " " W em a d eg a m e sa n dh a dal o to ff u nm a k i n gt h e m . " i fb l _ g a m e : " W e l l ,a p a r tf r o mt h a tb o y ' sl o v eg a m es h ei n s i s t e do nm a k i n g . " " A n do n ed a y . . . "

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 . r p yfiles into .rpyc files when it starts up. When a . r p yfile is changed, the . r p y cfile will be updated when Ren'Py starts up. However, if a .rpyc file exists without a corresponding . r p yfile, the . r p y cfile will be used. This can lead to problems if a . r p yfile 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.
#T h i si sac o m m e n t . s h o wb l a c k#t h i si sa l s oac o m m e n t . " #T h i si s n ' tac o m m e n t ,s i n c ei t ' sp a r to fas t r i n g . "

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.
" T h i si so n el o g i c a ll i n e " " S i n c et h i sl i n ec o n t a i n sas t r i n g ,i tc o n t i n u e s e v e nw h e nt h el i n ee n d s . " $a=[" B e c a u s eo fp a r e n t h e s i s ,t h i sl i n ea l s o " , " s p a n sm o r et h a no n el i n e . "]

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.
" T h i ss t a t e m e n t ,a n dt h ei fs t a t e m e n tt h a tf o l l o w s ,i sp a r to fab l o c k . " i fT r u e : " B u tt h i ss t a t e m e n ti sp a r to fan e wb l o c k . " " T h i si sa l s op a r to ft h a tn e wb l o c k . "

" T h i si sp a r to ft h ef i r s tb l o c k ,a g a i n . "

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 m a r yb e a c hn i g h th a p p y . The image tag is m a r y , while the image attributes are m a r y ,b e a c h , and n i g h t . 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.
' S t r i n g sc a n \ ' tc o n t a i nt h e i rd e l i m i t e r ,u n l e s sy o ue s c a p ei t . '

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 ) ,f o o . b a r , and f o o ( 4 2 )are all simple expressions. But 3 + 4is not, as the expression ends at the end of a string. At List An at list is a list of simple expressions, separated by commas.

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. 3and 4 2are 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. T r u eis a true value, F a l s eis a false value. N o n erepresents 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 4tuple (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 ," # 5 5 5 " ) ( 3 2 ,2 4 ,2 0 0 ,1 0 0 )

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:
n a m e l o v e _ l o v e _ p o i n t s t r e b u c h e t 2 _ r a n g e

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:
c o n f i g . s c r e e n _ w i d t h

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:
C h a r a c t e r ( " E i l e e n " ,t y p e = a d v ,c o l o r = " # 0 f 0 " )

we call the Character function. It's given one positional argument, the string "Eileen". It's given two keyword argument: t y p ewith the value of the a d vvariable, and c o l o rwith 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:

S a m p l e (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. Has one keyword argument, position, which has a default value of (0, 0).

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:
" T h i si sn a r r a t i o n . " " E i l e e n "" T h i si sd i a l o g u e ,w i t ha ne x p l i c i tc h a r a c t e rn a m e . " e" T h i si sd i a l o g u e ,u s i n gac h a r a c t e ro b j e c ti n s t e a d . "

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:
" Iw a l k e dp a s tas i g ns a y i n g ,\ " L e t ' sg i v ei t1 0 0 % ! \ " "

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:
d e f i n ee=C h a r a c t e r ( " E i l e e n " , w h o _ c o l o r = " # c 8 f f c 8 " )

Once this is done, the character can be used in a say statement:

e" H e l l o ,w o r l d . "

Character is a python function, that takes a large number of keyword arguments. These keyword arguments control the behavior of the character.

C h a r a c t e r (name, kind=adv, **args)

Creates and returns a Character object, which controls the look and feel of dialogue and narration.
n a m e

If a string, the name of the character for dialogue. When n a m eis N o n e , display of the name is omitted, as for narration.
k i n d

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 k i n d . 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.
i m a g e

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.
w h a t _ p r e f i x

A string that is prepended to the dialogue being spoken before it is shown.

w h a t _ s u f f i x

A string that is appended to the dialogue being spoken before it is shown.

w h o _ p r e f i x

A string that is prepended to the name of the character before it is shown.

w h o _ s u f f i x

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.
d y n a m i c

If true, then n a m eshould 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 character.

Controlling Interactions. These options control if the dialogue is displayed, if an interaction occurs, and the mode that is entered upon display.
c o n d i t i o n

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.
i n t e r a c t

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.
m o d e

A string giving the mode to enter when this character speaks. See the section on modes for more details.
c a l l b a c k

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.
c t c

A Displayable to use as the click-to-continue indicator, unless a more specific indicator is used.
c t c _ p a u s e

A Displayable to use a the click-to-continue indicator when the display of text is paused by the {p} or {w} text tags.
c t c _ t i m e d p a u s e

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 N u l l ( )when you want a ctc_pause but no ctc_timedpause.
c t c _ p o s i t i o n

Controls the location of the click-to-continue indicator. If " n e s t l e d " , the indicator is displayed as part of the text being shown, immediately after the last character. If " f i x e d " , 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.
s c r e e n

The name of the screen that is used to display the dialogue. Keyword arguments beginning with s h o w _have the prefix stripped off, and are passed to the screen as arguments. For example, the value of s h o w _ s i d e _ i m a g ewill become the value of the s i d e _ i m a g evariable in the screen. Some useful s h o w _variables implemented by the default screens are:
s h o w _ s i d e _ i m a g e

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.
s h o w _ t w o _ w i n d o w

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 w h o _ ,w h a t _ , and w i n d o w _ `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 w h o _ c o l o r = " # c 8 f f c 8 " , the color of the character's name is changed, in this case to green. w i n d o w _ b a c k g r o u n d = " f r a m e . p n g " 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 w h o _ s t y l e ,w h a t _ s t y l e , and w i n d o w _ s t y l earguments, 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:
d e f i n ee=C h a r a c t e r ( " E i l e e n " ,i m a g e = " e i l e e n " ) l a b e ls t a r t : s h o we i l e e nm a d e" I ' mal i t t l eu p s e ta ty o u . " eh a p p y" B u ti t ' sj u s tap a s s i n gt h i n g . "

is equivalent to:
d e f i n ee=C h a r a c t e r ( " E i l e e n " ) l a b e ls t a r t : s h o we i l e e nm a d e" I ' mal i t t l eu p s e ta ty o u . " s h o we i l e e nh a p p y e" B u ti t ' sj u s tap a s s i n gt h i n g . "

To cause a transition to occur whenever the images are changed in this way, set c o n f i g . s a y _ a t t r i b u t e _ t r a n s i t i o nto a transition. Example Characters Here are a few example characters:
#Ac h a r a c t e rt h a th a si t sd i a l o g u ee n c l o s e di np a r e n t h e s i s . d e f i n ee=C h a r a c t e r ( " E i l e e n " ,w h a t _ p r e f i x = ' " ' ,w h a t _ s u f f i x = ' " ' ) #Ac h a r a c t e rt h a tp u l l si t sn a m ef r o mav a r i a b l e . d e f i n ep=C h a r a c t e r ( " p l a y e r _ n a m e " ,d y n a m i c = T r u e )

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.
a d v

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.
n v l

A kind of Character that causes dialogue to be displayed in NVL-mode, with multiple lines of text on the screen at once.
n a r r a t o r

The character that's used to display narration, by say statements without a character name.
n a m e _ o n l y

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:
i m a g e- defines a new image. s h o w- shows an image on a layer. s c e n e- clears a layer, and optionally shows an image on that layer. h i d e- removes an image from a layer.

As abrupt changes of image can be disconcerting to the user, Ren'Py has the w i t hstatement, 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 m a r yb e a c hn i g h th a p p y . The image tag is m a r y , while the image attributes are b e a c h ,n i g h t , and h a p p y . 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 " m a r y _ b e a c h _ n i g h t _ h a p p y . p n g "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 c o n f i g . l a y e r svariable), 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 c o n f i g . l a y e r s , and the various other layerrelated config variables. Using r e n p y . l a y e r _ a t _ l i s t ( ) , 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 i m a g e , followed by an image name, an equals sign (= ), and a displayable. For example:
i m a g ee i l e e nh a p p y=" e i l e e n _ h a p p y . p n g " i m a g eb l a c k=" # 0 0 0 " i m a g eb gt i l e d=L i v e T i l e ( " t i l e . j p g " ) i m a g ee i l e e nh a p p yq u e s t i o n=V B o x ( " q u e s t i o n . p n g " , " e i l e e n _ h a p p y . p n g " , )

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 s h o w , followed by an image name, followed by zero or more properties. If the show statement is given the exact name of an existing image, that image is the one that

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:
a s

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.
a t

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 d e f a u l ttransform.
b e h i n d

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.
o n l a y e r

Takes a name. Shows the image on the named layer.

z o r d e r

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:
i m a g em a r yn i g h th a p p y=" m a r y _ n i g h t _ h a p p y . p n g " i m a g em a r yn i g h ts a d=" m a r y _ n i g h t _ s a d . p n g " i m a g em o o n=" m o o n . p n g "

Some example show statements are:

#B a s i cs h o w s h o wm a r yn i g h ts a d #S i n c e' m a r yn i g h th a p p y 'i ss h o w i n g ,t h ef o l l o w i n gs t a t e m e n ti s #e q u i v a l e n tt o : #s h o wm a r yn i g h th a p p y s h o wm a r yh a p p y #S h o wa ni m a g eo nt h er i g h ts i d eo ft h es c r e e n .

s h o wm a r yn i g h th a p p ya tr i g h t #S h o wt h es a m ei m a g et w i c e . s h o wm a r yn i g h ts a da sm a r y 2a tl e f t #S h o wa ni m a g eb e h i n da n o t h e r . s h o wm o o nb e h i n dm a r y ,m a r y 2 #S h o wa ni m a g eo nau s e r d e f i n e dl a y e r . s h o wm o o no nu s e r _ l a y e r

Show Expression. A variant of the show statement replaces the image name with the keyword e x p r e s s i o n , 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:
s h o we x p r e s s i o n" m o o n . p n g "a sm o o n

Scene Statement The scene statement removes all displayables from a layer, and then shows an image on that layer. It consists of the keyword s c e n e , 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:
s c e n eb gb e a c h

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 h i d e , 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:
o n l a y e r

Takes a name. Hides the image from the named layer. For example:
e" I ' mo u to fh e r e . " h i d ee i l e e n

You should never write:

h i d ee i l e e n s h o we i l e e nh a p p y

Instead, just write:

s h o we i l e e nh a p p y

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 w i t h , followed by a simple expression that evaluates either to a transition object or the special value N o n e . 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:
s h o wb gw a s h i n g t o n w i t hd i s s o l v e s h o we i l e e nh a p p ya tl e f t s h o wl u c ym a da tr i g h t w i t hd i s s o l v e

This causes two transitions to occur. The first with statement uses the d i s s o l v etransition to change the screen from what was previously shown to the washington background. (The d i s s o l v etransition 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 N o n e . The w i t hN o n e 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:
s h o wb gw a s h i n g t o n w i t hN o n e

s h o we i l e e nh a p p ya tl e f t s h o wl u c ym a da tr i g h t w i t hd i s s o l v e

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 w i t h , followed by a simple expression. The with clause is equivalent to preceding the line with a w i t hN o n estatement, and following it by a with statement containing the text of the with clause. For example:
s h o we i l e e nh a p p ya tl e f tw i t hd i s s o l v e s h o wl u c ym a da tr i g h tw i t hd i s s o l v e

is equivalent to:
w i t hN o n e s h o we i l e e nh a p p ya tl e f t w i t hd i s s o l v e w i t hN o n e s h o wl u c ym a da tr i g h t w i t hd i s s o l v e

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:
m e n u : " W h a ts h o u l dId o ? " " D r i n kc o f f e e . " : " Id r i n kt h ec o f f e e ,a n di t ' sg o o dt ot h el a s td r o p . " " D r i n kt e a . " : $d r a n k _ t e a=T r u e " Id r i n kt h et e a ,t r y i n gn o tt om a k eap o l i t i c a ls t a t e m e n ta sId o . " " G e n u f l e c t . " : j u m pg e n u f l e c t _ e n d i n g l a b e la f t e r _ m e n u : " A f t e rh a v i n gm yd r i n k ,Ig o to nw i t hm ym o r n i n g . "

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:
m e n ud r i n k _ m e n u : . . .

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 i f , followed by a python expression. The menu choice is only displayed if the expression is true. In the following menu:
m e n u : " G ol e f t . " : . . . " G or i g h t . " : . . . " F l ya b o v e . "i fd r a n k _ t e a : . . .

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 T e x t ( )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. 2. 3. 4. 5. Translating text. Interpolating data into the text. Styling the text using styles and text tags. Laying out the styled text. 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 p l a y e r n a m evariable, one could write a line of dialogue like:
g" W e l c o m et ot h eN e k o m i m iI n s t i t u t e ,[ p l a y e r n a m e ] ! "

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" M yf i r s tn a m ei s[ p l a y e r . n a m e s [ 0 ] ] . "

It's possible to apply formatting codes when displaying numbers. This code will display a floating point number to two decimal places:
$p e r c e n t=1 0 0 . 0*p o i n t s/m a x _ p o i n t s g" Il i k ey o u[ p e r c e n t : . 2 ]p e r c e n t ! "

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" D o n ' tp u l laf a s to n eo nm e ,[ p l a y e r n a m e ! 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:
#T h i sl i n ei sc o r r e c t . " P l a i n{ b } B o l d{ i } B o l d I t a l i c { / i }B o l d { / b }P l a i n " #T h i sl i n ei si n c o r r e c t ,a n dw i l lc a u s ea ne r r o ro ri n c o r r e c t #b e h a v i o r . " P l a i n{ b } B o l d{ i } B o l d I t a l i c { / b }I t a l i c { / i }P l a i n "

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 h y p e r l i n k _ f u n c t i o n sstyle property, the default handler has the following behavior. Hyperlinks are rendered using the s t y l e . h y p e r l i n k _ t e x tstyle. If the argument begins with the text " h t t p : / / " , 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.
l a b e lt e s t : e" W h yd o n ' ty o uv i s i t{ a = h t t p : / / r e n p y . o r g } R e n ' P y ' sh o m ep a g e { / a } ? " e" T h e{ a = d e f i n e _ t r e b u c h e t } t r e b u c h e t { / a }i sa tt h eg a t e s . " r e t u r n l a b e ld e f i n e _ t r e b u c h e t : e" At r e b u c h e ti sak i n do fs i e g ee n g i n e . " e" I tu s e sal e v e rt of l i n gt h i n g sa tt a r g e t s . " e" L i k eu s ! " r e t u r n

b
The bold tag renders the text between itself and its closing tag in a bold font.
" A ne x a m p l eo f{ b } b o l dt e s t { / b } . "

c o l o r
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.
" { c o l o r = # f 0 0 } R e d { / c o l o r } ,{ c o l o r = # 0 0 f f 0 0 } G r e e n { c o l o r } ,{ c o l o r = # 0 0 0 0 f f f f } B l u e { / c o l o r } "

c p s
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.
" { c p s = 2 0 } F i x e dS p e e d { / c p s }{ c p s = * 2 } D o u b l eS p e e d { / c p s }

f o n t
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.
" T r yo u tt h e{ f o n t = m i k a c h a n . t t f } m i k a c h a nf o n t { / f o n t } . "

i
The italics tag renders the text between itself and its closing tag in italics.
" V i s i tt h e{ i } l e a n i n gt o w e ro fP i s a { / 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 } N e g a t i v e { / k }N o r m a l{ k = . 5 } P o s i t i v e { / k } "

i m a g e
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" G o o dt os e ey o u !{ i m a g e = h e a r t . p n g } "

s
The strikethrough tag draws a line through text between itself and its closing tag.
g" I t ' sg o o d{ s } t os e ey o u { / s } . "

r b
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.

r t
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.

s i z e
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.
" { s i z e = + 1 0 } B i g g e r { / s i z e }{ s i z e = 1 0 } S m a l l e r { / s i z e }{ s i z e = 2 4 } 2 4p x { / s i z e } . "

s p a c e
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.
" B e f o r et h es p a c e . { s p a c e = 3 0 } A f t e rt h es p a c e . "

u
The underline tag underlines the text between itself and its closing tag.
g" I t ' sg o o dt o{ u } s e e { / u }y o u . "

v s p a c e
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.
" L i n e1 { v s p a c e = 3 0 } L i n e2 "
Dialogue Text Tags

Text tags that only apply to dialogue are:

f a s t
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" L o o k sl i k et h e y ' r e { n w } " s h o wt r e b u c h e t g" L o o k sl i k et h e y ' r e { f a s t }p l a y i n gw i t ht h e i rt r e b u c h e ta g a i n . "

n w
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" L o o k sl i k et h e y ' r e { n w } " s h o wt r e b u c h e t g" L o o k sl i k et h e y ' r e { f a s t }p l a y i n gw i t ht h e i rt r e b u c h e ta g a i n . "

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.
" L i n e1 { p } L i n e2 { p = 1 . 0 } L i n e3 "

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.
" L i n e1 { w }L i n e1 { w = 1 . 0 }L i n e1 "
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:
i n i tp y t h o n : s t y l e . d e f a u l t . f o n t=" m i k a c h a n . t t f "

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:
i n i tp y t h o n : s t y l e . d e f a u l t . l a n g u a g e=" k o r e a n w i t h s p a c e s "

Finally, ideographic languages provide a large number of opportunities for line breaking. To enable a faster line-breaking algorithm, use the code:
i n i tp y t h o n : s t y l e . d e f a u l t . l a y o u t=" g r e e d y "

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 l i n e _ l e a d i n gproperty 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 s i z eshould 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 r u b y _ s t y l efield of the text's style should be set to the newly-created style. For example:
i n i tp y t h o n : s t y l e . d e f a u l t . l i n e _ l e a d i n g=1 2 s t y l e . r u b y _ s t y l e=S t y l e ( s t y l e . d e f a u l t ) s t y l e . r u b y _ s t y l e . s i z e=1 2 s t y l e . r u b y _ s t y l e . y o f f s e t=2 0 s t y l e . d e f a u l t . r u b y _ s t y l e=s t y l e . r u b y _ s t y l e

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" R u b yc a nb eu s e df o rf u r i g a n a( { r t } { / r t } { r t } { / r t } ) . " e" I t ' sa l s ou s e df o rt r a n s l a t i o n s( { r b } { / r b } { r t } T o k y o { / r t } ) . "

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, "0@font.ttc" is the first font in a collection, "1@font.ttc" the second, and so on.
Font Replacement

The c o n f i g . f o n t _ r e p l a c e m e n t _ m a pvariable 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.)
i n i tp y t h o n : c o n f i g . f o n t _ r e p l a c e m e n t _ m a p [ " D e j a V u S a n s . t t f " ,F a l s e ,T r u e ]=( " D e j a V u S a n s O b l i q u e . t t f "

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.
r e n p y . r e g i s t e r _ b m f o n t (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.
n a m e

The name of the font being registered, a string.

s i z e

The size of the font being registered, an integer.

b o l d

The boldness of the font being registered, a boolean.

i t a l i c s

The italicness of the font being registered, a boolean.

u n d e r l i n e

An ignored parameter.
f i l e n a m e

The file containing BMFont control information.

r e n p y . r e g i s t e r _ m u d g e f o n t (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

font. Please see the MudgeFont home page for the tool that creates MudgeFonts. Ren'Py assumes that character codes found in the MudgeFont xml file are unicode character numbers, and ignores negative character codes.
n a m e

The name of the font being registered, a string.

s i z e

The size of the font being registered, an integer.

b o l d

The boldness of the font being registered, a boolean.

i t a l i c s

The italicness of the font being registered, a boolean.

u n d e r l i n e

An ignored parameter.
f i l e n a m e

The file containing the MudgeFont image, a string. The image is usually a TGA file, but could be a PNG or other format that Ren'PY supports.
x m l

The xml file containing information generated by the MudgeFont tool.

s p a c e w i d t h

The width of a space character, an integer in pixels.

d e f a u l t _ k e r n

The default kern spacing between characters, in pixels.

k e r n s

A map from two-character strings to the kern that should be used between those characters.
r e n p y . r e g i s t e r _ s f o n t (name=None, size=None, bold=False, italics=False,

underline=False, filename=None, spacewidth=10, default_kern=0, kerns={}, charset=u'!"#$%&'()*+, -./0123456789:;<=>? @ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~') This registers an SFont 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. More information about SFont.
n a m e

The name of the font being registered, a string.

s i z e

The size of the font being registered, an integer.

b o l d

The boldness of the font being registered, a boolean.

i t a l i c s

The italicness of the font being registered, a boolean.

u n d e r l i n e

An ignored parameter.
f i l e n a m e

The file containing the sfont image, a string.

s p a c e w i d t h

The width of a space character, an integer in pixels.

d e f a u l t _ k e r n

The default kern spacing between characters, in pixels.

k e r n s

A map from two-character strings to the kern that should be used between those characters.
c h a r s e t- The character set of the font. A string containing characters in

the order in which they are found in the image. The default character set for a SFont is:
! "#$%&'()*+,-./0123456789:;<=>? @ ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_ ` abcdefghijklmnopqrstuvwxyz{|}~

As BMFont is the most complete of the three image font formats Ren'Py supports, it's the one recommended for new projects. An example of BMFont use is:
i n i tp y t h o n : r e n p y . r e g i s t e r _ b m f o n t ( " b m f o n t " ,2 2 ,f i l e n a m e = " b m f o n t . f n t " ) d e f i n ee b f=C h a r a c t e r ( ' E i l e e n ' ,w h a t _ f o n t = " b m f o n t " ,w h a t _ s i z e = 2 2 ) l a b e ld e m o _ b m f o n t : e b f" F i n a l l y ,R e n ' P ys u p p o r t sB M F o n t s . "
Font Groups

When creating a multilingual game, it may not be possible to find a single font that covers every writing system the game use while projecting the the mood the creator intends. To support this, Ren'Py supports font groups that can take characters from two or more fonts and combine them into a single font. To create a font group, create a FontGroup object and call the .add method on it once or more. a FontGroup can be used wherever a font name can be used. The add method takes the start and end of a range of unicode character points, and the first range to cover a point is used. For example:

i n i tp y t h o n : s t y l e . d e f a u l t . f o n t=F o n t G r o u p ( ) . a d d ( " e n g l i s h . t t f " ,0 x 0 0 2 0 ,0 x 0 0 7 f ) . a d d ( " j a p a n e s e . t t f "

F o n t G r o u p ()
A group of fonts that can be used as a single font.

a d d (font, start, end)

Associates a range of characters with a f o n t .
s t a r t

The start of the range. This may be a single-character string, or an integer giving a unicode code point.
e n d

The end of the range. This may be a single-character string, or an integer giving a unicode code point. When multiple .add() calls include the same character, the first call takes precedence. This returns the FontGroup, so that multiple calls to .add() can be chained together. Text Displayable Text can also be used as a displayable, which allows you to apply transforms to text, displaying it as if it was an image and moving it around the screen.

T e x t (text, slow=None, scope=None, substitute=None, slow_done=None, **properties)

A displayable that displays text on the screen.
t e x t

The text to display on the screen. This may be a string, or a list of strings and displayables.
s l o w

Determines if the text is displayed slowly, being typed out one character at the time. If None, slow text mode is determined by the s l o w _ c p sstyle property. Otherwise, the truth value of this parameter determines if slow text mode is used.
s c o p e

If not None, this should be a dictionary that provides an additional scope for text interpolation to occur in.
s u b s t i t u t e

If true, text interpolation occurs. If false, it will not occur. If None, they are controlled by c o n f i g . n e w _ s u b s t i t u t i o n s . Slow Text Concerns Ren'Py allows the creator or user to indicate that text should be displayed slowly. In this case, Ren'Py will render the text to a texture, and then draw rectangles from the texture to the screen. Unfortunately, this means that it's possible to get rendering artifacts when characters overlap. To minimize these rendering artifacts, ensure that the l i n e _ l e a d i n gand l i n e _ s p a c i n g properties are large enough that lines do not overlap. If the bottoms of characters on the first line are clipped, espeically if line_spacing is negative, consider increasing l i n e _ o v e r l a p _ s p l i t . Horizontal artifacts are also possible when characters are kerned together, but these artifacts are less severe, as they exist for only a single frame. Artifacts aren't a problem for static text, like the text in menus and other parts of the user interface.

Translations Ren'Py supports the automatic translation of text. The translation occurs whenever text is displayed, and before text interpolation occurs. Ren'Py reads translations out of .rpt files. A .rpt file is a text file containing lines beginning with the following characters: # Lines beginning with the hash mark are comment lines, that are ignored. < Lines beginning with a less-than followed by a space are translation source lines, giving strings to be translated. > Lines beginning with a greater-than followed by a space are translation lines, giving the translation of the previous translation source. Inside a translation line, newlines are escaped with \n, and backslashes are escaped with \\. By default, Ren'Py reads translations out of a file called translations.rpt, if it exists. The L a n g u a g e ( )action can be used to change the translation file. Creating Translation Files Ren'Py has support for automatically creating translation files. Taking advantage of this is a three-step process. 1. Create an empty translation file, such as translations.rpt, in the game directory. 2. Set the RENPY_UPDATE_TRANSLATIONS environment variable to a non-empty string. 3. Play through the game until all text is seen. Ren'Py will add an entry to the translations file for each unit of text shown. This text can then be translated.
Text Overflow Logging

Ren'Py can log cases where text expands outside of the area allocated for it. To enable text overflow logging, the following steps are necessary. 1. Set the c o n f i g . d e b u g _ t e x t _ o v e r f l o wvariable to true. 2. Set the x m a x i m u mand y m a x i m u mstyle properties on either the Text displayable, or a container enclosing it. 3. Run the game. Whenever text is displayed that overflows the available area, Ren'Py will log an error to the t e x t _ o v e r f l o w . t x tfile.

Displayables
A displayable is an object that can be shown to the user. Ren'Py displayables can be used in many ways. Assignment to an image name using the image statement. Added to a screen using the screen language add statement.

Assignment to certain config variables. Assignment to certain style properties. When a Ren'Py function or variable expects a displayable, there are four things that can be provided: An object of type Displayable, created by calling one of the functions given below. A string with a dot (.) in it. Such a string is interpreted as a filename by I m a g e ( ) . A color. A color may either be given as a hexidecimal color string in "#rgb", "#rgba", "#rrggbb", or "#rrggbbaa" form, or an (r, g, b, a) tuple, where each component is an integer between 0 and 255. Colors are passed to S o l i d ( ) . An image name. Any other string is interpreted as a reference to an image defined with the image statement. Images The most commonly used displayable is Image, which loads a file from disk and displays it. Since Image is so commonly used, when a string giving a filename is used in a context that expects a displayable, an Image is automatically created. The only time it's necessary to use Image directly is when you want to create an image with style properties.

I m a g e (filename, **properties)
Loads an image from a file. f i l e n a m eis a string giving the name of the file.
f i l e n a m eshould be a JPEG or PNG file with an appropriate extension. #T h e s et w ol i n e sa r ee q u i v a l e n t . i m a g el o g o=" l o g o . p n g " i m a g el o g o=I m a g e ( " l o g o . p n g " ) #U s i n gI m a g ea l l o w su st os p e c i f yad e f a u l tp o s i t i o na sp a r to f #a ni m a g e . i m a g el o g or i g h t=I m a g e ( " l o g o . p n g " ,x a l i g n = 1 . 0 )

Loading an Image from from a file on disk and decoding it so it can be drawn to the screen takes a long amount of time. While measured in the tenths or hundreds of seconds, the duration of the loading process is long enough that it can prevent an acceptable framerate, and become annoying to the user. Since an Image is of a fixed size, and doesn't change in response to input, game state, or the size of the area available to it, an Image can be loaded before it is needed, and placed into an area of memory known as the image cache. Once an Image is decoded and in the cache, it can be quickly drawn to the screen. Ren'Py attempts to predict the images that will be used in the future, and loads them into the image cache before they are used. When space in the cache is needed for other images, Ren'Py will remove images that are no longer being used. By default, Ren'Py will predictively cache up to 8 screens worth of image data. (If your screen is 800x600, then a screen's worth of data is one 800x600 image, two 400x600 images, and so on.) This can be changed with the :var:config.image_cache_size configuration variable. Although the precise amount is dependent on implementation details and there is significant overhead, as a rule of thumb, each pixel in the image cache consumes 4 bytes of main memory and 4 bytes of video memory. Image-Like Displayables We call these displayables image-like because they take up a rectangular area of the screen,

and do not react to input. These differ from normal images by varying their size to fill an area (Frame, LiveTile, and Solid), or by allowing the user to specify their size (LiveComposite, LiveCrop, Null). They are not image manipulators. Image-like displayables take Position Style Properties.

F r a m e (image, xborder, yborder, tile=False, **properties)

A displayable that resizes an image to fill the available area, while preserving the width and height of its borders. is often used as the background of a window or button.

Using a frame to resize an image to double its size.

i m a g e

An image manipulator that will be resized by this frame.

l e f t

The size of the border on the left side.

t o p

The size of the border on the top.

r i g h t

The size of the border on the right side. If None, defaults to l e f t .

b o t t o m

The side of the border on the bottom. If None, defaults to t o p .

t i l e

If true, tiling is used to resize sections of the image, rather than scaling.
#R e s i z et h eb a c k g r o u n do ft h et e x tw i n d o wi fi t ' st o os m a l l . i n i tp y t h o n : s t y l e . w i n d o w . b a c k g r o u n d=F r a m e ( " f r a m e . p n g " ,1 0 ,1 0 )

L i v e C r o p (rect, child, **properties)

This created a displayable by cropping c h i l dto r e c t , where r e c tis an (x, y, width, height) tuple.
i m a g ee i l e e nc r o p p e d=L i v e C r o p ( ( 0 ,0 ,3 0 0 ,3 0 0 ) ," e i l e e nh a p p y " )

L i v e T i l e (child, style='tile', **properties)

Tiles c h i l duntil it fills the area allocated to this displayable.
i m a g eb gt i l e=L i v e T i l e ( " b g . p n g " )

N u l l (width=0, height=0, **properties)

A displayable that creates an empty box on the screen. The size of the box is controlled by w i d t hand h e i g h t . This can be used when a displayable requires a child, but no child is suitable, or as a spacer inside a box.
i m a g el o g os p a c e d=H B o x ( " l o g o . p n g " ,N u l l ( w i d t h = 1 0 0 ) ," l o g o . p n g " )

S o l i d (color, **properties)
A displayable that fills the area its assigned with c o l o r .
i m a g ew h i t e=S o l i d ( " # f f f " )

Dynamic Displayables Dynamic displayables display a child displayable based on the state of the game. They do not take any properties, as layout is controlled by the properties of the child displayable they return.

C o n d i t i o n S w i t c h (*args, **kwargs)
This is a displayable that changes what it is showing based on python conditions. The positional argument should be given in groups of two, where each group consists of: A string containing a python condition. A displayable to use if the condition is true. The first true condition has its displayable shown, at least one condition should always be true.
i m a g ej i l l=C o n d i t i o n S w i t c h ( " j i l l _ b e e r s>4 " ," j i l l _ d r u n k . p n g " , " T r u e " ," j i l l _ s o b e r . p n g " )

D y n a m i c D i s p l a y a b l e (function, *args, **kwargs)

A displayable that can change its child based on a Python function, over the course of an interaction.
f u n c t i o n

A function that is called with the arguments: The amount of time the displayable has been shown for.

The amount of time any displayable with the same tag has been shown for. Any positional or keyword arguments supplied to DynamicDisplayable. and should return a (d, redraw) tuple, where:
dis a displayable to show. r e d r a wis the amount of time to wait before calling the function again, or None to

not call the function again before the start of the next interaction.
f u n c t i o nis called at the start of every interaction.

As a special case, f u n c t i o nmay also be a python string that evaluates to a displayable. In that case, function is run once per interaction.
#I ft o o l t i pi sn o te m p t y ,s h o w si ti nat e x t .O t h e r w i s e , #s h o wN u l l .C h e c k se v e r yt e n t ho fas e c o n dt os e ei ft h e #t o o l t i ph a sb e e nu p d a t e d . i n i tp y t h o n : d e fs h o w _ t o o l t i p ( s t ,a t ) : i ft o o l t i p : r e t u r nt o o l t i p ,. 1 e l s e : r e t u r nN u l l ( ) i m a g et o o l t i p p e r=D y n a m i c D i s p l a y a b l e ( s h o w _ t o o l t i p )

S h o w i n g S w i t c h (*args, **kwargs)
This is a displayable that changes what it is showing based on the images are showing on the screen. The positional argument should be given in groups of two, where each group consists of: A string giving an image name, or None to indicate the default. A displayable to use if the condition is true. A default image should be specified. One use of ShowingSwitch is to have side images change depending on the current emotion of a character. For example:
d e f i n ee=C h a r a c t e r ( " E i l e e n " , s h o w _ s i d e _ i m a g e = S h o w i n g S w i t c h ( " e i l e e nh a p p y " ,I m a g e ( " e i l e e n _ h a p p y _ s i d e . p n g " ,x a l i g n = 1 . 0 ,y a l i g n = 1 . 0 ) , " e i l e e nv h a p p y " ,I m a g e ( " e i l e e n _ v h a p p y _ s i d e . p n g " ,x a l i g n = 1 . 0 ,y a l i g n = 1 . 0 ) , N o n e ,I m a g e ( " e i l e e n _ h a p p y _ d e f a u l t . p n g " ,x a l i g n = 1 . 0 ,y a l i g n = 1 . 0 ) , ) )

Applying Transforms to Displayables The At function produces a displayable from a displayable and one or more transforms.

A t (d, *args)
Given a displayable d , applies each of the transforms in a r g sto it. The transforms are applied in left-to-right order, so that the outermost transform is the rightmost argument.
t r a n s f o r mb i r d s _ t r a n s f o r m :

x p o s2 0 0 l i n e a r1 0x p o s8 0 0 p a u s e2 0 r e p e a t i m a g eb i r d s=A t ( " b i r d s . p n g " ,b i r d s _ t r a n s f o r m )

Layout Boxes Layout boxes are displayables that lay out their children on the screen. They can lay out the children in a horizontal or vertical manner, or can lay them out using the standard positioning algorithm. The box displayables take any number of positional and keyword arguments. Positional arguments should be displayables that are added to the box as children. Keyword arguments are style properties that are applied to the box. Boxes take Position Style Properties and Box Style Properties.

F i x e d (*args, **properties)
A box that fills the screen. Its members are laid out from back to front, with their position properties controlling their position.

H B o x (*args, **properties)
A box that lays out its members from left to right.

V B o x (*args, **properties)
A layout that lays out its members from top to bottom.
#D i s p l a yt w ol o g o s ,t ot h el e f ta n dr i g h to fe a c ho t h e r . i m a g el o g oh b o x=H B o x ( " l o g o . p n g " ," l o g o . p n g " ) #D i s p l a yt w ol o g o s ,o n eo nt o po ft h eo t h e r . i m a g el o g ov b o x=V B o x ( " l o g o . p n g " ," l o g o . p n g " ) #D i s p l a yt w ol o g o s .S i n c eb o t hd e f a u l tt ot h eu p p e r l e f t #c o r n e ro ft h es c r e e n ,w en e e dt ou s eI m a g et op l a c e #t h o s el o g o so nt h es c r e e n . i m a g el o g of i x e d=F i x e d ( I m a g e ( " l o g o . p n g " ,x a l i g n = 0 . 0 ,y a l i g n = 0 . 0 ) , I m a g e ( " l o g o . p n g " ,x a l i g n = 1 . 0 ,y a l i g n = 1 . 0 ) )

Effects These displayables are used to create certain visual effects.

A l p h a B l e n d (control, old, new, alpha=False)

This transition uses a c o n t r o ldisplayable (almost always some sort of animated transform) to transition from one displayable to another. The transform is evaluated. The n e wdisplayable is used where the transform is opaque, and the o l ddisplayable is used when it is transparent.
a l p h a

If true, the image is composited with what's behind it. If false, the default, the image is

opaque and overwrites what's behind it. Image Manipulators An image manipulator is a displayable that takes an image or image manipulator, performs an operation to it, and stores the result of that operation in the image cache. Since image manipulators can be predicted like images, they can perform expensive operations without incuring a display-time overhead. Image manipulators are limited to storing image data to the cache. This means that their result is of a fixed size, known in advance, and they can't change in response to game state or input. Generally, image manipulators can only take images or other image manipulators as input. An image manipulator can be used any place a displayable can, but not vice-versa. An I m a g e ( ) is a kind of image manipulator, so an Image can be used whenever an image manipulator is required. Many image manipulators provide the same functionality as other displayables. Most of these exist so they can be provided as input to other image manipulators, and so the game-maker can choose between cache memory usage and work done at render-time. There's also an element of historical accident here - many of these image manipulators predate their equivalents.
i m . A l p h a M a s k (base, mask, **properties)

An image manipulator that takes two image manipulators, b a s eand m a s k , as arguments. It replaces the alpha channel of b a s ewith the red channel of m a s k . This is used to provide an image's alpha channel in a second image, like having one jpeg for color data, and a second one for alpha. In some cases, two jpegs can be smaller than a single png file.
i m . C o m p o s i t e (size, *args, **properties)

This image manipulator composites multiple images together to form a single image. The s i z eshould be a (width, height) tuple giving the size of the composed image. The remaining positional arguments are interpreted as groups of two. The first argument in a group should be an (x, y) tuple, while the second should be an image manipulator. The image produced by the image manipulator is composited at the location given by the tuple.
i m a g eg i r lc l o t h e dh a p p y=i m . C o m p o s i t e ( ( 3 0 0 ,6 0 0 ) , ( 0 ,0 ) ," g i r l _ b o d y . p n g " , ( 0 ,0 ) ," g i r l _ c l o t h e s . p n g " , ( 1 0 0 ,1 0 0 ) ," g i r l _ h a p p y . p n g " )

i m . C r o p (im, rect)

An image manipulator that crops r e c t , a (x, y, width, height) tuple, out of i m , an image manipulator.
i m a g el o g oc r o p=i m . C r o p ( " l o g o . p n g " ,( 0 ,0 ,1 0 0 ,3 0 7 ) )

i m . F a c t o r S c a l e (im, width, height=None, bilinear=True, **properties)

An image manipulator that scales i m(a second image manipulator) to w i d t htimes its original w i d t h , and h e i g h ttimes its original height. If h e i g h tis ommitted, it defaults to w i d t h . If b i l i n e a ris true, then bilinear interpolation is used for the scaling. Otherwise, nearest neighbor interpolation is used.
i m a g el o g od o u b l e d=i m . F a c t o r S c a l e ( " l o g o . p n g " ,1 . 5 )

i m . F l i p (im, horizontal=False, vertical=False, **properties)

An image manipulator that flips i m(an image manipulator) vertically or horizontally. v e r t i c a land h o r i z o n t a lcontrol the directions in which the image is flipped.
i m a g ee i l e e nf l i p=i m . F l i p ( " e i l e e n _ h a p p y . p n g " ,v e r t i c a l = T r u e )

i m . G r a y s c a l e (im, **properties)

An image manipulator that creats a desaturated version of the image manipulator i m .

i m . S c a l e (im, width, height, bilinear=True, **properties)

An image manipulator that scales i m(an image manipulator) to w i d t hand h e i g h t . If b i l i n e a ris true, then bilinear interpolation is used for the scaling. Otherwise, nearest neighbor interpolation is used.
i m a g el o g os c a l e=i m . S c a l e ( " l o g o . p n g " ,1 0 0 ,1 5 0 )

i m . S e p i a (im, **properties)

An image manipulator that creates a sepia-toned version of the image manipulator i m .

i m . T i l e (im, size=None, **properties)

An image manipulator that tiles the image manipulator i m , until it is s i z e .

s i z e

If not None, a (width, height) tuple. If None, this defaults to (c o n f i g . s c r e e n _ w i d t h , c o n f i g . s c r e e n _ h e i g h t ). im.MatrixColor The im.MatrixColor image manipulator is an image manipulator that uses a matrix to control how the colors of an image are transformed. The matrix used can be an im.matrix object, which encodes a 5x5 matrix in an object that supports matrix multiplication, and is returned by a series of functions. im.matrix objects may be multiplied together to yield a second object that performs both operations. For example, the code:
i m a g ec i t yb l u e=i m . M a t r i x C o l o r ( " c i t y . j p g " , i m . m a t r i x . d e s a t u r a t e ( )*i m . m a t r i x . t i n t ( 0 . 9 ,0 . 9 ,1 . 0 ) )

first desaturates the image, and then tints it blue. When the intermediate image is not needed, multiplying matrices is far more efficient, in both time and image cache space, than using two

im.MatrixColors.
i m . M a t r i x C o l o r (im, matrix, **properties)

An image operator that uses m a t r i xto linearly transform the image manipulator i m .
M a t r i xshould be a list, tuple, or i m . m a t r i x ( )that is 20 or 25 elements long. If the object

has 25 elements, then elements past the 20th are ignored.

When the four components of the source color are R, G, B, and A, which range from 0.0 to 1.0; the four components of the transformed color are R', G', B', and A', with the same range; and the elements of the matrix are named:
[a ,b ,c ,d ,e , f ,g ,h ,i ,j , k ,l ,m ,n ,o , p ,q ,r ,s ,t]

the transformed colors can be computed with the formula:

R '=( a*R )+( b*G )+( c*B )+( d*A )+e G '=( f*R )+( g*G )+( h*B )+( i*A )+j B '=( k*R )+( l*G )+( m*B )+( n*A )+o A '=( p*R )+( q*G )+( r*B )+( s*A )+t

The components of the transformed color are clamped to the range [0.0, 1.0].
i m . m a t r i x ()

Constructs an im.matrix object from m a t r i x . im.matrix objects support The operations supported are matrix multiplication, scalar multiplication, element-wise addition, and element-wise subtraction. These operations are invoked using the standard mathematical operators (*, *, +, and -, respectively). If two im.matrix objects are multiplied, matrix multiplication is performed, otherwise scalar multiplication is used.
m a t r i xis a 20 or 25 element list or tuple. If it is 20 elements long, it is padded with (0, 0, 0,

0, 1) to make a 5x5 matrix, suitable for multiplication.

i m . m a t r i x . b r i g h t n e s s ( b)

Returns an im.matrix that alters the brightness of an image.

b

The amount of change in image brightness. This should be a number between -1 and 1, with -1 the darkest possible image and 1 the brightest.
i m . m a t r i x . c o l o r i z e (black_color, white_color)

Returns an im.matrix that colorizes a black and white image. b l a c k _ c o l o rand w h i t e _ c o l o rare Ren'Py style colors, so they may be specfied as strings or tuples of (0-255) color values.
#T h i sm a k e sb l a c kc o l o r sr e d ,a n dw h i t ec o l o r sb l u e . i m a g el o g oc o l o r e d=i m . M a t r i x C o l o r ( " b w l o g o . p n g " , i m . m a t r i x . c o l o r i z e ( " # f 0 0 " ," # 0 0 f " ) )

i m . m a t r i x . c o n t r a s t ( c)

Returns an im.matrix that alters the contrast of an image. cshould be greater than 0.0, with values between 0.0 and 1.0 decreasing contrast, and values greater than 1.0 increasing contrast.
i m . m a t r i x . d e s a t u r a t e ()

Returns an im.matrix that desaturates the image (makes it grayscale). This is equivalent to calling im.matrix.saturation(0).
i m . m a t r i x . h u e ( h)

Returns an im.matrix that rotates the hue by hdegrees, while preserving luminosity.
i m . m a t r i x . i d e n t i t y ()

Returns an identity matrix, one that does not change color or alpha.
i m . m a t r i x . i n v e r t ()

Returns an im.matrix that inverts the red, green, and blue channels of the image without changing the alpha channel.
i m . m a t r i x . o p a c i t y (o)

Returns an im.matrix that alters the opacity of an image. An oof 0.0 is fully transparent, while 1.0 is fully opaque.
i m . m a t r i x . s a t u r a t i o n (level, desat=(0.2126, 0.7152, 0.0722))

Returns an im.matrix that alters the saturation of an image. The alpha channel is untouched.
l e v e l

The amount of saturation in the resulting image. 1.0 is the unaltered image, while 0.0 is grayscale.
d e s a t

This is a 3-element tuple that controls how much of the red, green, and blue channels will be placed into all three channels of a fully desaturated image. The default is based on the constants used for the luminance channel of an NTSC television signal. Since the human eye is mostly sensitive to green, more of the green channel is kept then the other two channels.
i m . m a t r i x . t i n t ( r , g, b)

Returns an im.matrix that tints an image, without changing the alpha channel. r ,g , and b should be numbers between 0 and 1, and control what fraction of the given channel is placed into the final image. (For example, if ris .5, and the value of the red channel is 100, the transformed color will have a red value of 50.)

Transforms
A transform can be applied to a displayable to yield another displayable. The built-in

transforms are used to control where an object is placed on the screen, while user-defined transforms can cause more complex effects, like motion, zoom, and rotation. Transforms can be applied by giving the at clause to the scene and show statements. The following code applies the "right" transform to the eileen happy displayable.:
s h o we i l e e nh a p p ya tr i g h t

Multiple transforms can be applied by separating them with commas. These transforms are applied from left-to-right, with the rightmost transform taking precendece in the case of conflicts.
s h o we i l e e nh a p p ya th a l f s i z e ,r i g h t

A displayable always has a transform associated with it. If no transform is given, the prior transform is used. When the transform is changed, undefined values are taken from the prior transform, or from d e f a u l tif there is no prior transform. Default Transforms Ren'Py ships with a number of transforms defined by default. These transforms position things on the screen. Here's a depiction of where each default transform will position an image.
+ + | t o p l e f t ,r e s e t t o p t o p r i g h t | | | | | | | | | | t r u e c e n t e r | | | | | | | | | | l e f t c e n t e r ,d e f a u l t r i g h t | + +

The offscreenleft and offscreenright transforms position images off the screen. These transforms can be used to move things off the screen (remember to hide them afterwards, to ensure that they do not consume resources). The transforms are:

c e n t e r
Centers horizontally, and aligns to the bottom of the screen.

d e f a u l t
Centers horizontally, and aligns to the bottom of the screen. This can be redefined to change the default placement of images shown with the show or scene statements.

l e f t
Aligns to the bottom-left corner of the screen.

o f f s c r e e n l e f t
Places the displayable off the left side of the screen, aligned to the bottom of the screen.

o f f s c r e e n r i g h t
Places the displayable off the left side of the screen, aligned to the bottom of the screen.

r e s e t
Resets the transform. Places the displayable in the top-left corner of the scren, and also eliminates any zoom, rotation, or other effects.

r i g h t
Aligns to the bottom-right corner of the screen.

t o p
Centers horizontally, and aligns to the top of the screen.

t o p l e f t
Aligns to the top-left corner of the screen.

t o p r i g h t
Aligns to the top-right corner of the screen.

t r u e c e n t e r
Centers both horizontally and vertically. Creator-Defined Transforms A creator can define a transform using the animation and transformation language, or the T r a n s f o r mfunction.

Transitions
Transitions can be used as part of the with statement, as well as in other parts of Ren'Py, to apply effects to changes in the scene. Ren'Py comes with a small number of pre-defined transitions, which can be given directly to the with statement. It also includes transition classes, which can be used to create new transitions. Pre-Defined Transitions Pre-defined transitions can be given directly to the with statement. For example:
s h o wb gw a s h i n g t o n w i t hd i s s o l v e

f a d e
Takes 0.5 seconds to fade to black, and then 0.5 seconds to fade to the new screen. An instance of the F a d e ( )transition class.

d i s s o l v e
Takes 0.5 seconds to dissolve from the old to the new screen. An instance of the D i s s o l v e ( )transition class.

p i x e l l a t e
Pixellates the old scene for .5 seconds, and the new scene for another .5 seconds. An

instance of the P i x e l l a t e ( )transition class.

m o v e
Takes 0.5 seconds to the move images that have changed location to their new locations. An instance of the M o v e T r a n s i t i o n ( )transition class.

m o v e i n r i g h t
Also: moveinleft, moveintop, moveinbottom These move entering images onto the screen from the appropriate side, taking 0.5 seconds to do so.

m o v e o u t r i g h t
Also: moveoutleft, moveouttop, moveoutbottom These move leaving images off the screen via the appropriate side, taking 0.5 seconds to do so.

e a s e
Also: easeinright, easeinleft, easeintop, easeinbottom, easeoutright, easeoutleft, easeouttop, easeoutbottom These are similar to the move- family of transitions, except that they use a cosine-based curve to slow down the start and end of the transition.

z o o m i n
This zooms in entering images, taking 0.5 seconds to do so.

z o o m o u t
This zooms out leaving images, taking 0.5 seconds to do so.

z o o m i n o u t
This zooms in entering images and zooms out leaving images, taking 0.5 seconds to do so.

v p u n c h
When invoked, this transition shakes the screen vertically for a quarter second.

h p u n c h
When invoked, this transition shakes the screen horizontally for a quarter second.

b l i n d s
Transitions the screen in a vertical blinds effect lasting 1 second. An instance of the I m a g e D i s s o l v e ( )transition class.

s q u a r e s
Transitions the screen in a squares effect lasting 1 second.

w i p e l e f t
Also: wiperight, wipeup, wipedown Wipes the scene in the given direction. Instances of the C r o p M o v e ( )transition class.

s l i d e l e f t
Also: slideright, slideup, slidedown Slides the new scene in the given direction. Instances of the C r o p M o v e ( )transition class.

s l i d e a w a y l e f t
Also: slideawayright, slideawayup, slideawaydown Slides the new scene in the given direction. Instances of the C r o p M o v e ( )transition class.

i r i s i n
Also: irisout Use a rectangular iris to display the new screen, or hide the old screen. Instances of the C r o p M o v e ( )transition class. Transition Classes Transition classes are functions that can be called to create new transitions. These functions are parameterized, allowing entire families of transitions to be created. Calling transition classes can be done as part of the with statement. For example:
#Av e r yl o n gd i s s o l v e . w i t hD i s s o l v e ( 1 0 . 0 )

If we find ourselves calling the same transition class repeatedly, we can use the define statement to assign the transition to a variable:
d e f i n ea n n o y t h e u s e r=D i s s o l v e ( 1 . 0 ) l a b e ls t a r t : s h o wb gw a s h i n g t o n w i t ha n n o y t h e u s e r

A l p h a D i s s o l v e (control, delay=0.0, alpha=False, reverse=False)

Returns a transition that uses a control displayable (almost always some sort of animated transform) to transition from one screen to another. The transform is evaluated. The new screen is used where the transform is opaque, and the old image is used when it is transparent.
c o n t r o l

The control transform.

d e l a y

The time the transition takes, before ending.

a l p h a

If true, the image is composited with what's behind it. If false, the default, the image is opaque and overwrites what's behind it.
r e v e r s e

If true, the alpha channel is reversed. Opaque areas are taken from the old image, while transparent areas are taken from the new image.

C o m p o s e T r a n s i t i o n (trans, before, after)

Returns a transition that composes up to three transitions. If not None, the b e f o r eand a f t e rtransitions are applied to the old and new scenes, respectively. These updated old and new scenes are then supplied to the t r a n stransition.

#M o v et h ei m a g e si na n do u tw h i l ed i s s o l v i n g .( T h i si saf a i r l ye x p e n s i v et r a n s i t i o n . )

d e f i n em o v e i n o u t d i s s o l v e=C o m p o s e T r a n s i t i o n ( d i s s o l v e ,b e f o r e = m o v e o u t l e f t ,a f t e r = m o v e i n r

C r o p M o v e (time, mode="slideright", startcrop=(0.0, 0.0, 0.0, 1.0), startpos=(0.0, 0.0), endcrop=(0.0, 0.0, 1.0, 1.0), endpos=(0.0, 0.0), topnew=True)
Returns a transition that works by cropping a scene and positioning it on the screen. This can be used to implement a variety of effects, all of which involved changing rectangular slices of scenes.
t i m e

The time the transition takes.

m o d e

The name of the mode of the transition. There are three groups of modes: wipes, slides, and other. This can also be "custom", to allow a custom mode to be defined. In a wipe, the image stays fixed, and more of it is revealed as the transition progresses. For example, in "wiperight", a wipe from left to right, first the left edge of the image is revealed at the left edge of the screen, then the center of the image, and finally the right side of the image at the right of the screen. Other supported wipes are "wipeleft", "wipedown", and "wipeup". In a slide, the image moves. So in a "slideright", the right edge of the image starts at the left edge of the screen, and moves to the right as the transition progresses. Other slides are "slideleft", "slidedown", and "slideup". There are also slideaways, in which the old image moves on top of the new image. Slideaways include "slideawayright", "slideawayleft", "slideawayup", and "slideawaydown". We also support a rectangular iris in with "irisin" and a rectangular iris out with "irisout". The following parameters are only respected if the mode is "custom". Positions are relative to the size of the screen, while the crops are relative to the size of the image. So a crop of (0.25, 0.0, 0.5, 1.0) takes the middle half of an image.
s t a r t c r o p

The starting rectangle that is cropped out of the top image. A 4-element tuple containing x, y, width, and height.
s t a r t p o s

The starting place that the top image is drawn to the screen at, a 2-element tuple containing x and y.
e n d c r o p

The ending rectangle that is cropped out of the top image. A 4-element tuple containing x, y, width, and height.
e n d p o s

The ending place that the top image is drawn to the screen at, a 2-element tuple containing x and y.
t o p n e w

If true, the scene that is cropped and moved (and is on top of the other scene) is the new scene. If false, it is the old scene.
d e f i n ew i p e r i g h t=C r o p M o v e ( 1 . 0 ," w i p e r i g h t " ) d e f i n ew i p e l e f t=C r o p M o v e ( 1 . 0 ," w i p e l e f t " ) d e f i n ew i p e u p=C r o p M o v e ( 1 . 0 ," w i p e u p " )

d e f i n ew i p e d o w n=C r o p M o v e ( 1 . 0 ," w i p e d o w n " ) d e f i n es l i d e r i g h t=C r o p M o v e ( 1 . 0 ," s l i d e r i g h t " ) d e f i n es l i d e l e f t=C r o p M o v e ( 1 . 0 ," s l i d e l e f t " ) d e f i n es l i d e u p=C r o p M o v e ( 1 . 0 ," s l i d e u p " ) d e f i n es l i d e d o w n=C r o p M o v e ( 1 . 0 ," s l i d e d o w n " ) d e f i n es l i d e a w a y r i g h t=C r o p M o v e ( 1 . 0 ," s l i d e a w a y r i g h t " ) d e f i n es l i d e a w a y l e f t=C r o p M o v e ( 1 . 0 ," s l i d e a w a y l e f t " ) d e f i n es l i d e a w a y u p=C r o p M o v e ( 1 . 0 ," s l i d e a w a y u p " ) d e f i n es l i d e a w a y d o w n=C r o p M o v e ( 1 . 0 ," s l i d e a w a y d o w n " ) d e f i n ei r i s o u t=C r o p M o v e ( 1 . 0 ," i r i s o u t " ) d e f i n ei r i s i n=C r o p M o v e ( 1 . 0 ," i r i s i n " )

D i s s o l v e (time, alpha=False, time_warp=None)

Returns a transition that dissolves from the old scene to the new scene.
t i m e

The time the dissolve will take.

a l p h a

If true, the dissolve will alpha-composite the the result of the transition with the screen. If false, the result of the transition will replace the screen, which is more efficient.
t i m e _ w a r p

A function that adjusts the timeline. If not None, this should be a function that takes a fractional time between 0.0 and 1.0, and returns a number in the same range.

F a d e (out_time, hold_time, in_time, color="#000")

Returns a transition that takes o u t _ t i m eseconds to fade to a screen filled with c o l o r , holds at that screen for h o l d _ t i m eseconds, and then takes i n _ t i m eto fade to then new screen.
#F a d et ob l a c ka n db a c k . d e f i n ef a d e=F a d e ( 0 . 5 ,0 . 0 ,0 . 5 ) #H o l da tb l a c kf o rab i t . d e f i n ef a d e h o l d=F a d e ( 0 . 5 ,1 . 0 ,0 . 5 ) #C a m e r af l a s h-q u i c k l yf a d e st ow h i t e ,t h e nb a c kt ot h es c e n e . d e f i n ef l a s h=F a d e ( 0 . 1 ,0 . 0 ,0 . 5 ,c o l o r = " # f f f " )

I m a g e D i s s o l v e (image, time, ramplen=8, reverse=False, alpha=True, time_warp=None)

Returns a transition that dissolves the old scene into the new scene, using an image to control the dissolve process. This means that white pixels will dissolve in first, and black pixels will dissolve in last.
i m a g e

A control image to use. This must be either an image file or image manipulator. The control image should be the size of the scenes being dissolved.
t i m e

The time the dissolve will take.

r a m p l e n

The length of the ramp to use. This must be an integer power of 2. When this is the default value of 8, when a white pixel is fully dissolved, a pixel 8 shades of gray darker will have completed one step of dissolving in.
r e v e r s e

If true, black pixels will dissolve in before white pixels.

a l p h a

If true, the dissolve will alpha-composite the the result of the transition with the screen. If false, the result of the transition will replace the screen, which is more efficient.
t i m e _ w a r p

A function that adjusts the timeline. If not None, this should be a function that takes a fractional time between 0.0 and 1.0, and returns a number in the same range.
d e f i n ec i r c i r i s o u t=I m a g e D i s s o l v e ( " c i r c i r i s . p n g " ,1 . 0 ) d e f i n ec i r c i r i s i n=I m a g e D i s s o l v e ( " c i r c i r i s . p n g " ,1 . 0 ,r e v e r s e = T r u e ) d e f i n ec i r c i r i s t b i g r a m p=I m a g e D i s s o l v e ( " c i r c i r i s . p n g " ,1 . 0 ,r a m p l e n = 2 5 6 )

M o v e T r a n s i t i o n (delay, enter=None, leave=None, old=False, layers=['master'], time_warp=None, enter_time_warp=None, leave_time_warp=None)

Returns a transition that interpolates the position of images (with the same tag) in the old and new scenes.
d e l a y

The time it takes for the interpolation to finish.

e n t e r

If not None, images entering the scene will also be moved. The value of e n t e rshould be a transform that is applied to the image to get its starting position.
l e a v e

If not None, images leaving the scene will also be move. The value of l e a v eshould be a transform that is applied to the image to get its ending position.
o l d

If true, the old image will be used in preference to the new one.
l a y e r s

A list of layers that moves are applied to.

t i m e _ w a r p

A time warp function that's applied to the interpolation. This takes a number between 0.0 and 1.0, and should return a number in the same range.
e n t e r _ t i m e _ w a r p

A time warp function that's applied to images entering the scene.

e n t e r _ t i m e _ w a r p

A time warp function that's applied to images leaving the scene.

M u l t i p l e T r a n s i t i o n (args)
Returns a transition that allows multiple transitions to be displayed, one after the other.
a r g s

A list containing an odd number of items. The first, third, and other odd-numbered items must be scenes, and the even items must be transitions. A scene can be one of:

items must be scenes, and the even items must be transitions. A scene can be one of: A displayable. False, to use the old scene. True, to use the new scene. Almost always, the first argument will be False and the last True. The transitions in a r g sare applied in order. For each transition, the old scene is the screen preceding it, and the new scene is the scene following it. For example:
d e f i n el o g o d i s s o l v e=M u l t i p l e T r a n s i t i o n ( F a l s e ,D i s s o l v e ( 0 . 5 ) " l o g o . j p g " ,N o T r a n s i t i o n ( 1 . 0 ) , " l o g o . j p g " ,d i s s o l v e , T r u e )

This example will dissolve to logo.jpg, wait 1 second, and then dissolve to the new scene.

P a u s e (delay)
Returns a transition that only displays the new screen for d e l a yseconds. It can be useful as part of a MultipleTransition.

P i x e l l a t e (time, steps)
Returns a transition that pixellates out the old screen, and then pixellates in the new screen.
t i m e

The total time the transition will take, in seconds.

s t e p s

The number of steps that will occur, in each direction. Each step creates pixels about twice the size of those in the previous step, so a 5-step pixellation will create 32x32 pixels. Transition Families Transition families are functions that define a large family of related transitions.
d e f i n e . m o v e _ t r a n s i t i o n s (prefix, delay, time_warp=None, in_time_warp=None,

out_time_warp=None, old=False, layers=['master'], **kwargs) This defines a family of move transitions, similar to the move and ease transitions. For a given p r e f i x , this defines the transitions: prefix- A transition that takes d e l a yseconds to move images that changed positions to their new locations. prefixinleft, prefixinright, prefixintop, prefixinbottom - Transitions that take d e l a y seconds to move images that changed positions to their new locations, with newly shown images coming in from the appropriate side. prefixoutleft, prefixoutright, prefixouttop, prefixoutbottom - Transitions that take d e l a yseconds to move images that changed positions to their new locations, with newly hidden images leaving via the appropriate side.
t i m e _ w a r p ,i n _ t i m e _ w a r p ,o u t _ t i m e _ w a r p

Time warp functions that are given a time from 0.0 to 1.0 representing the fraction of the move complete, and return a value in the same range giving the fraction of a

the move complete, and return a value in the same range giving the fraction of a linear move that is complete. This can be used to define functions that ease the images around, rather than moving them at a constant speed. The three argument are used for images remaining on the screen, newly shown images, and newly hidden images, respectively.
o l d

If true, the transitions to move the old displayables, rather than the new ones.
l a y e r s

The layers the transition will apply to.

#T h i sd e f i n e sa l lo ft h ep r e d e f i n e dt r a n s i t i o n sb e g i n n i n g #w i t h" m o v e " . i n i tp y t h o n : d e f i n e . m o v e _ t r a n s i t i o n s ( " m o v e " ,0 . 5 )

Animation and Transformation Language

The Animation and Transformation Language (ATL) provides a high-level way of choosing a displayable to show, positioning it on the screen, and applying transformations such as rotation, zoom, and alpha-modification. These can be changed over time, and in response to events. The Python equivalent of an ATL transform is the T r a n s f o r m ( )displayable. There is no way to create an ATL transform programatically. Ren'Py Script Statements ATL Code can be included as part of three Ren'Py script statements.
Transform Statement

The transform statement creates a transform that can be supplied as part of an at clause. The syntax of the transform statement is:
a t l _ t r a n s f o r m: : = " t r a n s f o r m "n a m e" ( "p a r a m e t e r s" ) "" : " a t l _ b l o c k

The transform statement must be run at init time. If it is found outside an init block, then it is automatically placed inside an init block with a priority of 0. The transform may have a list of parameters, which must be supplied when it is called.
N a m emust be a python identifier. The transform created by the ATL block is bound to this

name.:

t r a n s f o r ml e f t _ t o _ r i g h t : x a l i g n0 . 0 l i n e a r2 . 0y a l i g n1 . 0 r e p e a t
Image Statement With ATL Block

The second way to use ATL is as part of an image statement with ATL block. This binds an image name to the given transform. As there's no way to supply parameters to this transform, it's only useful if the transform defines an animation. The syntax for an image statement with ATL block is:
a t l _ i m a g e: : = " i m a g e "i m a g e _ n a m e" : " a t l _ b l o c k i m a g ee i l e e na n i m a t e d : " e i l e e n _ h a p p y . p n g " p a u s e1 . 0 " e i l e e n _ v h a p p y . p n g " p a u s e1 . 0 r e p e a t
Scene and Show Statements with ATL Block

The final way to use ATL is as part of a scene or show statement. This wraps the image being shown inside an ATL transformation.
a t l _ s c e n e: : = s t m t _ s c e n e" : " a t l _ b l o c k a t l _ s h o w : : = s t m t _ s h o w" : " a t l _ b l o c k s c e n eb gw a s h i n g t o n : z o o m2 . 0 s h o we i l e e nh a p p y : x a l i g n1 . 0

ATL Syntax and Semantics An ATL block consists of one or more logical lines, all at the same indentation, and indented relative to the statement containing the block. Each logical line in an ATL block must contain one or more ATL statements. There are two kinds of ATL statements: simple and complex. Simple statements do not take an ATL block. A single logical line may contain one or more ATL statements, separated by commas. A complex statement contains a block, must be on its own line. The first line of a complex statement always ends with a colon (":"). By default, statements in a block are executed in the order in which they appear, starting with the first statement in the block. Execution terminates when the end of the block is reached. Time statements change this, as described in the appropriate section below. Execution of a block terminates when all statements in the block have terminated. If an ATL statement requires evaluation of an expression, such evaluation occurs when the transform is first added to the scene list. (Such as when using a show statement or ui function.) ATL Statements The following are the ATL statements.
Interpolation Statement

The interpolation statement is the main way that ATL controls transformations.
a t l _ i n t e r p: : = (w a r p e rs i m p l e _ e x p r e s s i o n|" w a r p "s i m p l e _ e x p r e s s i o ns i m p l e _ e x p r e s s i o n (p r o p e r t ys i m p l e _ e x p r e s s i o n(" k n o t "s i m p l e _ e x p r e s s i o n) * |" c l o c k w i s e " |" c o u n t e r c l o c k w i s e " |" c i r c l e s "s i m p l e _ e x p r e s s i o n |s i m p l e _ e x p r e s s i o n) *

The first part of the interpolation statement is used to select a function that time-warps the interpolation. (That is, a function from linear time to non-linear time.) This can either be done by giving the name of a warper registered with ATL, or by giving the keyword "warp" followed by an expression giving a function. Either case is followed by a number, giving the number of seconds the interpolation should take. If no warp function is given, the interpolation is run for 0 seconds, using the pause function. The warper and duration are used to compute a completion fraction. This is done by dividing the time taken by the interpolation by the duration of the interpolation. This is clamped to the duration, and then passed to the warper. The result returned by the warper is the completion fraction. The interpolation statement can then contain a number of other clauses. When a property and value are present, then the value is the value the property will obtain at the end of the statement. The value can be obtained in several ways: If the value is followed by one or two knots, then spline motion is used. The starting point is the value of the property at the start of the interpolation, the end point is the property value, and the knots are used to control the spline. If the interpolation statement contains a "clockwise" or "counterclockwise" clause, circular motion is used, as described below. Otherwise, the value is linearly interpolated between the start and end locations, using the completion fraction. If a simple expression is present, it should evaluate to a transform with only a single interpolation statement, without a warper, splines, or circular motion. The properties from the transform are processed as if they were included in this statement. Some sample interpolations are:
s h o wl o g ob a s e : #S h o wt h el o g oa tt h eu p p e rr i g h ts i d eo ft h es c r e e n . x a l i g n1 . 0y a l i g n0 . 0 #T a k e1 . 0s e c o n d st om o v et h i n g sb a c kt ot h el e f t . l i n e a r1 . 0x a l i g n0 . 0 #T a k e1 . 0s e c o n d st om o v et h i n g st ot h el o c a t i o ns p e c i f i e di nt h e #t r u e c e n t e rt r a n s f o r m .U s et h ee a s ew a r p e rt od ot h i s . e a s e1 . 0t r u e c e n t e r #J u s tp a u s ef o ras e c o n d . p a u s e1 . 0 #S e tt h el o c a t i o nt oc i r c l ea r o u n d . a l i g n a r o u n d( . 5 ,. 5 ) #U s ec i r c u l a rm o t i o nt ob r i n gu st os p i r a lo u tt ot h et o po f #t h es c r e e n .T a k e2s e c o n d st od os o . l i n e a r2 . 0y a l i g n0 . 0c l o c k w i s ec i r c l e s3

#U s eas p l i n em o t i o nt om o v eu sa r o u n dt h es c r e e n . l i n e a r2 . 0a l i g n( 0 . 5 ,1 . 0 )k n o t( 0 . 0 ,. 3 3 )k n o t( 1 . 0 ,. 6 6 )

An important special case is that the pause warper, followed by a time and nothing else, causes ATL execution to pause for that amount of time. Some properties can have values of multiple types. For example, the xpos property can be an int, float, or absolute. The behavior is undefined when an interpolation has old and new property values of different types.
Time Statement

The time statement is a simple control statement. It contains a single simple_expression, which is evaluated to give a time, expressed as seconds from the start of execution of the containing block.
a t l _ t i m e: : = " t i m e "s i m p l e _ e x p r e s s i o n

When the time given in the statement is reached, the following statement begins to execute.This transfer of control occurs even if a previous statement is still executing, and causes any prior statement to immediately terminate. Time statements are implicitly preceded by a pause statement with an infinite time. This means that if control would otherwise reach the time statement, it waits until the time statement would take control. When there are multiple time statements in a block, they must strictly increase in order.
i m a g eb a c k g r o u n d s : " b gb a n d " t i m e2 . 0 " b gw h i t e h o u s e " t i m e4 . 0 " b gw a s h i n g t o n "
Expression Statement

An expression statement is a simple statement that starts with a simple expression. It then contains an optional with clause, with a second simple expression.
a t l _ e x p r e s s i o n: : = s i m p l e _ e x p r e s s i o n( " w i t h "s i m p l e _ e x p r e s s i o n ) ?

There are three things the first simple expression may evaluate to: If it's a transform, that transform is executed. With clauses are ignored when a transform is supplied. If it's an integer or floating point number, it's taken as a number of seconds to pause execution for. Otherwise, the expression is interpreted to be a displayable. This displayable replaces the child of the transform when this clause executes, making it useful for animation. If a with clause is present, the second expression is evaluated as a transition, and the transition is applied to the old and new displayables.
i m a g ea t le x a m p l e : #D i s p l a yl o g o _ b a s e . p n g " l o g o _ b a s e . p n g "

#P a u s ef o r1 . 0s e c o n d s . 1 . 0 #S h o wl o g o _ b w . p n g ,w i t had i s s o l v e . " l o g o _ b w . p n g "w i t hD i s s o l v e ( 0 . 5 ,a l p h a = T r u e ) #R u nt h em o v e _ r i g h tt r a n f o r m . m o v e _ r i g h t

Pass Statement

a t l _ p a s s: : = " p a s s "

The pass statement is a simple statement that causes nothing to happen. This can be used when there's a desire to separate statements, like when there are two sets of choice statements that would otherwise be back-to-back.
Repeat Statement

The repeat statement is a simple statement that causes the block containing it to resume execution from the beginning. If the expression is present, then it is evaluated to give an integer number of times the block will execute. (So a block ending with "repeat 2" will execute at most twice.)
a t l _ r e p e a t: : = " r e p e a t "( s i m p l e _ e x p r e s s i o n ) ?

The repeat statement must be the last statement in a block.:

s h o wl o g ob a s e : x a l i g n0 . 0 l i n e a r1 . 0x a l i g n1 . 0 l i n e a r1 . 0x a l i g n0 . 0 r e p e a t
Block Statement

The block statement is a complex statement that contains a block of ATL code. This can be used to group statements that will repeat.
a t l _ b l o c k _ s t m t: : = " b l o c k "" : " a t l _ b l o c k l a b e ll o g ob a s e : a l p h a0 . 0x a l i g n0 . 0y a l i g n0 . 0 l i n e a r1 . 0a l p h a1 . 0 b l o c k : l i n e a r1 . 0x a l i g n1 . 0 l i n e a r1 . 0x a l i g n0 . 0 r e p e a t
Choice Statement

The choice statement is a complex statement that defines one of a set of potential choices. Ren'Py will pick one of the choices in the set, and execute the ATL block associated with it, and

Ren'Py will pick one of the choices in the set, and execute the ATL block associated with it, and then continue execution after the last choice in the choice set.
a t l _ c h o i c e: : = " c h o i c e "( s i m p l e _ e x p r e s s i o n ) ?" : " a t l _ b l o c k

Choice statements are greedily grouped into a choice set when more than one choice statement appears consecutively in a block. If the s i m p l e _ e x p r e s s i o nis supplied, it is a floating-point weight given to that block, otherwise 1.0 is assumed.
i m a g ee i l e e nr a n d o m : c h o i c e : " e i l e e nh a p p y " c h o i c e : " e i l e e nv h a p p y " c h o i c e : " e i l e e nc o n c e r n e d " p a u s e1 . 0 r e p e a t
Parallel Statement

The parallel statement is used to define a set of ATL blocks to execute in parallel.
a t l _ p a r a l l e l: : = " p a r a l l e l "" : " a t l _ b l o c k

Parallel statements are greedily grouped into a parallel set when more than one parallel statement appears consecutively in a block. The blocks of all parallel statements are then executed simultaneously. The parallel statement terminates when the last block terminates. The blocks within a set should be independent of each other, and manipulate different properties. When two blocks change the same property, the result is undefined.
s h o wl o g ob a s e : p a r a l l e l : x a l i g n0 . 0 l i n e a r1 . 3x a l i g n1 . 0 l i n e a r1 . 3x a l i g n0 . 0 r e p e a t p a r a l l e l : y a l i g n0 . 0 l i n e a r1 . 6y a l i g n1 . 0 l i n e a r1 . 6y a l i g n0 . 0 r e p e a t
Event Statement

The event statement is a simple statement that causes an event with the given name to be produced.
a t l _ e v e n t: : = " e v e n t "n a m e

When an event is produced inside a block, the block is checked to see if an event handler for the given name exists. If it does, control is transferred to the event handler. Otherwise, the event propagates to any containing event handler.

On Statement

The On statement is a complex statement that defines an event handler. On statements are greedily grouped into a single statement.
a t l _ o n: : = " o n "n a m e" : " a t l _ b l o c k

The on statement is used to handle events. When an event is handled, handling of any other event ends and handing of the new event immediately starts. When an event handler ends without another event occuring, the d e f a u l tevent is produced (unless were already handing the d e f a u l tevent). Execution of the on statement will never naturally end. (But it can be ended by the time statement, or an enclosing event handler.)
s h o wl o g ob a s e : o ns h o w : a l p h a0 . 0 l i n e a r. 5a l p h a1 . 0 o nh i d e : l i n e a r. 5a l p h a0 . 0
Contains Statement

The contains statement sets the displayable contained by this ATL transform. (The child of the transform.) There are two variants of the contains statement. The contains expression variant takes an expression, and sets that expression as the child of the transform. This is useful when an ATL transform wishes to contain, rather than include, a second ATL transform.
a t l _ c o n t a i n s: : = " c o n t a i n s "e x p r e s s i o n t r a n s f o r ma n _ a n i m a t i o n : " 1 . p n g " p a u s e2 " 2 . p n g " p a u s e2 r e p e a t i m a g em o v e _ a n _ a n i m a t i o n : c o n t a i n sa n _ a n i m a t i o n #I fw ed i d n ' tu s ec o n t a i n s ,w e ' ds t i l lb el o o p i n ga n d #w o u l dn e v e rr e a c hh e r e . x a l i g n0 . 0 l i n e a r1 . 0y a l i g n1 . 0

The contains block allows one to define an ATL block that is used for the child of this ATL transform. One or more contains block statements will be greedily grouped together, wrapped inside a F i x e d ( ) , and set as the child of this transform.
a t l _ c o u n t s: : = " c o n t a i n s "" : "

Each block should define a displayable to use, or else an error will occur. The contains statement executes instantaneously, without waiting for the children to complete. This

statement is mostly syntactic sugar, as it allows arguments to be easily passed to the children.
i m a g et e s td o u b l e : c o n t a i n s : " l o g o . p n g " x a l i g n0 . 0 l i n e a r1 . 0x a l i g n1 . 0 r e p e a t c o n t a i n s : " l o g o . p n g " x a l i g n1 . 0 l i n e a r1 . 0x a l i g n0 . 0 r e p e a t
Function Statement

The function statement allows ATL to use Python functions to control the ATL properties.
a t l _ f u n c t i o n: : = " f u n c t i o n "e x p r e s s i o n

The functions have the same signature as those used with T r a n s f o r m ( ) : The first argument is a transform object. Transform properties can be set on this object. The second argument is the shown timebase, the number of seconds since the function began executing. The third argument is the the animation timebase, which is the number of seconds something with the same tag has been on the screen. If the function returns a number, it will be called again after that number of seconds has elapsed. (0 seconds means to call the function as soon as possible.) If the function returns None, control will pass to the next ATL statement.
i n i tp y t h o n : d e fs l i d e _ f u n c t i o n ( t r a n s ,s t ,a t ) : i fs t>1 . 0 : t r a n s . x a l i g n=1 . 0 r e t u r nN o n e e l s e : t r a n s . x a l i g n=s t r e t u r n0 l a b e ls t a r t : s h o wl o g ob a s e : f u n c t i o ns l i d e _ f u n c t i o n p a u s e1 . 0 r e p e a t

Warpers A warper is a function that can change the amount of time an interpolation statement considers to have elapsed. The following warpers are defined by default. They are defined as functions from t to t', where t and t' are floating point numbers between 0.0 and 1.0. (If the statement has 0 duration, than t is 1.0 when it runs.)
p a u s e

Pause, then jump to the new value. If t == 1.0, t = 1.0. Otherwise, t' = 0.0.
l i n e a r

Linear interpolation. t' = t

e a s e

Start slow, speed up, then slow down. t' = .5 - math.cos(math.pi * t) / 2.0
e a s e i n

Start fast, then slow down. t' = math.cos((1.0 - t) * math.pi / 2.0

e a s e o u t

Start slow, then speed up. t' = 1.0 - math.cos(t * math.pi / 2.0) New warpers can be defined using the renpy.atl_warper decorator, in a python early block. It should be placed in a file that is parsed before any file that uses the warper. The code looks like:
p y t h o ne a r l yh i d e : @ r e n p y . a t l _ w a r p e r d e fl i n e a r ( t ) : r e t u r nt

List of Transform Properties The following transform properties exist. When the type is given as position, it may be an int, renpy.absolute, or float. If it's a float, it's interpreted as a fraction of the size of the containing area (for pos) or displayable (for anchor). Note that not all properties are independent. For example, xalign and xpos both update some of the same underlying data. In a parallel statement, only one block should adjust horizontal position, and one should adjust vertical positions. (These may be the same block.) The angle and radius properties set both horizontal and vertical positions.

p o s
Type : (position, position) Default : (0, 0) The position, relative to the top-left corner of the containing area.

x p o s
Type : position Default : 0 The horizontal position, relative to the left side of the containing area.

y p o s
Type : position Default : 0 The vertical position, relative to the top of the containing area.

a n c h o r
Type : (position, position) Default : (0, 0) The anchor position, relative to the top-left corner of the displayable.

x a n c h o r
Type : position

Type : position Default : 0 The horizontal anchor position, relative to the left side of the displayable.

y a n c h o r
Type : position Default : 0 The vertical anchor position, relative to the top of the displayable.

a l i g n
Type : (float, float) Default : (0.0, 0.0) Equivalent to setting pos and anchor to the same value.

x a l i g n
Type : float Default : 0.0 Equivalent to setting xpos and xanchor to this value.

y a l i g n
Type : float Default : 0.0 Equivalent to setting ypos and yanchor to this value.

x c e n t e r
Type : float Default : 0.0 Equivalent to setting xpos to the value of this property, and xanchor to 0.5.

y c e n t e r
Type : float Default : 0.0 Equivalent to setting ypos to the value of this property, and yanchor to 0.5.

r o t a t e
Type : float or None Default : None If None, no rotation occurs. Otherwise, the image will be rotated by this many degrees clockwise. Rotating the displayable causes it to be resized, according to the setting of rotate_pad, below. This can cause positioning to change if xanchor and yanchor are not 0.5.

r o t a t e _ p a d
Type : boolean Default : True If True, then a rotated displayable is padded such that the width and height are equal to the hypotenuse of the original width and height. This ensures that the transform will not change size as its contents rotate. If False, the transform will be given the minimal size that contains the transformed displayable. This is more suited to fixed rotations.

that contains the transformed displayable. This is more suited to fixed rotations.

z o o m
Type : float Default : 1.0 This causes the displayable to be zoomed by the supplied factor.

x z o o m
Type : float Default : 1.0 This causes the displayable to be horizontally zoomed by the supplied factor. A negative value causes the image to be flipped horizontally.

y z o o m
Type : float Default : 1.0 This causes the displayable to be vertically zoomed by the supplied factor. A negative value causes the image to be flipped vertically.

a l p h a
Type : float Default : 1.0 This controls the opacity of the displayable.

a r o u n d
Type : (position, position) Default : (0.0, 0.0) If not None, specifies the polar coordinate center, relative to the upper-left of the containing area. Setting the center using this allows for circular motion in position mode.

a l i g n a r o u n d
Type : (float, float) Default : (0.0, 0.0) If not None, specifies the polar coordinate center, relative to the upper-left of the containing area. Setting the center using this allows for circular motion in align mode.

a n g l e
Type : float Get the angle component of the polar coordinate position. This is undefined when the polar coordinate center is not set.

r a d i u s
Type : position Get the radius component of the polar coordinate position. This is undefined when the polar coordinate center is not set.

c r o p
Type : None or (int, int, int, int)

Default : None If not None, causes the displayable to be cropped to the given box. The box is specified as a tuple of (x, y, width, height).

c o r n e r 1
Type : None or (int, int) Default : None If not None, gives the upper-left corner of the crop box. This takes priority over crop.

c o r n e r 2
Type : None or (int, int) Default : None If not None, gives the lower right corner of the crop box. This takes priority over crop.

s i z e
Type : None or (int, int) Default : None If not None, causes the displayable to be scaled to the given size.

s u b p i x e l
Type : boolean Default : False If True, causes things to be drawn on the screen using subpixel positioning.

d e l a y
Type : float Default : 0.0 If this transform is being used as a transition, then this is the duration of the transition. These properties are applied in the following order: 1. 2. 3. 4. 5. crop, corner1, corner2 size zoom, xzoom, yzoom rotate position properties

Circular Motion When an interpolation statement contains the c l o c k w i s eor c o u n t e r c l o c k w i s ekeywords, the interpolation will cause circular motion. Ren'Py will compare the start and end locations and figure out the polar coordinate center. Ren'Py will then compute the number of degrees it will take to go from the start angle to the end angle, in the specified direction of rotation. If the circles clause is given, Ren'Py will ensure that the appropriate number of circles will be made. Ren'Py will then interpolate the angle and radius properties, as appropriate, to cause the circular motion to happen. If the transform is in align mode, setting the angle and radius will set the align property. Otherwise, the pos property will be set. External Events The following events can be triggered automatically:

s t a r t

A pseudo-event, triggered on entering an on statement, if no event of higher priority has happened.

s h o w

Triggered when the transform is shown using the show or scene statement, and no image with the given tag exists.
r e p l a c e

Triggered when transform is shown using the show statement, replacing an image with the given tag.
h i d e

Triggered when the transform is hidden using the hide statement or its python equivalent. Note that this isn't triggered when the transform is eliminated via the scene statement or exiting the context it exists in, such as when exiting the game menu.
r e p l a c e d

Triggered when the transform is replaced by another. The image will not actually hide until the ATL block finishes.
h o v e r ,i d l e ,s e l e c t e d _ h o v e r ,s e l e c t e d _ i d l e

Triggered when button containing this transform, or a button contained by this transform, enters the named state.

Customizing Ren'Py

Styles and Style Properties

Styles allow the look of displayables to be customized. This is done by changing the value of style properties for displayables. For example, changing the b a c k g r o u n dproperty allows the background of a window or button to be customized. Each displayable has a style built-into it. When the displayable is created, either directly or using the screen system, style properties can be supplied to it, and these styles are used to update the look of the displayable. In the following example:
i m a g eb i g _ h e l l o _ w o r d=T e x t ( " H e l l o ,W o r l d " ,s i z e = 4 0 )

the s i z eproperty is supplied to a Text displayable, allowing us to change its text size. This will customize the look of the text displayable by displaying the text 40 pixels high. Ren'Py also supports style inheritance. Each displayable takes a s t y l eproperty, that gives the name of the style to use. If a property is not defined for a style, Ren'Py will look it up in the named style, that style's parent, and so on. This allows us to customize a named style in a central place. A named style exists as a field on the global s t y l eobject. Style properties exist as fields on styles. So to set the size property of the default style, one can use a python block:
i n i tp y t h o n : s t y l e . d e f a u l t . f o n t=" m i k a c h a n . t t f " s t y l e . d e f a u l t . s i z e=2 3

As Ren'Py caches styles, named styles should not be changed outside of init blocks. Style Property Prefixes Applying a prefix to a style property indicates allows a displayable to change it's look in response to its focus or selection status. For example, a button can change its color when the mouse hovers above it, or to indicate when the choice represented by the button is the currently selected one. There are five states a displayable can be it. insensitive Used when the user cannot interact with the displayable. idle Used when the displayable is neither focused nor selected. hover Used when the displayable is focused, but not selected. selected_idle Used when the displayable is not focused, and is selected. selected_hover Used when the displayable is focused and selected. Button and Bar displayables (and their variants) update their state, and the state of their children, in response to events. For example, when the user puts his mouse over an unselected button, it and all its children will be put into the hover state. Style property prefixes allow one to set style properties for the different states. There is a system of implications set up, so that a prefix can imply setting the property for more than one state. The implications are: prefix (no prefix)
i n s e n s i t i v e _ i d l e _ s e l e c t e d _ s e l e c t e d _ i d l e _ s e l e c t e d _ h o v e r _

states implied by prefix insensitive, idle, hover, selected_idle, selected_hover insensitive idle, selected_idle selected_idle, selected_hover selected_idle selected_hover

Using a text button, we can show this in action. Text buttons use two styles by default: b u t t o n for the button itself, and b u t t o n _ t e x tfor the text inside the button. The b a c k g r o u n dstyle property sets the background of a button, while the c o l o rproperty sets the color of text.
i n i tp y t h o n : #T h eb u t t o nb a c k g r o u n di sg r a yw h e ni n s e n s i t i v e ,l i g h t #b l u ew h e nh o v e r e d ,a n dd a r kb l u eo t h e r w i s e . s t y l e . b u t t o n . b a c k g r o u n d=" # 0 0 6 " s t y l e . b u t t o n . i n s e n s i t i v e _ b a c k g r o u n d=" # 4 4 4 " s t y l e . b u t t o n . h o v e r _ b a c k g r o u n d=" # 0 0 a " #T h eb u t t o nt e x ti sy e l l o ww h e ns e l e c t e d ,a n dw h i t e #o t h e r w i s e . s t y l e . b u t t o n _ t e x t . c o l o r=" # f f f "

s t y l e . b u t t o n _ t e x t . s e l e c t e d _ c o l o r=" # f f 0 "

Style Property Values Each style property expects a specific kind of data. Many of these are standard python types, but a few are novel. Here are descriptions of the novel kinds of value a style property can expect.
p o s i t i o n

Positions are used to specify locations relative to the upper-left corner of the containing area. (For positions, the containing area is given by the layout the displayable is in, if one is given, or the screen otherwise. For anchors, the containing area is the size of the displayable itself.) The way a position value is interpreted depends on the type of the value: int (like 0, 1, 37, or 42) An integer is intepreted as the number of pixels from the left or top side of the containing area. float (like 0.0, 0.5, or 1.0) A floating-point number is intepreted as a fraction of the containing area. For example, 0.5 is a point halfway between the sides of the containing area, while 1.0 is on the right or bottom side. renpy.absolute (like renpy.absolute(100.25)) A renpy.absolute number is intepreted as the number of pixels from the left or top side of the screen, when using subpixel-precise rendering.
d i s p l a y a b l e

Any displayable.
c o l o r

Colors in Ren'Py can be expressed as strings beginning with the hash mark (#), followed by a hex triple or hex quadruple, with each of the three or four elements consisting of a one or two hexidecimal character color code. In a triple, the components represent red, green, and blue. In a quadruple, the components represent red, green, blue, and alpha. For example:
" # f 0 0 "and " # f f 0 0 0 0 "represent an opaque red color. " # 0 f 0 8 "and # 0 0 f f 0 0 8 0 "represent a semi-transparent green color.

The color triples are the same as used in HTML. Colors can also be represented as a 4-component tuple, with the 4 components being integers between 0 and 255. The components correspond to red, green, blue, and alpha, in that order.
( 0 ,0 ,2 5 5 ,2 5 5 )represents an opaque blue color.

List of All Style Properties The style properties control the look of the various displayables. Not all style properties apply to all displayables, so we've divided them up into groups.
Position Style Properties

These are used to control the position of a displayable inside the area allocated to it by a layout, or on the screen when not inside a layout.

x p o s- position
The position of the displayable relative to the left side of the containing area.

y p o s- position
The position of the displayable relative to the right side of the containing area.

p o s- tuple of (position, position)

Equivalent to setting xpos to the first component of the tuple, and ypos to the second component of the tuple.

x a n c h o r- position
The position of the anchor relative to the left side of the displayable.

y a n c h o r- position
The position of the anchor relative to the top side of the displayable.

a n c h o r- tuple of (position, position)

Equivalent to setting xanchor to the first component of the tuple, and yanchor to the second component of the tuple.

x a l i g n- float
Equivalent to setting xpos and xanchor to the same value. This has the effect of placing the displayable at a relative location on the screen, with 0.0 being the left side, 0.5 the center, and 1.0 being the right side.

y a l i g n- float
Equivalent to setting ypos and yanchor to the same value. This has the effect of placing the displayable at a relative location on the screen, with 0.0 being the top, 0.5 the center, and 1.0 the bottom.

a l i g n- tuple of (float, float)

Equivalent to setting xalign to the first component of the tuple, and yalign to the second.

x c e n t e r- position
Equivalent to setting xpos to the value of this property, and xanchor to 0.5.

y c e n t e r- position
Equivalent to setting ypos to the value of tihis property, and yanchor to 0.5.

x o f f s e t- int
Gives a number of pixels that are added to the horizontal position computed using xpos and xalign.

y o f f s e t- int
Gives a number of pixels that are added to the vertical position computed using ypos and yalign.

x m a x i m u m- int
Specifies the maximum horizontal size of the displayable, in pixels.

y m a x i m u m- int
Specifies the maximum vertical size of the displayable in pixels.

m a x i m u m- tuple of (int, int)

Equivalent to setting xmaximum to the first component of the tuple, and ymaximum to the second.

x m i n i m u m- int
Sets the minimum width of the displayable, in pixels. Only works with displayables that can vary their size.

y m i n i m u m- int
Sets the minimum height of the displayables, in pixels. Only works with displayables that can vary their size.

m i n i m u m- tuple of (int, int)

Equivalent to setting xminimum to the first component of the tuple, and yminimum to the second.

x f i l l- boolean
If true, the displayable will expand to fill all available horizontal space. If not true, it will only be large enough to contain its children. This only works for displayables that can change size.

y f i l l- boolean
If true, the displayable will expand to fill all available horizontal space. If not true, it will only be large enough to contain its children. This only works for displayables that can change size.

a r e a- tuple of (int, int, int, int)

The tuple is interpreted as (x p o s ,y p o s ,w i d t h ,h e i g h t ). Attempts to position the displayable such that it's upper-left corner is at x p o sand y p o s , and its size is w i d t hand h e i g h t . It does this by setting the xpos, ypos, xanchor, yanchor, xmaximum, ymaximum, xminimum, yminimum, xfill, and yfill properties to appropriate values. This will not work with all displayables and all layouts.
Text Style Properties

a n t i a l i a s- boolean
If True, the default, truetype font text will be rendered anti-aliased.

b l a c k _ c o l o r- color
When rendering an image-based font, black will be mapped to this color. This has no effect for truetype fonts.

b o l d- boolean
If True, render the font in a bold style. For a truetype font, this usually involves synthetically increasing the font weight. It can also cause the font to be remapped, using c o n f i g . f o n t _ r e p l a c e m e n t _ m a p .

c a r e t- displayable or None
If not None, this should be a displayable. The input widget will use this as the caret at the end of the text. If None, a 1 pixel wide line is used as the caret.

c o l o r- color

The color the text is rendered in. When using a truetype font, the font is rendered in this color. When using an image-based font, white is mapped to this color.

f i r s t _ i n d e n t- int
The amount that the first line of text in a paragraph is indented by, in pixels.

f o n t- string
A string giving the name of the font used to render text. For a truetype font file, this is usually the name of the file containing the font (like " D e j a V u S a n s . t t f " ). To select a second font in a collection, this can be prefixed with a number and at sign (like " 0 @ f o n t . t t c "or " 1 @ f o n t . t t c " ). For an image-based font, this should be the name used to register the font.

s i z e- int
The size of the font on the screen. While this is nominally in pixels, font files may have creative interpretations of this value.

i t a l i c- boolean
If true, the text will be rendered in italics. For a truetype font, this usually involves synthetically increasing the font slant. It can also cause the font to be remapped, using c o n f i g . f o n t _ r e p l a c e m e n t _ m a p .

j u s t i f y- boolean
If true, additional whitespace is inserted between words so that the left and right margins of each line are even. This is not performed on the last line of a paragraph.

k e r n i n g- float
A kerning adjustment, the number of pixels of space that's added between each pair of characters. (This can be negative to remove space between characters.)

l a n g u a g e- string
Controls the language family used to break text into lines. Legal values are:
" u n i c o d e "(default)

Uses the unicode linebreaking algorithm, which is suitable for most languages.
" k o r e a n w i t h s p a c e s "

Used for Korean text delimited by whitespace. This prevents linebreaking between adjacent Korean characters.
" w e s t e r n

Allows breaking only at whitespace. Suitable for most languages.

" e a s t a s i a n "

Legacy alias for "unicode".

l a y o u t- string
Controls how words are allocated to lines. Legal values are:
" t e x "(default)

Uses the Knuth-Plass linebreaking algorithm, which attempts to minimize the difference in line lengths of all but the last line.
" s u b t i t l e "

Uses the Knuth-Plass linebreaking algorithm, but attempts to even out the lengths of all lines.

" g r e e d y "

A word is placed on the first line that has room for it.
" n o w r a p "

Do not line-break.

l i n e _ l e a d i n g- int
The number of pixels of spacing to include above each line.

l i n e _ o v e r l a p _ s p l i t- int
When in slow text mode, and two lines overlap, this many pixels of the overlap are allocated to the top line. Increase this if the bottoms of characters on the top line are clipped.

l i n e _ s p a c i n g- int
The number of pixels of spacing to include below each line.

m i n _ w i d t h- int
Sets the minimum width of each line of that. If a line is shorter than this, it is padded to this length, with text_align used to specify where such padding is placed.

n e w l i n e _ i n d e n t- boolean
If true, the f i r s t _ i n d e n tindentation is used after each newline in a string. Otherwise, the r e s t _ i n d e n tindentation is used.

o u t l i n e s- list of tuple of (int, color, int, int)

This is a list of outlines that are drawn behind the text. Each tuple specifies an outline, and outlines are drawn from back to front. The list contains (s i z e ,c o l o r ,x o f f s e t ,y o f f s e t ) tuples. S i z eis the amount the font is expanded by, in pixels. C o l o ris the color of the outline. x o f f s e tand y o f f s e tare the amount the outline is shifted by, in pixels. The outline functionality can also be used to give drop-shadows to fonts, by specifiying a size of 0 and non-zero offsets. Outlines only work with truetype fonts.

r e s t _ i n d e n t- int
Specifies the number of pixels the second and later lines in a paragraph are indented by.

r u b y _ s t y l e- style or None
If not None, this should be a style object. The style that's used for ruby text.

s l o w _ c p s- int or True
If a number, shows text at the rate of that many characters per second. If True, shows text at the speed taken from the "Text Speed" preference.

s l o w _ c p s _ m u l t i p l i e r- float
The speed of the text is multiplied by this number. This can be used to have a character that speeks at a faster-than-normal rate of speed.

s t r i k e t h r o u g h- boolean
If True, a line is drawn through the text.

t e x t _ a l i g n- float

This is used when a line is shorter than the width of the text displayable. It determines how much of the extra space is placed on the left side of the text. (And hence, the text alignment.) 0.0 will yield left-aligned text, 0.5 centered text, and 1.0 right-aligned text.

u n d e r l i n e- boolean
If true, an underline will be added to the text.

h y p e r l i n k _ f u n c t i o n s- tuple of (function, function, function)

This is a tuple of three functions relating to hyperlinks in text. The first item is the hyperlink style function. When called with a single argument, the argument of the hyperlink, it must return a style object to use for the hyperlink, such as s t y l e . h y p e r l i n k _ t e x t . Note that a style object is not a string. The second item is the hyperlink clicked function. This function is called when a hyperlink is chosen by the user. If it returns a value other than None, the interaction returns that value. The third item is the hyperlink focus function. This function is called with the argument of the hyperlink when the hyperlink gains focus, and with None when it loses focus. If it returns a value other than None, the interaction returns that value
Window Style Properties

Window properties are used to specify the look of windows, frames, and buttons.

b a c k g r o u n d- displayable or None
A displayable that is used as the background of the window. This is often a F r a m e ( ) , allowing the size of the background to scale with the size of the window. If None, no background is drawn, but other properties function as if the background was present.

f o r e g r o u n d- displayable or None
If not None, this displayable is drawn above the contents of the window.

l e f t _ m a r g i n- int
The amount of transparent space to the left of the background, in pixels.

r i g h t _ m a r g i n- int
The amount of transparent space to the right of the background, in pixels.

x m a r g i n- int
Equivalent to setting left_margin and right_margin to the same value.

t o p _ m a r g i n- int
The amount of transparent space above the background, in pixels.

b o t t o m _ m a r g i n- int
The amount of transparent space below the background, in pixels.

y m a r g i n- int
Equivalent to setting top_margin and bottom_margin to the same value.

l e f t _ p a d d i n g- int

The amount of space between the background and the left side of the window content, in pixels.

r i g h t _ p a d d i n g- int
The amount of space between the background and the right side of the window content, in pixels.

x p a d d i n g- int
Equivalent to setting left_padding and right_padding to the same value.

t o p _ p a d d i n g- int
The amount of space between the background and the top side of the window content, in pixels.

b o t t o m _ p a d d i n g- int
The amount of space between the background and the bottom side of the window content, in pixels.

y p a d d i n g- int
Equivalent to setting top_padding and bottom_padding to the same value.

s i z e _ g r o u p- string or None
If not None, this should be a string. Ren'Py will render all windows with the same size_group value at the same size.
Button Style Properties

h o v e r _ s o u n d- string
A sound that is played when the button gains focus.

a c t i v a t e _ s o u n d- string
A sound that is played when the button is clicked.

m o u s e- string
The mouse style that is used when the button is focused. This should be one of the styles in c o n f i g . m o u s e .

f o c u s _ m a s k- displayable or True or None

A mask that's used to control what portions of the button can be focused, and hence clicked on. If it's a displayable, then areas of the displayable that are not transparent can be focused. If it's True, then the button itself is used as the displayable (so non-transparent areas of the button can be focused.) Otherwise, the entire button can be focused.
Bar Style Properties

Bars are drawn with gutters on the left and right, that when clicked can cause the bart to move by a small amount. The remaining space is the portion of the bar that can change, with the amount on each side proportional to the bar's value as a fraction of the range. The thumb is an area in the center of the bar that can be dragged by the user. When a bar is drawn, the thumb's shadow is drawn first. Then the left/bottom and right/top sides of the bar, followed by the thumb itself. Note that the valid sides of a bar depend on the value of the bar_vertical property. If it's True, the top and bottom sides are relevant. Otherwise, the left and right sides are used.

the top and bottom sides are relevant. Otherwise, the left and right sides are used.

b a r _ v e r t i c a l- boolean
If true, the bar has a vertical orientation. If false, it has a horizontal orientation.

b a r _ i n v e r t- boolean
If true, the value of the bar is represented on the right/top side of the bar, rather than the left/bottom side.

b a r _ r e s i z i n g- boolean
If true, we resize the sides of the bar. If false, we render the sides of the bar at full size, and then crop them.

l e f t _ g u t t e r- int
The size of the gutter on the left side of the bar, in pixels.

r i g h t _ g u t t e r- int
The size of the gutter on the right side of the bar, in pixels.

t o p _ g u t t e r- int
The size of the gutter on the top side of the bar, in pixels.

b o t t o m _ g u t t e r- int
The size of the gutter on the bottom side of the bar, in pixels.

l e f t _ b a r- displayable
The displayable used for the left side of the bar.

r i g h t _ b a r- displayable
The displayable used for the right side of the bar.

t o p _ b a r- displayable
The displayable used for the top side of the bar.

b o t t o m _ b a r- displayable
The displayable uses for the bottom side of the bar.

t h u m b- displayable or None
If not None, this is a displayable that is drawn over the break between the sides of the bar.

t h u m b _ s h a d o w- displayable or None
If not None, this is a displayable that is drawn over the break between the sides of the bar.

t h u m b _ o f f s e t- int
The amount that by which the thumb overlaps the bars, in pixels. To have the left and right bars continue unbroken, set this to half the width of the thumb in pixels.

m o u s e- string
The mouse style that is used when the button is focused. This should be one of the styles in c o n f i g . m o u s e .

u n s c r o l l a b l e- string or None
Controls what happens if the bar is unscrollable (if the range is set to 0, as is the case with

a viewport containing a displayable smaller than itself). There are three possible values:
N o n e

Renders the bar normally.

" i n s e n s i t i v e "

Renders the bar in the insensitive state. This allows the bat to change its style to reflect its lack of usefulness.
" h i d e "

Prevents the bar from rendering at all. Space will be allocated for the bar, but nothing will be drawn in that space.
Box Style Properties

These are used for the horizontal and vertical box layouts.

s p a c i n g- int
The spacing between members of this box, in pixels.

f i r s t _ s p a c i n g- int
If not None, the spacing between the first and second members of this box, in pixels. This overrides the spacing property.

b o x _ w r a p- boolean
If true, then boxes will wrap when they reach the end of a line or column. If false (the default), they will extend past the end of the line.
Fixed Style Properties

These are used with the fixed layout.

f i t _ f i r s t- bool
If true, then the size of the fixed layout is shrunk to be equal with the size of the first item in the layout. Creating New Named Styles Named styles exists as fields on the global s t y l eobject. To create a new style, create an instance of the Style class, and assign it to a field on the s t y l eobject.
i n i tp y t h o n : s t y l e . b i g _ t e x t=S t y l e ( s t y l e . d e f a u l t ) s t y l e . b i g _ t e x t . s i z e=4 2

Once created, a named style can be applied to displayables by supplying it's name, or the style object.
s c r e e nt w o _ b i g _ l i n e s : v b o x : t e x t" T h i si sB i gT e x t ! "s t y l e" b i g _ t e x t " t e x t" S oi st h i s . "s t y l es t y l e . b i g _ t e x t

class S t y l e (parent) Creates a new style object. Style properties can be assigned to the fields of this object.

p a r e n t

The styles parent. This can be another style object, or a string.

c l e a r ()
This removes all style properties from this object. Values will be inherited from this object's parent.

s e t _ p a r e n t (parent)
Sets the parent of this style object to p a r e n t .

t a k e (other)
This takes all style properties from o t h e r .o t h e rmust be a style object.
Indexed Styles

Indexed styles are lightweight styles that can be used to customize the look of a displayable based on the data supplied to that displayable. An index style is created by indexing a style object with a string or integer. If an indexed style does not exist, indexing creates it.
i n i tp y t h o n : s t y l e . b u t t o n [ ' F o o ' ] . b a c k g r o u n d=" # f 0 0 " s t y l e . b u t t o n [ ' B a r ' ] . b a c k g r o u n d=" # 0 0 f "

An index style is used by supplying the indexed style to a displayable.

s c r e e ni n d e x e d _ s t y l e _ t e s t : v b o x : t e x t b u t t o n" F o o "s t y l es t y l e . b u t t o n [ " F o o " ] t e x t b u t t o n" B a r "s t y l es t y l e . b u t t o n [ " B a r " ]
Style Inheritance

When a property is not defined by a style, it is inherited from the style's parent. When indexing is involved, properties are inherited first from the unindexed form of the style, then from the indexed form of the parent, then the unindexed form of the parent, and so on. For example, when s t y l e . m m _ b u t t o ni n h e r i t sfrom s t y l e . b u t t o n , which in turn inherits from s t y l e . d e f a u l t , then the properties of s t y l e . m m _ b u t t o n [ " S t a r tG a m e " ]are taken from: 1. 2. 3. 4. 5. 6.
s t y l e . m m _ b u t t o n [ " S t a r tG a m e " ] s t y l e . m m _ b u t t o n s t y l e . b u t t o n [ " S t a r tG a m e " ] s t y l e . b u t t o n s t y l e . d e f a u l t [ " S t a r tG a m e " ] s t y l e . d e f a u l t

With the property value taken from the lowest numbered style with the property defined.
Style Preferences

It's often desireable to allow the user to customize aspects of the user interface that are best expressed as styles. For example, a creator may want to give players of his game the ability to adjust the look, color, and size of the text. Style preferences allow for this customization. A style preference is a preference that controls one or more style properties. A style preference has a name and one or more alternatives. At any given time, one of the alternatives is the selected alternative for the style preference. The selected alternative is

alternatives is the selected alternative for the style preference. The selected alternative is saved in the persistent data, and defaults to the first alternative registered for a style property. An alternative has one or more associations of style, property, and value associated with it, and represents a promise that when the alternative becomes the selected alternative for the style preference, the property on the style will be assigned the given value. This occurs when Ren'Py first initializes, and then whenever a new alternative is selected. One should ensure that every alternative for a given style preference updates the same set of styles and properties. Otherwise, some styles may not be assigned values, and the result will not be deterministic. The style preference functions are:

S t y l e P r e f e r e n c e (preference, alternative)
An action that causes a l t e r n a t i v eto become the selected alternative for the given style preference.
p r e f e r e n c e

A string giving the name of the style preference.

a l t e r n a t i v e

A string giving the name of the alternative.

r e n p y . g e t _ s t y l e _ p r e f e r e n c e (preference)

Returns a string giving the name of the selected alternative for the named style preference.
p r e f e r e n c e

A string giving the name of the style preference.

r e n p y . r e g i s t e r _ s t y l e _ p r e f e r e n c e (preference, alternative, style, property, value)

Registers information about an alternative for a style preference.

p r e f e r e n c e

A string, the name of the style property.

a l t e r n a t i v e

A string, the name of the alternative.

s t y l e

The style that will be updated. This may be a style object or a string giving the style name.
p r o p e r t y

A string giving the name of the style property that will be update.
v a l u e

The value that will be assigned to the style property.

r e n p y . s e t _ s t y l e _ p r e f e r e n c e (preference, alternative)

Sets the selected alternative for the style preference.

p r e f e r e n c e

A string giving the name of the style preference.

a l t e r n a t i v e

A string giving the name of the alternative. Here's an example of registering a style property that allows the user to choose between large, simple text and smaller outlined text.
i n i tp y t h o n : r e n p y . r e g i s t e r _ s t y l e _ p r o p e r t y ( " t e x t " ," d e c o r a t e d " ,s t y l e . s a y _ d i a l o g u e ," o u t l i n e s " , r e n p y . r e g i s t e r _ s t y l e _ p r o p e r t y ( " t e x t " ," d e c o r a t e d " ,s t y l e . s a y _ d i a l o g u e ," s i z e " ,2 2 ) r e n p y . r e g i s t e r _ s t y l e _ p r o p e r t y ( " t e x t " ," l a r g e " ,s t y l e . s a y _ d i a l o g u e ," o u t l i n e s " ,[] ) r e n p y . r e g i s t e r _ s t y l e _ p r o p e r t y ( " t e x t " ," l a r g e " ,s t y l e . s a y _ d i a l o g u e ," s i z e " ,2 4 )

The following code will allow the user to select these alternatives using buttons:
t e x t b u t t o n" D e c o r a t e d "a c t i o nS t y l e P r e f e r e n c e ( " t e x t " ," d e c o r a t e d " ) t e x t b u t t o n" L a r g e "a c t i o nS t y l e P r e f e r e n c e ( " t e x t " ," l a r g e " )
Other Style Functions

s t y l e . r e b u i l d ()

This causes named styles to be rebuilt, allowing styles to be changed outside of init code.
Warning Named styles are not saved as part of the per-game data. This means that changes to them will not be persisted through a save and load cycle.

Screens and Screen Language

The things that a user sees when looking at a Ren'Py game can be broken divided into images and user interface. Images are displayed to the user using the scene, show, and hide statements, and are generally part of the story being told. Everything else the user sees is part of the user interface, which is customized using screens. Screens can be displayed in four ways: Implicitly, when script statements execute. For example, the say statement will cause the s a yscreen to be displayed. Automatically. For example, Ren'Py will display the m a i n _ m e n uscreen when it starts running, or when the user returns to the main menu. As an action, associated with a button, mouse button, or keyboard key. By default, the s a v escreen is shown when the user right-clicks or presses escape. It's also possible to define an on-screen button that shows the s a v escreen. Explicitly, using statements that cause screens to be shown. More than one screen can be shown at a time. Screens have two main functions. The first is to display information to the user. Information can be displayed using text, bars, and images. Some of the information displayed in this manner is vital to gameplay. The s a yscreen, for example, is used to display dialogue to the user, including the character's name and what she is saying. The other thing a screen can do is to allow the user to interact with the game. Buttons and bars

allow the user to invoke actions and adjust values. Ren'Py includes a pool of pre-defined actions, allowing the user to advance the game, control preferences, load and save games, and invoke many other actions. A game-maker can also write new actions in Python. Screens are updated at the start of each interaction, and each time an interaction is restarted. Screen code must not cause side effects that are visible from outside the screen. Ren'Py will run screen code multiple times, as it deems necessary. It runs screen code as part of the image prediction process, before the screen is first shown. As a result, if screen code has side effects, those side effects may occur at unpredictable times. A screen has a scope associated with it, giving values to some variables. When a variable is accessed by a screen, it's first looked up in the scope, and then looked up as a global variable. Screen Language The screen language is a mostly-declarative way of displaying screens. It consists of a statement that declares a new screen, statements that add displayables to that screen, and control statements. Here's an example of a screen.:
s c r e e ns a y : w i n d o wi d" w i n d o w " : v b o x : s p a c i n g1 0 t e x tw h oi d" w h o " t e x tw h a ti d" w h a t "

The first line of this is a screen statement, a Ren'Py language statement that's used to declare a screen. The name of the screen is s a y , so this is the screen that's used to display dialogue. The screen contains a window, which has been given the id of "window". This window contains a vertical box, and the spacing inside that box is 10 pixels. It contains two text fields, one of the name of the speaker, and the other with the speaker's id.
Screen Language Syntax

Most screen language statements share a common syntax. (Some of the control statements have other syntaxes.) A statement starts at the beginning of a line, with a keyword that introduces the statement. If a statement takes parameters, they immediately follow the keyword. The parameters are space-separated simple expressions, unless otherwise noted. The positional parameters are followed by a property list. A property consists of the property name, followed by the value of that property. Property values are simple expressions, unless otherwise noted. A property list is a space-separated list of these properties. If a statement ends with a colon (:), then it takes a block. Each line in a block may be one of two things: A property list. A screen language statement.
Screen Statement

The s c r e e nstatement is a Ren'Py script language statement that is used to declare a new screen. It is parsed using the screen language common syntax.

It takes one parameter, the name of the screen. This is a name, not an expression. It takes the following properties:
m o d a l

If True, the screen is modal. A modal screen prevents the user from interacting with displayables below it, except for the default keymap.
t a g

Parsed as a name, not an expression. This specifies a tag associated with this screen. Showing a screen replaces other screens with the same tag. This can be used to ensure that only one screen of a menu is shown at a time, in the same context.
z o r d e r

This controls how close to the user a screen is displayed. The larger the number, the closer the screen is displayed to the user. It defaults to 0.
v a r i a n t

If present, this should be a string giving the variant of screen to be defined. See Screen Variants.
s c r e e nh e l l o _ w o r l d : t a ge x a m p l e z o r d e r1 m o d a lF a l s e t e x t" H e l l o ,W o r l d . "

User Interface Statements The user interface statements create displayables and add them either to the screen, or to an enclosing displayable. They allow the user to display information, allow the user to interact with the game, or allow the game to react to various events. All user interface statements take the following common properties:
a t

A transform, or list of transforms, that are used to wrap this displayable. The show, hide, replace, and replaced external events are delivered to a transform if and only if it is added directly to the screen. For example, if a vbox is wrapped in a transform, and added directly to the screen, then events are delivered to that transform. But if a transform wraps a textbutton that is added to the vbox, this second transform is not given events.
d e f a u l t

If given and true, the displayable is focused by default. Only one displayable should have this.
i d

An identifier for the user-interface statement. When a screen is shown, property values can be supplied for the displayables with a given identifier. Some screens will require that a displayable with a given identifier is created. By default, the id is automatically-generated.
s t y l e

The name of the style applied to this displayable. This may be a string name, or a style object. The style gives default values for style properties.
s t y l e _ g r o u p

Style_group is used to provide a prefix to the style of a displayable, for this displayable and

all of its children (unless they have a more specific group set). For example, if a vbox has a group of " p r e f " , then the vbox will have the style " p r e f _ v b o x " , unless a more specific style is supplied to it. A button inside that vbox would default to the style " p r e f _ b u t t o n " . Styles accessed in this way are automatically created, if they do not exist. This prevents an error from being signalled. Setting a group of N o n edisables this behavior for a displayable and all of its children.
f o c u s

Takes a string or integer, and gives a name to the displayable for focus purposes. Ren'Py looks for structural similarity between focus names when deciding with displayable to give focus to at the start of an interaction. If a box is given a focus name, and the third button in that box is focused at the end of an interaction, the third button of a box with the same will be highlighted at the start of the next interaction. Many user interface statements take classes of style properties, or transform properties. These properties can have a style prefix associated with them, that determines when they apply. For example, if text is given the hover_size property, it sets the text size when the text is hovered.
Add

Adds an image or other displayable to the screen. This optionally takes transform properties. If at least one transform property is given, a Transform is created to wrap the image, and the properties are given to the transform. This does not take any children.
s c r e e na d d _ t e s t : a d d" l o g o . p n g "x a l i g n1 . 0y a l i g n0 . 0
Bar

Creates a horizontally-oriented bar that can be used to view or adjust data. It takes the following properties:
v a l u e

The current value of the bar. This can be either a BarValue object, or a number.
r a n g e

The maximum value of the bar. This is required if v a l u eis a number.

a d j u s t m e n t Au i . a d j u s t m e n t ( )object that this bar adjusts. c h a n g e d

If given, this should be a python function. The function is called with the value of the adjustment when the adjustment is changed.
h o v e r e d

An action to run when the bar gains focus.

u n h o v e r e d

An action to run when the bar loses focus. One of v a l u eor a d j u s t m e n tmust be given. In addition, this function takes: Common Properties Position Style Properties

Bar Style Properties This does not take children.

s c r e e nv o l u m e _ c o n t r o l s : f r a m e : h a sv b o x b a rv a l u eP r e f e r e n c e ( " s o u n dv o l u m e " ) b a rv a l u eP r e f e r e n c e ( " m u s i cv o l u m e " ) b a rv a l u eP r e f e r e n c e ( " v o i c ev o l u m e " )
Button

Creates an area of the screen that can be activated to run an action. A button takes no parameters, and the following properties.
a c t i o n

The action to run when the button is activated. This also controls if the button is sensitive, and if the button is selected.
h o v e r e d

An action to run when the button gains focus.

u n h o v e r e d

An action to run when the button loses focus. It also takes: Common Properties Position Style Properties Window Style Properties Button Style Properties It takes one children. If zero, two, or more children are supplied, they are implicitly added to a fixed, which is added to the button.
Fixed

This creates an area to which children can be added. By default, the fixed expands to fill the available area, but the x m a x i m u mand y m a x i m u mproperties can change this. The children are laid out according to their position style properties. They can overlap if not positioned properly. The fixed statement takes no parameters, and the following groups of properties: Common Properties Position Style Properties Fixed Style Properties This takes any number of children, which are added to the fixed. It's often unnecessary to explicitly create a fixed displayable. Each screen is contained within a fixed displayable, and many screen language statements automatically create a fixed displayable if they have two or more children.
s c r e e na s k _ a r e _ y o u _ s u r e : f i x e d : t e x t" A r ey o us u r e ? "x a l i g n0 . 5y a l i g n0 . 3

t e x t b u t t o n" Y e s "x a l i g n0 . 3 3y a l i g n0 . 5a c t i o nR e t u r n ( T r u e ) t e x t b u t t o n" N o "x a l i g n0 . 6 6y a l i g n0 . 5a c t i o nR e t u r n ( F a l s e )

Frame

A frame is a window that contains a background that is intended for displaying user-interface elements like buttons, bars, and text. It takes the following groups of properties: Common Properties Position Style Properties Window Style Properties It takes one child. If zero, two, or more children are supplied, then a fixed is created to contain them.
s c r e e nt e s t _ f r a m e : f r a m e : x p a d d i n g1 0 y p a d d i n g1 0 x a l i g n0 . 5 y a l i g n0 . 5 v b o x : t e x t" D i s p l a y " n u l lh e i g h t1 0 t e x t b u t t o n" F u l l s c r e e n "a c t i o nP r e f e r e n c e ( " d i s p l a y " ," f u l l s c r e e n " ) t e x t b u t t o n" W i n d o w "a c t i o nP r e f e r e n c e ( " d i s p l a y " ," w i n d o w " )
Grid

This displays its children in a grid. Each child is given an area of the same size, the size of the largest child. It takes two parameters. The first is the number of columns in the grid, and the second is the number of rows in the grid. It takes the following property:
t r a n s p o s e

If False (the default), rows are filled before columns. If True, then columns are filled before rows.
s p a c i n g

The spacing between the rows and columns of the grid. It also takes: Common Properties Position Style Properties This must be given columns * rows children. Giving it a different number of children is an error.
s c r e e ng r i d _ t e s t : g r i d23 : t e x t" T o p L e f t " t e x t" T o p R i g h t " t e x t" C e n t e r L e f t " t e x t" C e n t e r R i g h t " t e x t" B o t t o m L e f t "

t e x t" B o t t o m R i g h t "
Hbox

This displays its children side by side, in an invisible horizontal box. It takes no parameters, and the following groups of properties: Common Properties Position Style Properties Box Style Properties UI displayable children are added to the box.
s c r e e nh b o x _ t e x t : h b o x : t e x t" L e f t " t e x t" R i g h t "
Imagebutton

Creates a button consisting of images, that change state when the user hovers over them. This takes no parameters, and the following properties:
a u t o

Used to automatically define the images used by this button. This should be a string that contains %s in it. If it is, and one of the image properties is omitted, %s is replaced with the name of that property, and the value is used as the default for that property. For example, if a u t ois "button_%s.png", and i d l eis omitted, then idle defaults to "button_idle.png". The behavior of a u t ocan be customized by changing c o n f i g . i m a g e m a p _ a u t o _ f u n c t i o n .
i n s e n s i t i v e

The image used when the button is insensitive.

i d l e

The image used when the button is not focused.

h o v e r

The image used when the button is focused.

s e l e c t e d _ i d l e

The image used when the button is selected and idle.

s e l e c t e d _ h o v e r

The image used when the button is selected and hovered.

a c t i o n

The action to run when the button is activated. This also controls if the button is sensitive, and if the button is selected.
h o v e r e d

An action to run when the button gains focus.

u n h o v e r e d

An action to run when the button loses focus. It also takes:

Common Properties Position Style Properties Window Style Properties Button Style Properties This takes no children.
s c r e e ng u i _ g a m e _ m e n u : v b o xx a l i g n1 . 0y a l i g n1 . 0 : i m a g e b u t t o na u t o" s a v e _ % s . p n g "a c t i o nS h o w M e n u ( ' s a v e ' ) i m a g e b u t t o na u t o" p r e f s _ % s . p n g "a c t i o nS h o w M e n u ( ' p r e f e r e n c e s ' ) i m a g e b u t t o na u t o" s k i p _ % s . p n g "a c t i o nS k i p ( ) i m a g e b u t t o na u t o" a f m _ % s . p n g "a c t i o nP r e f e r e n c e ( " a u t o f o r w a r dm o d e " ," t o g g l e "

Input

Creates a text input area, which allows the user to enter text. When the user presses return, the text will be returned by the interaction. This takes no parameters, and the following properties:
d e f a u l t

The default text in this input.

l e n g t h

The maximum length of the text in this input.

a l l o w

A string containing characters that are allowed to be typed into this input. (By default, allow all characters.)
e x c l u d e

A string containing characters that are disallowed from being typed into this input. (By default, "{}".)
p r e f i x

An immutable string to prepend to what the user has typed.

s u f f i x

An immutable string to append to what the user has typed.

c h a n g e d

A python function that is called with what the user has typed, when the string changes. It also takes: Common Properties Position Style Properties Text Style Properties This does not take any children.
s c r e e ni n p u t _ s c r e e n : w i n d o w : h a sv b o x t e x t" E n t e ry o u rn a m e . " i n p u td e f a u l t" J o s e p hP .B l o w ,E S Q . "

Key

This creates a keybinding that runs an action when a key is pressed. Key is used in a loose sense here, as it also allows joystick and mouse events. Key takes one positional parameter, a string giving the key to bind. See the `Keymap`_ section for a description of available keysyms. It takes one property:
a c t i o n

This gives an action that is run when the key is pressed. This property is mandatory. It takes no children.
s c r e e nk e y m a p _ s c r e e n : k e y" g a m e _ m e n u "a c t i o nS h o w M e n u ( ' s a v e ' ) k e y" p "a c t i o nS h o w M e n u ( ' p r e f e r e n c e s ' ) k e y" s "a c t i o nS c r e e n s h o t ( )
Label

Creates a window in the label style, and then places text inside that window. Together, this combination is used to label things inside a frame. It takes one positional argument, the text of the label. It takes the property:
t e x t _ s t y l e

The name of the style to use for the button text. If not supplied, and the s t y l eproperty is a string, then " _ t e x t "is appended to that string to give the default text style.
t e x t _ -

Other properties prefixed with text have this prefix stripped, and are then passed to the text displayable. It also takes: Common Properties Position Style Properties Window Style Properties It does not take children.
s c r e e nd i s p l a y _ p r e f e r e n c e : f r a m e : h a sv b o x l a b e l" D i s p l a y " t e x t b u t t o n" F u l l s c r e e n "a c t i o nP r e f e r e n c e ( " d i s p l a y " ," f u l l s c r e e n " ) t e x t b u t t o n" W i n d o w "a c t i o nP r e f e r e n c e ( " d i s p l a y " ," w i n d o w " )
Null

The null statement inserts an empty area on the screen. This can be used to space things out. The null statement takes no parameters, and the following properties:
w i d t h

The width of the empty area, in pixels.

h e i g h t

The height of the empty area, in pixels. It also takes: Common Properties Position Style Properties It does not take children.
s c r e e nt e x t _ b o x : v b o x : t e x t" T h et i t l e . " n u l lh e i g h t2 0 t e x t" T h i sb o d yt e x t . "
Mousearea

A mouse area is an area of the screen that can react to the mouse entering or leaving it. Unlike a button, a mouse area does not take focus, so it's possible to have a mouse area with buttons inside it. The mousearea statement takes not parameters, and the following properties:
h o v e r e d

An action to run when the mouse enters the mouse area.

u n h o v e r e d

An action to run when the mouse leaves the mouse area. It also takes: Common Properties Position Style Properties It does not take children. Usually, a mousearea statement is given the a r e astyle property, which controls the size and position of the mouse area. Without some way of controlling its size, the mouse area would take up the entire screen, a less useful behavior.
Note Since Ren'Py games can be played using the keyboard and joystick, it often makes sense to duplicate mousearea functionality by some other means.

s c r e e nb u t t o n _ o v e r l a y : m o u s e a r e a : a r e a( 0 ,0 ,1 . 0 ,1 0 0 ) h o v e r e dS h o w ( " b u t t o n s " ,t r a n s i t i o n = d i s s o l v e ) u n h o v e r e dH i d e ( " b u t t o n s " ,t r a n s i t i o n = d i s s o l v e ) s c r e e nb u t t o n s : h b o x : t e x t b u t t o n" S a v e "a c t i o nS h o w M e n u ( " s a v e " ) t e x t b u t t o n" P r e f s "a c t i o nS h o w M e n u ( " p r e f e r e n c e s " ) t e x t b u t t o n" S k i p "a c t i o nS k i p ( ) t e x t b u t t o n" A u t o "a c t i o nP r e f e r e n c e ( " a u t o f o r w a r d " ," t o g g l e " ) l a b e ls t a r t : s h o ws c r e e nb u t t o n _ o v e r l a y

Side

This positions displayables in the corners or center of a grid. It takes a single parameter, string containing a space-separated list of places to place its children. Each component of this list should be one of: 'c', 't', 'b', 'l', 'r', 'tl', 'tr', 'bl', 'br' 'c' means center, 't' top, 'tl' top left, 'br' bottom right, and so on. A side taks the following properties:
s p a c i n g

The spacing between the rows and columns of the grid. A side takes the following property groups: Common Properties Position Style Properties When being rendered, this first sizes the corners, then the sides, then the center. The corners and sides are rendered with an available area of 0, so it may be necessary to supply them a minimum size (using x m i n i m u mor y m i n i m u m ) to ensure they render at all. Children correspond to entries in the places list, so this must have the same number of children as there are entries in the places list.
s c r e e ns i d e _ t e s t : s i d e" ct lb r " : t e x t" C e n t e r " t e x t" T o p L e f t " t e x t" B o t t o m R i g h t "
Text

The text statement displays text. It takes a single parameter, the text to display. It also takes the following groups of properties: Common Properties Position Style Properties Text Style Properties It does not take children.
s c r e e nh e l l o _ w o r l d : t e x t" H e l l o ,W o r l d . "s i z e4 0
Textbutton

Creates a button containing a text label. The button takes a single parameter, the text to include as part of the button. It takes the following properties:
a c t i o n

The action to run when the button is activated. This also controls if the button is sensitive, and if the button is selected.
h o v e r e d

An action to run when the button gains focus.

u n h o v e r e d

An action to run when the button loses focus.

t e x t _ s t y l e

The name of the style to use for the button text. If not supplied, and the s t y l eproperty is a string, then " _ t e x t "is appended to that string to give the default text style.
t e x t _ -

Other properties prefixed with text have this prefix stripped, and are then passed to the text displayable. It also takes: Common Properties Position Style Properties Window Style Properties Button Style Properties It does not take children.
s c r e e nt e x t b u t t o n _ s c r e e n : v b o x : t e x t b u t t o n" W i n e "a c t i o nJ u m p ( " w i n e " ) t e x t b u t t o n" W o m e n "a c t i o nJ u m p ( " w o m e n " ) t e x t b u t t o n" S o n g "a c t i o nJ u m p ( " s o n g " )
Timer

This creates a timer that runs an action when time runs out. It takes one positional parameter, giving the timeout time, in seconds. It takes the properties:
a c t i o n

This gives an action that is run when the timer expires. This property is mandatory.
r e p e a t

If True, the timer repeats after it times out. It takes no children.

s c r e e nt i m e r _ t e s t : v b o x : t e x t b u t t o n" Y e s . "a c t i o nJ u m p ( " y e s " ) t e x t b u t t o n" N o . "a c t i o nJ u m p ( " n o " ) t i m e r3 . 0a c t i o nJ u m p ( " t o o _ s l o w " )
Transform

Applies a transform to its child. This takes no parameters, and the following property groups : Common Properties Transform Properties This should take a single child.
Vbar

The vertically oriented equivalent of bar. Properties are the same as b a r .

s c r e e nv o l u m e _ c o n t r o l s : f r a m e : h a sh b o x v b a rv a l u eP r e f e r e n c e ( " s o u n dv o l u m e " ) v b a rv a l u eP r e f e r e n c e ( " m u s i cv o l u m e " ) v b a rv a l u eP r e f e r e n c e ( " v o i c ev o l u m e " )

Vbox

This displays its children one above the other, in an invisible vertical box. It takes no parameters, and the following groups of properties: Common Properties Position Style Properties Box Style Properties UI displayable children are added to the box.
s c r e e nv b o x _ t e s t : v b o x : t e x t" T o p . " t e x t" B o t t o m . "
Viewport

A viewport is area of the screen that can be scrolled by dragging, with the mouse wheel, or with scrollbars. It can be used to display part of something that is bigger than the screen. It takes the following properties:
c h i l d _ s i z e

The size that is offered to the child for rendering. An (x s i z e ,y s i z e ) tuple. This can usually be omitted, when the child can compute it's own size. If either component is None, the child's size is used.
m o u s e w h e e l

If True, the mouse wheel can be used to scroll the viewport.

d r a g g a b l e

If True, dragging the mouse will scroll the viewport.

x a d j u s t m e n t The u i . a d j u s t m e n t ( )used for the x-axis of the viewport. When omitted, a new adjustment

is created.

y a d j u s t m e n t The u i . a d j u s t m e n t ( )used for the y-axis of the viewport. When omitted, a new adjustment

is created.

x i n i t i a l

The initial horizontal offset of the viewport. This may be an integer giving the number of pixels, or a float giving a fraction of the possible offset.
y i n i t i a l

The initial vertical offset of the viewport. This may be an integer giving the number of pixels, or a float giving a fraction of the possible offset.
s c r o l l b a r s

If not None, scrollbars are added allong with this viewport. This works by creating a side

layout, and placing the created viewport in the center of the side. If s c r o l l b a r sis "horizontal", a horizontal scrollbar is placed beneath the viewport. If s c r o l l b a r sis "vertical", a vertical scrollbar is placed to the right of the viewport. If s c r o l l b a r sis "both", both horizontal and vertical scrollbars are created. If s c r o l l b a r sis not None, the viewport takes properties prefixed with "side". These are passed to the created side layout. In addition, it takes the following groups of style properties: Common Properties Position Style Properties It takes one child. If zero, two, or more children are supplied, then a fixed is created to contain them. To make a viewport scrollable, it's often best to assign an id to it, and then use X S c r o l l V a l u e ( ) and Y S c r o l l V a l u e ( )with that id.
s c r e e nv i e w p o r t _ e x a m p l e : s i d e" cbr " : a r e a( 1 0 0 ,1 0 0 ,6 0 0 ,4 0 0 ) v i e w p o r ti d" v p " : d r a g g a b l eT r u e a d d" w a s h i n g t o n . j p g " b a rv a l u eX S c r o l l V a l u e ( " v p " ) v b a rv a l u eY S c r o l l V a l u e ( " v p " )
Window

A window is a window that contains a background that is intended for displaying in-game dialogue. It takes the following groups of properties: Common Properties Position Style Properties Window Style Properties It takes one child. If zero, two, or more children are supplied, then a fixed is created to contain them.
s c r e e ns a y : w i n d o wi d" w i n d o w " v b o x : s p a c i n g1 0 t e x tw h oi d" w h o " t e x tw h a ti d" w h a t "

Imagemap Statements A convenient way of creating a screen, especially for those who think visually is to create an imagemap. When creating an imagemap, the imagemap statement is used to specify up to six images. The hotspot and hotbar images are used to carve rectangular areas out of the image, and apply actions and values to those areas. Here's an example of a preferences screen that uses imagemaps.

s c r e e np r e f e r e n c e s : t a gm e n u u s en a v i g a t i o n i m a g e m a p : a u t o" g u i _ s e t / g u i _ p r e f s _ % s . p n g " h o t s p o t( 7 4 0 ,2 3 2 ,7 5 ,7 3 )c l i c k e dP r e f e r e n c e ( " d i s p l a y " ," f u l l s c r e e n " ) h o t s p o t( 8 3 2 ,2 3 2 ,7 5 ,7 3 )c l i c k e dP r e f e r e n c e ( " d i s p l a y " ," w i n d o w " ) h o t s p o t( 1 0 7 4 ,2 3 2 ,7 5 ,7 3 )c l i c k e dP r e f e r e n c e ( " t r a n s i t i o n s " ," a l l " ) h o t s p o t( 1 1 6 6 ,2 3 2 ,7 5 ,7 3 )c l i c k e dP r e f e r e n c e ( " t r a n s i t i o n s " ," n o n e " ) h o t b a r( 7 3 6 ,4 1 5 ,1 6 1 ,2 0 )v a l u eP r e f e r e n c e ( " m u s i cv o l u m e " ) h o t b a r( 1 0 7 0 ,4 1 5 ,1 6 1 ,2 0 )v a l u eP r e f e r e n c e ( " s o u n dv o l u m e " ) h o t b a r( 6 6 7 ,5 3 5 ,1 6 1 ,2 0 )v a l u eP r e f e r e n c e ( " v o i c ev o l u m e " ) h o t b a r( 1 0 0 1 ,5 3 5 ,1 6 1 ,2 0 )v a l u eP r e f e r e n c e ( " t e x ts p e e d " )
Imagemap

The imagemap statement is used to specify an imagemap. It takes no parameters, and the following properties:
a u t o

Used to automatically define the images used by this imagemap. This should be a string that contains %s in it. If it is, and one of the image properties is omitted, %s is replaced with the name of that property, and the value is used as the default for that property. For example, if a u t ois "imagemap_%s.png", and i d l eis omitted, then idle defaults to "imagemap_idle.png". The behavior of a u t ocan be customized by changing c o n f i g . i m a g e m a p _ a u t o _ f u n c t i o n .
g r o u n d

The image used for portions of the imagemap that are not part of a hotspot or hotbar.
i n s e n s i t i v e

The image used when a hotspot or hotbar is insensitive.

i d l e

The image used when a hotspot is not selected and not focused, and for the empty portion of unfocused hotbars.
h o v e r

The image used when a hotspot is not selected and focused, and for the empty portion of focused hotbars.
s e l e c t e d _ i d l e

The image used when a hotspot is selected and not focused, and for the full portion of unfocused hotbars.
s e l e c t e d _ h o v e r

The image used when a hotspot is selected and focused, and for the full portion of focused hotbars.
a l p h a

If true, the default, a hotspot only gains focus when the mouse is in an area of the hover image that is opaque. If false, the hotspot gains focus whenever the mouse is within its rectangular boundary.
c a c h e

If true, the default, hotspot data is cached in to improve performance at the cost of some additional disk space. It takes the following groups of properties: Common Properties Position Style Properties Fixed Style Properties An imagemap creates a fixed, allowing any child to be added to it (not just hotspots and hotbars).
Hotspot

A hotspot is a button consisting of a portion of the imagemap that contains it. It takes a single parameter, a (x, y, width, height) tuple giving the area of the imagemap that makes up the button. It also takes the following properties:
a c t i o n

The action to run when the button is activated. This also controls if the button is sensitive, and if the button is selected.
h o v e r e d

An action to run when the button gains focus.

u n h o v e r e d

An action to run when the button loses focus. It also takes: Common Properties Button Style Properties A hotspot creates a fixed, allowing children to be added to it. The fixed has an area that is the same size as the hotspot, meaning that the children will be positioned relative to the hotpsot.
Hotbar

A hotbar is a bar that consists of a portion of the imagemap that contains it. It takes a single parameter, a (x, y, width, height) tuple giving the area of the imagemap that makes up the button. It also takes the following properties:
v a l u e

The current value of the bar. This can be either a Value object, or a number.
r a n g e

The maximum value of the bar. This is required if v a l u eis a number.

a d j u s t m e n t Au i . a d j u s t m e n t ( )object that this bar adjusts.

One of v a l u eor a d j u s t m e n tmust be given. In addition, this function takes: Common Properties Bar Style Properties This does not take children. Advanced Displayables

In addition to the commonly-used statements, the screen language has statements that correspond to advanced displayables. The mapping from displayable to statement is simple. Positional parameters of the displayables become positional parameters of the statement. Keyword arguments and the relevant style properties become screen language properties. The advanced displayable statements are:
d r a g

Creates a D r a g . A drag can be given an optional child, or the c h i l dstyle property can be used to supply the child, and its focused variants.
d r a g g r o u p

Creates a D r a g G r o u p . A drag group may have zero or more drags as its children. Has Statement The has statment allows you to specify a container to use, instead of fixed, for statements that take only one child. The has statement may only be used inside a statement that takes one child. The keyword h a sis followed (on the same line) by another statement, which must be a statement that creates a container displayable, one that takes more than one child. The has statement changes the way in which the block that contains it is parsed. Child displayables created in that block are added to the container, rather than the parent displayable. Keyword arguments to the parent displayable are not allowed after the has statement. Multiple has statements can be used in the same block. The has statement can be supplied as a child of the following statements: button frame window The has statement can be given the following statements as a container. fixed grid hbox side vbox
s c r e e nv o l u m e _ c o n t r o l s : f r a m e : h a sv b o x b a rv a l u eP r e f e r e n c e ( " s o u n dv o l u m e " ) b a rv a l u eP r e f e r e n c e ( " m u s i cv o l u m e " ) b a rv a l u eP r e f e r e n c e ( " v o i c ev o l u m e " )

Control Statements The screen language includes control statements for conditional execution, iteration, including other screens, executing actions when events occur, and executing arbitrary python code.
Default

The default statement sets the default value of a variable, if it is not passed as an argument to the screen, or inherited from a screen that calls us using the use statement.
s c r e e nm e s s a g e : d e f a u l tm e s s a g e=" N om e s s a g ed e f i n e d . "

d e f a u l tm e s s a g e=" N om e s s a g ed e f i n e d . " t e x tm e s s a g e
For

The for statement is similar to the Python for statment, except that it does not support the else clause. It supports assignment to (optionally nested) tuple patterns, as well as variables.
$n u m e r a l s=[' I ' ,' I I ' ,' I I I ' ,' I V ' ,' V '] s c r e e nf i v e _ b u t t o n s : v b o x : f o ri ,n u m e r a li ne n u m e r a t e ( n u m e r a l s ) : t e x t b u t t o nn u m e r a la c t i o nR e t u r n ( i+1 )
If

The screen language if statement is the same as the Python/Ren'Py if statement. It supports the if, elif, and else clauses.
s c r e e ns k i p p i n g _ i n d i c a t o r : i fc o n f i g . s k i p p i n g : t e x t" S k i p p i n g . " e l s e : t e x t" N o tS k i p p i n g . "
On

The on statement allows the screen to execute an action when an event occurs. It takes one parameter, a string giving the name of an event. This should be one of:
" s h o w " " h i d e " " r e p l a c e " " r e p l a c e d "

It then takes an action property, giving an action to run if the event occurs.
s c r e e np r e f e r e n c e s : f r a m e : h a sh b o x t e x t" D i s p l a y " t e x t b u t t o n" F u l l s c r e e n "a c t i o nP r e f e r e n c e s ( " d i s p l a y " ," f u l l s c r e e n " ) t e x t b u t t o n" W i n d o w "a c t i o nP r e f e r e n c e s ( " d i s p l a y " ," w i n d o w " ) o n" s h o w "a c t i o nS h o w ( " n a v i g a t i o n " ) o n" h i d e "a c t i o nH i d e ( " n a v i g a t i o n " )
Use

The use statement allows a screen to include another. The use statement takes the name of the screen to use. This can optionally be followed by a keyword argument list, in parenthesis. The scope of the included code includes the scope of the current statement's code, updated by assinging the parameters their new values.

s c r e e nf i l e _ s l o t : b u t t o n : a c t i o nF i l e A c t i o n ( s l o t ) h a sh b o x a d dF i l e S c r e e n s h o t ( s l o t ) v b o x : t e x tF i l e T i m e ( s l o t ,e m p t y = " E m p t yS l o t . " ) t e x tF i l e S a v e N a m e ( s l o t ) s c r e e ns a v e : g r i d25 : f o rii nr a n g e ( 1 ,1 1 ) : u s ef i l e _ s l o t ( s l o t = i )

Python

The screen language also includes single-line and multiple-line python statements, which can execute python code. This code runs in the scope of the screen. Python code must not cause side effects that are visible from outside the screen. Ren'Py will run screen code multiple times, as it deems necessary. It runs screen code as part of the image prediction process, before the screen is first shown. As a result, if screen code has side effects, those side effects may occur at unpredictable times.
s c r e e np y t h o n _ s c r e e n : p y t h o n : t e s t _ n a m e=" T e s t% d "%t e s t _ n u m b e r t e x tt e s t _ n a m e $t e s t _ l a b e l=" t e s t _ % d "%t e s t _ l a b e l t e x t b u t t o n" R u nT e s t "a c t i o nJ u m p ( t e s t _ l a b e l )

Screen Statements In addition to the screen statement, there are three Ren'Py script language statements that involve screens. Two of these statements take a keyword argument list. This is a python argument list, in parenthesis, consisting of only keyword arguments. Positional arguments, extra positional arguments (*), and extra keyword arguments (**) are not allowed.
Show Screen

The show screen statement causes a screen to be shown. It takes an screen name, and an optional argument list. If present, the arguments are used to intialize the scope of the screen. Screens shown in this way are displayed until they are explicitly hidden. This allows them to be used for overlay purposes.
s h o ws c r e e no v e r l a y _ s c r e e n s h o ws c r e e nc l o c k _ s c r e e n ( h o u r = 1 1 ,m i n u t e = 3 0 )
Hide Screen

The hide screen statement is used to hide a screen that is currently being shown. If the screen is not being shown, nothing happens.
h i d es c r e e no v e r l a y _ s c r e e n h i d es c r e e nc l o c k
Call Screen

The call screen statement shows a screen, and then hides it again at the end of the current interaction. If the screen returns a value, then the value is placed in _ r e t u r n . This can be used to display an imagemap. The imagemap can place a value into the _ r e t u r n variable using the R e t u r n ( )action, or can jump to a label using the J u m p ( )action.
c a l ls c r e e nm y _ i m a g e m a p

Screen Variants Ren'Py runs both on traditional mouse-oriented devices such as Windows, Mac, and Linux PCs, and newer touch-oriented devices such as Android-based smartphones and tablets. Screen variants allow a game to supply multiple versions of a screen, and use the version that best matches the hardware it is running on. Ren'Py chooses a screen variant to use by searching variants in the order they are listed in c o n f i g . v a r i a n t s . The first variant that exists is used. If the RENPY_VARIANT environment variable is present, config.variants is initialized by splitting the value of the variable on whitespace, and then appending N o n e . Setting RENPY_VARIANT to a value such as " t a b l e tt o u c h "or " p h o n et o u c h "allows screens intended for Android devices to be tested on a PC. If the environment variable is not present, a list of variants is built up automatically, by going through the following list in order and choosing the entries that apply to the current platform.
" t a b l e t "

Defined on touchscreen based devices where the screen has a diagonal size of 6 inches or more.
" p h o n e "

Defined on touchscren-based devices where the diagonal size of the screen is less than 6 inches. On such a small device, it's important to make buttons large enough a user can easily choose them.
" t o u c h "

Defined on touchscreen-based devices, such as those running the Android platform.

" p c "

Defined on Windows, Mac OS X, and Linux. A PC is expected to have a mouse and keyboard present, to allow buttons to be hovered, and to allow precise pointing.
N o n e

Always defined. An example of defining a screen variant is:

#Av a r i a n th e l l o _ w o r l ds c r e e n ,u s e do ns m a l lt o u c h b a s e d #d e v i c e s . s c r e e nh e l l o _ w o r l d : t a ge x a m p l e

z o r d e r1 m o d a lF a l s e v a r i a n t" t o u c h " t e x t" H e l l o ,W o r l d . "s i z e3 0

Screen Actions, Values, and Functions

Ren'Py ships with a number of actions, values, and functions intended for use with screens and the screen language. Actions Actions are invoked when a button (including imagebuttons, textbuttons, and hotspots) is activated, hovered, or unhovered. Actions may determine when a button is selected or insensitive. Along with these actions, an action may be a function that does not take any arguments. The function is called when the action is invoked. If the action returns a value, then the value is returned from an interaction. An action may also be a list of actions, in which case the actions in the list are run in order.
Control Actions

These are actions that manage screens, interaction results, and control flow.

H i d e (screen, transition=None)
This causes the screen named s c r e e nto be hidden, if it is shown.
t r a n s i t i o n

If not None, a transition that occurs when hiding the screen.

J u m p (label)
Causes control to transfer to the given label. This can be used in conjunction with renpy.run_screen to define an imagemap that jumps to a label when run.

R e t u r n (value=None)
Causes the current interaction to return the supplied value. This is often used with menus and imagemaps, to select what the return value of the interaction is. When in a menu, this returns from the menu.

S h o w (screen, transition=None, **kwargs)

This causes another screen to be shown. s c r e e nis a string giving the name of the screen. The keyword arguments are passed to the screen being shown. If not None, t r a n s i t i o nis use to show the new screen.

S h o w T r a n s i e n t (screen, **kwargs)
Shows a transient screen. A transient screen will be hidden when the current interaction

completes.
Data Actions

These set or toggle data.

S e t D i c t (dict, key, value)

Causes the value of k e yin d i c tto be set to v a l u e .

S e t F i e l d (object, field, value)

Causes the a field on an object to be set to a given value. o b j e c tis the object, f i e l dis a string giving the name of the field to set, and v a l u eis the value to set it to.

S e t S c r e e n V a r i a b l e (name, value)
Causes the variable n a m eassociated with the current screen to be set to v a l u e .

S e t V a r i a b l e (variable, value)
Causes v a r i a b l eto be set to v a l u e .

T o g g l e D i c t (dict, key, true_value=None, false_value=None)

Toggles the value of k e yin d i c t . Toggling means to invert the value when the action is performed.
t r u e _ v a l u e

If not None, then this is the true value we use.

f a l s e _ v a l u e

If not None, then this is the false value we use.

T o g g l e F i e l d (object, field, true_value=None, false_value=None)

Toggles f i e l don o b j e c t . Toggling means to invert the boolean value of that field when the action is performed.
t r u e _ v a l u e

If not None, then this is the true value we use.

f a l s e _ v a l u e

If not None, then this is the false value we use.

T o g g l e S c r e e n V a r i a b l e (name, true_value=None, false_value=None)

Toggles the value of the variable n a m ein the current screen.
t r u e _ v a l u e

If not None, then this is the true value we use.

f a l s e _ v a l u e

If not None, then this is the false value we use.

T o g g l e V a r i a b l e (variable, true_value=None, false_value=None)

Toggles v a r i a b l e .
t r u e _ v a l u e

If not None, then this is the true value we use.

f a l s e _ v a l u e

If not None, then this is the false value we use.

Menu Actions

These actions invoke menus, or are primarily useful while in the main or game menus.

M a i n M e n u (confirm=True)
Causes Ren'Py to return to the main menu.
c o n f i r m

If true, causes Ren'Py to ask the user if he wishes to return to the main menu, rather than returning directly.

Q u i t (confirm=True)
Quits the game.
c o n f i r m

If true, prompts the user if he wants to quit, rather than quitting directly.

S h o w M e n u (screen=None)
Causes us to enter the game menu, if we're not there already. If we are in the game menu, then this shows a screen or jumps to a label.
s c r e e nis usually the name of a screen, which is shown using the screen mechanism. If the

screen doesn't exist, then "_screen" is appended to it, and that label is jumped to. ShowMenu("load") ShowMenu("save") ShowMenu("preferences")

This can also be used to show user-defined menu screens. For example, if one has a "stats" screen defined, one can show it as part of the game menu using: ShowMenu("stats") ShowMenu without an argument will enter the game menu at the default screen, taken from _game_menu_screen.

S t a r t (label='start')
Causes Ren'Py to jump out of the menu context to the named label. The main use of this is to start a new game from the main menu. Common uses are: Start() - Start at the start label. Start("foo") - Start at the "foo" label.
File Actions

These actions handle saving, loading, and deleting of files. Many of these take the n a m eand p a g earguments.

n a m e

The name of the file to save to. This can be a string or an integer. It's combined with the page to create the filename.
p a g e

The page that this action acts on. This is one of "auto", "quick", or a positive integer. If None, the page is determined automatically, based on a persistent page number.

F i l e A c t i o n (name, page=None)
"Does the right thing" with the file. This means loading it if the load screen is showing, and saving to it otherwise.
n a m e

The name of the slot to save to or load from. If None, an unused slot (a large number based on the current time) will be will be used.
p a g e

The page that the file will be saved to or loaded from. If None, the current page is used.

F i l e D e l e t e (name, confirm=True, page=None)

Deletes the file.
c o n f i r m

If true, prompts before deleting a file.

F i l e L o a d (name, confirm=True, page=None, newest=True)

Loads the file.
n a m e

The name of the slot to load from. If None, an unused slot the file will not be loadable.
c o n f i r m

If true, prompt if loading the file will end the game.

p a g e

The page that the file will be loaded from. If None, the current page is used.
n e w e s t

If true, the button is selected if this is the newest file.

F i l e P a g e (page)
Sets the file page to p a g e , which should be one of "auto", "quick", or an integer.

F i l e P a g e N e x t (max=None)
Goes to the next file page.
m a x

If set, this should be an integer that gives the number of the maximum file page we can go to.

F i l e P a g e P r e v i o u s (self)

Goes to the previous file page, if possible.

F i l e S a v e (name, confirm=True, newest=True, page=None, cycle=False)

Saves the file. The button with this slot is selected if it's marked as the newest save file.
n a m e

The name of the slot to save to. If None, an unused slot (a large number based on the current time) will be will be used.
c o n f i r m

If true, then we will prompt before overwriting a file.

n e w e s t

If true, then this file will be marked as the newest save file when it's saved.
p a g e

The name of the page that the slot is on. If None, the current page is used.
c y c l e

If true, then saves on the supplied page will be cycled before being shown to the user.

F i l e T a k e S c r e e n s h o t ()
Take a screenshot to be used when the game is saved. This can be used to ensure that the screenshot is accurate, by taking a pictue of the screen before a file save screen is shown.

Q u i c k L o a d ()
Performs a quick load.

Q u i c k S a v e (message='Quick save complete.', newest=False)

Performs a quick save.
m e s s a g e

A message to display to the user when the quick save finishes.

n e w e s t

Set to true to mark the quicksave as the newest save.

Audio Actions

P l a y (channel, file, **kwargs)

Causes an audio file to be played on a given channel.
c h a n n e l

The channel to play the sound on.

f i l e

The file to play. Any keyword arguments are passed to r e n p y . m u s i c . p l a y ( )

Q u e u e (channel, file, **kwargs)

Causes an audio file to be queued on a given channel.

c h a n n e l

The channel to play the sound on.

f i l e

The file to play. Any keyword arguments are passed to r e n p y . m u s i c . q u e u e ( )

S e t M i x e r (mixer, volume)
Sets the volume of m i x e rto v a l u e .
m i x e r

The mixer to set the volume of. A string, usually one of "music", "sfx", or "voice".
v a l u e

The value to set the volume to. A number between 0.0 and 1.0, inclusive.

S t o p (channel, **kwargs)
Causes an audio channel to be stopped.
c h a n n e l

The channel to play the sound on.

f i l e

The file to play. Any keyword arguments are passed to r e n p y . m u s i c . p l a y ( )

Other Actions

These are other actions, not found anywhere else.

H e l p (help=None)
Displays help.
h e l p

If this is a string giving a label in the programe, then that label is called in a new context when the button is chosen. Otherwise, it should be a string giving a file that is opened in a web browser. If None, the value of config.help is used in the same wayt.

I f (expression, true=None, false=None)

This returns t r u eif e x p r e s s i o nis true, and f a l s eotherwise. Use this to select an action based on an expression. Note that the default, None, can be used as an action that causes a button to be disabled.

I n v e r t S e l e c t e d (action)
This inverts the selection state of the provided action, while proxying over all of the other methods.

L a n g u a g e (language)

Changes the language of the game to l a n g u a g e . A language change causes the current statement to be restarted, and all contexts but the outermost being exited.
l a n g u a g e

A string giving the language to translate to, or None to use the language given in the game script.

N o t i f y (message)
Displays m e s s a g eusing r e n p y . n o t i f y ( ) .

O p e n U R L (url)
Causes u r lto be opened in a web browser.

R o l l F o r w a r d ()
This action causes a rollforward to occur, if a roll forward is possible. Otherwise, it is insensitive.

R o l l b a c k ()
This action causes a rollback to occur, when a rollback is possible. Otherwise, nothing happens.

S c r e e n s h o t ()
Takes a screenshot.

S e l e c t e d I f (expression)
This allows an expression to control if a button should be marked as selected. It should be used as part of a list with one or more actions. For example:
#T h eb u t t o ni ss e l e c t e di fm a r s _ f l a gi sT r u e t e x t b u t t o n" M a r s o p o l i s " : a c t i o n[J u m p ( " m a r s " ) ,S e l e c t e d I f ( m a r s _ f l a g )]

S k i p ()
Causes the game to begin skipping. If the game is in a menu context, then this returns to the game. Otherwise, it just enables skipping.

W i t h (transition)
Causes t r a n s i t i o nto occur. Values Values are used with bars, to set the bar value, and to allow the bar to adjust an underlying property.

A n i m a t e d V a l u e (value=0.0, range=1.0, delay=1.0, old_value=None)

This animates a value, taking d e l a yseconds to vary the value from o l d _ v a l u eto v a l u e .

v a l u e

The value itself, a number.

r a n g e

The range of the value, a number.

d e l a y

The time it takes to animate the value, in seconds. Defaults to 1.0.

o l d _ v a l u e

The old value. If this is None, then the value is taken from the AnimatedValue we replaced, if any. Otherwise, it is initialized to v a l u e .

F i e l d V a l u e (object, field, range, max_is_zero=False, style='bar', offset=0, step=None)

A value that allows the user to adjust the value of a field on an object.
o b j e c t

The object.
f i e l d

The field, a string.

r a n g e

The range to adjust over.

m a x _ i s _ z e r o

If True, then when the field is zero, the value of the bar will be range, and all other values will be shifted down by 1. This works both ways - when the bar is set to the maximum, the field is set to 0. This is used internally, for some preferences.
s t y l e

The styles of the bar created.

o f f s e t

An offset to add to the value.

s t e p

The amount to change the bar by. If None, defaults to 1/10th of the bar.

M i x e r V a l u e (mixer)
The value of an audio mixer.
m i x e r

The name of the mixer to adjust. This is usually one of "music", "sfx", or "voice", but user code can create new mixers.

S t a t i c V a l u e (value=0.0, range=1.0)
This allows a value to be specified statically.
v a l u e

The value itself, a number.

r a n g e

The range of the value.

X S c r o l l V a l u e (viewport)
The value of an adjustment that horizontally scrolls the the viewport with the given id, on the current screen. The viewport must be defined before a bar with this value is.

Y S c r o l l V a l u e (viewport)
The value of an adjustment that vertically scrolls the the viewport with the given id, on the current screen. The viewport must be defined before a bar with this value is. Functions and Classes These functions and classes are useful in association with screens.
Preferences

While all preferences can be defined based on the Actions and Values given above, it requires some knowledge of Ren'Py to figure out the correct one to use. The preferences constructor makes this easy, by creation an action or value, as appropriate, based on the names used in the default preferences screen.

P r e f e r e n c e (name, value=None)
This constructs the approprate action or value from a preference. The preference name should be the name given in the standard menus, while the value should be either the name of a choice, "toggle" to cycle through choices, a specific value, or left off in the case of buttons. Actions that can be used with buttons and hotspots are: Preference("display", "fullscreen") - displays in fullscreen mode. Preference("display", "window") - displays in windowed mode at 1x normal size. Preference("display", 2.0) - displays in windowed mode at 2.0x normal size. Preference("display", "toggle") - toggle display mode. Preference("transitions", "all") - show all transitions. Preference("transitions", "none") - do not show transitions. Preference("transitions", "toggle") - toggle transitions. Preference("text speed", 0) - make text appear instantaneously. Preference("text speed", 142) - set text speed to 142 characters per second. Preference("joystick") - Show the joystick preferences. Preference("skip", "seen") - Only skip seen messages. Preference("skip", "all") - Skip unseen messages. Preference("skip", "toggle") - Toggle between skip seen and skip all. Preference("begin skipping") - Starts skipping. Preference("after choices", "skip") - Skip after choices. Preference("after choices", "stop") - Stop skipping after choices. Preference("after choices", "toggle") - Toggle skipping after choices. Preference("auto-forward time", 0) - Set the auto-forward time to infinite. Preference("auto-forward time", 10) - Set the auto-forward time (unit is seconds per 250 characters). Preference("auto-forward", "enable") - Enable auto-forward mode. Preference("auto-forward", "disable") - Disable auto-forward mode. Preference("auto-forward", "toggle") - Toggle auto-forward mode. Preference("music mute", "enable") - Mute the music mixer. Preference("music mute", "disable") - Un-mute the music mixer. Preference("music mute", "toggle") - Toggle music mute. Preference("sound mute", "enable") - Mute the sound mixer. Preference("sound mute", "disable") - Un-mute the sound mixer. Preference("sound mute", "toggle") - Toggle sound mute.

Preference("voice mute", "enable") - Mute the voice mixer. Preference("voice mute", "disable") - Un-mute the voice mixer. Preference("voice mute", "toggle") - Toggle voice mute. Preference("music volume", 0.5) - Set the music volume. Preference("sound volume", 0.5) - Set the sound volume. Preference("volice volume", 0.5) - Set the voice volume. Values that can be used with bars are: Preference("text speed") Preference("auto-forward time") Preference("music volume") Preference("sound volume") Preference("voice volume")
File Functions

These functions return useful information about files. They use the same default page as the file actions.

F i l e C u r r e n t P a g e ()
Returns the current file page as a string.

F i l e L o a d a b l e (name, page=None)
This is a function that returns true if the file is loadable, and false otherwise.

F i l e P a g e N a m e (auto='a', quick='q')
Returns the name of the current file page, as a string. If a normal page, this returns the page number. Otherwise, it returns a u t oor q u i c k .

F i l e S a v e N a m e (name, empty='', page=None)

Return the save_name that was in effect when the file was saved, or e m p t yif the file does not exist.

F i l e S c r e e n s h o t (name, empty=None, page=None)

Returns the screenshot associated with the given file. If the file is not loadable, then e m p t y is returned, unless it's None, in which case, a Null displayable is created. The return value is a displayable.

F i l e S l o t N a m e (slot, slots_per_page, auto='a', quick='q', format='%s%d')

Returns the name of the numbered slot. This assumes that slots on normal pages are numbered in a linear order starting with 1, and that page numbers start with 1. When slot is 2, and slots_per_page is 10, and the other variables are the defauts: When the When the When the When the
s l o t

first page is slowing, this returns "2". second page is showing, this returns "12". auto page is showing, this returns "a2". quicksave page is showing, this returns "q2".

The number of the slot to access.

s l o t s _ p e r _ p a g e

The number of slots per page.

a u t o

A prefix to use for the auto page.

q u i c k

A prefix to use for the quick page.

f o r m a t

The formatting code to use. This is given two arguments: A string giving the page prefix, and an integer giving the slot number.

F i l e T i m e (name, format='%b %d, %H:%M', empty='', page=None)

Returns the time the file was saved, formatted according to the supplied f o r m a t . If the file is not found, e m p t yis returned. The return value is a string.

F i l e U s e d S l o t s (page=None, highest_first=True)
Returns a list of used numeric file slots on the page.
p a g e

The name of the page that will be scanned. If None, the current page is used.
h i g h e s t _ f i r s t

If true, the highest-numbered file slot is listed first. Otherwise, the lowest-numbered slot is listed first.
Side Image Functions

This function returns the side image to use.

S i d e I m a g e (prefix_tag='side')
Returns the side image associated with the currently speaking character, or a Null displayable if no such side image exists.
Tooltips

The tooltip class changes the screen when a button is hovered. class T o o l t i p (default) A tooltip object can be used to define a portion of a screen that is updated when the mouse hovers an area. A tooltip object has a v a l u efield, which is set to the d e f a u l tvalue passed to the constructor when the tooltip is created. When a button using an action creadted by the tooltip is hovered, the value field changes to the value associated with the action.

A c t i o n (value)
Returns an action that is generally used as the hovered property of a button. When the button is hovered, the value field of this tooltip is set to v a l u e . When the buttton loses focus, the value field of this tooltip reverts to the default. When using a tooltip with a screen, the usual behavior is to create a tooltip object in a default

statement. The value of the tooltip and the action method can then be used within the screen. The order of use within a screen doesn't matter - it's possible to use the value before an action is used. Tooltips can take on any value. While in the example below we use the text statement to display a string on the screen, it's also possible to use the add statement to add a displayable. More complex behavior is also possible.
s c r e e nt o o l t i p _ t e s t : d e f a u l tt t=T o o l t i p ( " N ob u t t o ns e l e c t e d . " ) f r a m e : x f i l lT r u e h a sv b o x t e x t b u t t o n" O n e . " : a c t i o nR e t u r n ( 1 ) h o v e r e dt t . A c t i o n ( " T h el o n e l i e s tn u m b e r . " ) t e x t b u t t o n" T w o . " : a c t i o nR e t u r n ( 2 ) h o v e r e dt t . A c t i o n ( " I sw h a ti tt a k e s . " ) t e x t b u t t o n" T h r e e . " : a c t i o nR e t u r n ( 3 ) h o v e r e dt t . A c t i o n ( " Ac r o w d . " ) t e x tt t . v a l u e

Special Screen Names

There are two kinds of special screen names in Ren'Py. The first are screens that will be automatically displayed when Ren'Py script language commands (or their programmatic equivalents) are run. The other type are menu screens. These have conventional names for conventional functionality, but screens can be omitted or changed as is deemed necessary. On this page, we'll give example screens. It's important to realize that, while some screens must have minimal functionality, the screen system makes it possible to add additional functionality to screens. For example, while the standard say screen only displays text, the screen systen makes it easy to add features like skipping, auto-forward mode, or muting. Some special screens take parameters. These parameters can be accessed as variables in the screen's scope. Some of the screens also have special ids associated with them. A special id should be assigned to a displayable of a given type. It can cause properties to be assigned to that displayable, and can make that displayable accessible to calling code. In-Game Screens These screens are automatically displayed when certain Ren'Py statements execute.
Say

The s a yscreen is called by the say statement, when displaying ADV-mode dialogue. It is

displayed with the following parameters:

w h o

The text of the name of the speaking character.

w h a t

The dialogue being said by the speaking character. It's expected to declare displayables with the following ids: "who" A text displayable, displaying the name of the speaking character. The character object can be given arguments that style this displayable. "what" A text displayable, displaying the dialogue being said by the speaking character. The character object can be given arguments that style this displayable. A displayable with this id must be defined, as Ren'Py uses it to calculate auto-forward-mode time, click-tocontinue, and other things. "window" A window or frame. This conventionally contains the who and what text. The character object can be given arguments that style this displayable.
s c r e e ns a y : w i n d o wi d" w i n d o w " : h a sv b o x i fw h o : t e x tw h oi d" w h o " t e x tw h a ti d" w h a t "
Choice

The c h o i c escreen is used to display the in-game choices created with the menu statement. It is given the following parameter:
i t e m s

This is a list of (c a p t i o n ,a c t i o n ,c h o s e n ) tuples. For each choice, c a p t i o nis the name of the choice, and a c t i o nis the action to invoke for the choice, or None if this is a choice label. C h o s e nif a choice with this label has been chosen by the user before. (It doesn't have to be in the current game.)
s c r e e nc h o i c e : w i n d o w : s t y l e" m e n u _ w i n d o w " v b o x : s t y l e" m e n u " f o rc a p t i o n ,a c t i o n ,c h o s e ni ni t e m s : i fa c t i o n : b u t t o n : a c t i o na c t i o n

s t y l e" m e n u _ c h o i c e _ b u t t o n " t e x tc a p t i o ns t y l e" m e n u _ c h o i c e " e l s e : t e x tc a p t i o ns t y l e" m e n u _ c a p t i o n "

Input

The i n p u tscreen is used to display r e n p y . i n p u t ( ) . It is given one parameter:

p r o m p t

The prompt text supplied to renpy.input. It is expected to declare a displayable with the following id: "input" An input displayable, which must exist. This is given all the parameters supplied to renpy.input, so it must exist.
s c r e e ni n p u t : w i n d o w : h a sv b o x t e x tp r o m p t i n p u ti d" i n p u t "
NVL

The n v lscreen is used to display NVL-mode dialogue. It is given the following parameter:
d i a l o g u e

This is a list of ( w h o ,w h a t ,w h o _ i d ,w h a t _ i d ,w i n d o w _ i d ) tuples, each of which corresponds to a line of dialogue on the screen. W h oand w h a tare strings containing the speaking character and the line of dialogue, respectively. The ids should be assigned to the who and what text displayables, and a window containing each unit of dialogue.
i t e m s

This is a list of (c a p t i o n ,a c t i o n ,c h o s e n ) tuples. For each choice, c a p t i o nis the name of the choice, and a c t i o nis the action to invoke for the choice, or None if this is a choice label. C h o s e nif a choice with this label has been chosen by the user before. (It doesn't have to be in the current game.) If items is empty, the menu should not be shown. Ren'Py also supports an n v l _ c h o i c escreen, which takes the same parameters as n v l , and is used in preference to n v lwhen an in-game choice is presented to the user, if it exists.
s c r e e nn v l : w i n d o w : s t y l e" n v l _ w i n d o w " h a sv b o x : s t y l e" n v l _ v b o x " #D i s p l a yd i a l o g u e . f o rw h o ,w h a t ,w h o _ i d ,w h a t _ i d ,w i n d o w _ i di nd i a l o g u e :

w i n d o w : i dw i n d o w _ i d h a sh b o x : s p a c i n g1 0 i fw h oi sn o tN o n e : t e x tw h oi dw h o _ i d t e x tw h a ti dw h a t _ i d #D i s p l a yam e n u ,i fg i v e n . i fi t e m s : v b o x : i d" m e n u " f o rc a p t i o n ,a c t i o n ,c h o s e ni ni t e m s : i fa c t i o n : b u t t o n : s t y l e" n v l _ m e n u _ c h o i c e _ b u t t o n " a c t i o na c t i o n t e x tc a p t i o ns t y l e" n v l _ m e n u _ c h o i c e " e l s e : t e x tc a p t i o ns t y l e" n v l _ d i a l o g u e "

Notify

The n o t i f yscreen is used by r e n p y . n o t i f y ( )to display notifications to the user. It's generally used in conjunction with a transform to handle the entire task of notification. It's given a single parameter:
m e s s a g e

The message to display. The default notify screen, and its associated transform, are:
s c r e e nn o t i f y : z o r d e r1 0 0 t e x tm e s s a g ea t_ n o t i f y _ t r a n s f o r m #T h i sc o n t r o l sh o wl o n gi tt a k e sb e t w e e nw h e nt h es c r e e ni s #f i r s ts h o w n ,a n dw h e ni tb e g i n sh i d i n g . t i m e r3 . 2 5a c t i o nH i d e ( ' n o t i f y ' ) t r a n s f o r m_ n o t i f y _ t r a n s f o r m : #T h e s ec o n t r o lt h ep o s i t i o n . x a l i g n. 0 2y a l i g n. 0 1 5 #T h e s ec o n t r o lt h ea c t i o n so ns h o wa n dh i d e . o ns h o w : a l p h a0 l i n e a r. 2 5a l p h a1 . 0 o nh i d e : l i n e a r. 5a l p h a0 . 0

Menu Screens These are the menu screens. The m a i n _ m e n uand y e s n o _ p r o m p tare invoked implictly. When the user invokes the game menu, the screen named in _ g a m e _ m e n u _ s c r e e nwill be displayed. (This defaults to s a v e .) Remember, menu screens can be combined and modified fairly freely.
Main Menu

The m a i n _ m e n uscreen is the first screen shown when the game begins.
s c r e e nm a i n _ m e n u : #T h i se n s u r e st h a ta n yo t h e rm e n us c r e e ni sr e p l a c e d . t a gm e n u #T h eb a c k g r o u n do ft h em a i nm e n u . w i n d o w : s t y l e" m m _ r o o t " #T h em a i nm e n ub u t t o n s . f r a m e : s t y l e _ g r o u p" m m " x a l i g n. 9 8 y a l i g n. 9 8 h a sv b o x t e x t b u t t o n_ ( " S t a r tG a m e " )a c t i o nS t a r t ( ) t e x t b u t t o n_ ( " L o a dG a m e " )a c t i o nS h o w M e n u ( " l o a d " ) t e x t b u t t o n_ ( " P r e f e r e n c e s " )a c t i o nS h o w M e n u ( " p r e f e r e n c e s " ) t e x t b u t t o n_ ( " H e l p " )a c t i o nH e l p ( ) t e x t b u t t o n_ ( " Q u i t " )a c t i o nQ u i t ( c o n f i r m = F a l s e ) i n i tp y t h o n : #M a k ea l lt h em a i nm e n ub u t t o n sb et h es a m es i z e . s t y l e . m m _ b u t t o n . s i z e _ g r o u p=" m m "
Navigation

The n a v i g a t i o nscreen isn't special to Ren'Py. But by convention, we place the game menu navigation in a screen named n a v i g a t i o n , and then use that screen from the save, load and preferences screens.
s c r e e nn a v i g a t i o n : #T h eb a c k g r o u n do ft h eg a m em e n u . w i n d o w : s t y l e" g m _ r o o t " #T h ev a r i o u sb u t t o n s . f r a m e : s t y l e _ g r o u p" g m _ n a v " x a l i g n. 9 8 y a l i g n. 9 8

h a sv b o x t e x t b u t t o n_ ( " R e t u r n " )a c t i o nR e t u r n ( ) t e x t b u t t o n_ ( " P r e f e r e n c e s " )a c t i o nS h o w M e n u ( " p r e f e r e n c e s " ) t e x t b u t t o n_ ( " S a v eG a m e " )a c t i o nS h o w M e n u ( " s a v e " ) t e x t b u t t o n_ ( " L o a dG a m e " )a c t i o nS h o w M e n u ( " l o a d " ) t e x t b u t t o n_ ( " M a i nM e n u " )a c t i o nM a i n M e n u ( ) t e x t b u t t o n_ ( " H e l p " )a c t i o nH e l p ( ) t e x t b u t t o n_ ( " Q u i t " )a c t i o nQ u i t ( ) i n i tp y t h o n : s t y l e . g m _ n a v _ b u t t o n . s i z e _ g r o u p=" g m _ n a v "
Save

The s a v escreen is used to select a file in which to save the game.

s c r e e ns a v e : #T h i se n s u r e st h a ta n yo t h e rm e n us c r e e ni sr e p l a c e d . t a gm e n u u s en a v i g a t i o n f r a m e : h a sv b o x #T h eb u t t o n sa tt h et o pa l l o wt h eu s e rt op i c ka #p a g eo ff i l e s . h b o x : t e x t b u t t o n_ ( " P r e v i o u s " )a c t i o nF i l e P a g e P r e v i o u s ( ) t e x t b u t t o n_ ( " A u t o " )a c t i o nF i l e P a g e ( " a u t o " ) f o rii nr a n g e ( 1 ,9 ) : t e x t b u t t o ns t r ( i )a c t i o nF i l e P a g e ( i ) t e x t b u t t o n_ ( " N e x t " )a c t i o nF i l e P a g e N e x t ( ) #D i s p l a yag r i do ff i l es l o t s . g r i d25 : t r a n s p o s eT r u e x f i l lT r u e #D i s p l a yt e nf i l es l o t s ,n u m b e r e d1-1 0 . f o rii nr a n g e ( 1 ,1 1 ) : #E a c hf i l es l o ti sab u t t o n . b u t t o n : a c t i o nF i l e A c t i o n ( i ) x f i l lT r u e s t y l e" l a r g e _ b u t t o n " h a sh b o x #A d dt h es c r e e n s h o ta n dt h ed e s c r i p t i o nt ot h e #b u t t o n . a d dF i l e S c r e e n s h o t ( i ) t e x t("% 2 d ."%i +F i l e T i m e ( i ,e m p t y = _ ( " E m p t yS l o t . " ) ) +" \ n " +F i l e S a v e N a m e ( i ) )s t y l e" l a r g e _ b u t t o n _ t e x t "

Load

The l o a dscreen is used to select a file from which to load the game.
s c r e e nl o a d : #T h i se n s u r e st h a ta n yo t h e rm e n us c r e e ni sr e p l a c e d . t a gm e n u u s en a v i g a t i o n f r a m e : h a sv b o x #T h eb u t t o n sa tt h et o pa l l o wt h eu s e rt op i c ka #p a g eo ff i l e s . h b o x : t e x t b u t t o n_ ( " P r e v i o u s " )a c t i o nF i l e P a g e P r e v i o u s ( ) t e x t b u t t o n_ ( " A u t o " )a c t i o nF i l e P a g e ( " a u t o " ) f o rii nr a n g e ( 1 ,9 ) : t e x t b u t t o ns t r ( i )a c t i o nF i l e P a g e ( i ) t e x t b u t t o n_ ( " N e x t " )a c t i o nF i l e P a g e N e x t ( ) #D i s p l a yag r i do ff i l es l o t s . g r i d25 : t r a n s p o s eT r u e x f i l lT r u e #D i s p l a yt e nf i l es l o t s ,n u m b e r e d1-1 0 . f o rii nr a n g e ( 1 ,1 1 ) : #E a c hf i l es l o ti sab u t t o n . b u t t o n : a c t i o nF i l e A c t i o n ( i ) x f i l lT r u e s t y l e" l a r g e _ b u t t o n " h a sh b o x #A d dt h es c r e e n s h o ta n dt h ed e s c r i p t i o nt ot h e #b u t t o n . a d dF i l e S c r e e n s h o t ( i ) t e x t("% 2 d ."%i +F i l e T i m e ( i ,e m p t y = _ ( " E m p t yS l o t . " ) ) +" \ n " +F i l e S a v e N a m e ( i ) )s t y l e" l a r g e _ b u t t o n _ t e x t "
Preferences

The p r e f e r e n c e sscreen is used to select options that control the display of the game.
s c r e e np r e f e r e n c e s : t a gm e n u #I n c l u d et h en a v i g a t i o n . u s en a v i g a t i o n

#P u tt h en a v i g a t i o nc o l u m n si nat h r e e w i d eg r i d . g r i d31 : s t y l e _ g r o u p" p r e f s " x f i l lT r u e #T h el e f tc o l u m n . v b o x : f r a m e : s t y l e _ g r o u p" p r e f " h a sv b o x l a b e l_ ( " D i s p l a y " ) t e x t b u t t o n_ ( " W i n d o w " )a c t i o nP r e f e r e n c e ( " d i s p l a y " ," w i n d o w " ) t e x t b u t t o n_ ( " F u l l s c r e e n " )a c t i o nP r e f e r e n c e ( " d i s p l a y " ," f u l l s c r e e n " ) f r a m e : s t y l e _ g r o u p" p r e f " h a sv b o x l a b e l_ ( " T r a n s i t i o n s " ) t e x t b u t t o n_ ( " A l l " )a c t i o nP r e f e r e n c e ( " t r a n s i t i o n s " ," a l l " ) t e x t b u t t o n_ ( " N o n e " )a c t i o nP r e f e r e n c e ( " t r a n s i t i o n s " ," n o n e " ) f r a m e : s t y l e _ g r o u p" p r e f " h a sv b o x l a b e l_ ( " T e x tS p e e d " ) b a rv a l u eP r e f e r e n c e ( " t e x ts p e e d " ) f r a m e : s t y l e _ g r o u p" p r e f " h a sv b o x t e x t b u t t o n_ ( " J o y s t i c k . . . " )a c t i o nS h o w M e n u ( " j o y s t i c k _ p r e f e r e n c e s " ) v b o x : f r a m e : s t y l e _ g r o u p" p r e f " h a sv b o x l a b e l_ ( " S k i p " ) t e x t b u t t o n_ ( " S e e nM e s s a g e s " )a c t i o nP r e f e r e n c e ( " s k i p " ," s e e n " ) t e x t b u t t o n_ ( " A l lM e s s a g e s " )a c t i o nP r e f e r e n c e ( " s k i p " ," a l l " ) f r a m e : s t y l e _ g r o u p" p r e f " h a sv b o x t e x t b u t t o n_ ( " B e g i nS k i p p i n g " )a c t i o nS k i p ( ) f r a m e : s t y l e _ g r o u p" p r e f " h a sv b o x l a b e l_ ( " A f t e rC h o i c e s " ) t e x t b u t t o n_ ( " S t o pS k i p p i n g " )a c t i o nP r e f e r e n c e ( " a f t e rc h o i c e s " ," s t o p " t e x t b u t t o n_ ( " K e e pS k i p p i n g " )a c t i o nP r e f e r e n c e ( " a f t e rc h o i c e s " ," s k i p " f r a m e : s t y l e _ g r o u p" p r e f " h a sv b o x

l a b e l_ ( " A u t o F o r w a r dT i m e " ) b a rv a l u eP r e f e r e n c e ( " a u t o f o r w a r dt i m e " ) v b o x : f r a m e : s t y l e _ g r o u p" p r e f " h a sv b o x l a b e l_ ( " M u s i cV o l u m e " ) b a rv a l u eP r e f e r e n c e ( " m u s i cv o l u m e " ) f r a m e : s t y l e _ g r o u p" p r e f " h a sv b o x

l a b e l_ ( " S o u n dV o l u m e " ) b a rv a l u eP r e f e r e n c e ( " s o u n dv o l u m e " ) t e x t b u t t o n" T e s t "a c t i o nP l a y ( " s o u n d " ," s o u n d _ t e s t . o g g " )s t y l e" s o u n d t e s t _ b u f r a m e : s t y l e _ g r o u p" p r e f " h a sv b o x

l a b e l_ ( " V o i c eV o l u m e " ) b a rv a l u eP r e f e r e n c e ( " v o i c ev o l u m e " ) t e x t b u t t o n" T e s t "a c t i o nP l a y ( " v o i c e " ," v o i c e _ t e s t . o g g " )s t y l e" s o u n d t e s t _ b u i n i tp y t h o n : s t y l e . p r e f _ f r a m e . x f i l l=T r u e s t y l e . p r e f _ f r a m e . x m a r g i n=5 s t y l e . p r e f _ f r a m e . t o p _ m a r g i n=5 s t y l e . p r e f _ v b o x . x f i l l=T r u e s t y l e . p r e f _ b u t t o n . s i z e _ g r o u p=" p r e f " s t y l e . p r e f _ b u t t o n . x a l i g n=1 . 0 s t y l e . p r e f _ s l i d e r . x m a x i m u m=1 9 2 s t y l e . p r e f _ s l i d e r . x a l i g n=1 . 0 s t y l e . s o u n d t e s t _ b u t t o n . x a l i g n=1 . 0

Yesno_Prompt

The y e s n o _ p r o m p tmessage is used to ask yes/no choices of the user. It takes the following parameters:
m e s s a g e

The message to display to the user. This is one of: layout.ARE_YOU_SURE - "Are you sure?" This should be the default if the message is unknown. layout.DELETE_SAVE - "Are you sure you want to delete this save?" layout.OVERWRITE_SAVE - "Are you sure you want to overwrite your save?" layout.LOADING - "Loading will lose unsaved progress.nAre you sure you want to do this?" layout.QUIT - "Are you sure you want to quit?"

layout.MAIN_MENU - "Are you sure you want to return to the mainnmenu? This will lose unsaved progress." The values of the variables are strings, which means they can be displayed using a text displayable.
y e s _ a c t i o n

The action to run when the user picks "Yes".

n o _ a c t i o n

The action to run when the user picks "No".

s c r e e ny e s n o _ p r o m p t : m o d a lT r u e w i n d o w : s t y l e" g m _ r o o t " f r a m e : s t y l e _ g r o u p" y e s n o _ p r o m p t " x f i l lT r u e x m a r g i n5 0 y p a d d i n g2 5 y a l i g n. 2 5 v b o x : x f i l lT r u e s p a c i n g2 5 t e x t_ ( m e s s a g e ) : t e x t _ a l i g n0 . 5 x a l i g n0 . 5 h b o x : s p a c i n g1 0 0 x a l i g n. 5 t e x t b u t t o n_ ( " Y e s " )a c t i o ny e s _ a c t i o n t e x t b u t t o n_ ( " N o " )a c t i o nn o _ a c t i o n

Side Images
Many visual novels include a picture of the character that is speaking as part of their interface. Ren'Py calls this image a side image, and has support for automatically selecting and displaying a side image as part of the dialogue. The side image support assumes that a C h a r a c t e r ( )is declared with a linked image tag:
d e f i n ee=C h a r a c t e r ( " E i l e e n " ,i m a g e = " e i l e e n " )

When a character with a linked image tag speaks, Ren'Py creates a pool of image attributes. The linked image tag is added to this pool, as are the current image attributes that are associated with that tag. To determine the side image associated with a tag, Ren'Py tries to find an image with the tag "side", and the largest number of attributes from the pool. If no image can be found, or more than one image has the same number of attributes, an N u l lis shown instead.

than one image has the same number of attributes, an N u l lis shown instead. For example, say we have the following script:
d e f i n ee=C h a r a c t e r ( " E i l e e n " ,i m a g e = " e i l e e n " ) i m a g ee i l e e nh a p p y=" e i l e e n _ h a p p y . p n g " i m a g ee i l e e nc o n c e r n e d=" e i l e e n _ c o n c e r n e d . p n g " i m a g es i d ee i l e e nh a p p y=" s i d e _ e i l e e n _ h a p p y . p n g " i m a g es i d ee i l e e n=" s i d e _ e i l e e n . p n g " l a b e ls t a r t : s h o we i l e e nh a p p y e" L e t ' sc a l lt h i sl i n eP o i n tA . " ec o n c e r n e d" A n dt h i so n ei sp o i n tB . "

At point A, the character eis speaking, which is linked to the image tag "eileen". The "eileen happy" image is showing, so the pool of attributes is "eileen" and "happy". We look for an image with the "side" tag, and as many of those attributes as possible - and we match "side eileen happy", which is the side image Ren'Py will display. At point B, the "eileen concerned" image is showing. The pool of attributes is now "eileen" and "concerned". The only matching image is "side eileen", so that's what Ren'Py selects. If the was a "side concerned" image, there would be ambiguity, and Ren'Py wouldn't display an image. Invisible Characters Another use of the side image is to show an image of the player character, when that character has dialogue. The way to do this is to link an image to the character, and then use the say with attributes construct to select the side image to show. For example:
d e f i n ep=C h a r a c t e r ( " P l a y e r " ,i m a g e = " p l a y e r " ) i m a g es i d ep l a y e rh a p p y=" s i d e _ p l a y e r _ h a p p y . p n g " i m a g es i d ep l a y e rc o n c e r n e d=" s i d e _ p l a y e r _ c o n c e r n e d . p n g " l a b e ls t a r t : ph a p p y" T h i si ss h o w nw i t ht h e' s i d ep l a y e rh a p p y 'i m a g e . " p" T h i si sa l s os h o w nw i t h' s i d ep l a y e rh a p p y ' . " pc o n c e r n e d" T h i si ss h o w nw i t h' s i d ep l a y e rc o n c e r n e d ' . "

Variations There are two variants of side image support that can be selected - either alone or together using config variables:

c o n f i g . s i d e _ i m a g e _ t a g= None
If this is given, then the side image will track the given image tag, rather than the image associated with currently speaking character. For example,

d e f i n ee=C h a r a c t e r ( " E i l e e n " ,i m a g e = " e i l e e n " ) i n i tp y t h o n : c o n f i g . s i d e _ i m a g e _ t a g=" e i l e e n "

Will make the side image track the "eileen" image tag, which is associated with the e character.

c o n f i g . s i d e _ i m a g e _ o n l y _ n o t _ s h o w i n g= False
When set to true, the side image will only show if an image with that tag is not already being shown on the screen. Leaving Room / Customization By default, the entire width of the screen is taken up by the text. If one tries to display a side image, it will be displayed on top of the text. To fix this, one should include margin or padding on the appropriate side of the text window, using code like:
i n i tp y t h o n : s t y l e . w i n d o w . p a d d i n g _ l e f t=1 5 0

The position of the side image can be changed by customizing the s a yor n v lscreens. Both include the line:
a d dS i d e I m a g e ( )x a l i g n0 . 0y a l i g n1 . 0

By changing the xalign and yalign properties, you can control the positioning of the side image on the screen. Finally, the S i d e I m a g e ( )function returns, as a displayable, the current side image. This can be used as part of more advanced screen customization.

Configuration Variables
Configuration variables control the behavior of Ren'Py's implementation, allowing Ren'Py itself to be customized in a myriad of ways. These range from the common (such as changing the screen size) to the obscure (adding new kinds of archive files). Ren'Py's implementation makes the assumption that, once the GUI system has initialized, configuration variables will not change. Changing configuration variables outside of init blocks can lead to undefined behavior. Configuration variables are not part of the save data. Configuration variables are often changed in init python blocks:
i n i tp y t h o n : #U s eaw i d e s c r e e nr e s o l u t i o n . c o n f i g . s c r e e n _ w i d t h=1 0 2 4 c o n f i g . s c r e e n _ h e i g h t=6 0 0

Commonly Used

c o n f i g . d e v e l o p e r= False

If set to True, developer mode is enabled. Developer mode gives access to the shift+D developer menu, shift+R reloading, and various other features that are not intended for end users. The default game template sets this to True. We suggest setting it to False before releasing a game.

c o n f i g . h e l p= "README.html"
This controls the functionality of the help system invoked by the help button on the main and game menus, or by pressing f1 or command-?. If None, the help system is disabled and does not show up on menus. If a string corresponding to a label found in the script, that label is invoked in a new context. This allows you to define an in-game help-screen. Otherwise, this is interpreted as a filename relative to the base directory, that is opened in a web browser.

c o n f i g . n a m e= ""
This should be a string giving the name of the game. This is included as part of tracebacks and other log files, helping to identify the version of the game being used.

c o n f i g . s a v e _ d i r e c t o r y= "..."
This is used to generate the directory in which games and persistent information are saved. The name generated depends on the platform: Windows %APPDATA%/RenPy/s a v e _ d i r e c t o r y Mac OS X ~/Library/RenPy/s a v e _ d i r e c t o r y Linux/Other ~/.renpy/s a v e _ d i r e c t o r y Setting this to None creates a "saves" directory underneath the game directory. This is not recommended, as it prevents the game from being shared between multiple users on a system. It can also lead to problems when a game is installed as Administrator, but run as a user. This must be set in a python early block, so that persistent information can be loaded before init code is run. The user may change the directory. Code that needs to know the save directory should read c o n f i g . s a v e d i rinstead of this variable.

c o n f i g . s c r e e n _ h e i g h t= 600
The height of the screen.

c o n f i g . s c r e e n _ w i d t h= 800
The width of the screen.

c o n f i g . t r a n s l a t i o n s= dict(...)
This is a map used to translate text in the game menu into your language. See Localizing Ren'Py for how to use it, and here for a list of available translations.

c o n f i g . w i n d o w _ i c o n= None
If not None, this is expected to be the filename of an image giving an icon that is used for the window on Linux and Mac OS X. This should be a large image, with 8-bit alpha. This should generally be a PNG format file.

c o n f i g . w i n d o w s _ i c o n= None
If not None, this is expected to be the filename of an image giving an icon that is used for the window on Windows. This should be a 32x32 image with 1-bit alpha. (Opaque images work the best.) This should be a PNG format file.

c o n f i g . w i n d o w _ t i t l e= "A Ren'Py Game"

The static portion of the title of the window containing the Ren'Py game. _ w i n d o w _ s u b t i t l e is appended to this to get the full title of the window.

c o n f i g . v e r s i o n= ""
This should be a string giving the version of the game. This is included as part of tracebacks and other log files, helping to identify the version of the game being used. Occasionally Used

c o n f i g . a d v _ n v l _ t r a n s i t i o n= None
A transition that is used when showing NVL-mode text directly after ADV-mode text.

c o n f i g . a f t e r _ l o a d _ t r a n s i t i o n= None
A transition that is used after loading, when entering the loaded game.

c o n f i g . a u t o _ l o a d= None
If not None, the name of a save file to automatically load when Ren'Py starts up. This is intended for developer use, rather than for end users. Setting this to "1" will automatically load the game in save slot 1.

c o n f i g . a u t o m a t i c _ i m a g e s= None
If not None, this causes Ren'Py to automatically define images. When not set to None, this should be set to a list of separators. (For example, [ ' ' ,' _ ' , ' / '] .) Ren'Py will scan through the list of files on disk and in archives. When it finds a file ending with .png or .jpg, it will strip the extension, then break the name at separators, to creatge an image name. If the name consists of at least two components, and no image with that name already is defined, Ren'Py will define that image to refer to a filename. With the example list of separators, if your game directory contains: eileen_happy.png, Ren'Py will define the image "eileen happy". lucy/mad.png, Ren'Py will define the image "lucy mad". mary.png, Ren'Py will do nothing. (As the image does not have two components.)

c o n f i g . a u t o m a t i c _ i m a g e s _ s t r i p= []
A list of strings giving prefixes that are stripped out when defining automatic images. This can be used to remove directory names, when directories contain images.

c o n f i g . d e b u g= False
Enables debugging functionality (mostly by turning some missing files into errors.) This should always be turned off in a release.

c o n f i g . d e b u g _ i m a g e _ c a c h e= False
If True, Ren'Py will print the contents of the image cache to standard output (wherever that goes) whenever the contents of the image cache change.

c o n f i g . d e b u g _ s o u n d= False
Enables debugging of sound functionality. This disables the supression of errors when generating sound. However, if a sound card is missing or flawed, then such errors are normal, and enabling this may prevent Ren'Py from functioning normally. This should always be False in a released game.

c o n f i g . d e b u g _ t e x t _ o v e r f l o w= False
When true, Ren'Py will log text overflows to text_overflow.txt. A text overflow occurs when aT e x tdisplayable renders to a size larger than that allocated to it. By setting this to True and setting the x m a x i m u mand y m a x i m u mstyle properties of the dialogue window to the window size, this can be used to report cases where the dialogue is too large for its window.

c o n f i g . d e f a u l t _ a f m _ t i m e= None
If not None, this sets the default auto-forward-mode timeout. If not None, then this is the time in seconds we should delay when showing 250 characters. 0 is special-cased to be infinite time, disabling auto-forward mode. Persistent data must be deleted for this to take effect.

c o n f i g . d e f a u l t _ a f m _ e n a b l e= None
If not None, this should be a boolean that controls if auto-forward-mode is enabled by default. When it's False, auto-forwarding will not occur. Set this to False with caution, as the default Ren'Py UI does not provide a way of changing it's setting. (But one can use Preference action in a screen to create such a UI.) Persistent data must be deleted for this to take effect.

c o n f i g . d e f a u l t _ f u l l s c r e e n= None
This sets the default value of the fullscreen preference. This should be True or False. If None, this is ignored, allowing other code to set the default value. (It's usually set to False in options.rpy.)

c o n f i g . d e f a u l t _ t e x t _ c p s= None
If not None, this sets the default number of characters per second to show. 0 is special cased to mean an infinite number of characters per second. (It's usually set to 0 in options.rpy.) Persistent data must be deleted for this to take effect.

c o n f i g . d e f a u l t _ t r a n s f o r m= ...
When a displayable is shown using the show or scene statements, the transform properties are taken from this transform and used to initialize the values of the displayable's transform. The default default transform is c e n t e r .

c o n f i g . e m p t y _ w i n d o w= ...
This is called when _window is True, and no window has been shown on the screen. (That is, no call to r e n p y . s h o w n _ w i n d o w ( )has occurred.) It's expected to show an empty window on the screen, and return without causing an interaction. The default implementation of this uses the narrator character to display a blank line without interacting.

c o n f i g . e n d _ g a m e _ t r a n s i t i o n= None
The transition that is used to display the main menu after the game ends normally, either by invoking return with no place to return to, or by calling r e n p y . f u l l _ r e s t a r t ( ) .

c o n f i g . e n d _ s p l a s h _ t r a n s i t i o n= None
The transition that is used to display the main menu after the end of the splashscreen.

c o n f i g . e n t e r _ s o u n d= None
If not None, this is a sound file that is played when entering the game menu.

c o n f i g . e n t e r _ t r a n s i t i o n= None
If not None, this variable should give a transition that will be used when entering the game menu.

c o n f i g . e x i t _ s o u n d= None
If not None, this is a sound file that is played when exiting the game menu.

c o n f i g . e x i t _ t r a n s i t i o n= None
If not None, this variable should give a transition that will be performed when exiting the game menu.

c o n f i g . f i x _ r o l l b a c k _ w i t h o u t _ c h o i c e= False
This option determines how the built in menus or imagemaps behave during fixed rollback. The default value is False, which means that menu only the previously selected option remains clickable. If set to True, the selected option is marked but no options are clickable. The user can progress forward through the rollback buffer by clicking.

c o n f i g . f o n t _ r e p l a c e m e n t _ m a p= { }
This is a map from (font, bold, italics) to (font, bold, italics), used to replace a font with one that's specialized as having bold and/or italics. For example, if you wanted to have everything using an italic version of "Vera.ttf" use "VeraIt.ttf" instead, you could write:
i n i tp y t h o n : c o n f i g . f o n t _ r e p l a c e m e n t _ m a p [ " V e r a . t t f " ,F a l s e ,T r u e ]=( " V e r a I t . t t f " ,F a l s e ,F a l s e

Please note that these mappings only apply to specific variants of a font. In this case, requests for a bold italic version of vera will get a bold italic version of vera, rather than a bold version of the italic vera.

c o n f i g . f r a m e r a t e= 100
If not None, this is the upper limit on the number of frames Ren'Py will attempt to display per second. This is only respected by the software renderer. The GL renderer will synchronize to vertical blank instead.

c o n f i g . g a m e _ m a i n _ t r a n s i t i o n= None
The transition that is used to display the main menu after leaving the game menu. This is used when the load and preferences screens are invoked from the main menu, and it's also used when the user picks "Main Menu" from the game menu.

c o n f i g . g a m e _ m e n u= [ ... ]
This is used to customize the choices on the game menu. Please read Main and Game Menus for more details on the contents of this variable. This is not used when the game menu is defined using screens.

c o n f i g . g a m e _ m e n u _ m u s i c= None
If not None, a music file to play when at the game menu.

c o n f i g . g l _ t e s t _ i m a g e= "black"
The name of the image that is used when running the OpenGL performance test. This image will be shown for 5 frames or .25 seconds, on startup. It will then be automatically hidden.

c o n f i g . h a s _ a u t o s a v e= True
If true, the game will autosave. If false, no autosaving will occur.

c o n f i g . i m a g e _ c a c h e _ s i z e= 8
This is used to set the size of the image cache, as a multiple of the screen size. This number is multiplied by the size of the screen, in pixels, to get the size of the image cache in pixels. If set too large, this can waste memory. If set too small, images can be repeatedly loaded, hurting performance.

c o n f i g . m a i n _ g a m e _ t r a n s i t i o n= None
The transition used when entering the game menu from the main menu, as is done when clicking "Load Game" or "Preferences".

c o n f i g . m a i n _ m e n u= [ ... ]
The default main menu, when not using screens. For more details, see Main and Game Menus.

c o n f i g . m a i n _ m e n u _ m u s i c= None
If not None, a music file to play when at the main menu.

c o n f i g . m e n u _ c l e a r _ l a y e r s= []
A list of layer names (as strings) that are cleared when entering the game menu.

c o n f i g . m e n u _ w i n d o w _ s u b t i t l e= ""
The _ w i n d o w _ s u b t i t l evariable is set to this value when entering the main or game menus.

c o n f i g . m i s s i n g _ b a c k g r o u n d= "black"
This is the background that is used when c o n f i g . d e v e l o p e ris True and an undefined image is used in a scene statement. This should be an image name (a string), not a displayable.

c o n f i g . m o d e _ c a l l b a c k s= [ ... ]
A list of callbacks called when entering a mode. For more documentation, see the section on Modes. The default value includes a callback that implements c o n f i g . a d v _ n v l _ t r a n s i t i o nand c o n f i g . n v l _ a d v _ t r a n s i t i o n .

c o n f i g . m o u s e= None
This variable controls the use of user-defined mouse cursors. If None, the system mouse is used, which is usually a black-and-white mouse cursor. Otherwise, this should be a dictionary giving the mouse animations for various mouse types. Keys used by the default library include "default", "say", "with", "menu", "prompt", "imagemap", "pause", "mainmenu", and "gamemenu". The "default" key should always be present, as it is used when a more specific key is absent. Each value in the dictionary should be a list of (i m a g e ,x o f f s e t ,o f f s e t ) tuples, representing frames.

i m a g e

The mouse cursor image.

x o f f s e t

The offset of the hotspot pixel from the left side of the cursor.
y o f f s e t

The offset of the hotspot pixel from the top of the cursor. The frames are played back at 20hz, and the animation loops after all frames have been shown.

c o n f i g . n a r r a t o r _ m e n u= False
(This is set to True by the default screens.rpy file.) If true, then narration inside a menu is displayed using the narrator character. Otherwise, narration is displayed as captions within the menu itself.

c o n f i g . n v l _ a d v _ t r a n s i t i o n= None
A transition that is used when showing ADV-mode text directly after NVL-mode text.

c o n f i g . o v e r l a y _ f u n c t i o n s= [ ]
A list of functions. When called, each function is expected to use ui functions to add displayables to the overlay layer.

c o n f i g . p y t h o n _ c a l l b a c k s= [ ]
A list of functions. The functions in this list are called, without any arguments, whenever a python block is run outside of the init phase. One possible use of this would be to have a function limit a variable to within a range each time it is adjusted. The functions may be called during internal Ren'Py code, before the start of the game proper, and potentially before the variables the function depends on are intialized. The functions are required to deal with this, perhaps by using h a s a t t r ( s t o r e ,' v a r n a m e ' )to check if a variable is defined.

c o n f i g . q u i t _ a c t i o n= ...
The action that is called when the user clicks the quit button on a window. The default action prompts the user to see if he wants to quit the game.

c o n f i g . s a y _ a t t r i b u t e _ t r a n s i t i o n= None
If not None, a transition to use when the image is changed by a say statement with image attributes.

c o n f i g . t h u m b n a i l _ h e i g h t= 75
The height of the thumbnails that are taken when the game is saved. These thumbnails are shown when the game is loaded. Please note that the thumbnail is shown at the size it was taken at, rather than the value of this setting when the thumbnail is shown to the user. When using a load_save layout, a different default may be used.

c o n f i g . t h u m b n a i l _ w i d t h= 100
The width of the thumbnails that are taken when the game is saved. These thumbnails are shown when the game is loaded. Please note that the thumbnail is shown at the size it was taken at, rather than the value of this setting when the thumbnail is shown to the user. When using a load_save layout, a different default may be used.

c o n f i g . w i n d o w _ h i d e _ t r a n s i t i o n= None
The transition used by the window hide statement when no transition has been explicitly specified.

c o n f i g . w i n d o w _ o v e r l a y _ f u n c t i o n s= []
A list of overlay functions that are only called when the window is shown.

c o n f i g . w i n d o w _ s h o w _ t r a n s i t i o n= None
The transition used by the window show statement when no transition has been explicitly specified. Rarely or Internally Used

c o n f i g . a f m _ b o n u s= 25
The number of bonus characters added to every string when auto-forward mode is in effect.

c o n f i g . a f m _ c a l l b a c k= None
If not None, a python function that is called to determine if it is safe to auto-forward. The intent is that this can be used by a voice system to disable auto-forwarding when a voice is playing.

c o n f i g . a f m _ c h a r a c t e r s= 250
The number of characters in a string it takes to cause the amount of time specified in the auto forward mode preference to be delayed before auto-forward mode takes effect.

c o n f i g . a l l _ c h a r a c t e r _ c a l l b a c k s= [ ]
A list of callbacks that are called by all characters. This list is prepended to the list of character-specific callbacks.

c o n f i g . a l l o w _ s k i p p i n g= True
If set to False, the user is not able to skip over the text of the game.

c o n f i g . a r c h i v e s= [ ]
A list of archive files that will be searched for images and other data. The entries in this should consist of strings giving the base names of archive files, without the .rpa extension. The archives are searched in the order they are found in this list. A file is taken from the first archive it is found in. At startup, Ren'Py will automatically populate this variable with the names of all archives found in the game directory, sorted in reverse ascii order. For example, if Ren'Py finds the files data.rpa, patch01.rpa, and patch02.rpa, this variable will be populated with [ ' p a t c h 0 2 ' ,' p a t c h 0 1 ' ,' d a t a ' ] .

c o n f i g . a u t o _ c h o i c e _ d e l a y= None
If not None, this variable gives a number of seconds that Ren'Py will pause at an in-game menu before picking a random choice from that menu. We'd expect this variable to always be set to None in released games, but setting it to a number will allow for automated demonstrations of games without much human interaction.

c o n f i g . a u t o s a v e _ f r e q u e n c y= 200
Roughly, the number of interactions that will occur before an autosave occurs. To disable autosaving, set c o n f i g . h a s _ a u t o s a v eto False, don't change this variable.

c o n f i g . c h a r a c t e r _ c a l l b a c k= None
The default value of the callback parameter of Character.

c o n f i g . c l e a r _ l a y e r s= []
A list of names of layers to clear when entering the main and game menus.

c o n f i g . c o n t e x t _ c l e a r _ l a y e r s= [ 'screens' ]
A list of layers that are cleared when entering a new context.

c o n f i g . f a d e _ m u s i c= 0.0
This is the amount of time in seconds to spend fading the old track out before a new music track starts. This should probably be fairly short, so the wrong music doesn't play for too long.

c o n f i g . f a s t _ s k i p p i n g= False
Set this to True to allow fast skipping outside of developer mode.

c o n f i g . f i l e _ o p e n _ c a l l b a c k= None
If not None, this is a function that is called with the file name when a file needs to be opened. It should return a file-like object, or None to load the file using the usual Ren'Py mechanisms. Your file-like object must implement at least the read, seek, tell, and close methods.

c o n f i g . f o c u s _ c r o s s r a n g e _ p e n a l t y= 1024
This is the amount of penalty to apply to moves perpendicular to the selected direction of motion, when moving focus with the keyboard.

c o n f i g . g l _ e n a b l e= True
Set this to False to disable OpenGL acceleration. OpenGL acceleration will automatically be disabled if it's determined that the system cannot support it, so it usually isn't necessary to set this. OpenGL can also be disabled by holding down shift at startup.

c o n f i g . g l _ r e s i z e= True
Determines if the user is allowed to resize an OpenGL-drawn window.

c o n f i g . h a r d _ r o l l b a c k _ l i m i t= 100
This is the number of steps that Ren'Py will let the user interactively rollback. Set this to 0 to disable rollback entirely, although we don't recommend that, as rollback is useful to let the user see text he skipped by mistake.

c o n f i g . h i d e= renpy.hide
A function that is called when the hide statement is executed. This should take the same arguments as renpy.hide.

c o n f i g . i m a g e m a p _ a u t o _ f u n c t i o n= ...
A function that expands the a u t oproperty of a screen language imagebutton or imagemap statement into a displayable. It takes the value of the auto property, and the desired image, one of: "insensitive", "idle", "hover", "selected_idle", "selected_hover", or "ground". It should return a displayable or None. The default implementation formats the a u t oproperty with the desired image, and then checks if the computed filename exists.

c o n f i g . i m a g e m a p _ c a c h e= True
If true, imagemap hotspots will be cached to PNG files, reducing time and memory usage, but increasing the size of the game on disk. Set this to false to disable this behavior.

c o n f i g . i m p l i c i t _ w i t h _ n o n e= True
If True, then by default the equivalent of a with None statement will be performed after interactions caused by dialogue, menus input, and imagemaps. This ensures that old screens will not show up in transitions.

c o n f i g . i n t e r a c t _ c a l l b a c k s= ...
A list of functions that are called (without any arguments) when an interaction is started or restarted.

c o n f i g . j o y s t i c k= True
If True, joystick support is enabled.

c o n f i g . k e e p _ r u n n i n g _ t r a n s f o r m= True
If true, showing an image without supplying a transform or ATL block will cause the image to continue the previous transform an image with that tag was using, if any. If false, the transform is stopped.

c o n f i g . k e y m a p= dict(...)
This variable contains a keymap giving the keys and mouse buttons assigned to each possible operation. Please see the section on Keymaps for more information.

c o n f i g . l a b e l _ c a l l b a c k= None
If not None, this is a function that is called whenever a label is reached. It is called with two parameters. The first is the name of the label. The second is true if the label was reached through jumping, calling, or creating a new context, and false otherwise.

c o n f i g . l a b e l _ o v e r r i d e s= { }
This variable gives a way of causing jumps and calls of labels in Ren'Py code to be redirected to other labels. For example, if you add a mapping from "start" to "mystart", all jumps and calls to "start" will go to "mystart" instead.

c o n f i g . l a y e r _ c l i p p i n g= { }
Controls layer clipping. This is a map from layer names to (x, y, height, width) tuples, where x and y are the coordinates of the upper-left corner of the layer, with height and width giving the layer size. If a layer is not mentioned in config.layer_clipping, then it is assumed to take up the full screen.

c o n f i g . l a y e r s= [ 'master', 'transient', 'screens', 'overlay' ]

This variable gives a list of all of the layers that Ren'Py knows about, in the order that they will be displayed to the screen. (The lowest layer is the first entry in the list.) Ren'Py uses the layers "master", "transient", "screens", and "overlay" internally, so they should always be in this list.

c o n f i g . l i n t _ h o o k s= ...
This is a list of functions that are called, with no arguments, when lint is run. The functions are expected to check the script data for errors, and print any they find to standard output (using the python print statement is fine in this case).

c o n f i g . l o a d _ b e f o r e _ t r a n s i t i o n= True

If True, the start of an interaction will be delayed until all images used by that interaction have loaded. (Yeah, it's a lousy name.)

c o n f i g . l o g= None
If not None, this is expected to be a filename. Much of the text shown to the user by say or menu statements will be logged to this file.

c o n f i g . m i s s i n g _ i m a g e _ c a l l b a c k= None
If not None, this function is called when an attempt to load an image fails. It may return None, or it may return an image manipulator. If an image manipulator is returned, that image manipulator is loaded in the place of the missing image.

c o n f i g . m o u s e _ h i d e _ t i m e= 30
The mouse is hidden after this number of seconds has elapsed without any mouse input. This should be set to longer then the expected time it will take to read a single screen, so mouse users will not experience the mouse appearing then disappearing between clicks.

c o n f i g . n e w _ s u b s t i t u t i o n s= True
If true, Ren'Py will apply new-style (square-bracket) substitutions to all text displayed.

c o n f i g . o l d _ s u b s t i t u t i o n s= False
If true, Ren'Py will apply old-style (percent) substitutions to text displayed by the say and menu statements.

c o n f i g . o v e r l a y _ d u r i n g _ w i t h= True
True if we want overlays to be shown during with statements, or False if we'd prefer that they be hidden during the with statements.

c o n f i g . o v e r l a y _ l a y e r s= [ 'overlay' ]
This is a list of all of the overlay layers. Overlay layers are cleared before the overlay functions are called. "overlay" should always be in this list.

c o n f i g . p e r i o d i c _ c a l l b a c k= None
If not None, this should be a function. The function is called, with no arguments, at around 20hz.

c o n f i g . p r e d i c t _ s t a t e m e n t s= 10
This is the number of statements, including the current one, to consider when doing predictive image loading. A breadth-first search from the current statement is performed until this number of statements is considered, and any image referenced in those statements is potentially predictively loaded. Setting this to 0 will disable predictive loading of images.

c o n f i g . p r o f i l e= False
If set to True, some profiling information will be output to stdout.

c o n f i g . r o l l b a c k _ e n a b l e d= True
Should the user be allowed to rollback the game? If set to False, the user cannot interactively rollback.

c o n f i g . r o l l b a c k _ l e n g t h= 128
When there are more than this many statements in the rollback log, Ren'Py will consider trimming the log.

c o n f i g . s a y _ a l l o w _ d i s m i s s= None
If not None, this should be a function. The function is called with no arguments when the user attempts to dismiss a say statement. If this function returns true, the dismissal is allowed, otherwise it is ignored.

c o n f i g . s a y _ m e n u _ t e x t _ f i l t e r= None
If not None, then this is a function that is given the text found in strings in the say and menu statements. It is expected to return new (or the same) strings to replace them.

c o n f i g . s a y _ s u s t a i n _ c a l l b a c k s= ...
A list of functions that are called, without arguments, before the second and later interactions caused by a line of dialogue with pauses in it. Used to sustain voice through pauses.

c o n f i g . s a v e _ d u m p= False
If set to true, Ren'Py will create the file save_dump.txt whenever it saves a game. This file contains information about the objects contained in the save file. Each line consists of a relative size estimate, the path to the object, information about if the object is an alias, and a representation of the object.

c o n f i g . s a v e _ p h y s i c a l _ s i z e= True
If true, the physical size of the window will be saved in the preferences, and restored when the game resumes.

c o n f i g . s a v e d i r= ...
The complete path to the directory in which the game is saved. This should only be set in a python early block. See also config.save_directory, which generates the default value for this if it is not set during a python early block.

c o n f i g . s c e n e= renpy.scene
A function that's used in place of renpy.scene by the scene statement. Note that this is used to clear the screen, and config.show is used to show a new image. This should have the same signature as renpy.scene.

c o n f i g . s c r e e n s h o t _ c a l l b a c k= ...
A function that is called when a screenshot is taken. The function is called with a single parameter, the full filename the screenshot was saved as.

c o n f i g . s c r e e n s h o t _ c r o p= None
If not None, this should be a (x ,y ,h e i g h t ,w i d t h ) tuple. Screenshots are cropped to this rectangle before being saved.

c o n f i g . s c r e e n s h o t _ p a t t e r n= "screenshot%04d.png"
The pattern used to create screenshot files. This pattern is applied (using python's %formatting rules) to the natural numbers to generate a sequence of filenames. The filenames may be absolute, or relative to config.renpy_base. The first filename that does not exist is used as the name of the screenshot.

c o n f i g . s c r i p t _ v e r s i o n= None
If not None, this is interpreted as a script version. The library will use this script version to enable some compatibility features, if necessary. If None, we assume this is a latestversion script. This is normally set in a file added by the Ren'Py launcher when distributions are built.

c o n f i g . s e a r c h p a t h= [ 'common', 'game' ]
A list of directories that are searched for images, music, archives, and other media, but not scripts. This is initialized to a list containing "common" and the name of the game directory.

c o n f i g . s h o w= renpy.show
A function that is used in place of renpy.show by the show and scene statements. This should have the same signature as renpy.show.

c o n f i g . s k i p _ d e l a y= 75
The amount of time that dialogue will be shown for, when skipping statements using ctrl, in milliseconds. (Although it's nowhere near that precise in practice.)

c o n f i g . s k i p _ i n d i c a t o r= True
If True, the library will display a skip indicator when skipping through the script.

c o n f i g . s o u n d= True
If True, sound works. If False, the sound/mixer subsystem is completely disabled.

c o n f i g . s o u n d _ s a m p l e _ r a t e= 44100
The sample rate that the sound card will be run at. If all of your wav files are of a lower rate, changing this to that rate may make things more efficent.

c o n f i g . s t a r t _ i n t e r a c t _ c a l l b a c k s= ...
A list of functions that are called (without any arguments) when an interaction is started. These callbacks are not called when an interaction is restarted.

c o n f i g . t o p _ l a y e r s= [ ]
This is a list of names of layers that are displayed above all other layers, and do not participate in a transition that is applied to all layers. If a layer name is listed here, it should not be listed in config.layers.

c o n f i g . t r a n s i e n t _ l a y e r s= [ 'transient' ]
This variable gives a list of all of the transient layers. Transient layers are layers that are cleared after each interaction. "transient" should always be in this list.

c o n f i g . t r a n s f o r m _ u s e s _ c h i l d _ p o s i t i o n= True
If True, transforms will inherit position properties from their child. If not, they won't.

c o n f i g . v a r i a n t s= [ ... ]
A list of screen variants that are searched when choosing a screen to display to the user. This should always end with None, to ensure that the default screens are chosen. See Screen Variants.

c o n f i g . w i t h _ c a l l b a c k= None
If not None, this should be a function that is called when a with statement occurs. This function can be responsible for putting up transient things on the screen during the transition. The function is called with a single argument, which is the transition that is occurring. It is expected to return a transition, which may or may not be the transition supplied as its argument.

Image Gallery and Music Room Actions

Image Gallery A image gallery is a screen that allows the player to unlock images, and then view those images. The screen has one or more buttons associated with it, and each button has one or more associated images. Buttons and images also have conditions that determine if they have unlocked. Image galleries are managed by instances of the Gallery class. A single instance of the gallery class may be shared between multiple image gallery screens. A gallery has one or more buttons associated with it, a button has one or more images associated with it, and each image has one or more displayables associated with it. Conditions can be assigned to buttons and images. A button is unlocked when all of the conditions associated with it are satisfied and at least one image associated with that button is unlocked. An image is unlocked when all associated conditions are satisfied. Creating an image gallery consists of the following four steps. 1. Create an instance of Gallery. 2. Add buttons and images to that gallery, along with conditions that determine if the buttons and images they belong to are unlocked. This is also a multi-step process. 1. Declare a new button by calling G a l l e r y . b u t t o n ( ) . 2. Optionally, add one or more unlock conditions to the button by calling G a l l e r y . u n l o c k ( )or G a l l e r y . c o n d i t i o n ( ) . 3. Declare an image by calling G a l l e r y . i m a g e ( )with one or displayables as arguments. Or call the convenience method G a l l e r y . u n l o c k _ i m a g e ( )instead. 4. Optionally, call G a l l e r y . t r a n s f o r m ( )to associate transforms with the displayables. 5. Optionally, add one or more unlock conditions to the image by calling G a l l e r y . u n l o c k ( ) ,G a l l e r y . c o n d i t i o n ( ) , or G a l l e r y . a l l p r i o r ( ) . Additional images can be added to a button by repeating steps 3-5, while additional buttons can be added to the gallery by repeating all five steps. 3. Create an image gallery screen. The screen should display a background, and should contain navigation that allows the user to show other image galleries, or to return to the main or extras menu. 4. Add code to display the image gallery screen to the main or extras menu. Here's an example of the first three steps:
i n i tp y t h o n : #S t e p1 .C r e a t et h eg a l l e r yo b j e c t . g=G a l l e r y ( ) #S t e p2 .A d db u t t o n sa n di m a g e st ot h eg a l l e r y . #Ab u t t o nt h a tc o n t a i n sa ni m a g et h a ta u t o m a t i c a l l yu n l o c k s . g . b u t t o n ( " d a w n " ) g . i m a g e ( " d a w n 1 " ) g . u n l o c k ( " d a w n 1 " ) #T h i sb u t t o nh a sm u l t i p l ei m a g e sa s s o c a t e dw i t hi t .W eu s eu n l o c k _ i m a g e #s ow ed o n ' th a v et oc a l lb o t h. i m a g ea n d. u n l o c k .W ea l s oa p p l ya #t r a n s f o r mt ot h ef i r s ti m a g e . g . b u t t o n ( " d a r k " ) g . u n l o c k _ i m a g e ( " b i g b e a c h 1 " ) g . t r a n s f o r m ( s l o w p a n )

g . u n l o c k _ i m a g e ( " b e a c h 1m a r y " ) g . u n l o c k _ i m a g e ( " b e a c h 2 " ) g . u n l o c k _ i m a g e ( " b e a c h 3 " ) #T h i sb u t t o nh a sac o n d i t i o na s s o c i a t e dw i t hi t ,a l l o w i n gc o d e #t oc h o o s ew h i c hi m a g e su n l o c k . g . b u t t o n ( " e n d 1 " ) g . c o n d i t i o n ( " p e r s i s t e n t . u n l o c k _ 1 " ) g . i m a g e ( " t r a n s f e r " ) g . i m a g e ( " m o o n p i c " ) g . i m a g e ( " g i r l p i c " ) g . i m a g e ( " n o g i r l p i c " ) g . i m a g e ( " b a d _ e n d i n g " ) g . b u t t o n ( " e n d 2 " ) g . c o n d i t i o n ( " p e r s i s t e n t . u n l o c k _ 2 " ) g . i m a g e ( " l i b r a r y " ) g . i m a g e ( " b e a c h 1n o m o o n " ) g . i m a g e ( " b a d _ e n d i n g " ) #T h el a s ti m a g ei nt h i sb u t t o nh a sa nc o n d i t i o na s s o c i a t e dw i t hi t , #s oi tw i l lo n l yu n l o c ki ft h eu s e rg e t sb o t he n d i n g s . g . b u t t o n ( " e n d 3 " ) g . c o n d i t i o n ( " p e r s i s t e n t . u n l o c k _ 3 " ) g . i m a g e ( " l i t t l e m a r y 2 " ) g . i m a g e ( " l i t t l e m a r y " ) g . i m a g e ( " g o o d _ e n d i n g " ) g . c o n d i t i o n ( " p e r s i s t e n t . u n l o c k _ 3a n dp e r s i s t e n t . u n l o c k _ 4 " ) g . b u t t o n ( " e n d 4 " ) g . c o n d i t i o n ( " p e r s i s t e n t . u n l o c k _ 4 " ) g . i m a g e ( " h o s p i t a l 1 " ) g . i m a g e ( " h o s p i t a l 2 " ) g . i m a g e ( " h o s p i t a l 3 " ) g . i m a g e ( " h e a v e n " ) g . i m a g e ( " w h i t e " ) g . i m a g e ( " g o o d _ e n d i n g " ) g . c o n d i t i o n ( " p e r s i s t e n t . u n l o c k _ 3a n dp e r s i s t e n t . u n l o c k _ 4 " ) #T h ef i n a lt w ob u t t o n sc o n t a i ni m a g e st h a ts h o wm u l t i p l ep i c t u r e s #a tt h es a m et i m e .T h i sc a nb eu s e dt oc o m p o s ec h a r a c t e ra r to n t o #ab a c k g r o u n d . g . b u t t o n ( " d a w nm a r y " ) g . u n l o c k _ i m a g e ( " d a w n 1 " ," m a r yd a w nw i s t f u l " ) g . u n l o c k _ i m a g e ( " d a w n 1 " ," m a r yd a w ns m i l i n g " ) g . u n l o c k _ i m a g e ( " d a w n 1 " ," m a r yd a w nv h a p p y " ) g . b u t t o n ( " d a r km a r y " ) g . u n l o c k _ i m a g e ( " b e a c h 2 " ," m a r yd a r kw i s t f u l " ) g . u n l o c k _ i m a g e ( " b e a c h 2 " ," m a r yd a r ks m i l i n g " ) g . u n l o c k _ i m a g e ( " b e a c h 2 " ," m a r yd a r kv h a p p y " ) #T h et r a n s i t i o nu s e dw h e ns w i t c h i n gi m a g e s . g . t r a n s i t i o n=d i s s o l v e #S t e p3 .T h eg a l l e r ys c r e e nw eu s e . s c r e e ng a l l e r y : #E n s u r et h i sr e p l a c e st h em a i nm e n u . t a gm e n u #T h eb a c k g r o u n d . a d d" b e a c h 2 "

#Ag r i do fb u t t o n s . g r i d33 : x f i l lT r u e y f i l lT r u e #C a l lm a k e _ b u t t o nt os h o wap a r t i c u l a rb u t t o n . a d dg . m a k e _ b u t t o n ( " d a r k " ," g a l d a r k . p n g " ,x a l i g n = 0 . 5 ,y a l i g n = 0 . 5 ) a d dg . m a k e _ b u t t o n ( " d a w n " ," g a l d a w n . p n g " ,x a l i g n = 0 . 5 ,y a l i g n = 0 . 5 ) a d dg . m a k e _ b u t t o n ( " e n d 1 " ," g a l e n d 1 . p n g " ,x a l i g n = 0 . 5 ,y a l i g n = 0 . 5 ) a d dg . m a k e _ b u t t o n ( " e n d 2 " ," g a l e n d 2 . p n g " ,x a l i g n = 0 . 5 ,y a l i g n = 0 . 5 ) a d dg . m a k e _ b u t t o n ( " e n d 3 " ," g a l e n d 3 . p n g " ,x a l i g n = 0 . 5 ,y a l i g n = 0 . 5 ) a d dg . m a k e _ b u t t o n ( " e n d 4 " ," g a l e n d 4 . p n g " ,x a l i g n = 0 . 5 ,y a l i g n = 0 . 5 ) a d dg . m a k e _ b u t t o n ( " d a r km a r y " ," g a l d a r k _ m a r y . p n g " ,x a l i g n = 0 . 5 ,y a l i g n = 0 . 5 ) a d dg . m a k e _ b u t t o n ( " d a w nm a r y " ," g a l d a w n _ m a r y . p n g " ,x a l i g n = 0 . 5 ,y a l i g n = 0 . 5 ) #T h es c r e e ni sr e s p o n s i b l ef o rr e t u r n i n gt ot h em a i nm e n u .I tc o u l da l s o #n a v i g a t et oo t h e rg a l l e r ys c r e e n s . t e x t b u t t o n" R e t u r n "a c t i o nR e t u r n ( )x a l i g n0 . 5y a l i g n0 . 5

Step 4 will vary based on how your game is structured, but one way of accomplishing it is to add the following line:
t e x t b u t t o n" G a l l e r y "a c t i o nS h o w M e n u ( " g a l l e r y " )

to the main menu screen. class G a l l e r y (self) This class supports the creation of an image gallery by handling the locking of images, providing an action that can show one or more images, and a providing method that creates buttons that use that action.

t r a n s i t i o n
The transition that is used when changing images.

l o c k e d _ b u t t o n
The default displayable used by make_button for a locked button.

h o v e r _ b o r d e r
The default hover border used by make_button.

i d l e _ b o r d e r
The default idle border used by make_button.

A c t i o n (name)
An action that displays the images associated with the given button name.

a l l p r i o r (self)
A condition that is true if all prior images associated with the current button have been unlocked.

b u t t o n (name)

Creates a new button, named n a m e .

n a m e

The name of the button being created.

c o n d i t i o n (expression)
A condition that is satisfied when an expression evaluates to true.
e x p r e s s i o n

A string giving a python expression.

d i s p l a y (*displayables)
Adds a new image to the current button, where an image consists of one or more displayables.

i m a g e (*displayables)
Adds a new image to the current button, where an image consists of one or more displayables.

m a k e _ b u t t o n (name, unlocked, locked=None, hover_border=None, idle_border=None, **properties)

This creates a button that displays the images associated with the given button name.
n a m e

The name of the button that will be created.

u n l o c k e d

A displayable that is displayed for this button when it is unlocked.

l o c k e d

A displayable that is displayed for this button when it is locked. If None, the locked_button field of the gallery object is used instead.
h o v e r _ b o r d e r

A displayable that is used to overlay this button when when it is unlocked and has focus. If None, the hover_border field of the gallery object is used.
i d l e _ b o r d e r

A displayable that is used to overlay this button when when it is unlocked but unfocused. If None, the idle_border field of the gallery object is used. Additional keyword arguments become style properties of the created button object.

t r a n s f o r m (*transforms)
Applies transforms to the last image registered. This should be called with the same number of transforms as the image has displayables. The transforms are applied to the corresponding displayables. If a transform is None, the default transform is used.

u n l o c k (*images)
A condition that takes one or more image names as argument, and is satisfied when all the named images have been seen by the player. The image names should be given as strings.

u n l o c k _ i m a g e (*images)
A convenience method that is equivalent to calling image and unlock with the same

parameters. This will cause an image to be displayed if it has been seen before. The images should be specified as strings giving image names. Music Room A music room is a screen that allows the user to select and play music tracks from the game. These tracks may start off locked when the user first begins playing a particular game, and will be unlocked as the user listens to the music while playing the game. A music room is managed by an instance of the MusicRoom class. There can be more than one MusicRoom instance in a game, allowing a game to have multiple music rooms. Creating a music room consists of the following four steps: 1. Create an instance of MusicRoom. The MusicRoom constructor takes parameters to control the channel on which music is played back, and how long it takes to fade music out and back in. 2. Add music files to the instance. 3. Create a screen that uses the MusicRoom instance to create actions for buttons, imagebuttons, or hotspots. These actions can pick a track, the next or previous track, or stop and start the music. Note that the actions used are members of a MusicRoom instance, so if the MusicRoom instance is named m r , then m r . P l a y ( " t r a c k 1 . o g g " )is how you'd use the play action. 4. Add the music room screen to the main menu, or an extras menu. Here's an example of the first three steps:
i n i tp y t h o n : #S t e p1 .C r e a t eaM u s i c R o o mi n s t a n c e . m r=M u s i c R o o m ( f a d e o u t = 1 . 0 ) #S t e p2 .A d dm u s i cf i l e s . m r . a d d ( " t r a c k 1 . o g g " ,a l w a y s _ u n l o c k e d = T r u e ) m r . a d d ( " t r a c k 2 . o g g " ) m r . a d d ( " t r a c k 3 . o g g " ) #S t e p3 .C r e a t et h em u s i cr o o ms c r e e n . s c r e e nm u s i c _ r o o m : t a gm e n u f r a m e : h a sv b o x #T h eb u t t o n st h a tp l a ye a c ht r a c k . t e x t b u t t o n" T r a c k1 "a c t i o nm r . P l a y ( " t r a c k 1 . o g g " ) t e x t b u t t o n" T r a c k2 "a c t i o nm r . P l a y ( " t r a c k 2 . o g g " ) t e x t b u t t o n" T r a c k3 "a c t i o nm r . P l a y ( " t r a c k 3 . o g g " ) n u l lh e i g h t2 0 #B u t t o n st h a tl e tu sa d v a n c et r a c k s . t e x t b u t t o n" N e x t "a c t i o nm r . N e x t ( ) t e x t b u t t o n" P r e v i o u s "a c t i o nm r . P r e v i o u s ( ) n u l lh e i g h t2 0

#T h eb u t t o nt h a tl e t st h eu s e re x i tt h em u s i cr o o m . t e x t b u t t o n" M a i nM e n u "a c t i o nS h o w M e n u ( " m a i n _ m e n u " ) #S t a r tt h em u s i cp l a y i n go ne n t r yt ot h em u s i cr o o m . o n" r e p l a c e "a c t i o nm r . P l a y ( ) #R e s t o r et h em a i nm e n um u s i cu p o nl e a v i n g . o n" r e p l a c e d "a c t i o nP l a y ( " m u s i c " ," t r a c k 1 . o g g " )

Step 4 will vary based on how your game is structured, but one way of accomplishing it is to add the following line:
t e x t b u t t o n" M u s i cR o o m "a c t i o nS h o w M e n u ( " m u s i c _ r o o m " )

to the main menu screen. Using the P r e f e r e n c e s ( )function, especially P r e f e r e n c e s ( " m u s i cv o l u m e " ) , it's possible to include a volume slider on the music screen. class M u s i c R o o m (channel='music', fadeout=0.0, fadein=0.0) A music room that contains a series of songs that can be unlocked by the user, and actions that can play entries from the list in order.
c h a n n e l

The channel that this music room will operate on.

f a d e o u t

The number of seconds it takes to fade out the old music when changing tracks.
f a d e i n

The number of seconds it takes to fade in the new music when changing tracks.

N e x t (self)
An action that causes the music room to play the next unlocked file in the playlist.

P l a y (filename=None)
Causes the music room to start playing. If f i l e n a m eis given, that file begins playing. Otherwise, the currently playing file starts over (if it's unlocked), or the first file starts playing. If f i l e n a m eis given, buttons with this action will be insensitive while f i l e n a m eis locked, and will be selected when f i l e n a m eis playing.

P r e v i o u s (self)
An action that causes the music room to play the previous unlocked file in the playlist.

S t o p (self)
Stops the music.

a d d (filename, always_unlocked=False)
Adds the music file f i l e n a m eto this music room. The music room will play unlocked files in the order that they are added to the room.
a l w a y s _ u n l o c k e d

If true, the music file will be always unlocked. This allows the file to show up in the music room before it has been played in the game.

i s _ u n l o c k e d (filename)
Returns true if the filename has been unlocked (or is always unlocked), and false if it is still locked.

NVL-Mode Tutorial
There are two main styles of presentation used for visual novels. ADV-style games present dialogue and narration one line at a time, generally in a window at the bottom of the screen. NVL-style games present multiple lines on the screen at a time, in a window that takes up the entire screen. In this tutorial, we will explain how to make an NVL-mode game using Ren'Py. This tutorial assumes that you are already familiar with the basics of Ren'Py, as explained in the Quickstart manual. Getting Started NVL-mode can be added to a Ren'Py script in two steps. The first is to declare the characters to use NVL-mode, and the second is to add n v lc l e a rstatements at the end of each page. Characters can be declared to use NVL-mode by adding a k i n d = n v lparameter to each of the Character declarations. For example, if we the character declarations from the Quickstart manual are:
d e f i n es=C h a r a c t e r ( ' S y l v i e ' ,c o l o r = " # c 8 f f c 8 " ) d e f i n em=C h a r a c t e r ( ' M e ' ,c o l o r = " # c 8 c 8 f f " )

Changed to use NVL-mode, those declarations become:

d e f i n es=C h a r a c t e r ( ' S y l v i e ' ,k i n d = n v l ,c o l o r = " # c 8 f f c 8 " ) d e f i n em=C h a r a c t e r ( ' M e ' ,k i n d = n v l ,c o l o r = " # c 8 c 8 f f " ) d e f i n en a r r a t o r=C h a r a c t e r ( N o n e ,k i n d = n v l )

Note that we have also added an NVL-mode declaration of n a r r a t o r . The n a r r a t o rcharacter is used to speak lines that do not have another character name associated with it. If we ran the game like this, the first few lines would display normally, but after a while, lines would begin displaying below the bottom of the screen. To break the script into pages, include an n v lc l e a rstatement after each page. The following is an example script with pagination:
l a b e ls t a r t : " I ' l la s kh e r . . . " m" U m . . .w i l ly o u . . . " m" W i l ly o ub em ya r t i s tf o rav i s u a ln o v e l ? " n v lc l e a r " S i l e n c e . " " S h ei ss h o c k e d ,a n dt h e n . . . " s" S u r e ,b u tw h a ti sa\ " v i s u a ln o v e l ? \ " " n v lc l e a r

While nvl-mode games generally have more text per paragraph, this example demonstrates a basic NVL-mode script. (Suitable for use in a kinetic novel that does not have transitions.) Menus By default, menus are displayed in ADV-mode, taking up the full screen. There is also an alternate NVL-mode menu presentation, which displays the menus immediately after the current page of NVL-mode text. To access this alternate menu presentation, write:
i n i tp y t h o n : m e n u=n v l _ m e n u

The menu will disappear after the choice has been made, so it usually makes sense to follow menus with an "nvl clear" or some sort of indication as to the choice. Showing and Hiding the NVL-mode Window The NVL-mode window can be controlled with the standard w i n d o ws h o wand w i n d o wh i d e statements. To enable this, add the following code to your game:
i n i tp y t h o n : c o n f i g . e m p t y _ w i n d o w=n v l _ s h o w _ c o r e c o n f i g . w i n d o w _ h i d e _ t r a n s i t i o n=d i s s o l v e c o n f i g . w i n d o w _ s h o w _ t r a n s i t i o n=d i s s o l v e

Setting c o n f i g . e m p t y _ w i n d o wto n v l _ s h o w _ c o r ewill cause the NVL-mode window to be displayed during a transition. (The last two lines select the default transitions to be used for showing and hiding the window.) An example of using the window commands to show and hide the window is:
l a b e lm e a d o w : n v lc l e a r w i n d o wh i d e s c e n eb gm e a d o w w i t hf a d e w i n d o ws h o w " W er e a c h e dt h em e a d o w sj u s to u t s i d eo u rh o m e t o w n .A u t u m nw a ss o b e a u t i f u lh e r e . " " W h e nw ew e r ec h i l d r e n ,w eo f t e np l a y e dh e r e . " m" H e y . . .u m m m . . . " w i n d o wh i d e s h o ws y l v i es m i l e w i t hd i s s o l v e w i n d o ws h o w " S h et u r n e dt om ea n ds m i l e d . " " I ' l la s kh e r . . . " m" U m m m . . .w i l ly o u . . . " m" W i l ly o ub em ya r t i s tf o rav i s u a ln o v e l ? "

Customizing Characters NVL-mode characters can be customized to have several looks, hopefully allowing you to pick the one that is most appropriate to the game you are creating. 1. The default look has a character's name to the left, and dialogue indented to the right of the name. The color of the name is controlled by the ''color'' parameter.
d e f i n es=C h a r a c t e r ( ' S y l v i e ' ,k i n d = n v l ,c o l o r = " # c 8 f f c 8 " )

2. A second look has the character's name embedded in with the text. Dialogue spoken by the character is enclosed in quotes. Note that here, the character's name is placed in the ''what_prefix'' parameter, along with the open quote. (The close quote is placed in the ''what_suffix'' parameter.)
d e f i n es=C h a r a c t e r ( N o n e ,k i n d = n v l ,w h a t _ p r e f i x = " S y l v i e :\ " " , w h a t _ s u f f i x = " \ " " )

3. A third look dispenses with the character name entirely, while putting the dialogue in quotes.
d e f i n es=C h a r a c t e r ( N o n e ,k i n d = n v l ,w h a t _ p r e f i x = " \ " " ,w h a t _ s u f f i x = " \ " " )

4. Since the third look might make it hard to distinguish who's speaking, we can tint the dialogue using the ''what_color'' parameter.
d e f i n es=C h a r a c t e r ( N o n e ,k i n d = n v l ,w h a t _ p r e f i x = " \ " " ,w h a t _ s u f f i x = " \ " " , w h a t _ c o l o r = " # c 8 f f c 8 " )

5. Of course, a completely uncustomized NVL-mode character can be used, if you want to take total control of what is shown. (This is often used for the narrator.)
d e f i n es=C h a r a c t e r ( N o n e ,k i n d = n v l )

Customizing Menus There are a few styles that control the look of the menus. Here's some code showing how to customize them. See Styles and Style Properties for more information about styles.
i n i tp y t h o n : #T h ec o l o ro fam e n uc h o i c ew h e ni ti s n ' th o v e r e d . s t y l e . n v l _ m e n u _ c h o i c e . i d l e _ c o l o r=" # c c c c c c f f " #T h ec o l o ro fam e n uc h o i c ew h e ni ti sh o v e r e d . s t y l e . n v l _ m e n u _ c h o i c e . h o v e r _ c o l o r=" # f f f f f f f f " #T h ec o l o ro ft h eb a c k g r o u n do fam e n uc h o i c e ,w h e ni ti s n ' t #h o v e r e d . s t y l e . n v l _ m e n u _ c h o i c e _ b u t t o n . i d l e _ b a c k g r o u n d=" # 0 0 0 0 0 0 0 0 " #T h ec o l o ro ft h eb a c k g r o u n do fam e n uc h o i c e ,w h e ni ti s #h o v e r e d . s t y l e . n v l _ m e n u _ c h o i c e _ b u t t o n . h o v e r _ b a c k g r o u n d=" # f f 0 0 0 0 4 4 " #H o wf a rf r o mt h el e f tm e n uc h o i c e ss h o u l db ei n d e n t e d .

s t y l e . n v l _ m e n u _ c h o i c e _ b u t t o n . l e f t _ m a r g i n=2 0

Customizing the NVL window There are a few styles that control the NVL window; here's some code showing how to customize them. See Styles and Style Properties for more information about styles.
i n i tp y t h o n : #S e tt h eb a c k g r o u n do ft h eN V Lw i n d o w ;t h i si m a g es h o u l db et h e #s a m es i z ea st h es c r e e n . s t y l e . n v l _ w i n d o w . b a c k g r o u n d=" n v l _ w i n d o w . p n g " #A d ds o m ea d d i t i o n a lp a d d i n ga r o u n dt h ec o n t e n t so ft h eN V Lw i n d o w . #T h i sk e e p st h et e x ti n s i d et h eb o r d e r so fo u ri m a g e . s t y l e . n v l _ w i n d o w . x p a d d i n g=5 5 s t y l e . n v l _ w i n d o w . y p a d d i n g=5 5 #S e tt h es p a c i n gb e t w e e ne a c hb l o c ko ft e x to nt h ep a g e . #T h ed e f a u l ti s1 0p i x e l s . s t y l e . n v l _ v b o x . b o x _ s p a c i n g=1 0

You can also completely customize the screen used to display NVL text, which is named n v l ; see NVL. Paged Rollback Paged rollback causes Ren'Py to rollback one NVL-mode page at a time, rather than one block of text at a time. It can be enabled by including the following code in your script.
i n i tp y t h o n : c o n f i g . n v l _ p a g e d _ r o l l b a c k=T r u e

Script of The Question (NVL-mode Edition) You can view the full script of the NVL-mode edition of ''The Question'' here.

Advanced Displayables

Drag and Drop

Ren'Py includes drag and drop displayables that allow things to be moved around the screen with the mouse. Some of the uses of dragging are: Allowing windows to be repositioned by the user, storing the window positions. Card games that require cards to be dragged around the screen. (For example, solitaire.) Inventory systems. Drag-to-reorder systems. The drag and drop displayables make it possible to implement these and other uses of drag and drop. There are two classes involved here. The Drag class represents either something that can be dragged around the screen, something that can have a draggable dropped onto it, or something that can do both. The DragGroup class represents a group of Drags - for a drag

and drop to occur, both Drags must be part of the same drag group. The drag and drop system can be used either through the Screen Language or directly as displayables. It makes sense to use the screen language when you don't need to refer to the Drags that you create after they've been created. This might be the case if the draggable represents a window that the user places on the scren. If you need to refer to the drags after they've been created, then it's often better to create Drags directly, and add them to a DragGroup. Displayables class D r a g (d=None, drag_name=None, draggable=True, droppable=True, drag_raise=True, dragged=None, dropped=None, drag_handle=(0.0, 0.0, 1.0, 1.0), drag_joined=..., clicked=None, hovered=None, unhovered=None, **properties) A displayable that represents an object that can be dragged around its enclosing area. A Drag can also represent an area that other Drags can be dropped on. A Drag can be moved around inside is parent. Generally, its parent should be either a F i x e d ( )or D r a g G r o u p . A Drag has one child. The child's state reflects the status of the drag and drop operation:
s e l e c t e d _ h o v e r- when it is being dragged. s e l e c t e d _ i d l e- when it can be dropped on. h o v e r- when the draggable will be dragged when the mouse is clicked. i d l e- otherwise.

The drag handle is a rectangle inside the child. The mouse must be over a nontransparent pixel inside the drag handle for dragging or clicking to occur. A newly-created draggable is added to the default DragGroup. A draggable can only be in a single DragGroup - if it's added to a second group, it's removed from the first. When a Drag is first rendered, if it's position cannot be determined from the DragGroup it is in, the position of its upper-left corner is computed using the standard layout algorithm. Once that position
d

If present, the child of this Drag. Drags use the child style in preference to this, if it's not None.
d r a g _ n a m e

If not None, the name of this draggable. This is available as the n a m eproperty of draggable objects. If a Drag with the same name is or was in the DragGroup, the starting position of this Drag is taken from that Draggable.
d r a g g a b l e

If true, the Drag can be dragged around the screen with the mouse.
d r o p p a b l e

If true, other Drags can be dropped on this Drag.

d r a g _ r a i s e

If true, this Drag is raised to the top when it is dragged. If it is joined to other Drags, all joined drags are raised.
d r a g g e d

A callback (or list of callbacks) that is called when the Drag has been dragged. It is called with two arguments. The first is a list of Drags that are being dragged. The second is either a Drag that is being dropped onto, or None of a drop did not occur. If the callback returns a value other than None, that value is returned as the result of the

interaction.
d r o p p e d

A callback (or list of callbacks) that is called when this Drag is dropped onto. It is called with two arguments. The first is the Drag being dropped onto. The second is a list of Drags that are being dragged. If the callback returns a value other than None, that value is returned as the result of the interaction. When a dragged and dropped callback are triggered for the same event, the dropped callback is only called if dragged returns None.
c l i c k e d

A callback this is called, with no arguments, when the Drag is clicked without being moved. A droppable can also be focused and clicked. If the callback returns a value othe than None, that value is returned as the result of the interaction.
d r a g _ h a n d l e

A (x, y, width, height) tuple, giving the position of the drag handle within the child. In this tuple, integers are considered to be a literal number of pixels, while floats are relative to the size of the child.
d r a g _ j o i n e d

This is called with the current Drag as an argument. It's expected to return a list of [ (drag, x, y) ] tuples, giving the draggables to drag as a unit. xand yare the offsets of the drags relative to each other, they are not relative to the corner of this drag. Except for d , all of the parameters are available as fields (with the same name) on the Drag object. In addition, after the drag has been rendered, the following fields become available:
x ,y

The position of the Drag relative to its parent, in pixels.

w ,h

The width and height of the Drag's child, in pixels.

s e t _ c h i l d ( d)
Changes the child of this drag to d .

s n a p (x, y, delay=0)
Changes the position of the drag. If the drag is not showing, then the position change is instantaneous. Otherwise, the position change takes d e l a yseconds, and is animated as a linear move.

t o p (self)
Raises this displayable to the top of its drag_group. class D r a g G r o u p (*children, **properties) Represents a group of Drags. A Drag is limited to the boundary of its DragGroup. Dropping only works between Drags that are in the same DragGroup. Drags may only be raised when they are inside a DragGroup. A DragGroup is laid out like a F i x e d ( ) . All positional parameters to the DragGroup constructor should be Drags, that are added to the DragGroup.

a d d (child)
Adds c h i l d , which must be a Drag, to this DragGroup.

g e t _ c h i l d _ b y _ n a m e (name)
Returns the first child of this DragGroup that has a drag_name of name.

r e m o v e (child)
Removes c h i l dfrom this DragGroup. Examples An example of a say screen that allows the user to choose the location of the window by dragging it around the screen.:
s c r e e ns a y : d r a g : d r a g _ n a m e" s a y " y a l i g n1 . 0 d r a g _ h a n d l e( 0 ,0 ,1 . 0 ,3 0 ) x a l i g n0 . 5 w i n d o wi d" w i n d o w " : #E n s u r et h a tt h ew i n d o wi ss m a l l e rt h a nt h es c r e e n . x m a x i m u m6 0 0 h a sv b o x i fw h o : t e x tw h oi d" w h o " t e x tw h a ti d" w h a t "

Here's a more complicated example, one that shows how dragging can be used to influence gameplay. It shows how dragging can be used to send a character to a location:
i n i tp y t h o n : d e fd e t e c t i v e _ d r a g g e d ( d r a g s ,d r o p ) : i fn o td r o p : r e t u r n s t o r e . d e t e c t i v e=d r a g s [ 0 ] . d r a g _ n a m e s t o r e . c i t y=d r o p . d r a g _ n a m e r e t u r nT r u e s c r e e ns e n d _ d e t e c t i v e _ s c r e e n : #Am a pa sb a c k g r o u n d . a d d" e u r o p e . j p g " #Ad r a gg r o u pe n s u r e st h a tt h ed e t e c t i v e sa n dt h ec i t i e sc a nb e #d r a g g e dt oe a c ho t h e r . d r a g g r o u p : #O u rd e t e c t i v e s . d r a g : d r a g _ n a m e" I v y " c h i l d" i v y . p n g " d r o p p a b l eF a l s e

d r o p p a b l eF a l s e d r a g g e dd e t e c t i v e _ d r a g g e d x p o s1 0 0y p o s1 0 0 d r a g : d r a g _ n a m e" Z a c k " c h i l d" z a c k . p n g " d r o p p a b l eF a l s e d r a g g e dd e t e c t i v e _ d r a g g e d x p o s1 5 0y p o s1 0 0 #T h ec i t i e st h e yc a ng ot o . d r a g : d r a g _ n a m e" L o n d o n " c h i l d" l o n d o n . p n g " d r a g g a b l eF a l s e x p o s4 5 0y p o s1 4 0 d r a g : d r a g _ n a m e" P a r i s " d r a g g a b l eF a l s e c h i l d" p a r i s . p n g " x p o s5 0 0y p o s2 8 0 l a b e ls e n d _ d e t e c t i v e : " W en e e dt oi n v e s t i g a t e !W h os h o u l dw es e n d ,a n dw h e r es h o u l dt h e yg o ? " c a l ls c r e e ns e n d _ d e t e c t i v e _ s c r e e n " O k a y ,w e ' l ls e n d[ d e t e c t i v e ]t o[ c i t y ] . "

More complicated systems take significant programming skill to get right. The Ren'Py cardgame framework is both an example of how to use drag and drop in a complex system, and useful for making card games in its own right.

Sprites
To support the display of a large number of images at once, Ren'Py supports a sprite system. This system allows one to create sprites, where each sprite contains a displayable. The sprites can then have their location on the screen and vertical ordering changed. If one ignores performance, the sprite system is conceptually similar to a F i x e d ( )wrapping T r a n s f o r m ( ) s. Sprites are much faster than transforms, but also less flexible. The big performance improvement of sprites is that each Displayable is rendered only once per frame, even if that Displayable is used by many sprites. The limitation is that Sprites only allow one to change their xoffset and yoffset, rather than the many properties that a Transform has. To use the sprite system, create a SpriteManager object, and then call its create method to create new particles. As necessary, update the xoffset, yoffset, and zorder fields of each sprite to move it around the screen. By supplying u p d a t eand e v e n targuments to SpriteManager, you can have the sprites change over time, and react to user input. Sprite Classes class S p r i t e This represents a sprite that is managed by the SpriteManager. It contains fields that control the placement of the sprite on the screen. Sprites should not be created directly. Instead, they should be created by calling S p r i t e M a n a g e r . c r e a t e ( ) .

The fields of a sprite object are:

x ,y

The x and y coordinates of the upper-left corner of the sprite, relative to the SpriteManager.
z o r d e r

An integer that's used to control the order of this sprite in the relative to the other sprites in the SpriteManager. The larger the number is, the closer to the viewer the sprite is.
e v e n t s

If True, then events are passed to child. If False, the default, the children igore events (and hence don't spend time processing them). The methods of a Sprite object are:

d e s t r o y (self)
Destroys this sprite, preventing it from being displayed and removing it from the SpriteManager.

s e t _ c h i l d ( d)
Changes the Displayable associated with this sprite to d . class S p r i t e M a n a g e r (update=None, event=None, predict=None, ignore_time=False, **properties) This displayable manages a collection of sprites, and displays them at the fastest speed possible.
u p d a t e

If not None, a function that is called each time a sprite is rendered by this sprite manager. It is called with one argument, the time in seconds since this sprite manager was first displayed. It is expected to return the number of seconds until the function is called again, and the SpriteManager is rendered again.
e v e n t

If not None, a function that is called when an event occurs. It takes as arguments: * A pygame event object. * The x coordinate of the event. * The y coordinate of the event. * The time since the sprite manager was first shown. If it returns a non-None value, the interaction ends, and that value is returned.
p r e d i c t

If not None, a function that returns a list of displayables. These displayables are predicted when the sprite manager is.
i g n o r e _ t i m e

If True, then time is ignored when rendering displayables. This should be used when the sprite manager is used with a relatively small pool of images, and those images do not change over time. This should only be used with a small number of displayables, as it will keep all displayables used in memory for the life of the SpriteManager. After being rendered once (before the u p d a t efunction is called), SpriteManagers have the following fields:
w i d t h ,h e i g h t

The width and height of this SpriteManager, in pixels.

SpriteManagers have the following methods:

c r e a t e ( d)
Creates a new Sprite for the displayable d , and adds it to this SpriteManager.

S n o w B l o s s o m (d, count=10, border=50, xspeed=(20, 50), yspeed=(100, 200), start=0, fast=False, horizontal=False)
The snowblossom effect moves multiple instances of a sprite up, down, left or right on the screen. When a sprite leaves the screen, it is returned to the start.
d

The displayable to use for the sprites.

b o r d e r

The size of the border of the screen. The sprite is considered to be on the screen until it clears the border, ensuring that sprites do not disappear abruptly.
x s p e e d ,y s p e e d

The speed at which the sprites move, in the horizontal and vertical directions, respectively. These can be a single number or a tuple of two numbers. In the latter case, each particle is assigned a random speed between the two numbers. The speeds can be positive or negative, as long as the second number in a tuple is larger than the first.
s t a r t

The delay, in seconds, before each particle is added. This can be allows the particles to start at the top of the screen, while not looking like a "wave" effect.
f a s t

If true, particles start in the center of the screen, rather than only at the edges.
h o r i z o n t a l

If true, particles appear on the left or right side of the screen, rather than the top or bottom. Sprite Examples The SnowBlossom class is an easy-to use way of placing falling things on the screen.
i m a g es n o w=S n o w B l o s s o m ( " s n o w . p n g " ,c o u n t = 1 0 0 )

This example shows how a SpriteManager can be used to create complex behaviors. In this case, it shows 400 particles, and has them avoid the mouse.
i n i tp y t h o n : i m p o r tm a t h d e fr e p u l s o r _ u p d a t e ( s t ) : #I fw ed o n ' tk n o ww h e r et h em o u s ei s ,g i v eu p . i fr e p u l s o r _ p o si sN o n e : r e t u r n. 0 1 p x ,p y=r e p u l s o r _ p o s #F o re a c hs p r i t e . . . f o rii nr e p u l s o r _ s p r i t e s : #C o m p u t et h ev e c t o rb e t w e e ni ta n dt h em o u s e .

#C o m p u t et h ev e c t o rb e t w e e ni ta n dt h em o u s e . v x=i . x-p x v y=i . y-p y #G e tt h ev e c t o rl e n g t h ,n o r m a l i z et h ev e c t o r . v l=m a t h . h y p o t ( v x ,v y ) i fv l> =1 5 0 : c o n t i n u e #C o m p u t et h ed i s t a n c et om o v e . d i s t a n c e=3 . 0*( 1 5 0-v l )/1 5 0 #M o v e i . x+ =d i s t a n c e*v x/v l i . y+ =d i s t a n c e*v y/v l #E n s u r ew es t a yo nt h es c r e e n . i fi . x<2 : i . x=2 i fi . x>r e p u l s o r . w i d t h-2 : i . x=r e p u l s o r . w i d t h-2 i fi . y<2 : i . y=2 i fi . y>r e p u l s o r . h e i g h t-2 : i . y=r e p u l s o r . h e i g h t-2 r e t u r n. 0 1 #O na ne v e n t ,r e c o r dt h em o u s ep o s i t i o n . d e fr e p u l s o r _ e v e n t ( e v ,x ,y ,s t ) : s t o r e . r e p u l s o r _ p o s=( x ,y ) l a b e lr e p u l s o r _ d e m o : p y t h o n : #C r e a t eas p r i t em a n a g e r . r e p u l s o r=S p r i t e M a n a g e r ( u p d a t e = r e p u l s o r _ u p d a t e ,e v e n t = r e p u l s o r _ e v e n t ) r e p u l s o r _ s p r i t e s=[] r e p u l s o r _ p o s=N o n e #E n s u r ew eo n l yh a v eo n es m i l ed i s p l a y a b l e . s m i l e=I m a g e ( " s m i l e . p n g " ) #A d d4 0 0s p r i t e s . f o rii nr a n g e ( 4 0 0 ) : r e p u l s o r _ s p r i t e s . a p p e n d ( r e p u l s o r . c r e a t e ( s m i l e ) ) #P o s i t i o nt h e4 0 0s p r i t e s . f o rii nr e p u l s o r _ s p r i t e s : i . x=r e n p y . r a n d o m . r a n d i n t ( 2 ,7 9 8 ) i . y=r e n p y . r a n d o m . r a n d i n t ( 2 ,5 9 8 ) d e ls m i l e d e li #A d dt h er e p u l s o rt ot h es c r e e n . s h o we x p r e s s i o nr e p u l s o ra sr e p u l s o r " . . . "

h i d er e p u l s o r #C l e a nu p . p y t h o n : d e lr e p u l s o r d e lr e p u l s o r _ s p r i t e s d e lr e p u l s o r _ p o s

Python and Ren'Py

Statement Equivalents
To allow Ren'Py to be scripted in python, each Ren'Py statement has equivalent Python code. This usually consists of a Python function, but may also consist of a code pattern that performs an action equivalent to the statement. Dialogue The Ren'Py say statement is equivalent to calling the character object as a function. The following code displays the same line twice:
e" H e l l o ,w o r l d . " $e ( " H e l l o ,w o r l d . " )

Displaying narration can be done the same way, by using the n a r r a t o rcharacter. When calling a character, it's possible to supply the keyword argument i n t e r a c t . When interact is false, Ren'Py will display the character dialogue box, and will then return before performing an interaction. This equivalence of characters and function objects works in the other direction as well. It is possible to declare a python function, and then use that function in the place of a character object. For example, the following function uses a variable to choose between two characters.
d e f i n el u c y _ n o r m a l=C h a r a c t e r ( " L u c y " ) d e f i n el u c y _ e v i l=C h a r a c t e r ( " E v i lL u c y " ) i n i tp y t h o n : d e fl ( w h a t ,* * k w a r g s ) : i fl u c y _ i s _ e v i l : l u c y _ e v i l ( w h a t ,* * k w a r g s ) e l s e : l u c y _ n o r m a l ( w h a t ,* * k w a r g s ) l a b e ls t a r t : $l u c y _ i s _ e v i l=F a l s e l" U s u a l l y ,If e e lq u i t en o r m a l . " $l u c y _ i s _ e v i l=T r u e l" B u ts o m e t i m e s ,Ig e tr e a l l ym a d ! "

A function used in this way should either ignore unknown keyword arguments, or pass them to a character function. Doing this will allow the game to continue working if Ren'Py adds additional keyword arguments to character calls. Displaying Images The image, scene, show, and hide statements each have an equivalent python function.
r e n p y . h i d e (name, layer='master')

Hides an image from a layer. The python equivalent of the hide statement.
n a m e

The name of the image to hide. Only the image tag is used, and any image with the tag is hidden (the precise name does not matter).
l a y e r

The layer on which this function operates.

r e n p y . i m a g e (name, d)

Defines an image. This function is the python equivalent of the image statement.
n a m e

The name of the image to display, a string.

d

The displayable to associate with that image name. This function may only be run from inside an init block. It is an error to run this function once the game has started.
r e n p y . s c e n e (layer='master')

Removes all displayables from l a y e r . This is equivalent to the scene statement, when the scene statement is not given an image to show. A full scene statement is equivalent to a call to renpy.scene followed by a call to r e n p y . s h o w ( ) . For example:
s c e n eb gb e a c h

is equivalent to:
$r e n p y . s c e n e ( ) $r e n p y . s h o w ( " b gb e a c h " )

r e n p y . s h o w (name, at_list=[], layer='master', what=None, zorder=0, tag=None,

behind=[]) Shows an image on a layer. This is the programmatic equivalent of the show statement.
n a m e

The name of the image to show, a string.

a t _ l i s t

A list of transforms that are applied to the image. The equivalent of the a tproperty.
l a y e r

A string, giving the name of the layer on which the image will be shown. The equivalent of the o n l a y e rproperty.
w h a t

If not None, this is a displayable that will be shown in lieu of looking on the image. (This is the equivalent of the show expression statement.) When a w h a tparameter is given, n a m ecan be used to associate a tag with the image.
z o r d e r

An integer, the equivalent of the z o r d e rproperty.

t a g

A string, used to specify the the image tag of the shown image. The equivalent of the a sproperty.
b e h i n d

A list of strings, giving image tags that this image is shown behind. The equivalent of the b e h i n dproperty. Transitions The equivalent of the with statement is the renpy.with_statement function.
r e n p y . w i t h _ s t a t e m e n t (trans, always=False)

Causes a transition to occur. This is the python equivalent of the with statement.
t r a n s

The transition.
a l w a y s

If True, the transition will always occur, even if the user has disabled transitions. This function returns true if the user chose to interrupt the transition, and false otherwise.

Saving, Loading, and Rollback

Ren'Py has support for saving game state, loading game state, and rolling back to a previous game state. Although implemented in a slightly different fashion, rollback can be thought of as saving the game at the start of each statement that interacts with the user, and loading saves when the user rolls back.
Note While we usually attempt to keep save compatibility between releases, this compatibility is not guaranteed. We may decide to break save-compatibility if doing so provides a sufficiently large benefit.

What is Saved Ren'Py attempts to save the game state. This includes both internal state and python state. The internal state consists of all aspects of Ren'Py that are intented to change once the game has started, and includes:

The The The The The

current statement, and all statements that can be returned to. images and displayables that are being shown. screens being shown, and the values of variables within those screens. music that Ren'Py is playing. list of nvl-mode text blocks.

The python state consists of the variables in the store that have changed since the game began, and all objects reachable from those variables. Note that it's the change to the variables that matters - changes to fields in objects will not cause those objects to be saved. In this example:
d e f i n ea=1 d e f i n eo=o b j e c t ( ) l a b e ls t a r t : $b=1 $o . v a l u e=4 2

only bwill be saved. A will not be saved because it does not change once the game begins. Ois not saved because it does not change - the object it refers to changes, but the variable itself does not. What isn't Saved Python variables that are not changed before the game begins will not be saved. This can be a major problem if a variable that is saved and one that is refer to the same object. (Alias the object.) In this example:
i n i tp y t h o n : a=o b j e c t ( ) a . f=1 l a b e ls t a r t : $b=a $b . f=2 " a . f = [ a . f ]b . f = [ b . f ] " aand bare aliased. Saving and loading may break this aliasing, causing aand bto refer to

different objects. Since this can be very confusing, it's best to avoid aliasing saved and unsaved variables. (This is rare to encounter directly, but might come up when an unsaved variable and saved field alias.) There are several other kinds of state that isn't saved: control flow path Ren'Py only saves the current statement, and the statement it needs to return to. It doesn't remember how it got there. Importantly, if code (like variable assignments) is added to the game, it won't run. mappings of image names to displayables Since this mapping is not saved, the image may change to a new image when the game loads again. This allows an image to change to a new file as the game evolves. configuration variables, styles, and style properties Configuration variables and styles aren't saved as part of the game. Therefore, they should only be changed in init blocks, and left alone once the game has started.

Where Ren'Py Saves Saves occur at the start of a Ren'Py statement in the outermost interaction context. What's important here is to note that saving occurs at the start of a statement. If a load or rollback occurs in the middle of a statement that interacts multiple times, the state will be the state that was active when the statement began. This can be a problem in python-defined statements. In code like:
p y t h o n : i=0 w h i l ei<1 0 : i+ =1 n a r r a t o r ( " T h ec o u n ti sn o w[ i ] . " )

if the user saves and loads in the middle, the loop will begin anew. Using similar code in Ren'Py - rather than Python - avoids this problem.:
$i=0 w h i l ei<1 0 : $i+ =1 " T h ec o u n ti sn o w[ i ] . "

What Ren'Py can Save Ren'Py uses the python pickle system to save game state. This module can save: Basic types, such as True, False, None, int, str, float, complex, str, and unicode objects. Compound types, like lists, tuples, sets, and dicts. Creator-defined objects, classes, functions, methods, and bound methods. For pickling these functions to succeed, they must remain available under their original names. Character, Displayable, Transform, and Transition objects. There are certain types that cannot be pickled: Render objects. Iterator objects. File-like objects. Inner functions and lambdas. By default, Ren'Py uses the cPickle module to save the game. Setting c o n f i g . u s e _ c p i c k l ewill make Ren'Py use the pickle module instead. This makes the game slower, but is better at reporting save errors. Save Functions and Variables There is one variable that is used by the high-level save system:

s a v e _ n a m e= ...
This is a string that is stored with each save. It can be used to give a name to the save, to help users tell them apart. There are a number of high-level save actions and functions defined in the screen actions. In addition, there are the following low-level save and load actions.
r e n p y . c a n _ l o a d (filename, test=False)

Returns true if f i l e n a m eexists as a save file, and False otherwise.

r e n p y . l i s t _ s a v e d _ g a m e s (regexp='.', fast=False)

Lists the save games. For each save game, returns a tuple containing: The filename of the save. The extra_info that was passed in. A displayable that, when displayed, shows the screenshot that was used when saving the game. The time the game was stayed at, in seconds since the UNIX epoch.
r e g e x p

A regular expression that is matched against the start of the filename to filter the list.
f a s t

If fast is true, the filename is returned instead of the tuple.

r e n p y . l o a d (filename)

Loads the game state from f i l e n a m e . This function never returns.

r e n p y . r e n a m e _ s a v e (old, new)

Renames a save from o l dto n e w .

r e n p y . s a v e (filename, extra_info='')

Saves the game state to a save slot.

f i l e n a m e

A string giving the name of a save slot. Despite the variable name, this corresponds only loosely to filenames.
e x t r a _ i n f o

An additional string that should be saved to the save file. Usually, this is the value of s a v e _ n a m e .
r e n p y . t a k e _ s c r e e n s h o t ( )should be called before this function. r e n p y . t a k e _ s c r e e n s h o t (scale=None, background=False)

Causes a screenshot to be taken. This screenshot will be saved as part of a save game.
r e n p y . u n l i n k _ s a v e (filename)

Deletes the save with the given f i l e n a m e . Rollback Rollback allows the user to revert the game to an earlier state in much the same way as undo/redo systems that are available in most modern applications. While the system takes care of maintaining the visuals and game variables during rollback events, there are several things that should be considered while creating a game.
Supporting Rollback and Roll Forward

Most Ren'Py statements automatically support rollback and roll forward. If you call u i . i n t e r a c t ( )directly, you'll need to add support for rollback and roll-forward yourself. This can be done using the following structure:
#T h i si sN o n ei fw e ' r en o tr o l l i n gb a c k ,o re l s et h ev a l u et h a tw a s #p a s s e dt oc h e c k p o i n tl a s tt i m ei fw e ' r er o l l i n gf o r w a r d . r o l l _ f o r w a r d=r e n p y . r o l l _ f o r w a r d _ i n f o ( ) #S e tu pt h es c r e e nh e r e . . . #I n t e r a c tw i t ht h eu s e r . r v=u i . i n t e r a c t ( r o l l _ f o r w a r d = r o l l _ f o r w a r d ) #S t o r et h er e s u l to ft h ei n t e r a c t i o n . r e n p y . c h e c k p o i n t ( r v )

It's important that your game does not interact with the user after renpy.checkpoint has been called. (If you do, the user may not be able to rollback.)
r e n p y . c h e c k p o i n t (data=None)

Makes the current statement a checkpoint that the user can rollback to. Once this function has been called, there should be no more interaction with the user in the current statement.
d a t a

This data is returned by r e n p y . r o l l _ f o r w a r d _ i n f o ( )when the game is being rolled back.

r e n p y . i n _ r o l l b a c k ()

Returns true if the game has been rolled back.

r e n p y . r o l l _ f o r w a r d _ i n f o ()

When in rollback, returns the data that was supplied to r e n p y . c h e c k p o i n t ( )the last time this statement executed. Outside of rollback, returns None.
Blocking Rollback

Warning Blocking rollback is a user-unfriendly thing to do. If a user mistakenly clicks on an unintended choice, he or she will be unable to correct their mistake. Since rollback is equivalent to saving and loading, your users will be forced to save more often, breaking game engagement.

It is possible to disable rollback in part or in full. If rollback is not wanted at all, it can simply be turned of through the c o n f i g . r o l l b a c k _ e n a b l e doption. More common is a partial block of rollback. This can be achieved by the r e n p y . b l o c k _ r o l l b a c k ( )function. When called, it will instruct Ren'Py not to roll back before that point. For example:
l a b e lf i n a l _ a n s w e r : " I st h a ty o u rf i n a la n s w e r ? " m e n u : " Y e s " : j u m pn o _ r e t u r n

" N o " : " W eh a v ew a y so fm a k i n gy o ut a l k . " " Y o us h o u l dc o n t e m p l a t et h e m . " " I ' l la s ky o uo n em o r et i m e . . . " j u m pf i n a l _ a n s w e r l a b e ln o _ r e t u r n : $r e n p y . b l o c k _ r o l l b a c k ( ) " S ob ei t .T h e r e ' sn ot u r n i n gb a c kn o w . "

When the label no_return is reached, Ren'Py won't allow a rollback back to the menu.
Fixing Rollback

Fixing rollback provides for an intemediate choice between unconstrained rollback and blocking rollback entirely. Rollback is allowed, but the user is not allowed to make changes to their decisions. Fixing rollback is done with the r e n p y . f i x _ r o l l b a c k ( )function, as shown in the following example:
l a b e lf i n a l _ a n s w e r : " I st h a ty o u rf i n a la n s w e r ? " m e n u : " Y e s " : j u m pn o _ r e t u r n " N o " : " W eh a v ew a y so fm a k i n gy o ut a l k . " " Y o us h o u l dc o n t e m p l a t et h e m . " " I ' l la s ky o uo n em o r et i m e . . . " j u m pf i n a l _ a n s w e r l a b e ln o _ r e t u r n : $r e n p y . f i x _ r o l l b a c k ( ) " S ob ei t .T h e r e ' sn ot u r n i n gb a c kn o w . "

Now, after the fix_rollback function is called, it will still be possible for the user to roll back to the menu. However, it will not be possible to make a different choice. There are some caveats to consider when designing a game for fix_rollback. Ren'Py will automatically take care of locking any data that is given to c h e c k p o i n t ( ) . However, due to the generic nature of Ren'Py, it is possible to write Python code that bypasses this and changes things in ways that may have unpredictable results. It is up to the game designer to block rollback at problematic locations or write additional code to deal with it. The internal user interaction options for menus, r e n p y . i n p u t ( )and r e n p y . i m a g e m a p ( )are designed to fully work with fix_rollback.
Styling Fixed Rollback

Because fix_rollback changes the functionality of menus and imagemaps, it is advisable to reflect this in the appearance. To do this, it is important to understand how the widget states of the menu buttons are changed. There are two modes that can be selected through the c o n f i g . f i x _ r o l l b a c k _ w i t h o u t _ c h o i c eoption. The default option will set the chosen option to "selected", thereby activating the style properties with the "selected_" prefix. All other buttons will be made insensitive and show using the properties with the "insensitive_" prefix. Effectively this leaves the menu with a single selectable choice.

When the c o n f i g . f i x _ r o l l b a c k _ w i t h o u t _ c h o i c eoption is set to False, all buttons are made insensitive. This means that the chosen option will use the "selected_insensitive_" prefix for the style properties while the other buttons use properties with the "insensitive_" prefix.
Fixed Rollback and Custom Screens

When writing custom Python routines that must play nice with the fix_rollback system there are a few simple things to know. First of all the r e n p y . i n _ f i x e d _ r o l l b a c k ( )function can be used to determine whether the game is currently in fixed rollback state. Second, when in fixed rollback state, u i . i n t e r a c t ( )will always return the supplied roll_forward data regardless of what action was performed. This effectively means that when the u i . i n t e r a c t ( ) /r e n p y . c h e c k p o i n t ( )functions are used, most of the work is done. To simplify the creation of custom screens, two actions are provided to help with the most common uses. The u i . C h o i c e R e t u r n ( )action returns the value when the button it is attached to is clicked. The u i . C h o i c e J u m p ( )action can be used to jump to a script label. However, this action only works properly when the screen is called trough a c a l ls c r e e nstatement. Example:
s c r e e nd e m o _ i m a g e m a p : i m a g e m a p : g r o u n d" i m a g e m a p _ g r o u n d . j p g " h o v e r" i m a g e m a p _ h o v e r . j p g " s e l e c t e d _ i d l e" i m a g e m a p _ s e l e c t e d _ i d l e . j p g " s e l e c t e d _ h o v e r" i m a g e m a p _ h o v e r . j p g "

h o t s p o t( 8 ,2 0 0 ,7 8 ,7 8 )a c t i o nu i . C h o i c e J u m p ( " s w i m m i n g " ," g o _ s w i m m i n g " ,b l o c k _ a l l h o t s p o t( 2 0 4 ,5 0 ,7 8 ,7 8 )a c t i o nu i . C h o i c e J u m p ( " s c i e n c e " ," g o _ s c i e n c e _ c l u b " ,b l o c k _ a h o t s p o t( 4 5 2 ,7 9 ,7 8 ,7 8 )a c t i o nu i . C h o i c e J u m p ( " a r t " ," g o _ a r t _ l e s s o n s " ,b l o c k _ a l l h o t s p o t( 6 0 2 ,3 1 6 ,7 8 ,7 8 )a c t i o nu i C h o i c e J u m p ( " h o m e " ," g o _ h o m e " ,b l o c k _ a l l = F a l s e

Example:
p y t h o n : r o l l _ f o r w a r d=r e n p y . r o l l _ f o r w a r d _ i n f o ( ) i fr o l l _ f o r w a r dn o ti n( " R o c k " ," P a p e r " ," S c i s s o r s " ) : r o l l _ f o r w a r d=N o n e

u i . h b o x ( ) u i . i m a g e b u t t o n ( " r o c k . p n g " ," r o c k _ h o v e r . p n g " ,s e l e c t e d _ i n s e n s i t i v e = " r o c k _ h o v e r . p n g " , u i . i m a g e b u t t o n ( " p a p e r . p n g " ," p a p e r _ h o v e r . p n g " ,s e l e c t e d _ i n s e n s i t i v e = " p a p e r _ h o v e r . p n g " u i . i m a g e b u t t o n ( " s c i s s o r s . p n g " ," s c i s s o r s _ h o v e r . p n g " ,s e l e c t e d _ i n s e n s i t i v e = " s c i s s o r s _ h o v e u i . c l o s e ( ) i fr e n p y . i n _ f i x e d _ r o l l b a c k ( ) : u i . s a y b e h a v i o r ( ) c h o i c e=u i . i n t e r a c t ( r o l l _ f o r w a r d = r o l l _ f o r w a r d ) r e n p y . c h e c k p o i n t ( c h o i c e ) $r e n p y . f i x _ r o l l b a c k ( ) m" [ c h o i c e ] ! "

Rollback-blocking and -fixing Functions

r e n p y . b l o c k _ r o l l b a c k ()

Prevents the game from rolling back to before the current statement.
r e n p y . f i x _ r o l l b a c k ()

Prevents the user from changing decisions made before the current statement.
r e n p y . i n _ f i x e d _ r o l l b a c k ()

Returns true if rollback is currently occurring and the current context is before an executed renpy.fix_rollback() statement.
u i . C h o i c e J u m p (label, value, location=None, block_all=None)

A menu choice action that returns v a l u e , while managing the button state in a manner consistent with fixed rollback. (See block_all for a description of the behavior.)
l a b e l

The label text of the button. For imagebuttons and hotspots this can be anything. This label is used as a unique identifier of the options within the current screen. Together with l o c a t i o nit is used to store whether this option has been chosen.
v a l u e

The location to jump to.

l o c a t i o n

A unique location identifier for the current choices screen.

b l o c k _ a l l

If false, the button is given the selected role if it was the chosen choice, and insensitive if it was not selected. If true, the button is always insensitive during fixed rollback. If None, the value is taken from the c o n f i g . f i x _ r o l l b a c k _ w i t h o u t _ c h o i c evariable. When true is given to all items in a screen, it will become unclickable (rolling forward will still work). This can be changed by calling u i . s a y b e h a v i o r ( )before the call to u i . i n t e r a c t ( ) .
u i . C h o i c e R e t u r n (label, value, location=None, block_all=None)

A menu choice action that returns v a l u e , while managing the button state in a manner consistent with fixed rollback. (See block_all for a description of the behavior.)
l a b e l

The label text of the button. For imagebuttons and hotspots this can be anything. This label is used as a unique identifier of the options within the current screen. Together with l o c a t i o nit is used to store whether this option has been chosen.
v a l u e

The value this is returned when the choice is chosen.

l o c a t i o n

A unique location identifier for the current choices screen.

b l o c k _ a l l

If false, the button is given the selected role if it was the chosen choice, and insensitive if it was not selected. If true, the button is always insensitive during fixed rollback. If None, the value is taken from the c o n f i g . f i x _ r o l l b a c k _ w i t h o u t _ c h o i c evariable.

When true is given to all items in a screen, it will become unclickable (rolling forward will still work). This can be changed by calling u i . s a y b e h a v i o r ( )before the call to u i . i n t e r a c t ( ) .

Transforms and Transitions in Python

Python can be used to create new transforms and transitions for use by Ren'Py scripts. Transforms A transform is a python callable that, when called with a displayable, returns another displayable. For example:
i n i tp y t h o n : #T h i si sat r a n s f o r mt h a tu s e st h er i g h ta n d #l e f tt r a n s f o r m s . d e fr i g h t _ o r _ l e f t ( d ) : i fs w i t c h : r e t u r nr i g h t ( d ) e l s e : r e t u r nl e f t ( d )

The python equivalent of an ATL transform is a Transform object. class T r a n s f o r m (child=None, function=None, **properties) A transform applies operations such as cropping, rotation, scaling, and alpha-blending to its child. A transform object has fields corresponding to the transform properties, which it applies to its child.
c h i l d

The child the transform applies to.

f u n c t i o n

If not none, this is a function that is called when the transform is rendered. The function is called with three arguments: The transform object. The shown timebase, in seconds. The animation timebase, in seconds. The function should return a delay, in seconds, after which it will be called again, or None to never be called again. Additional arguments are taken as values to set transform properties to.

h i d e _ r e q u e s t
This is set to true when the function is caled, to indicate that the transform is being hidden.

h i d e _ r e s p o n s e
If hide request is true, this can be set to false to prevent the transform from being hidden.

s e t _ c h i l d (child)
Call this method with a new c h i l dto change the child of this transform.

u p d a t e ()
This should be called when a transform property field is updated outside of the callback method, to ensure that the change takes effect. Transitions A transition is a python callable that, when called with two keyword arguments, returns a displayable that performs the transition effect. The two keyword arguments are:
o l d _ w i d g e t

A displayable representing the old screen.

n e w _ w i d g e t

A displayable representing the new screen. The returned displayable should have a d e l a yfield, which gives the number of seconds the transition should run for. For example:
i n i tp y t h o n : d e fd i s s o l v e _ o r _ p i x e l l a t e ( o l d _ w i d g e t = N o n e ,n e w _ w i d g e t = N o n e ) : i fp e r s i s t e n t . w a n t _ p i x e l l a t e : r e t u r np i x e l l a t e ( o l d _ w i d g e t = o l d _ w i d g e t ,n e w _ w i d g e t = n e w _ w i d g e t ) e l s e : r e t u r nd i s s o l v e ( o l d _ w i d g e t = o l d _ w i d g e t ,n e w _ w i d g e t = n e w _ w i d g e t )

Screens and Python

Ren'Py supports defining screens in Python, as well as in the Ren'Py screen language. A Python screen is created by supplying a screen function to the r e n p y . d e f i n e _ s c r e e n ( )function. It can then be used like it was any other screen. The screen function should have parameters corresponding to the scope variables it expects, and it should ignore extra keyword arguments. (That is, it should have * * k w a r g sat the end of its parameter list.) It is then expected to call the UI functions to add displayables to the screen.The screen function is called whenever an interaction starts or restarts. To ensure that this restarting is seamless to the user (and not causing things to reset), it's important that every call to a UI function supply the i dargument. As a screen is re-created, Ren'Py will update each displayable with the contents of the old displayable with the same id. Ids are generated automatically by the screen language, but when doing things by hand, they must be manually specified. Here's an example python screen:
i n i tp y t h o n : d e fs a y _ s c r e e n ( w h o ,w h a t ,* * k w a r g s ) : u i . w i n d o w ( i d = " w i n d o w " ) u i . v b o x ( i d = " s a y _ v b o x " ) u i . t e x t ( w h o ,i d = " w h o " )

u i . t e x t ( w h a t ,i d = " w h a t " ) u i . c l o s e ( " r e t u r n " ) r e n p y . d e f i n e _ s c r e e n ( " s a y " ,s a y _ s c r e e n )

Screen Functions The following functions support the definition, display, and hiding of screens.
r e n p y . c a l l _ s c r e e n (_screen_name, **kwargs)

The programmatic equivalent of the show screen statement. This shows _ s c r e e n _ n a m eas a screen, then causes an interaction to occur. The screen is hidden at the end of the interaction, and the result of the interaction is returned. Keyword arguments not beginning with _ are passed to the scope of the screen.
r e n p y . d e f i n e _ s c r e e n (name, function, modal="False", zorder="0", tag=None,

variant=None) Defines a screen with n a m e , which should be a string.

f u n c t i o n

The function that is called to display the screen. The function is called with the screen scope as keyword arguments. It should ignore additional keyword arguments. The function should call the ui functions to add things to the screen.
m o d a l

A string that, when evaluated, determines of the created screen should be modal. A modal screen prevents screens underneath it from receiving input events.
z o r d e r

A string that, when evaluated, should be an integer. The integer controls the order in which screens are displayed. A screen with a greater zorder number is displayed above screens with a lesser zorder number.
t a g

The tag associated with this screen. When the screen is shown, it replaces any other screen with the same tag. The tag defaults to the name of the screen.
p r e d i c t

If true, this screen can be loaded for image prediction. If false, it can't. Defaults to true.
v a r i a n t

String. Gives the variant of the screen to use.

r e n p y . g e t _ s c r e e n (name, layer='screens')

Returns the ScreenDisplayable with the given t a g , on l a y e r . If no displayable with the tag is not found, it is interpreted as screen name. If it's still not found, None is returned.
r e n p y . g e t _ w i d g e t (screen, id, layer='screens')

From the s c r e e non l a y e r , returns the widget with i d . Returns None if the screen doesn't exist, or there is no widget with that id on the screen.

r e n p y . h i d e _ s c r e e n (tag, layer='screens')

The programmatic equivalent of the hide screen statement. Hides the screen with t a gon l a y e r .
r e n p y . s h o w _ s c r e e n (_screen_name, _layer='screens', _tag=None, _widget_properties={},

_transient=False, **kwargs) The programmatic equivalent of the show screen statement. Shows the named screen.
_ s c r e e n _ n a m e

The name of the screen to show.

_ l a y e r

The layer to show the screen on.

_ t a g

The tag to show the screen with. If not specified, defaults to the tag associated with the screen. It that's not specified, defaults to the name of the screen.,
_ w i d g e t _ p r o p e r t i e s

A map from the id of a widget to a property name -> property value map. When a widget with that id is shown by the screen, the specified properties are added to it.
_ t r a n s i e n t

If true, the screen will be automatically hidden at the end of the current interaction. Keyword arguments not beginning with underscore (_) are used to initialize the screen's scope.
r e n p y . v a r i a n t (name)

Returns true if a n a m eis a screen variant that can be chosen by Ren'Py. See Screen Variants for more details. This function can be used as the condition in a python if statement to set up the appropriate styles for the selected screen variant. UI Functions The UI functions are python equivalents of the screen language statements. For each screen language statement, there is a ui function with the same name. For example, ui.text corresponds to the text statement, and ui.add corresponds to the add statement. There is a simple mapping between screen language parameters and arguments and python arguments. Screen language parameters become positional arguments, while properties become keyword arguments. For example, the screen language statement:
t e x t" H e l l o ,W o r l d "s i z e4 0x a l i g n0 . 5

becomes:
u i . t e x t ( " H e l l o ,W o r l d " ,s i z e = 4 0 ,x a l i g n = 0 . 5 )

(It really should have an i dparameter added.) There are three groups of UI functions, corresponding to the number of children they take. The following UI functions do not take any children.

ui.add ui.bar ui.imagebutton ui.input ui.key ui.label ui.null ui.text ui.textbutton ui.timer ui.vbar ui.hotspot ui.hotbar ui.spritemanager The following UI functions take a single child. They must be given that child - use ui.null() if the child is missing. ui.button ui.frame ui.transform ui.window ui.drag The following UI functions take multiple children. They continue taking children until u i . c l o s e ( )is called. ui.fixed ui.grid ui.hbox ui.side ui.vbox ui.imagemap ui.draggroup There are a few UI functions that do not correspond to screen language statments, as they correspond to concepts that are not present in the screen language.
u i . a d j u s t m e n t (range=1, value=0, step=None, page=0, changed=None, adjustable=None,

ranged=None) Adjustment objects represent a value that can be adjusted by a bar or viewport. They contain information about the value, the range of the value, and how to adjust the value in small steps and large pages. The following parameters correspond to fields or properties on the adjustment object:
r a n g e

The range of the adjustment, a number.

v a l u e

The value of the adjustment, a number.

s t e p

The step size of the adjustment, a number. If None, then defaults to 1/10th of a page, if set. Otherwise, defaults to the 1/20th of the range. This is used when scrolling a viewport with the mouse wheel.
p a g e

The page size of the adjustment. If None, this is set automatically by a viewport. If

never set, defaults to 1/10th of the range. It's can be used when clicking on a scrollbar. The following parameters control the behavior of the adjustment.
a d j u s t a b l e

If True, this adjustment can be changed by a bar. If False, it can't. It defaults to being adjustable if a c h a n g e dfunction is given or if the adjustment is associated with a viewport, and not adjustable otherwise.
c h a n g e d

This function is called with the new value when the value of the adjustment changes.
r a n g e d

This function is called with the adjustment object when the range of the adjustment is set by a viewport.

c h a n g e (value)
Changes the value of the adjustment to v a l u e , updating any bars and viewports that use the adjustment.
u i . a t (transform)

Specifieds a transform that is applied to the next displayable to be created. This is largely obsolete, as all UI functions now take an a targument.
u i . c l o s e ()

Closes a displayable created with by a UI function. When a displayable is closed, we add new displayables to its parent, or to the layer if no displayable is open.
u i . d e t a c h e d ()

Do not add the next displayable to any later or container. Use this if you want to assign the result of a ui function to a variable.
u i . l a y e r (name)

Adds displayables to the layer named n a m e . The later must be closed with u i . c l o s e ( ) . Actions Many of the displayables created in the screen language take actions as arguments. An action is one of three things: A callable python object (like a function or bound method) that takes no arguments. An object of a class that inherits from the Action class. A list of other Actions. The advantage to inheriting from the Action class is that it allows you to override the methods that determine when a button should be sensitive, and when it is selected. class A c t i o n To define a new action, inherit from this class. Override the methods in this class to change the behavior of the action.

_ _ c a l l _ _ (self)
This is the method that is called when the action is activated. In many cases, returning a non-None value from the action will cause the current interaction to end. This method must be overriden, as the default method will raise NotImplemented (and hence cause Ren'Py to report an error).

g e t _ s e n s i t i v e (self)
This is called to determine if the button with this action should be sensitive. It should return true if the button is sensitive. Note that __call__ can be called, even if this returns False. The default implementation returns True.

g e t _ s e l e c t e d (self)
This should return true if the button should be rendered as a selected button, and false otherwise. The default implemention returns False.

p e r i o d i c (self, st)
This method is called once at the start of each interaction, and then is called periodically thereafter. If it returns a number, it will be called before that many seconds elapse, but it might be called sooner. The main use of this is to call r e n p y . r e s t a r t _ i n t e r a c t i o n ( )if the value of get_selected or get_sensitive should change. It takes one argument:
s t

The number of seconds since the screen or displayable this action is associated with was first shown.

u n h o v e r e d ( s e l f ) :
When the action is used as the h o v e r e dparameter to a button (or similar object), this method is called when the object loses focus. BarValues When creating a bar, vbar, or hotbar, a BarValue object can be supplied as the v a l u e argument. Methods on the BarValue object are called to get the adjustment and styles. class B a r V a l u e To define a new BarValue, inherit from this class and override some of the methods.

g e t _ a d j u s t m e n t (self)
This method is called to get an adjustment object for the bar. It should create the adjustment with u i . a d j u s t m e n t ( ) , and then return the object created this way. This method must be overriden, as the default method will raise NotImplemented (and hence cause Ren'Py to report an error).

g e t _ s t y l e (self)
This is used to determine the style of bars that use this value. It should return a tuple of two style names or style objects. The first is used for a bar, and the second for vbar. This defaults to ("bar", "vbar").

r e p l a c e s (self, other)
This is called when a BarValue replaces another BarValue, such as when a screen is updated. It can be used to update this BarValue from the other. It is called before get_adjustment. Note that o t h e ris not necessarily the same type as s e l f .

p e r i o d i c (self, st)
This method is called once at the start of each interaction. If it returns a number of seconds, it will be called before that many seconds elapse, but it might be called sooner. It is called after get_adjustment. It can be used to update the value of the bar over time, like A n i m a t e d V a l u e ( )does. To do this, get_adjustment should store the adjustment, and periodic should calle the adjustment's changed method.

Modes
In Ren'Py, a mode is a concise way of describing the type of an interaction. When a mode is reported to Ren'Py, user-defined callbacks can be run. These calbacks can be used to react to a change in mode, perhaps by reconfiguring the user interface. For example, one can cause a transition to occur when switching from ADV-mode to NVL-mode, or when going to a menu, etc. The goal of the mode systems is to provide a powerful and flexible way of detecting and responding to these changes. Default Modes The following are the modes corresponding to built-in interactions: start This is the mode that Ren'Py is in when a new context is created, such as at the start of a game. Ren'Py never automatically enters this mode, but instead, initializes the list of modes to include start. say The mode Ren'Py enters when an ADV-mode say executes. menu The mode Ren'Py enters when an ADV-mode menu executes. nvl The mode Ren'Py enters when an NVL-mode say executes. nvl_menu The mode Ren'Py enters when an NVL-mode menu executes. pause The mode Ren'Py enters when r e n p y . p a u s e ( )is run. This is also the mode Ren'Py is in when a p a u s estatement of indefinite duration occurs. with The mode Ren'Py enters when a transition introduced by the w i t hstatement occurs. This is also used for p a u s estatement with a duration specified. Note that the with mode is entered at the start of the with statement, which is after any preceding scene, show, or hide statements have been run.

screen The mode Ren'Py enters when a screen is invoked using the c a l ls c r e e nstatement. imagemap The mode Ren'Py enters when an old-style imagemap is invoked using r e n p y . i m a g e m a p ( ) . input The mode Ren'Py enters when text input is requested using the r e n p y . i n p u t ( )function. Other modes can be entered by calling the renpy.mode function.
r e n p y . m o d e (mode)

Causes Ren'Py to enter the named mode, or stay in that mode if it's already in it. Mode Callbacks The c o n f i g . m o d e _ c a l l b a c k svariable contains a list of mode callbacks that are invoked whenever Ren'Py enters a mode. The mode callbacks are called with two parameters: mode A string giving the name of the mode that we are entering. old_modes A list of strings, giving the modes that the system has previously entered, ordered from most recent to least recent. Note that when entering a mode we're already in, the first item in o l d _ m o d e swill be equal to m o d e .
Example Mode Callbacks

This mode callback causes transitions to occur when switching from ADV to NVL mode, and vice-versa. This ships as part of Ren'Py, so there's no need to actually use it.
i n i tp y t h o n : d e f_ n v l _ a d v _ c a l l b a c k ( m o d e ,o l d _ m o d e s ) : o l d=o l d _ m o d e s [ 0 ] i fc o n f i g . a d v _ n v l _ t r a n s i t i o n : i fm o d e= =" n v l "o rm o d e= =" n v l _ m e n u " : i fo l d= =" s a y "o ro l d= =" m e n u " : n v l _ s h o w ( c o n f i g . a d v _ n v l _ t r a n s i t i o n ) i fc o n f i g . n v l _ a d v _ t r a n s i t i o n : i fm o d e= =" s a y "o rm o d e= =" m e n u " : i fo l d= =" n v l "o ro l d= =" n v l _ m e n u " : n v l _ h i d e ( c o n f i g . n v l _ a d v _ t r a n s i t i o n ) c o n f i g . m o d e _ c a l l b a c k s . a p p e n d ( _ n v l _ a d v _ c a l l b a c k )

Creator-Defined Displayables
The most complex, but most powerful, way of customizing Ren'Py's behavior is to use a creator-defined displayable. A creator-defined displayable is allowed to take arbitrary pygame events. It can also render other displayables, and place them at arbitrary locations on the

events. It can also render other displayables, and place them at arbitrary locations on the screen. This makes it suitable for creating 2D mini-games that cannot be expressed with the tools Ren'Py gives you. (But see also the section sprites, which describes a higher-level way of accomplishing many of the same things.) Creator-defined displayables are programmed entirely in Python, and we encourage you to have a reasonable degree of skill at object-oriented Python programming before you begin creating one. Example Here's an example of a creator-defined displayable. This displayable changes renders its child with an alpha that is determined by the distance of the mouse pointer from the center of the child.
i n i tp y t h o n : i m p o r tm a t h c l a s sA p p e a r i n g ( r e n p y . D i s p l a y a b l e ) : d e f_ _ i n i t _ _ ( s e l f ,c h i l d ,o p a q u e _ d i s t a n c e ,t r a n s p a r e n t _ d i s t a n c e ,* * k w a r g s ) : #P a s sa d d i t i o n a lp r o p e r t i e so nt ot h er e n p y . D i s p l a y a b l e #c o n s t r u c t o r . s u p e r ( A p p e a r i n g ,s e l f ) . _ _ i n i t _ _ ( * * k w a r g s ) #T h ec h i l d . s e l f . c h i l d=r e n p y . d i s p l a y a b l e ( c h i l d ) #T h ed i s t a n c ea tw h i c ht h ec h i l dw i l lb e c o m ef u l l yo p a q u e ,a n d #w h e r ei tw i l lb e c o m ef u l l yt r a n s p a r e n t .T h ef o r m e rm u s tb el e s s #t h a nt h el a t t e r . s e l f . o p a q u e _ d i s t a n c e=o p a q u e _ d i s t a n c e s e l f . t r a n s p a r e n t _ d i s t a n c e=t r a n s p a r e n t _ d i s t a n c e #T h ea l p h ac h a n n e lo ft h ec h i l d . s e l f . a l p h a=0 . 0 #T h ew i d t ha n dh e i g h to fu s ,a n do u rc h i l d . s e l f . w i d t h=0 s e l f . h e i g h t=0 d e fr e n d e r ( s e l f ,w i d t h ,h e i g h t ,s t ,a t ) : #C r e a t eat r a n s f o r m ,t h a tc a na d j u s tt h ea l p h ac h a n n e lo ft h e #c h i l d . t=T r a n s f o r m ( c h i l d = s e l f . c h i l d ,a l p h a = s e l f . a l p h a ) #C r e a t ear e n d e rf r o mt h ec h i l d . c h i l d _ r e n d e r=r e n p y . r e n d e r ( t ,w i d t h ,h e i g h t ,s t ,a t ) #G e tt h es i z eo ft h ec h i l d . s e l f . w i d t h ,s e l f . h e i g h t=c h i l d _ r e n d e r . g e t _ s i z e ( ) #C r e a t et h er e n d e rw ew i l lr e t u r n . r e n d e r=r e n p y . R e n d e r ( s e l f . w i d t h ,s e l f . h e i g h t ) #B l i t( d r a w )t h ec h i l d ' sr e n d e rt oo u rr e n d e r . r e n d e r . b l i t ( c h i l d _ r e n d e r ,( 0 ,0 ) )

#R e t u r nt h er e n d e r . r e t u r nr e n d e r d e fe v e n t ( s e l f ,e v ,x ,y ,s t ) : #C o m p u t et h ed i s t a n c eb e t w e e nt h ec e n t e ro ft h i sd i s p l a y a b l ea n d #t h em o u s ep o i n t e r .T h em o u s ep o i n t e ri ss u p p l i e di nxa n dy , #r e l a t i v et ot h eu p p e r l e f tc o r n e ro ft h ed i s p l a y a b l e . d i s t a n c e=m a t h . h y p o t ( x-( s e l f . w i d t h/2 ) ,y-( s e l f . h e i g h t/2 ) )

#B a s eo nt h ed i s t a n c e ,f i g u r eo u ta na l p h a . i fd i s t a n c e< =s e l f . o p a q u e _ d i s t a n c e : a l p h a=1 . 0 e l i fd i s t a n c e> =s e l f . t r a n s p a r e n t _ d i s t a n c e : a l p h a=0 . 0 e l s e : a l p h a=1 . 0-1 . 0*( d i s t a n c e-s e l f . o p a q u e _ d i s t a n c e )/( s e l f . t r a n s p a r e n t _ d i #I ft h ea l p h ah a sc h a n g e d ,t r i g g e rar e d r a we v e n t . i fa l p h a! =s e l f . a l p h a : s e l f . a l p h a=a l p h a r e n p y . r e d r a w ( s e l f ,0 ) #P a s st h ee v e n tt oo u rc h i l d . r e t u r ns e l f . c h i l d . e v e n t ( e v ,x ,y ,s t ) d e fv i s i t ( s e l f ) : r e t u r n[s e l f . c h i l d]

To use the creator-defined displayable, we can create an instance of it, and add that instance to the screen.
s c r e e na l p h a _ m a g i c : a d dA p p e a r i n g ( " l o g o . p n g " ,1 0 0 ,2 0 0 ) : x a l i g n0 . 5 y a l i g n0 . 5 l a b e ls t a r t : s h o ws c r e e na l p h a _ m a g i c " C a ny o uf i n dt h el o g o ? " r e t u r n

renpy.Displayable A creator-defined displayable is created by subclassing the renpy.Displayable class. A creatordefined displayable must override the render method, and may override other methods as well. A displayable object must be pickleable, which means it may not contain references to objects that cannot be pickled. Most notably, Render objects cannot be stored in a creator-defined displayable. Since we expect you to override the methods of the displayable class, we'll present them with the s e l fparameter. class r e n p y . D i s p l a y a b l e

Base class for creator-defined displayables.

_ _ i n i t _ _ ( * * p r o p e r t i e s ) :
A subclass may override the constructor, perhaps adding new parameters. If it does, it should pass all unknown keyword arguments to the renpy.Displayable constructor, using code like:
s u p e r ( M y D i s p l a y a b l e ,s e l f ) . _ _ i n i t _ _ ( p r o p e r t i e s )

r e n d e r (self, width, height, st, at)

Subclasses must override this, to return a r e n p y . R e n d e robject. The render object determines what, if anything, is shown on the screen.
w i d t h ,h e i g h t

The amount of space available to this displayable, in pixels.

s t

A float, the shown timebase, in seconds. The shown timebase begins when this displayable is first shown on the screen.
a t

A float, the animation timebase, in seconds. The animation timebase begins when an image with the same tag was shown, without being hidden. (When the displayable is shown without a tag, this is the same as the shown timebase.) The render method is called when the displayable is first shown. It can be called again if r e n p y . r e d r a w ( )is called on this object.

e v e n t (self, ev, x, y, st)

The event method is called to pass a pygame event to the creator-defined displayable. If the event method returns a value other than None, that value is returned as the result of the interaction. The event method exists on other displayables, allowing the creator-defined displayable to pass on the event.
e v

An event object
x ,y

The x and y coordinates of the event, relative to the upper-left corner of the displayable. These should be used in preference to position information found in the pygame event objects.
s t

A float, the shown timebase, in seconds. An event is generated at the start of each interaction, and r e n p y . t i m e o u t ( )can be used to cause another event to occur.

p e r _ i n t e r a c t (self)
This method is called at the start of each interaction. It can be used to trigger a redraw, and probably should be used to trigger a redraw if the object participates in rollback.

v i s i t (self)
If the displayable has child displayables, this method should be overridden to return a list of those displayables. This ensures that the per_interact methods of those

displayables are called, and also allows images used by those displayables to be predicted. renpy.Render creator-defined displayables work with renpy.Render objects. Render objects are returned by calling the r e n p y . r e n d e r ( )function on a displayable. A creator-defined displayable should create a Render object by calling r e n p y . R e n d e rfrom its render method. Since the render object isn't intended to be subclassed, we will omit the implicit s e l f parameter. class r e n p y . R e n d e r (width, height) Creates a new Render object.
w i d t h ,h e i g h t

The width and height of the render object, in pixels.

b l i t (source, pos)
Draws another render object into this render object.
s o u r c e

The render object to draw.

p o s

The location to draw into. This is an (x, y) tuple with the coordinates being pixels relative to the upper-left corner of the target render.

c a n v a s ()
Returns a canvas object. A canvas object has methods corresponding to the pygame.draw functions, with the first parameter (the surface) omitted.

g e t _ s i z e ()
Returns a (width, height) tuple giving the size of this render.

s u b s u r f a c e (rect)
Returns a render consisting of a rectangle cut out of this render.
r e c t

A (x, y, width, height) tuple. Utility Functions These function manage the rendering process.
r e n p y . d i s p l a y a b l e ( d)

This takes d , which may be a displayable object or a string. If it's a string, it converts that string into a displayable using the usual rules.
r e n p y . r e n d e r (d, width, height, st, at)

Causes a displayable to be rendered, and a renpy.Render object to be returned.

d

The displayable to render.

w i d t h ,h e i g h t

The width and height available for the displayable to render into.
s t ,a t

The shown and animation timebases. Renders returned by this object may be cached, and should not be modified once they have been retrieved.
r e n p y . t i m e o u t (seconds)

Causes an event to be generated before s e c o n d sseconds have elapsed. This ensures that the event method of a user-defined displayable will be called.
r e n p y . r e d r a w (d, when)

Causes the displayable dto be redrawn after w h e nseconds have elapsed.

Other Functions
We're in the process of migrating the documentation over to a new tool. As not every page has been migrated yet, this exists to document new functionality that has no other place to go.
r e n p y . c a l l (label, *args, **kwargs)

Causes the current Ren'Py statement to terminate, and a jump to a l a b e lto occur. When the jump returns, control will be passed to the statement following the current statement.
r e n p y . c l e a r _ g a m e _ r u n t i m e ()

Resets the game runtime counter.

r e n p y . f o c u s _ c o o r d i n a t e s ()

This attempts to find the coordinates of the currently-focused displayable. If it can, it will return them as a (x, y, w, h) tuple. If not, it will return a (None, None, None, None) tuple.
r e n p y . f s d e c o d e (s)

Converts s from filesystem encoding to unicode.

r e n p y . f s e n c o d e (s)

Converts s from unicode to the filesystem encoding.

r e n p y . g e t _ g a m e _ r u n t i m e ()

Returns the game runtime counter. The game runtime counter counts the number of seconds that have elapsed while waiting for user input in the top-level context. (It does not count time spent in the main or game menus.)

r e n p y . g e t _ i m a g e _ l o a d _ l o g (age=None)

A generator that yields a log of image loading activity. For the last 100 image loads, this returns: The time the image was loaded (in seconds since the epoch). The filename of the image that was loaded. A boolean that is true if the image was preloaded, and false if the game stalled to load it. The entries are ordered from newest to oldest.
a g e

If not None, only images that have been loaded in the past a g eseconds are included. The image load log is only kept if config.developer = True.
r e n p y . g e t _ p h y s i c a l _ s i z e ()

Returns the size of the physical window.

r e n p y . g e t _ r e n d e r e r _ i n f o ()

Returns a dictionary, giving information about the renderer Ren'Py is currently using. The dictionary has one required key:
" r e n d e r e r " One of " g l "or " s w " , corresponding to the OpenGL and software renderers,

respectively.

" r e s i z a b l e

True if and only if the window is resizable. Other, renderer-specific, keys may also exist. The dictionary should be treated as immutable. This should only be called once the display has been started (that is, after the init code is finished).
r e n p y . g e t _ s a y _ a t t r i b u t e s ()

Gets the attributes associated with the current say statement, or None if no attributes are associated with this statement. This is only valid when executing or predicting a say statement.
r e n p y . g e t _ s i d e _ i m a g e (prefix_tag, image_tag=None, not_showing=True,

layer='master') This attempts to find an image to show as the side image. It begins by determining a set of image attributes. If i m a g e _ t a gis given, it gets the image attributes from the tag. Otherwise, it gets them from the currently showing character. It then looks up an image with the tag p r e f i x _ t a gand those attributes, and returns it if it exists. If not_showing is True, this only returns a side image if the image the attributes are taken from is not on the screen.
r e n p y . i m a g e _ s i z e (im)

Given an image manipulator, loads it and returns a (w i d t h ,h e i g h t ) tuple giving its size.

This reads the image in from disk and decompresses it, without using the image cache. This can be slow.
r e n p y . l i s t _ f i l e s (common=False)

Lists the files in the game directory and archive files. Returns a list of files, with / as the directory separator.
c o m m o n

If true, files in the common directory are included in the listing.

r e n p y . n o t i f y (message)

Causes Ren'Py to display the m e s s a g eusing the notify screen. By default, this will cause the message to be dissolved in, displayed for two seconds, and dissolved out again. This is useful for actions that otherwise wouldn't produce feedback, like screenshots or quicksaves. Only one notification is displayed at a time. If a second notification is displayed, the first notification is replaced.
r e n p y . s e t _ p h y s i c a l _ s i z e (size)

Attempts to set the size of the physical window to size. This has the side effect of taking the screen out of windowed mode.
r e n p y . v i b r a t e (duration)

Causes the device to vibrate for d u r a t i o nseconds. Currently, this is only supported on Android.
r e n p y . m u s i c . r e g i s t e r _ c h a n n e l (name, mixer=None, loop=None, stop_on_mute=True,

tight=False, file_prefix='', file_suffix='', buffer_queue=True) This registers a new audio channel named n a m e . Audio can then be played on the channel by supplying the channel name to the play or queue statements.
m i x e r

The name of the mixer the channel uses. By default, Ren'Py knows about the "music", "sfx", and "voice" mixers. Using other names is possible, but may require changing the preferences screens.
l o o p

If true, sounds on this channel loop by default.

s t o p _ o n _ m u t e

If true, music on the channel is stopped when the channel is muted.

t i g h t

If true, sounds will loop even when fadeout is occuring. This should be set to True for a sound effects or seamless music channel, and False if the music fades out on its own.
f i l e _ p r e f i x

A prefix that is prepended to the filenames of the sound files being played on this channel.
f i l e _ s u f f i x

A suffix that is appended to the filenames of the sound files being played on this channel.

b u f f e r _ q u e u e

Should we buffer the first second or so of a queued file? This should be True for audio, and False for movie playback.
l a y o u t . y e s n o _ s c r e e n (message, yes=None, no=None)

This causes the a yes/no prompt screen with the given message to be displayed. The screen will be hidden when the user hits yes or no.
m e s s a g e

The message that will be displayed.

y e s

An action that is run when the user chooses yes.

n o

An action that is run when the user chooses no.

u p d a t e r . f s e n c o d e (s)

Converts s from unicode to the filesystem encoding.

Building, Updating, and Other Platforms

Building Distributions
Ren'Py includes support for building game distributions. Upon choosing "Build Distributions" in the launcher, Ren'Py will scan itself and the project to determine the files to include in the distribution, will create any archives that are necessary, and will build package and update files. With no configuration, Ren'Py will build the following four kinds of packages: All Desktop Platofrms A zip file targeting Windows x86, Macintosh x86, Linux x86, and Linux x86_64. Linux x86/x86_64 A tar.bz2 file targeting Linux x86 and Linux x86_64. Macintosh x86 A zip file containing a Macintosh application targeting Macintosh OS X on Intel processors. Game data will be included inside the application, which appears to the user as a single file. Windows x86 A zip file targeting Windows x86.
Warning The zip and tar.bz2 files that Ren'Py produces contain permissions information that must be present for Ren'Py to run on Linux and Macintosh.

Unpacking and re-packing a zip file on Windows and then running it on Linux or Macintosh is not supported.

Basic Configuration The build process can be configured by setting variables and calling function that live in the build namespace. This must be done from inside an init python block. There are a few basic variables and functions that many games will use.

b u i l d . d i r e c t o r y _ n a m e= "..."
This is used to create the names of directories in the archive files. For example, if this is set to "mygame-1.0", the Linux version of the project will unpack to "mygame-1.0-linux". This is also used to determine the name of the directory in which the package files are placed. For example, if you set build.directory_name to mygame-1.0, the archive files will be placed in mygame-1.0-dists in the directory above the base directory.

b u i l d . e x e c u t a b l e _ n a m e= "..."
This variable controls the name of the executables that the user clicks on to start the game. For example, if this is set to "mygame", the user will be able to run mygame.exe on Windows, mygame.app on Macintosh, and mygame.sh on Linux. Special Files There are two files that can be included in your game's base directory to customize the build. icon.ico The icon that is used on Windows. icon.icns The icon that is used on Macintosh. These icon files much be in specific formats. You'll need to use a program or web service (such as http://iconverticons.com/ ) to convert them. Classifying and Ignoring Files The build process works by first classifying files in the Ren'Py distribution and your game into file lists. These file lists are then added to package files. The classification is done by the build.classify function. It takes a patterns and a spaceseparated list of filenames. Patterns are matched from first to last, with the first match taking precedence (even if a more-specific pattern follows.) Patterns are matched with and without a leading /. Patterns may include the following special characters: / The directory separator. * Matches all characters except for the directory separator. ** Matches all characters. For example:

**.txt Matches all txt files. game/*.txt Matches txt files in the game directory. There are five file lists that files can be classified into by default. (Ren'Py places its own files into the first four of these.) all These files will be included in all packages. linux These files will be included in packages targeting Linux. mac These files will be included in packages targeting Macintosh. windows These files will be included in packages targeting Windows. archive These files will be included in the archive.rpa archive. Files that are not otherwise classified are placed in the "all" file list. To exclude files from distribution, classify them as None or the empty string. For example:
#I n c l u d eR E A D M E . t x t b u i l d . c l a s s i f y ( " R E A D M E . t x t " ," a l l " ) #B u te x c l u d ea l lo t h e rt x tf i l e s . b u i l d . c l a s s i f y ( " * * . t x t " ,N o n e ) #A d dp n ga n dj p gf i l e si nt h eg a m ed i r e c t o r yi n t oa na r c h i v e . b u i l d . c l a s s i f y ( " g a m e / * * . p n g " ," a r c h i v e " ) b u i l d . c l a s s i f y ( " g a m e / * * . j p g " ," a r c h i v e " )

Documentation Calling the build.documentation function with patterns marks files matching those patterns as documentation. Documentation files are included twice in a Macintosh application - both inside and outside of the application itself. For example, to mark all txt and html files in the base directory as documentation, call:
b u i l d . d o c u m e n t a t i o n ( " * . t x t " ) b u i l d . d o c u m e n t a t i o n ( " * . h t m l " )

Packages It's also possible to add new types of packages to the Ren'Py build process. This is done by calling the build.package function with a package name, type, and a string containing the file lists to include. Say we wanted to build a normal version of our game, and one containing bonus material. We could classify the bonus files in to a "bonus" file list, and then declare an all-premium package with:

with:
b u i l d . p a c k a g e ( " a l l p r e m i u m " ," z i p " ," w i n d o w sm a cl i n u xa l lb o n u s " )

Archives Ren'Py supports combining files into a simple archive format. While not very secure, this protects files from casual copying. By default, all files classified into the "archive" file list will be placed in an archive.rpa archive, which is included in the all file list. By calling build.archive, it's possible to declare a new archives and the file lists they will be included in. (It's rare to use anything but the all file list, however.) To use an archive, classify files into a list with its name. For example, the following code will archive images in images.rpa, and game scripts into scripts.rpa:
#D e c l a r et w oa r c h i v e s . b u i l d . a r c h i v e ( " s c r i p t s " ," a l l " ) b u i l d . a r c h i v e ( " i m a g e s " ," a l l " ) #P u ts c r i p tf i l e si n t ot h es c r i p t sa r c h i v e . r e n p y . c l a s s i f y ( " g a m e / * * . r p y " ," s c r i p t s " ) r e n p y . c l a s s i f y ( " g a m e / * * . r p y c " ," s c r i p t s " ) #P u ti m a g e si n t ot h ei m a g e sa r c h i v e . r e n p y . c l a s s i f y ( " g a m e / * * . j p g " ," i m a g e s " ) r e n p y . c l a s s i f y ( " g a m e / * * . p n g " ," i m a g e s " )

If an archive file is empty, it will not be built. Please think twice about archiving your game. Keeping files open will help others run your game on future platforms - platforms that may not exist until after you're gone. Build Functions
b u i l d . a r c h i v e (name, file_list='all')

Declares the existence of an archive. If one or more files are classified with n a m e ,n a m e .rpa is build as an archive. The archive is included in the named file lists.
b u i l d . c l a s s i f y (pattern, file_list)

Classifies files that match p a t t e r ninto f i l e _ l i s t .

b u i l d . c l e a r ()

Clears the list of patterns used to classify files.

b u i l d . d o c u m e n t a t i o n (pattern)

Declares a pattern that matches documentation. In a mac app build, files matching the documentation pattern are stored twice - once inside the app package, and again outside of it.

b u i l d . e x e c u t a b l e (pattern)

Adds a pattern marking files as executable on platforms that support it. (Linux and Macintosh)
b u i l d . p a c k a g e (name, format, file_lists, description=None, update=True, dlc=False)

Declares a package that can be built by the packaging tool.

n a m e

The name of the package.

f o r m a t

The format of the package. A string containing a space separated list of: zip A zip file. app-zip A zip file containing a macintosh application. tar.bz2 A tar.bz2 file. The empty string will not build any package formats (this makes dlc possible).
f i l e _ l i s t s

A list containing the file lists that will be contained within the package.
d e s c r i p t i o n

An optional description of the package to be built.

u p d a t e

If true and updates are being built, an update will be built for this package.
d l c

If true, any zip or tar.bz2 file will be built in standalone DLC mode, without an update directory.

Web Updater
Ren'Py includes an updater that can automatically download and install updates to a Ren'Py game hosted at a website. This can be useful in keeping a large game up to date. The Ren'Py updater works by automatically performing the following steps: 1. 2. 3. 4. 5. Downloading an index file that controls what is updated. Asking the user if he or she wants to proceed with the update. Producing an archive file from the files on disk. Downloading a zsync control file from the server. Using the zsync tool to update the archive file to the version on the server. Zsync automatically computes the differences between the two files, and attempts to only download the portions that have changed. 6. Unpacking the archive, replacing the files on disk. 7. Deleting files that have been removed between the old and new versions. 8. Restarting the game. The Ren'Py updater shows an updater screen during this process, prompting the user to

proceed and allowing the user to cancel when appropriate. Server Requirements The updater requires that you provide your own hosting. You should be able to download the update files by going to the appropriate URL directly, and your server must support HTTP range queries. (This means paying for web hosting, as "sharing" sites tend not to support the required features.) Building an Update Updates are built automatically when distributions are built. To build an update, set build.include_updates to True in options.rpy. This will unlock the "Build Updates" option in options.rpy. Check this option, and Ren'Py will create the update files. The update files consist of: updates.json An index of available updates and their versions. package.sums Contains checksums for each block in the package. package.update.gz Contains the update data for the given package. package.update.json Contains a list of the files in each package, which the updater uses when downloading DLC. package.zsync This is a control file that's used by zsync to manage the download. You must upload all these files to a single directory on your web server. Functions To cause an update to occur, invoke either updater.update or the updater.Update action.
u p d a t e r . U p d a t e (*args, **kwargs)

An action that calls u p d a t e r . u p d a t e ( ) . All arguments are stored and passed to that function.
u p d a t e r . c a n _ u p d a t e (base=None)

Returns true if it's possible that an update can succeed. Returns false if updating is totally impossible. (For example, if the update directory was deleted.)
u p d a t e r . g e t _ i n s t a l l e d _ p a c k a g e s (base=None)

Returns a list of installed DLC package names.

b a s e

The base directory to update. Defaults to the current project's base directory.

u p d a t e r . u p d a t e (url, base=None, force=False, public_key=None, simulate=None, add=[],

restart=True) Updates this Ren'Py game to the latest version.

u r l

The URL to the updates.json file.

b a s e

The base directory that will be updated. Defaults to the base of the current game. (This can usually be ignored.)
f o r c e

Force the update to occur even if the version numbers are the same. (Used for testing.)
p u b l i c _ k e y

The path to a PEM file containing a public key that the update signature is checked against. (This can usually be ignored.)
s i m u l a t e

This is used to test update guis without actually performing an update. This can be: None to perform an update. "available" to test the case where an update is available. "not_available" to test the case where no update is available. "error" to test an update error.
a d d

A list of packages to add during this update. This is only necessary for dlc.
r e s t a r t

Restart the game after the update. Screen To customize the look of the updater, you may override the u p d a t e rscreen. The default screen is defined in common/00updater.rpy.

Android
Ren'Py support devices running the Android operating system, such as smartphones and tablets. While these devices do not support 100% of Ren'Py's functionality, with minimal modification code can be packaged and ported to these devices. RAPT - the Ren'Py Android Packaging Tool - is a program, downloaded separately from Ren'Py, that creates an Android package for testing or release purposes. User Instructions When a Ren'Py game has been launched on Android, the following keybindings work:
H o m e

Returns to the Android home screen, suspending the Ren'Py game. As part of the suspend process, Ren'Py will automatically save the game. If necessary, the save will be automatically loaded when the user returns to the game.

M e n u

Brings up the in-game menu, and returns to the game.

B a c k

Rolls back.
V o l u m eU p ,V o l u m eD o w n

Controls Android's media volume. Platform Differences There are many important differences between the touch-based Android platform and the mouse-based platforms that Ren'Py supports. Changes due to the Android software and hardware are: The touchscreen is treated as if it was a mouse. However, it will only produce mouse events when the user is actively touching the screen. When the user is not touching the screen, the virtual pointer will move to the upper-left corner of the screen. I m a g e D i s s o l v e ( ) ,A l p h a D i s s o l v e ( ) , and A l p h a B l e n d ( )are not supported. Functions that render to a texture can only render an opaque texture. This means that the D i s s o l v e ( )and P i x e l l a t e ( )transitions will only produce opaque output. The f o c u s _ m a s kproperty is not supported. It will be treated as if all pixels in the mask are opaque. Movie playback is not supported. Launching the web browser is not supported. Some python modules (including network communication) modules are not supported. Ren'Py cannot change the device volume. However, the android volume buttons work normally. In addition, there are a few changes that may be necessary due to human factors: Since Android smartphones can be smaller than a computer monitor, it may be necessary to increase text size. Since touch input is less accurate than mouse input, touch-based buttons need to be larger than mouse-based ones. To help you adapt to these differences, Ren'Py for Android automatically selects a screen variant of t o u c h . It also selects screen variants of p h o n eor t a b l e tbased on the device's screen size. See Screen Variants for more information. Building Android Applications RAPT contains tools that help you take a packaging-centric approach to Android game development. In this approach, you will use a PC to build an Android package and upload it to your device. You can then run the game like any Android application. When it works correctly, you can upload the package you make to the Android Market or other app stores. Building your first package takes four steps: 1. Download and install RAPT, Python 2.7, the Java Development Kit, and Android USB Drivers (scroll down for links). 2. Use the a n d r o i d . p yi n s t a l l s d kcommand to install the Android SDK and set up your development environment. 3. Use the a n d r o i d . p yc o n f i g u r ecommand to configure Android-specific settings in your game. 4. Use the a n d r o i d . p yb u i l dcommand to build a package, and to install the package on your device. Once you've finished these four steps, you'll have a runnable Android package. You'll only

need to run step 3 when you decide to make changes to your game's configuration or when configuring a new game entirely; you'll run step 4 most often, whenever you need to make a new build of your game.
Host Platform Support

We've tested RAPT on Linux and Windows computers. While it should work on Mac OS X, we haven't tested it there, so there may be problems encountered. The examples we give will be for Linux and Windows. The RAPT tools are command-line based. We will try to assist you with examples to familiarize you with the command line on Windows.
Step 1: Installing RAPT and its Dependencies

There are four things you may need to manually download and install before you can run RAPT: Java Development Kit. The Java Development Kit (JDK) contains several tools that are used by RAPT, including the tools used to generate keys and sign packages. It can be downloaded from: http://www.oracle.com/technetwork/java/javase/downloads/index.html Please note that the developer-focused JDK is different from the user-focused JRE, and you'll need the JDK to create Android packages. Python 2.7. Python 2.7 is required to run the android.py script that's included with RAPT. It can be downloaded from: http://python.org/download/releases/2.7.2/ RAPT is not compatible with Python 3 at this time. Android Device Drivers. On Windows, you may want to install a device driver to access your device, although this is not necessary. Links to android device drivers can be found at: http://developer.android.com/sdk/oem-usb.html On Linux or OS X, you won't need a device driver. If you can't access your device, you may need to read: http://developer.android.com/guide/developing/device.html#setting-up However, modern versions of Linux and OS X should just work. RAPT Itself. The latest version of RAPT can be downloaded from: http://www.renpy.org/dl/android/ Once RAPT has been downloaded, you should extract it using an archive program. The directory contained in that archive is what we will refer to as the RAPT directory.
Aside: Running android.py

In this documentation, we'll ask you to run the a n d r o i d . p ycommand. The technique we use to run this varies based on the system you're on. In all cases, you should run a n d r o i d . p yfrom within the RAPT directory. (That is, the directory containing a n d r o i d . p yitself.)

On Windows, to do this, you will need to open up the command line by pressing and holding down the Windows key and 'R'. In the small window that pops up write "cmd" and press Enter. This should bring up the command line. To run the command from within the RAPT directory you need to navigate to it from the command line. Find out where you extracted RAPT and copy the path from Explorer (just click in the address bar so the path turns blue and press Ctrl+c). In the command prompt, write c d then a space, a double-quote, paste the path you just copied from Explorer (right click and choose p a s t e ), then another double-quote. Let's assume you extracted RAPT to C:\tools\RAPT. In the command line write:
c d" C : \ t o o l s \ R A P T "

Now you're within the RAPT directory. On Windows, if the .py extension is registered to Python 2.7, you then can just run:
a n d r o i d . p yt e s t

If you don't know what the above means or you don't want to do it, you will have to add the full path to Python to each command in the following steps of this guide beginning with 'android.py'. If you installed Python to the default location, the above command would become:
C : \ p y t h o n 2 7 \ p y t h o n . e x ea n d r o i d . p yt e s t

If you installed Python to a different location, then find your Python install in Explorer, click in the address bar and copy the path, then replace C : \ p y t h o n 2 7with the path you copied instead - leaving \ p y t h o n . e x eon the end. So if your Python install is in C : \ t o o l s \ p y t h o n , you would type:
C : \ t o o l s \ p y t h o n \ p y t h o n . e x ea n d r o i d . p yt e s t
Warning If the path to Python that you copied has any spaces in - for example, if you had installed it in the P r o g r a mF i l e sdirectory - you will need to put double quotes at the beginning of the whole command and just after p y t h o n . e x e :
" C : \ P r o g r a mF i l e s \ P y t h o n \ p y t h o n . e x e "a n d r o i d . p yt e s t

On Linux, you may need to prefix the command with the current directory:
. / a n d r o i d . p yt e s t

For the rest of this documentation, we'll just use a n d r o i d . p y- if you had to include the path to Python in the example above, you will need to do the same thing every time you see a n d r o i d . p yin these instructions.
Step 2: Set up the Android SDK and Development Environment

The next step is to set up the Android SDK and the rest of your development environment. This step will: Check that the JDK is installed properly.

Install Apache Ant. Install the Android SDK. Use the Android SDK to install the appropriate development packages. Create a signing key that will be used to sign packages that are placed on the market (android.keystore: this will be generated in the RAPT directory). This step requires Internet access. To perform this step, run:
a n d r o i d . p yi n s t a l l s d k

RAPT will report on what it's doing. It will also prompt you with warnings about licenses, and ask if you want it to generate a key.
Warning The key generated by RAPT is created with a standard passphrase. You should really use keytool to generate your own signing keys. http://docs.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html At the very least, you should keep the android.keyring file in a safe place. You should also back it up, because without the key, you won't be able to upload the generated applications.

In the examples below, m y g a m eis short for the path to the game you're working on, relative to the current directory. When you make your own game, you should change m y g a m eto something else. The easiest way to do this, of course, is to make a copy of your game's directory inside the RAPT directory and then replace m y g a m ein the examples below with the name of your game's directory.
Step 3: Configure Your Game

Before building a package, you must give RAPT some information about your game. You can do this with the following command:
a n d r o i d . p yc o n f i g u r em y g a m e

This will ask you a series of questions about your game, and store that information in a file in the game directory. If you need to change the information - for example, if you release a new version of your game - you can re-run the configure command. Your previous choices will be remembered.
Step 4: Build and Install the Package

Finally, you can build and install the package. This is done with a command like:
a n d r o i d . p yb u i l dm y g a m er e l e a s ei n s t a l l

This command will build a releasable version of your game, and then install it on the connected device. Please look at the output of this command to make sure it succeeds. Once the game successfully installs, you can touch its icon in your device's launcher to start it running. If you'd rather just copy the game's apk file to your Android device manually, you can just run:
a n d r o i d . p yb u i l dm y g a m er e l e a s e

Then navigate to the 'bin' directory inside RAPT and copy the file mygame-release.apk into your Android Device. You will then need to find the .apk file in your Android device using your file application and open it to install the game. The build command passes the options after the game name to the ant tool, which is responsible for creating the Android package. Other commands are also possible - for a list, run:
a n d r o i d . p yb u i l dm y g a m eh e l p
Viewing Debug Output

To view debug output from your application, run the logcat command:
a n d r o i d . p yl o g c a t

This command runs the a d bl o g c a tcommand in a mode that selects only Python output.
Troubleshooting and Support

Here's a list of errors that you might encounter and possible solutions: When trying to run:
a n d r o i d . p yt e s t

After having associated .py files with Python 2.7, if you get:
T r a c e b a c k( m o s tr e c e n tc a l ll a s t ) : F i l e" C : \ V i s u a lN o v e l sa n dG a m e s \ r a p t 6 . 1 3 . 1 1 . 0 \ a n d r o i d . p y " ,l i n e9 ,i n< m o d u l e > i m p o r ts u b p r o c e s s F i l e" C : \ P y t h o n 2 7 \ l i b \ s u b p r o c e s s . p y " ,l i n e4 4 4 ,i n< m o d u l e > f r o m_ s u b p r o c e s si m p o r tC R E A T E _ N E W _ C O N S O L E ,C R E A T E _ N E W _ P R O C E S S _ G R O U P I m p o r t E r r o r :c a n n o ti m p o r tn a m eC R E A T E _ N E W _ P R O C E S S _ G R O U P

This may be related to having more than one version of Python installed on your system. Try running android.py with the full path to Python, e.g.:
C : \ p y t h o n 2 7 \ p y t h o n . e x ea n d r o i d . p yt e s t

(If this works, then you will need to include the full path to Python in every command, as if you didn't have the file type associated.) If while downloading Apache Ant you get:
I O E r r o r :[ E r r n os o c k e te r r o r ][ E r r n o1 0 0 5 4 ]A ne x i s t i n gc o n n e c t i o nw a sf o r c i b l y c l o s e db yt h er e m o t eh o s t

Just try installing the sdk again with the same command. If while configuring your game you get something like:
T a g< m a n i f e s t >a t t r i b u t ep a c k a g eh a si n v a l i dc h a r a c t e r' ' .

You may have inserted an invalid character in the package name you used during configuration (in this case a hyphen '-'). You'll have to use a different package name which does not contain anything other than letters and dots. If while configuring you get something like:
T r a c e b a c k( m o s tr e c e n tc a l ll a s t ) : F i l e" a n d r o i d . p y " ,l i n e6 6 ,i n< m o d u l e > m a i n ( ) F i l e" a n d r o i d . p y " ,l i n e4 4 ,i nm a i n c o n f i g u r e . c o n f i g u r e ( i f a c e ,d i r e c t o r y ) F i l e" b u i l d l i b \ c o n f i g u r e . p y " ,l i n e1 0 8 ,i nc o n f i g u r e c o n f i g . s a v e ( d i r e c t o r y ) F i l e" b u i l d l i b \ c o n f i g u r e . p y " ,l i n e3 0 ,i ns a v e w i t hf i l e ( o s . p a t h . j o i n ( d i r e c t o r y ," . a n d r o i d . j s o n " ) ," w " )a sf : I O E r r o r :[ E r r n o2 ]N os u c hf i l eo rd i r e c t o r y :' m y g a m e \ \ . a n d r o i d . j s o n '

You should check whether you specified the correct path to your game directory. The easiest way to be sure is to put your game's directory inside the RAPT directory, and simply supply the name of your game's directory. (If your game's directory name has spaces, you may need to surround it with double quotes.) If building your game gives you an error like: Error: Target id android-8 is not valid. Use 'android list targets' to get the target ids You might want to check whether you have Android 2.2 (API 8) in the Android SDK manager. You can run it by navigating to the android-sdk/tools directory inside the RAPT directory and run android.bat.

If Android 2.2 (API 8) is missing like in the above image, click 'Updates' and then 'Install Updates'. Once the updates are installed, make sure Android 2.2 (API 8) and SDK platform are ticked:

And install the packages. Then, try building your game again. If you still have questions or doubts you can try searching through or posting on the RAPT thread over at the Lemmasoft forums: http://lemmasoft.renai.us/forums/viewtopic.php?f=32&t=13987&hilit=rapt

End-User Documentation

Dealing With Display Problems

As of version 6.13, Ren'Py will take advantage of graphics acceleration hardware, if it's present and functional. Using hardware acceleration brings with it several advantages, such as allowing vertical-blank synchronization and scaling games to full-screen size while preserving aspect ratio. By default, Ren'Py selects a renderer to use in the following order: 1. 2. 3. 4. OpenGL 2.0 or greater. DirectX 9, provided that all libraries are available. OpenGL 1.x. Software.

A small fraction of systems may experience problems when running hardware accelerated Ren'Py games. These problems are often due to buggy graphics drivers, and so your first step to fixing them should be to check for an update to your graphics card drivers. If upgrading your video drivers does not fix the problem, you should consider switching video renderers, using the following steps. 1. Hold down shift while starting Ren'Py, or press shift+G once Ren'Py has started. 2. From the "Graphics Acceleration" menu that appears, choose the renderer to use. 3. Choose "Quit", then restart Ren'Py. We suggest trying OpenGL, DirectX, and Software, in that order.

Engine Developer Documentation

Text Editor Integration

Ren'Py uses a text editor to allow the user to edit game scripts from the launcher, and to report errors to the user. By default, Ren'Py uses jEdit as the text editor when launched from the launcher and the system default editor otherwise. This can be customized by the user as necessary. The editor is customized by creating an Editor class in a .edit.py file. This class contains methods that are called to manage text editing. When run directly, Ren'Py first looks at the RENPY_EDIT_PY environment variable to find an .edit.py file to use. If it can find one, it uses the Editor class defined in that file. If not, it uses a built-in editor class that launches the editor in a system-specific manner. When the Ren'Py Launcher is run, it scans subdirectories of the projects directory and Ren'Py directory to find files of the form n a m e .edit.py. (For example, it would find launcher/jEdit.edit.py and myeditor/MyEditor.edit.py.) The latest editor with a given n a m eis presented to the creator as part of the launcher options. The launcher also sets RENPY_EDIT_PY to the selected file, so that games launched from the launcher will use the selected editor. Writing an .edit.py File An edit.py file is a Python (not Ren'Py) file that must define a single class, named Editor. Ren'Py will call methods on this class to cause editing to occur. Use of the editor is done as part of an editor transaction, which groups related operations together. For example, if an editor transaction asks for a new window, all of the files in that transaction should be opened in the same new window. An editor transaction starts with a call to the begin method, may contain one or more calls to operation methods, and ends with a call to the end method. The edit.py file should import renpy.editor, and the Editor class should inherit from renpy.editor.Editor. As additional keyword arguments may be added to methods, each method you define should ignore unknown keyword arguments. Since you're expected to define your own Editor subclass, we present the methods with the s e l fparameter. class E d i t o r

b e g i n (self, new_window=False, **kwargs)

Starts an editor transaction.

If n e w _ w i n d o wis true, the editor should attempt to open a new window. Otherwise, it should attempt to perform the transaction in an existing editor window.

e n d (self, **kwargs)
Ends a transaction.

o p e n (self, filename, line=None, **kwargs)

Opens a f i l e n a m ein the editor. If l i n eis not None, attempts to position the editing cursor at l i n e .

Changes and License

Full Changelog
Ren'Py 6.14
Ren'Py Launcher Rewrite

The Ren'Py launcher has been rewritten. Some of the improvements are: A new visual design by Doomfest of the Dischan visual novel team. The launcher now includes direct access to open the script and game directories, and common script files. The launcher includes Script Navigation support. Clicking the name of a label, define, transform, screen, or callable will open the editor to the location where that name is defined. Script navigation also provides access to individual script files. The launcher now supports one-click project building. Instead of using multiple steps to build a project, a single click will now cause the launcher to: Read the build process configuration from the game script. Build the archives needed. Generate the archive and update files. The launcher can now use the Ren'Py updater to update Ren'Py, and to download editors.
Editra & Text Editing

For most users, Ren'Py recommends the use of the Editra editor. We have developed an Editra plugin that communicates with the Ren'Py launcher and supports the editing of Ren'Py script. While still in beta, Editra is a fast and light editor with good code editing support. Editra also includes a spell-checker that can be enabled, and applies to dialogue and other strings. If Editra is selected by the user, and it is not installed, Ren'Py will automatically download it. The jEdit editor remains supported, and is preferred for use with languages (like Chinese, Japanese, and Korean) that Editra doesn't support fully. If selected, Ren'Py will download jEdit automatically. Ren'Py also supports editing files through system-specific file associations. (This support will not send the cursor to the correct line, however.)

Ren'Py Web Updater

Ren'Py includes an updater that can update Ren'Py and individual Ren'Py games by downloading changes from a properly-configured web server with a small number of update files uploaded to it. The updater uses zsync to download the minimal set of changes between the local files on disk and the files stored on the server. A single set of files on the server supports updating from all prior versions of a project. Ren'Py includes a default updater interface that can be further configured by interested users.
Transform Changes

This release changes the behavior of transforms to make them more correct and easier to use. The xzoom and yzoom properties are now applied before, rotation. This means that the shape of the image will remain consistent as the image is rotated. Previously, the image to change shape as it was rotated. The xzoom and yzoom properties may now be negative, with negative zoom values causing the images to be flipped. The positioning code now takes this into account, and positions a flipped image properly. Thanks to Edwin for contributing these changes.
Screen Language, Displayable, and Transition Enhancements

The Textbutton and Label screen language statements now take properties prefixed with t e x t _ . These properties have the text_ prefix stripped, and are then passed to the internal text displayable. The Viewport screen language statement now takes a s c r o l l b a r sparameter. If given, scrollbars that manipulate the viewport are created. The Viewport screen language statement now takes x i n i t i a land y i n i t i a lparameters. If given, these control the initial positioning of the viewport. A screen language block may now contain multiple has statements. Screen language widgets that take single children can now take a has statement. The input displayable now supports the use of the left and right arrow keys within the text. (Thanks to Edwin for this feature.) M o v e T r a n s i t i o n ( )has been rewritten. The new version now uses transforms to control the positioning of entering and leaving images, and can interpolate between the locations of moving images.
Rollback Improvements

The new r e n p y . f i x _ r o l l b a c k ( )function allows the game to fix choices, even if they are made in rollback mode. The user can roll back and roll forward, but is restricted to making the choices he made the first time through the game. Thanks to Edwin for contributing fix_rollback. Rolling forward now works through a jump out of a c a l ls c r e e nstatement.
Video Improvements

Ren'Py's video playback support has been partially rewritten to improve robustness, speed, and framerate stability. These improvements should reduce the number of frame drops Ren'Py performs, and should also prevent Ren'Py from locking up if too many frames are dropped.

Ren'Py now supports the WebM video format.

Image Load Log

When c o n f i g . d e v e l o p e ris true, Ren'Py keeps an internal log of image loads. This log can be access by showing the _image_load_log screen. This screen displays the name of an image file for a few seconds after that image has been loaded. The name is in white if the image was loaded by the image predictor, and pink if Ren'Py was unable to predict the image.
File Actions and Functions

Two screen functions have been added, and two screen actions have been changed: The new F i l e U s e d S l o t s ( )function returns a list of used file slots on the current page. The new F i l e C u r r e n t P a g e ( )function returns the name of the current page. The F i l e S a v e ( )and F i l e A c t i o n ( )actions have been modified so that if the slot name is None, an unused slot based on the current time is used. Taken together, these changes make it possible to create a list of save slots where the user is able to add new slots to the list.
Multiple Store Support

Ren'Py now supports multiple stores - multiple namespaces in which python code can be run. Variables in these stores are saved, loaded, and rolled-back in the same way that variables in the default store are. Stores are accessed by supplying an in-clause to a python block. For example:
i n i tp y t h o ni ns t a t s : d e fr e s e t ( ) : " " " C o d et or e s e tt h es t a t i s t i c s . " " "

User-created stores are placed into the "store" package, with the default store being the package itself. Names can be imported between packages.
i n i tp y t h o n : f r o ms t o r e . s t a t si m p o r tr e s e t i n i tp y t h o ni ns t a t s : f r o ms t o r ei m p o r tT o g g l e F i e l d

Note that stores do not affect the order in which init python blocks are run. A name must be defined in a block before the one that imports that name.
Platform Support and Library Updates

Linux support has been changed. The Linux platform supports the x86_64 CPU architecture in addition to the x86 architecture. The Ren'Py shell script will automatically determine the platform it is running on when it is launched. The Linux version is now linked agains the libraries from the 2009-era Ubuntu 10.04 Lucid. (Previously, Ren'Py had been linked against 2006's Dapper.) Older versions of

Lucid. (Previously, Ren'Py had been linked against 2006's Dapper.) Older versions of Linux are no longer supported. Many libraries that Ren'Py depends on have been updated. Some of the changes that have occured are: Python has been updated to version 2.7.3. Pygame has been updated to version 1.9.1. GLEW has been updated to version 1.7.0. This may fix OpenGL problems on some Linux systems. LibAV has been updated to version 0.7.6, and has been compiled with CPU detection enabled.
Other Changes

The r e n p y . c a l l ( )function allows - with major and important caveats - a call to a Ren'Py label to begin from inside python code. Such a call immediately terminates the current statement. When an action is expected, nested lists of actions can be given. The lists are flattened and the action executed. Added the O p e n U R L ( )action, which opens a URL in a web browser. Added the c o n f i g . g l _ r e s i z evariable, which determines if the user can resize OpenGL windows. Ren'Py's handling of command line argments has been rewritten. Most notably, lint is now invoked with the
r e n p y . s h< g a m e n a m e >l i n t

command. (Which also works with renpy.exe.) Ren'Py can now dump information about the game to a json file when starting up. The information dumped can assist other tools in providing launcher-like code navigation. The little-used remote control feature has been removed from Ren'Py. The c o n f i g . g l _ r e s i z evariable now controls resizing of a game running in GL mode. Documentation fixes (by SleepKirby and others). The NVL-Mode tutorial has been ported to Sphinx (by Apricotorange). Ren'Py now defaults to reporting errors with sound and music files when config.developer is True. Ren'Py 6.13.9 The new RAPT tool makes it far easier to package a Ren'Py game for Android. It can semiautomatically set up an Android build environment on your system, build a package, and install that package on your Android device. To fix some editor-related problems, backported the 6.14 editor system. This changes how editors are configured. Please see Text Editor Integration for a description of the new system. The new c o n f i g . s a v e _ d u m pvariable causes Ren'Py to write out save_dump.txt each time it saves. This file describes the contents of the save, making it possible to figure out what's causing an overly large save file. Worked around a bug in Mesa that can cause crashes on certain Linux systems. Fixed the following bugs in Ren'Py.

The (default) texwrap layout represents character widths as floating-point numbers. This fixes a bug where non-integer kerning would lead to text overflowing its bounding box. Menu choices are logged correctly. All file access is now done in unicode, rather than the system's native encoding. This prevents crashes that occured when Ren'Py was placed in a directory that had non-ASCII characters in it. Fixed focus_mask on the ANGLE renderer. Displayables can now have fractional-pixel sizes. This allows a zooming image to remain precisely centered on the screen. Fixed a problem where Ren'Py would save unnecessary trees of displayables each time it saved a screen. This would lead to overly large save files and slow save performance. Ren'Py would not attempt an alternate rendering method if the texture test failed, leading a "Textures are not rendering properly." exception. A crash in Render.fill. Ren'Py 6.13.8 Side images can now be limited to showing a single character, or only showing characters that are not on the screen. See c o n f i g . s i d e _ i m a g e _ t a gand c o n f i g . s i d e _ i m a g e _ o n l y _ n o t _ s h o w i n g . Added c o n f i g . p y t h o n _ c a l l b a c k s , a list of python functions that are called at the end of each python block. Ren'Py now tests the video card it is running on for functionality. If it can't draw textured rectangles to the screen, it will proceed to a different renderer. Old-style string interpolation is now enabled by default, alongside new-style string interpolation. Ren'Py is now compatible with libpng 1.5. Thanks to James Broadhead for the patch. Fixed the following bugs: A crash when dealing with certain invalid fonts. Pausing too long when typing out text. Cutting one pixel off a block of text when fractional kerning was used. Crashing when the time was set in the far future or past. Immediately exiting when rolling forward at the quit prompt. Crashing when a non-existing directory is added to the search path. (This prevented Katawa Shoujo from starting in the latest version.) Save-file size was overly large due to screens being included in save files. Ren'Py 6.13
Text Rewrite

Text display has been rewritten from scratch. In addition to supporting many new features, the new implementation of Text is much faster at text layout and display, and contains much cleaner code. Some of the new features that are now supported by the text display system are: Interpolation of variables enclosed in square brackets. It's now possible to write code like:
" Y o us c o r e d[ s c o r e ]o u to fap o s s i b l e[ m a x _ s c o r e ]p o i n t s . "

The new string interpolation takes place on all text that is displayed, rather than just say and menu statements. When used as part of a screen, interpolation has access to

screen-local variables. PEP 3101-style string formatting is supported, which means that this syntax can be used to display fields and items, as well as variables. Kerning support was added, both as the k e r n i n gstyle property and the ktext tag. Support for ruby text (also known as furigana), via the r tand r btext tags, and the r u b y _ s t y l estyle property. The new s p a c eand v s p a c etext tags make it easy to whitespace into the text. The new c p stext tag controls the speed of text display. By default, Ren'Py uses the unicode linebreaking algorithm to find points at which a line can be broken. This algorithm should correctly break lines that contain a mix of western and eastern languages. Since that algorithm is incorrect on some Korean texts, Ren'Py also implements a korean-with-spaces variant, that only breaks runs of Korean text at whitespace. These algorithms can be selected by the l a n g u a g estyle property. Ren'Py now uses the Knuth-Plass linebreaking algorithm to choose the points at which it actually splits lines. This algorithm attempts to minimize the unevenness of all lines except the last. Ren'Py also supports a nobreak mode, which allows one to create a Text larger than the screen without it being automatically wrapped. These can be selected using the l a y o u tstyle property. The new n e w l i n e _ i n d e n tstyle property determines if Ren'Py adds indentation after a newline in text. The new l i n e _ l e a d i n gstyle property inserts space above a line of text. (Ruby text can be placed into this space.) Text can be automatically translated before it is displayed. (This support will be improved in a future major release.)
DirectX Support

On Windows systems that have the February 2010 DirectX update installed, Ren'Py will use DirectX via the ANGLE adaptation layer, if OpenGL 2.0 or later is not found. The ANGLE layer is used by popular web browsers such as Firefox and Google Chrome. This allows hardware rendering to be used on netbooks, where drivers often support DirectX far better than OpenGL. At startup, Ren'Py will test the graphics capabilities of the computer it is running on. If the software render is being used, or the game renders at an unacceptably slow speed, Ren'Py will display a warning message to the user. The warning message includes a link to a page on renpy.org that explains how to update the graphics drivers. This version of Ren'Py will only use the software renderer if both DirectX and OpenGL are incapable of rendering Ren'Py games. Screen-scaling in the software renderer has been replaced by a simpler but slower version.
Other Changes

Ren'Py now includes a style preference system. This system allows styles to be changed after the init phase has finished. These changes are saved with the persistent data. Among other things, style preferences allow a game to offer the user the option to change the font, size, and color of dialogue text. Support has been added for screen-based image galleries and music rooms. This support consists of a classes that provides actions that make it easy to present the user with graphics and music. The creator is responsible for creating screens that use the supplied actions. The default screens.rpy file, used when a new game is created, contains support for a "quick menu". This menu adds buttons to screens that allow the user to quick save, quick load, save, toggle skipping, toggle auto-forward mode, and access the preferences

load, save, toggle skipping, toggle auto-forward mode, and access the preferences menu. Ren'Py includes 5 new themes, and a number of new color schemes. Several new actions have been added. The S e l e c t e d I f ( )action allows the creator to control if a button is displayed in the selected state. The S e t M i x e r ( )action allows a mixer to be set to a specific value. The R o l l b a c k ( )and R o l l F o r w a r d ( )actions allow the creator to bind rollback to buttons. The behavior of the xfill and yfill style properties was accidentally changed in the 6.12 series. It has been returned to the historical behavior. The D i s s o l v e ( )and I m a g e D i s s o l v e ( )transitions now take a time_warp parameter. The F r a m e ( )displayable now allows the user to specify the left, top, right, and bottom borders independently. The c a r e tstyle property allows the user to customize the caret of an input widget. The r e n p y . d i s p l a y a b l e ( )function has been exposed to the user. Timers can now take a list of actions, rather than just a single callable. Three transforms were added to the default library: t o p ,t o p l e f t , and t o p r i g h t . Ren'Py can now load files (including images, music, and fonts) from an Android package. User-defined statements can now take a block, which the statement is responsible for parsing. Wrote documentation for: Menus Transforms Creator-Defined Displayables Several indexes were added to the documentation, and the style was updated. Ren'Py now uses the libjpeg-turbo library, for faster jpeg loading. Ren'Py now uses libav 0.7.1, for improved compatibility with movie formats. Removed support for the iLiad platform. PowerPC support has been removed from the main Ren'Py distribution. It's available as a download from the Ren'Py web site. Thanks to Aleema for contributing the new themes and color schemes. Ren'Py 6.12.2 This release contains the following changes: ATL Transforms with parameters compile correctly. MultipleTransition works in conjunction with pauses. The mouse is shown when a quit action is run while a movie is playing. A fix for a lockup that occured when the user entered the game menu while a transition was running. RENPY_SCALE_FAST works again. Ren'Py compiles with newer versions of ffmpeg. Skipping ends when the game restarts. Fixed a problem with texture upload that made games noticeably slower. Choose a better default size for windows on small monitors, like netbooks. xfill and yfill now work for vbox and hbox, respectively. Click-to-continue fixes. Side image fixes. Documentation fixes.

Thanks to David Gowers and zhangning for contributing patches to this release. Ren'Py 6.12.1
Image Attributes

The process of showing images is now attribute-based. Image names now consist of a tag, and zero or more attributes. When showing an image, the order of attributes is no longer important - it's now possible to define an image using one set of attributes, and show it using those attributes in a different order. Attributes are also "sticky". This means that we attempt to preserve as many attributes as possible when showing a new image. For example, say we had the following images:
i m a g ee i l e e nb e a c hh a p p y=" e i l e e n _ b e a c h _ h a p p y . p n g " i m a g ee i l e e nb e a c hw o o z y=" e i l e e n _ b e a c h _ w o o z y . p n g "

We can now show the first image using the command:

s h o we i l e e nh a p p yb e a c h

Since the order of attributes no longer matters, this will show the "eileen beach happy" image. If we follow this with the show statement:
s h o we i l e e nw o o z y

the image "eileen beach woozy" will be shown. (Assuming no other images exist. If the image "eileen happy woozy" existed, an ambiguity error would occur.) When an image tag is shown without any attributes, then the current attributes are retained. Now, one can write:
s h o we i l e e na tr i g h t

to display Eileen on the right side of the screen, without changing the attributes supplied to an image. Say Attributes. Image attributes can be updated as part of a say statement. A character can be given an i m a g eargument, giving the name of an image that character is linked to. As part of the say statement, image attributes can be given before the dialogue string. These attributes are given to the linked image. For example, if we define a character using the code:
d e f i n ee=C h a r a c t e r ( ' E i l e e n ' ,i m a g e = " e i l e e n " )

the code:
ew o o z y" It h i n kI ' mg e t t i n gt o om u c hs u n . "

is equivalent to:
s h o we i l e e nw o o z y e" It h i n kI ' mg e t t i n gt o om u c hs u n . "

whenever an image with the tag eileen is being shown. Side Image. This release features a new implementation of Side Images, which allows side images to be defined like other images, and allows side images to be integrated with screens easily. Sticky Transforms. Finally, showing an image without providing a transform or ATL block will now continue the previous transform that an image with that tag was using. Previously, it caused those transforms to stop.
Error Handling

Ren'Py now has a new exception handing framework. Instead of always crashing when an error occurs, Ren'Py will now display the error message on the screen, and give the user the following choices, as appropriate to the situation: Rollback Reload Ignore Open Traceback Quit When an editor is defined, Ren'Py will allow the user to click on a filename and line number to open that line in the editor. The framework is used to handle exceptions and parse errors.
Other

When in OpenGL mode, Ren'Py now remembers the window size between sessions. (This can be disabled using c o n f i g . s a v e _ p h y s i c a l _ s i z e , and it may make sense to do so if your game is using the pre-screen preferences system.) Choosing the "Window" display preference now resizes the window to 100% of normal size. Added the x c e n t e rand y c e n t e rposition and transform properties. These set the position of the center of a displayable. The r e n p y . v i b r a t e ( )function allows Ren'Py to ask Android devices to vibrate. The hyperlink style, callback, and focus functions have now been moved to the h y p e r l i n k _ f u n c t i o n sstyle property. This allows the functions to be changed on a per-style basis. Indentation errors are now reported on the indented line, and not the line preceding the erroneous indentation. Added the S e t S c r e e n V a r i a b l e ( )and T o g g l e S c r e e n V a r i a b l e ( )actions. These allow screenlocal variables to be changed. Ren'Py now attempts to elide personal information from filenames. Where possible, filenames are reported relative to the base or Ren'Py base directories, rather than the root of the filesystem. The new b o x _ w r a pstyle property allows hboxes and vboxes to automatically wrap when they reach the edge of their enclosing area. Actions now can have an A c t i o n . u n h o v e r e d ( )method. This method is called when an action supplied as a h o v e r e dparameter loses focus. Added the T o o l t i pclass, which makes it easier to define tooltips as part of a screen. Added c o n f i g . d e b u g _ t e x t _ o v e r f l o w , which controls the logging of cases where text exceeds its allocated area.

its allocated area. Ren'Py no longer attempts to adjust the system level mixer controls, which means that it's no longer possible to raise the volume from within Ren'Py. Controlling the system volume exhibited bugs on all three platforms, including hard-to-predict volume changes that affect other applications. Along with the new features, transitions have been documented in the new manual. Archives are now automatically detected in asciiabetical order. See the documentation for c o n f i g . a r c h i v e sfor more details. Bug fixes: launchpad bug 734137 - Timers do not participate in rollback. launchpad bug 735187 - Ren'Py get stuck when using {nw}. (Thanks to Franck_v for tracking this down.) Ren'Py 6.12.0
Android Support

Ren'Py now supports the Android platform. This includes support for a large fraction of Ren'Py's functionality, although we were unable to add support for imagedissolves and movie playback. It should be possible to package a Ren'Py game and distribute it through the Android market. Android support required several changes in Ren'Py: The OpenGL renderer has been extended to support OpenGL ES. For performance reasons, much of the display system has been rewritten in the Cython language. This also should improve performance on other platforms. Support was added for the Android lifecycle. Ren'Py automatically saves when the android device suspends, and reloads (if necessary) upon resume. We added the concept of Screen Variants. This allows a single game to have multiple interfaces - such a mouse interface for computer platforms, and a touch interface for Android-based smartphones and tablets. We built a system that allows one to package a game separately from Ren'Py. This allows one to build packages without having to set up the Android NDK (you'll still need the Android SDK, Java, Python, Ant, and a lot of patience).
New Widgets and Displayables

Added the SpriteManager displayable. This provides a high-performance way of drawing many similar sprites to the screen. This can scale to hundreds of particles, provided those particles are mostly similar to each other. Added the Mousearea widget. A mousearea allows hovered and unhovered callbacks to occur when the mouse enters and leaves an area of the screen. Since it doesn't participate in the focus system, a mousearea can include buttons and bars. Added Drag and Drop widgets and displayables. The drag and drop system can support: Windows being repositioned by the user. Card games. Inventory systems. Drag-to-reorder systems.
Image Prediction

Ren'Py is now better at predicting image usage. Along with predicting images used by normal gameplay, it now attempts to predict images that are used by screens one click away from the user. For example, during normal gameplay, it will predict images on the first screen of the game menu. While at the game menu, it will predict the other screens of the game menu, and also the images the user will see when returning to the main menu. This prediction is automatic, but only occurs when using screens. Screens may be invoked at any time, in order to allow for image prediction, unless they have a predict property of False. This means that displaying a screen should not have side effects. (Most screens only have side effects when a button is clicked or a bar changed - that's still fine.) Ren'Py now supports hotspot caching for screen language imagemaps. When c o n f i g . d e v e l o p e ris true, Ren'Py will write a PNG file in the game/cache/ directory containing image data for each of the hotspots in the imagemap. If the cache file exists (regardless of the config.developer setting) it will be loaded instead of loading the hotspot images. As the cache file is often much smaller than the size of the hotspot images, it will load faster and reduce image cache pressure, improving game performance. This behavior only applies to screen language imagemaps, and can be disabled with c o n f i g . i m a g e m a p _ c a c h e . This should remove most of the need for r e n p y . c a c h e _ p i n ( ) . While not an error, the use of cache pinning can cause unnecessary memory usage when the wrong image is loaded.
Screens

Ren'Py now ships with a default set of screens, which are used by the demo and installed by default when a new game is created. You can find them in template/game/screens.rpy, and they can be used by copying that file into your project. These screens are not 100% compatible with the previous layout system - for example, some styles have changed. That's why games must opt-in to them. The definition of the i t e m sparameter of the Choice and NVL screens has changed, and games will need to be updated to work with the new version. Character arguments beginning with s h o w _are passed to the Say screen. This allows things like show_side_image and show_two_window to work with screens. The screens we ship support these options. The new c o n f i g . i m a g e m a p _ a u t o _ f u n c t i o nvariable allows the game-maker to control the interpretation of the a u t oproperty of imagemaps and imagebuttons. The imagemap caching behavior described above applies only to screens. The F i l e P a g e N a m e ( )and F i l e S l o t N a m e ( )functions make it easier to name slots
Other Improvements

Ren'Py 6.12 includes a number of other improvements: We've continued writing the new manual. Notably, we have rewritten the documentation for displayables. When taking a screenshot, c o n f i g . s c r e e n s h o t _ c a l l b a c kis called. The default implementation of this function notifies the user of the location of the screenshot. The S o l i d ( )and F r a m e ( )displayables are now tiny and no longer take up (much) space in the image cache. We now create a log.txt file, which replaces the old opengl.txt, and can log other subsystems. Several missing properties have been added to the screen language. Ren'Py now treats filenames as if they were case-insensitive. This means that filename mismatches on Linux should no longer be a problem.

Bug Fixes

launchpad bug 680266 - Ensures that dynamic displayables update before Transforms that use them. launchpad bug 683412 - Do not crash if a shader fails to compile. Fixed a bug that caused Ren'Py to crash when the system volume was lowered to 0, but not muted. Fixed a bug that prevented R e n d e r . c a n v a s ( )from working with the OpenGL renderer. Ren'Py 6.11.2
New Features

This release includes four new themes, generously contributed by Aleema. You can see and change to these new themes by clicking the "Choose Theme" button in the launcher.
Software Update

The jEdit text editor included with Ren'Py has been updated to version 4.3.2, a supported version that should be able to run most plugins.
Behavior Changes

The maximum default physical size of the Ren'Py window is now 102 pixels smaller than the height of the screen. This should prevent Ren'Py from creating windows that can't be resized since they are much bigger than the screen. Buttons now only pass key events to their children when they are focused. This allows a screen language key statement to be used as the child of a button, and only activate when the button is focused. MoveTransition was rewritten to correctly deal with cases in which images changed their order. This may lead to differences in behavior from the old version, where the ordering was undefined.
Bug fixes

Fixed launchpad bug 647686, a regression that prevented sounds from looping properly. Fixed launchpad bug 661983, which caused insensitive hotspots to default to the idle, rather than ground, image when no insensitive image was supplied. Fixed launchpad bug 647324, where ImageDissolves are rendered as if specified with alpha=True whether or not alpha=True was set. Fixed a problem that caused the game to start when picking "No" after clicking the (windowlevel) quit button. Fixed a problem that prevented AnimatedValue from functioning properly when delay was not 1.0. Thanks to Scout for the fix. Fixed a problem that caused movies to display incorrectly when the screen was scaled using OpenGL scaling. Ren'Py 6.11.1
New Features

Add the A l p h a B l e n d ( )displayable and the A l p h a D i s s o l v e ( )transition. These take two displayables, and use the alpha channel of a third displayable to blend them together. (The

displayables, and use the alpha channel of a third displayable to blend them together. (The third displayable is often an animation, allowing the effect to change over time.) The new Modes system allows one to invoke callbacks when switching from one type of interaction to another. This can be used, for example, to automatically hide the window before transitions. Imagemaps created using the screen language now only have a size equal to that of their ground image. (Previously, they took up the entire screen.) This change makes it easier to position an imagemap at a different location on screen, such as the bottom. Imagemaps now take an alpha argument. If true (the default), hotspots are only focused if the mouse is over a non-transparent part of the idle or hover image. If set to false, the hotspot is focused whenever the mouse is within its boundaries. Added the r e n p y . f o c u s _ c o o r d i n a t e s ( )function, which returns the coordinates of the currently focused displayable, when possible. The new r e n p y . n o t i f y ( )function and N o t i f y ( )action make it simple to flash small status messages on the screen, such as might be used to notify the user of a completed quicksave or screenshot. The new H i d e I n t e r f a c e ( )action allows the interface to temporarily be hidden, as a screen language action. The developer menu now includes a command that will list all the files in the game directory. The urllib and urllib2 modules from the Python standard library are now distributed as part of Ren'Py. These modules allow data to be retrieved from web servers. The launcher now includes an experimental updater, that makes it easier to update to the latest pre-release. Hitting shift+U at the launcher's main screen will cause Ren'Py to be updated.
Fixes

M o v e T r a n s i t i o n ( )now respects the xoffset and yoffset parameters.

Fixed several bugs with screen-language imagemaps. Fixed a bug (#626303) that was caused by an incorrect texture unit check. Thanks to tmrwiz for the fix. Transforms no longer cause a divide by zero exception when the zoom, xzoom, or yzoom properties are 0. Clockwise and counterclockwise revolution in transforms now works. Fixed a bug with scaling, that occured when switching between the scaled software and GL renderers. Hidden screens are no longer considered when assigning default focus. FieldValues with max_is_zero set to True now work properly. Thanks to SleepKirby for the fix. Ren'Py 6.11.0
OpenGL Support

Ren'Py will now take advantage of a computer's OpenGL hardware acceleration, if supported. This OpenGL support has several user-visible changes: The window containing a Ren'Py game can be resized or maximized, using standard window controls. When the window's aspect ratio does not match the game's aspect

window controls. When the window's aspect ratio does not match the game's aspect ratio, black bars will be added. Displaying in full-screen mode should not change the monitor's resolution. This will prevent the game from being distorted when displayed on a monitor with a different aspect ratio. Unless disabled in the video driver configuration, Ren'Py will use vertical blank synchronization, eliminating image tearing. GPU rendering is used, which should make drawing the screen faster in most circumstances. Software rendering is still supported, and Ren'Py will automatically fall back to software rendering if it detects an improperly configured video card. You can test that Ren'Py is in OpenGL mode by attempting to resize the window. If it's resizable, it's OpenGL, otherwise, software rendering is being used.
Screens and Screen Language

This release introduces a new screen system, which allows one to use the new screen language to declaratively specify portions of the user interface. The screen language supersedes layouts, overlay functions, imagemaps, and most other means of customizing the out-of-game menus and the in-game screens. The previous way of customizing the behavior of the game menu, the layout system, had problems, especially when using imagemap layouts. Screens were single-purpose, and it would be difficult to (for example) load a quick-save game from the main menu, without extensive Python code. The screen system addresses this by providing a pool of functionality, in the form of Actions and BarValues. This makes it possible to pick and choose functionality, and add it to screens as is deemed necessary.
Transform Changes

If a transform does not define one of the position properties x p o s ,y p o s ,x a n c h o r , or y a n c h o r , that property will be taken from the transform's child, if the defines that property. This makes it possible to have one transform control a displayable's vertical motion, and the other control the horizontal. But this is incompatible with previous behavior, and so can be disabled with the c o n f i g . t r a n s f o r m _ u s e s _ c h i l d _ p o s i t i o nvariable. The new config.default_transform variable allows a transform to specify the initial transform properties of an image that does not have a more specific transform applied to it. Its default value is center, a transform that shows the image at the center-bottom of the screen. This can lead to a behavior change. When an image is shown, and then shown transforms, the transform will be initialized to the bottom center of the screen, not the top-left. The reset transform can be used to reset the position to the top-left. Transform (and ui.transform) have been changed so that their arguments can now be prefixed with a style prefix. One can write ui.transform(idle_rotate=30, hover_rotate=90) and have it work. Added the rotate_pad transform property, which controls how Transform pads rotated displayables. When set to False, _not_ the default, it's now possible to rotate a (100, 50) displayable by 90 degrees, and have the result be (50, 100) in size.
Other Changes

The Ren'Py documentation is in the process of being rewritten. This changelog is now being maintained as part of the Ren'Py documentation. Added support for composite style properties, that allow several style properties to be set using a single parameter. The new composite style properties are: pos - takes a pair, and uses it to set xpos and ypos. anchor - takes a pair, and uses it to set xanchor and yanchor. align - takes a pair, and uses it to set xalign and yalign. (And hence xpos, ypos, xanchor, and yanchor.) area - take (x, y, height, width) pair, and tries to set properties such that the displayable will be placed inside the rectangle. This sets the xpos, ypos, xanchor, yanchor, xfill, yfill, xminimum, yminimum, xmaximum, and ymaximum properties. ui.add can now take transform properties as keyword arguments. If at least one transform property is present, ui.add will create a transform that wraps the displayable it's adding to the screen. The new L i v e T i l e ( )displayable tiles its child, without consuming a large amount of memory to do so.
c o n f i g . q u i t _ a c t i o nallows one to specify an action that is run when the quit button (in

the corner of the window) is pressed. config.game_menu_action allows one to specify an action that is run when entering the game menu. The c o n f i g . s c r e e n s h o t _ c r o pconfiguration variable controls the area of the screen that it stored when the user presses the screenshot key. The r e n p y . m u s i c . r e g i s t e r _ c h a n n e l ( )method now has two additional parameters, file_prefix and file_suffix. These are prepended and appended to filenames provided to the registered channel, respectively. The new r e n p y . l i s t _ f i l e s ( )method returns a list of files in the game directory and archives. This can be used to write your own automatic image loading method, among other things. The interaction between Character and Text has been rewritten to ensure that text is only tokenized once. This required changing a few of the methods on ADVCharacter and NVLCharacter, so code that inherits from those classes should be checked. The distribution code has been moved into launcher/distribute.py. This file can be run from the command line to build distributions in shell scripts and other automated processes. When there are transparent areas on the screen, and c o n f i g . d e v e l o p e ris true, the transparent areas are filled with a checkerboard pattern. The new i n p u t ,s i d e ,g r i d , and f i x e dstyles were created, and the corresponding displayables use them by default. When a style is accessed at init-time, and doesn't exist, we divide it into two parts at the first underscore. If the second part corresponds to an existing style, we create a new style instead of causing an error. The python compiler has been rewritten to use the python ast module. This should both improve performance, and improve error handling for python syntax. Because of this change, Ren'Py now ships with and requires Python 2.6. The following numbered bugs were fixed: 520276 - ctc does not appear when cps interrupted 526297 - im.Rotozoom()s crash when Ren'Py is scaled down. (Thanks to Spiky Caterpillar for the bug report and fix.) 543785 - Launcher bug on select Projects Directory 583112 - rollback while a movie displayable is shown leaves a video frame onscreen 595532 - Wrong text in tutorial game. (Thanks to Viliam Br.)

The following other bugs were fixed: Renamed the internal show and hide methods of Displayable, so those names can once again be used by user-defined displayables. Rewrote MultipleTransition (which is used by Fade) to fix some problems it was exhibiting. Take the condition parameter to Character into account when determining if an nvl clear occurs before the next interaction.

Incompatible Changes
This is a list of changes that may require intervention in the form of changes to scripts or your development environment. Our intent is that all other changes should not affect existing scripts. Note that setting c o n f i g . s c r i p t _ v e r s i o nwill cause many of these changes to be reverted, at the cost of losing access to recent features. 6.14 Previously, Ren'Py moved archived files into the archived/ directory. It would search this directory automatically when running a game or building archives. One-click builds make this unnecessary, and files in archived/ should be moved back into the game directory.
M o v e T r a n s i t i o n ( )has changed its interface. The old version of MoveTransition can be

accessed as OldMoveTransition, if you don't want to rewrite your code. (The changes only matter if you use factories with MoveTransition.)
T r a n s f o r m ( )has changed its behavior with regards to asymmetrically scaled and rotated

images. It's unlikely the old behavior was ever used. 6.13.8

Old-style string interpolation has been re-enabled by default. If you wrote code (between 6.13 and 6.13.7) that uses % in say or menu statements, you should either write %% instead, or include the code:
i n i tp y t h o n : c o n f i g . o l d _ s u b s t i t u t i o n s=F a l s e

6.13 The changes to text behavior can affect games in development in many ways. The biggest change is the introduction of new-style (square-bracket) text substitutions, and the elimination of old-style (percent-based) substitutions. These changes can be reverted with the code:
i n i tp y t h o n : c o n f i g . o l d _ s u b s t i t u t i o n s=T r u e c o n f i g . n e w _ s u b s t i t u t i o n s=F a l s e

New- and old-style substitutions can coexist in the same game, by setting both variables to True. Ren'Py has also changed the default line-wrapping behavior. While the new behavior should never increase the number of lines in a paragraph, it may change which words fall on each

line. To restore the old behavior, add the code:

i n i tp y t h o n : s t y l e . d e f a u l t . l a y o u t=" g r e e d y " s t y l e . d e f a u l t . l a n g u a g e=" w e s t e r n "

A bug with negative line_spacing was fixed. This fix can cause blocks of text to shrink in height. To revert to the old behavior, use:
i n i tp y t h o n : c o n f i g . b r o k e n _ l i n e _ s p a c i n g=T r u e

Finally, the new text code may lead to artifacts when displaying slow text, especially in conjunction with a negative line spacing. Consider adjusting :prop:`line_overlap_split` to fix this. 6.12.1 Image names have changed from being static names to being attribute-based. This can lead to image names that were previously distinct becoming ambiguous. To disable attribute-based image names, set c o n f i g . i m a g e _ a t t r i b u t e sto False. Showing an image without providing a transform or ATL block will now continue the previous transform that the image was using. This means that a moving image may continue moving once it has changed. To revert to the old behavior, set c o n f i g . k e e p _ r u n n i n g _ t r a n s f o r mto False. The i m a g eargument to C h a r a c t e r ( )has changed meaning. While the old meaning was unsupported in the screens-based environment, it can be restored for compatibility purposes by setting c o n f i g . n e w _ c h a r a c t e r _ i m a g e _ a r g u m e n tto False. 6.12.0 The definition of the i t e m sparameter of the Choice and n v l _ c h o i c escreens has changed. The n v l _ c h o i c escreen is deprecated in favor of the NVL screen. Screens may be invoked at any time, in order to allow for image prediction, unless they have a predict property of False. When the predict property is not False, screens should not cause side effects to occur upon their initial display. For performance reason, Ren'Py now ignores the position properties of ImageReferences. This means that the position properties of style.image_placement are now ignored. To revert to the old behavior, set c o n f i g . i m a g e r e f e r e n c e _ r e s p e c t s _ p o s i t i o nto True. 6.11.1 MoveTransition has been modified to respect the xoffset and yoffset parameters of the displayables it is moving. The factory functions that are used for movement now take x o f f s e t and y o f f s e tparameters. While the built-in movement factories take these parameters without problem, user-defined factories may need to be upgraded to use or ignore these additional parameters. 6.11.0 The transform specified by the c o n f i g . d e f a u l t _ t r a n s f o r mvariable is used to initialize the transform properties of images shown using the show and hide statements. The default value of this transform sets x p o sand x a n c h o rto 0.5, and y p o sand y a n c h o rto 1.0.

This represents a change in the default value of these style properties, which were previously uninitialized and hence defaulted to 0. By including the r e s e ttransform in ATL transforms, these properties can be reset back to 0. Alternatively, one can stop using the default transform, and revert to the old behavior, using the code:
i n i tp y t h o n : s t y l e . i m a g e _ p l a c e m e n t . x p o s=0 . 5 s t y l e . i m a g e _ p l a c e m e n t . y p o s=1 . 0 s t y l e . i m a g e _ p l a c e m e n t . x a n c h o r=0 . 5 s t y l e . i m a g e _ p l a c e m e n t . y a n c h o r=1 . 0 c o n f i g . d e f a u l t _ t r a n s f o r m=N o n e

If a transform does not define one of the position properties x p o s ,y p o s ,x a n c h o r , or y a n c h o r , that property will be taken from the transform's child, if the defines that property. This makes it possible to have one transform control a displayable's vertical motion, and the other control the horizontal. But this is incompatible with previous behavior, and so can be disabled with the c o n f i g . t r a n s f o r m _ u s e s _ c h i l d _ p o s i t i o nvariable.
i n i tp y t h o n : c o n f i g . t r a n s f o r m _ u s e s _ c h i l d _ p o s i t i o n=F a l s e

6.10.0 The default positions (left, right, center, truecenter, offscreenleft, and offscreenright) are now defined as ATL transforms. This means that showing an image at such a position will cause the position to be remembered. If you do not want this behavior, you need to redefine these positions, by adding the code:
d e f i n el e f t=P o s i t i o n ( x a l i g n = 0 . 0 ) d e f i n ec e n t e r=P o s i t i o n ( x a l i g n = 0 . 5 ) d e f i n et r u e c e n t e r=P o s i t i o n ( x a l i g n = 0 . 5 ,y a l i g n = 0 . 5 ) d e f i n er i g h t=P o s i t i o n ( x a l i g n = 1 . 0 ) d e f i n eo f f s c r e e n l e f t=P o s i t i o n ( x p o s = 0 . 0 ,x a n c h o r = 1 . 0 ) d e f i n eo f f s c r e e n r i g h t=P o s i t i o n ( x p o s = 1 . 0 ,x a n c h o r = 0 . 0 )

6.9.2 To migrate your game from Ren'Py 6.9.2 or later, copy the directory containing your game into your projects directory. You can choose a projects directory by clicking "Options", "Projects Directory" in the Launcher. Please see the Ren'Py 6.9.2 release notes for information about migrating from older releases.

Distributor Notes
6.12.0 Ren'Py now creates a number of binary modules that live in the renpy.display package. As long as they go in the same place as _renpy.so, they should be picked up automatically.

6.11.0 Ren'Py now depends on: Python 2.6 OpenGL The GL Extension Wrangler Library: http://glew.sourceforge.net/ The argparse Python module: http://code.google.com/p/argparse/

License
Most of Ren'Py is covered by the terms of the following (MIT) license: Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. Portions of Ren'Py are derived from code that is copyright using the Lesser GNU Public License, so Ren'Py games must be distributed in a manner that satisfies the LGPL. Please see each individual source file for a list of copyright holders. The artwork in the demo is released by various copyright holders, under the same terms. Ren'Py binaries include code from the following projects: Python (Python License) Pygame (LGPL) SDL (LGPL) SDL_image (LGPL) SDL_ttf (LGPL) Freetype (LGPL) Fribidi (LGPL) libav (LGPL) libjpeg-turbo (LGPL) libpng (PNG license) zlib (Zlib License) bzip2 (Bzip2 License) pyobjc (MIT License) py2exe (MIT License) GLEW (Modified BSD, MIT) zsync (Artistic License) For the purpose of LGPL compliance, the source code to all LGPL software we depend on is

either in the Ren'Py package (available from http://www.renpy.org/), or in the renpy-deps package (http://www.renpy.org/dl/lgpl/). We believe compliance can be achieved by including a copy of this license with every copy of Ren'Py you distribute, and referring to it in your project's README file. Ren'Py may be distributed alongside the jEdit or Editra text editors. Editra is licensed under the wxWindows license, while jEdit is under the GNU General Public License. GNU Lesser General Public License
G N UL E S S E RG E N E R A LP U B L I CL I C E N S E V e r s i o n2 . 1 ,F e b r u a r y1 9 9 9 C o p y r i g h t( C )1 9 9 1 ,1 9 9 9F r e eS o f t w a r eF o u n d a t i o n ,I n c . 5 1F r a n k l i nS t ,F i f t hF l o o r ,B o s t o n ,M A 0 2 1 1 0 1 3 0 1 U S A E v e r y o n ei sp e r m i t t e dt oc o p ya n dd i s t r i b u t ev e r b a t i mc o p i e s o ft h i sl i c e n s ed o c u m e n t ,b u tc h a n g i n gi ti sn o ta l l o w e d . [ T h i si st h ef i r s tr e l e a s e dv e r s i o no ft h eL e s s e rG P L . I ta l s oc o u n t s a st h es u c c e s s o ro ft h eG N UL i b r a r yP u b l i cL i c e n s e ,v e r s i o n2 ,h e n c e t h ev e r s i o nn u m b e r2 . 1 . ] P r e a m b l e T h el i c e n s e sf o rm o s ts o f t w a r ea r ed e s i g n e dt ot a k ea w a yy o u r f r e e d o mt os h a r ea n dc h a n g ei t . B yc o n t r a s t ,t h eG N UG e n e r a lP u b l i c L i c e n s e sa r ei n t e n d e dt og u a r a n t e ey o u rf r e e d o mt os h a r ea n dc h a n g e f r e es o f t w a r e t om a k es u r et h es o f t w a r ei sf r e ef o ra l li t su s e r s . T h i sl i c e n s e ,t h eL e s s e rG e n e r a lP u b l i cL i c e n s e ,a p p l i e st os o m e s p e c i a l l yd e s i g n a t e ds o f t w a r ep a c k a g e s t y p i c a l l yl i b r a r i e s o ft h e F r e eS o f t w a r eF o u n d a t i o na n do t h e ra u t h o r sw h od e c i d et ou s ei t . Y o u c a nu s ei tt o o ,b u tw es u g g e s ty o uf i r s tt h i n kc a r e f u l l ya b o u tw h e t h e r t h i sl i c e n s eo rt h eo r d i n a r yG e n e r a lP u b l i cL i c e n s ei st h eb e t t e r s t r a t e g yt ou s ei na n yp a r t i c u l a rc a s e ,b a s e do nt h ee x p l a n a t i o n s b e l o w . W h e nw es p e a ko ff r e es o f t w a r e ,w ea r er e f e r r i n gt of r e e d o mo fu s e , n o tp r i c e . O u rG e n e r a lP u b l i cL i c e n s e sa r ed e s i g n e dt om a k es u r et h a t y o uh a v et h ef r e e d o mt od i s t r i b u t ec o p i e so ff r e es o f t w a r e( a n dc h a r g e f o rt h i ss e r v i c ei fy o uw i s h ) ;t h a ty o ur e c e i v es o u r c ec o d eo rc a ng e t i ti fy o uw a n ti t ;t h a ty o uc a nc h a n g et h es o f t w a r ea n du s ep i e c e so f i ti nn e wf r e ep r o g r a m s ;a n dt h a ty o ua r ei n f o r m e dt h a ty o uc a nd o t h e s et h i n g s . T op r o t e c ty o u rr i g h t s ,w en e e dt om a k er e s t r i c t i o n st h a tf o r b i d d i s t r i b u t o r st od e n yy o ut h e s er i g h t so rt oa s ky o ut os u r r e n d e rt h e s e r i g h t s . T h e s er e s t r i c t i o n st r a n s l a t et oc e r t a i nr e s p o n s i b i l i t i e sf o r y o ui fy o ud i s t r i b u t ec o p i e so ft h el i b r a r yo ri fy o um o d i f yi t . F o re x a m p l e ,i fy o ud i s t r i b u t ec o p i e so ft h el i b r a r y ,w h e t h e rg r a t i s o rf o raf e e ,y o um u s tg i v et h er e c i p i e n t sa l lt h er i g h t st h a tw eg a v e y o u . Y o um u s tm a k es u r et h a tt h e y ,t o o ,r e c e i v eo rc a ng e tt h es o u r c e c o d e . I fy o ul i n ko t h e rc o d ew i t ht h el i b r a r y ,y o um u s tp r o v i d e c o m p l e t eo b j e c tf i l e st ot h er e c i p i e n t s ,s ot h a tt h e yc a nr e l i n kt h e m w i t ht h el i b r a r ya f t e rm a k i n gc h a n g e st ot h el i b r a r ya n dr e c o m p i l i n g i t . A n dy o um u s ts h o wt h e mt h e s et e r m ss ot h e yk n o wt h e i rr i g h t s . W ep r o t e c ty o u rr i g h t sw i t hat w o s t e pm e t h o d :( 1 )w ec o p y r i g h tt h e l i b r a r y ,a n d( 2 )w eo f f e ry o ut h i sl i c e n s e ,w h i c hg i v e sy o ul e g a l p e r m i s s i o nt oc o p y ,d i s t r i b u t ea n d / o rm o d i f yt h el i b r a r y .

T op r o t e c te a c hd i s t r i b u t o r ,w ew a n tt om a k ei tv e r yc l e a rt h a t t h e r ei sn ow a r r a n t yf o rt h ef r e el i b r a r y . A l s o ,i ft h el i b r a r yi s m o d i f i e db ys o m e o n ee l s ea n dp a s s e do n ,t h er e c i p i e n t ss h o u l dk n o w t h a tw h a tt h e yh a v ei sn o tt h eo r i g i n a lv e r s i o n ,s ot h a tt h eo r i g i n a l a u t h o r ' sr e p u t a t i o nw i l ln o tb ea f f e c t e db yp r o b l e m st h a tm i g h tb e i n t r o d u c e db yo t h e r s . F i n a l l y ,s o f t w a r ep a t e n t sp o s eac o n s t a n tt h r e a tt ot h ee x i s t e n c eo f a n yf r e ep r o g r a m . W ew i s ht om a k es u r et h a tac o m p a n yc a n n o t e f f e c t i v e l yr e s t r i c tt h eu s e r so faf r e ep r o g r a mb yo b t a i n i n ga r e s t r i c t i v el i c e n s ef r o map a t e n th o l d e r . T h e r e f o r e ,w ei n s i s tt h a t a n yp a t e n tl i c e n s eo b t a i n e df o rav e r s i o no ft h el i b r a r ym u s tb e c o n s i s t e n tw i t ht h ef u l lf r e e d o mo fu s es p e c i f i e di nt h i sl i c e n s e . M o s tG N Us o f t w a r e ,i n c l u d i n gs o m el i b r a r i e s ,i sc o v e r e db yt h e o r d i n a r yG N UG e n e r a lP u b l i cL i c e n s e . T h i sl i c e n s e ,t h eG N UL e s s e r G e n e r a lP u b l i cL i c e n s e ,a p p l i e st oc e r t a i nd e s i g n a t e dl i b r a r i e s ,a n d i sq u i t ed i f f e r e n tf r o mt h eo r d i n a r yG e n e r a lP u b l i cL i c e n s e . W eu s e t h i sl i c e n s ef o rc e r t a i nl i b r a r i e si no r d e rt op e r m i tl i n k i n gt h o s e l i b r a r i e si n t on o n f r e ep r o g r a m s . W h e nap r o g r a mi sl i n k e dw i t hal i b r a r y ,w h e t h e rs t a t i c a l l yo ru s i n g as h a r e dl i b r a r y ,t h ec o m b i n a t i o no ft h et w oi sl e g a l l ys p e a k i n ga c o m b i n e dw o r k ,ad e r i v a t i v eo ft h eo r i g i n a ll i b r a r y . T h eo r d i n a r y G e n e r a lP u b l i cL i c e n s et h e r e f o r ep e r m i t ss u c hl i n k i n go n l yi ft h e e n t i r ec o m b i n a t i o nf i t si t sc r i t e r i ao ff r e e d o m . T h eL e s s e rG e n e r a l P u b l i cL i c e n s ep e r m i t sm o r el a xc r i t e r i af o rl i n k i n go t h e rc o d ew i t h t h el i b r a r y . W ec a l lt h i sl i c e n s et h e" L e s s e r "G e n e r a lP u b l i cL i c e n s eb e c a u s ei t d o e sL e s st op r o t e c tt h eu s e r ' sf r e e d o mt h a nt h eo r d i n a r yG e n e r a l P u b l i cL i c e n s e . I ta l s op r o v i d e so t h e rf r e es o f t w a r ed e v e l o p e r sL e s s o fa na d v a n t a g eo v e rc o m p e t i n gn o n f r e ep r o g r a m s . T h e s ed i s a d v a n t a g e s a r et h er e a s o nw eu s et h eo r d i n a r yG e n e r a lP u b l i cL i c e n s ef o rm a n y l i b r a r i e s . H o w e v e r ,t h eL e s s e rl i c e n s ep r o v i d e sa d v a n t a g e si nc e r t a i n s p e c i a lc i r c u m s t a n c e s . F o re x a m p l e ,o nr a r eo c c a s i o n s ,t h e r em a yb eas p e c i a ln e e dt o e n c o u r a g et h ew i d e s tp o s s i b l eu s eo fac e r t a i nl i b r a r y ,s ot h a ti t b e c o m e sad e f a c t os t a n d a r d . T oa c h i e v et h i s ,n o n f r e ep r o g r a m sm u s t b ea l l o w e dt ou s et h el i b r a r y . Am o r ef r e q u e n tc a s ei st h a taf r e e l i b r a r yd o e st h es a m ej o ba sw i d e l yu s e dn o n f r e el i b r a r i e s . I nt h i s c a s e ,t h e r ei sl i t t l et og a i nb yl i m i t i n gt h ef r e el i b r a r yt of r e e s o f t w a r eo n l y ,s ow eu s et h eL e s s e rG e n e r a lP u b l i cL i c e n s e . I no t h e rc a s e s ,p e r m i s s i o nt ou s eap a r t i c u l a rl i b r a r yi nn o n f r e e p r o g r a m se n a b l e sag r e a t e rn u m b e ro fp e o p l et ou s eal a r g eb o d yo f f r e es o f t w a r e . F o re x a m p l e ,p e r m i s s i o nt ou s et h eG N UCL i b r a r yi n n o n f r e ep r o g r a m se n a b l e sm a n ym o r ep e o p l et ou s et h ew h o l eG N U o p e r a t i n gs y s t e m ,a sw e l la si t sv a r i a n t ,t h eG N U / L i n u xo p e r a t i n g s y s t e m . A l t h o u g ht h eL e s s e rG e n e r a lP u b l i cL i c e n s ei sL e s sp r o t e c t i v eo ft h e u s e r s 'f r e e d o m ,i td o e se n s u r et h a tt h eu s e ro fap r o g r a mt h a ti s l i n k e dw i t ht h eL i b r a r yh a st h ef r e e d o ma n dt h ew h e r e w i t h a lt or u n t h a tp r o g r a mu s i n gam o d i f i e dv e r s i o no ft h eL i b r a r y . T h ep r e c i s et e r m sa n dc o n d i t i o n sf o rc o p y i n g ,d i s t r i b u t i o na n d m o d i f i c a t i o nf o l l o w . P a yc l o s ea t t e n t i o nt ot h ed i f f e r e n c eb e t w e e na " w o r kb a s e do nt h el i b r a r y "a n da" w o r kt h a tu s e st h el i b r a r y " . T h e f o r m e rc o n t a i n sc o d ed e r i v e df r o mt h el i b r a r y ,w h e r e a st h el a t t e rm u s t b ec o m b i n e dw i t ht h el i b r a r yi no r d e rt or u n .

G N UL E S S E RG E N E R A LP U B L I CL I C E N S E T E R M SA N DC O N D I T I O N SF O RC O P Y I N G ,D I S T R I B U T I O NA N DM O D I F I C A T I O N 0 .T h i sL i c e n s eA g r e e m e n ta p p l i e st oa n ys o f t w a r el i b r a r yo ro t h e r p r o g r a mw h i c hc o n t a i n san o t i c ep l a c e db yt h ec o p y r i g h th o l d e ro r o t h e ra u t h o r i z e dp a r t ys a y i n gi tm a yb ed i s t r i b u t e du n d e rt h et e r m so f t h i sL e s s e rG e n e r a lP u b l i cL i c e n s e( a l s oc a l l e d" t h i sL i c e n s e " ) . E a c hl i c e n s e ei sa d d r e s s e da s" y o u " . A" l i b r a r y "m e a n sac o l l e c t i o no fs o f t w a r ef u n c t i o n sa n d / o rd a t a p r e p a r e ds oa st ob ec o n v e n i e n t l yl i n k e dw i t ha p p l i c a t i o np r o g r a m s ( w h i c hu s es o m eo ft h o s ef u n c t i o n sa n dd a t a )t of o r me x e c u t a b l e s . T h e" L i b r a r y " ,b e l o w ,r e f e r st oa n ys u c hs o f t w a r el i b r a r yo rw o r k w h i c hh a sb e e nd i s t r i b u t e du n d e rt h e s et e r m s . A" w o r kb a s e do nt h e L i b r a r y "m e a n se i t h e rt h eL i b r a r yo ra n yd e r i v a t i v ew o r ku n d e r c o p y r i g h tl a w :t h a ti st os a y ,aw o r kc o n t a i n i n gt h eL i b r a r yo ra p o r t i o no fi t ,e i t h e rv e r b a t i mo rw i t hm o d i f i c a t i o n sa n d / o rt r a n s l a t e d s t r a i g h t f o r w a r d l yi n t oa n o t h e rl a n g u a g e . ( H e r e i n a f t e r ,t r a n s l a t i o ni s i n c l u d e dw i t h o u tl i m i t a t i o ni nt h et e r m" m o d i f i c a t i o n " . ) " S o u r c ec o d e "f o raw o r km e a n st h ep r e f e r r e df o r mo ft h ew o r kf o r m a k i n gm o d i f i c a t i o n st oi t . F o ral i b r a r y ,c o m p l e t es o u r c ec o d em e a n s a l lt h es o u r c ec o d ef o ra l lm o d u l e si tc o n t a i n s ,p l u sa n ya s s o c i a t e d i n t e r f a c ed e f i n i t i o nf i l e s ,p l u st h es c r i p t su s e dt oc o n t r o l c o m p i l a t i o na n di n s t a l l a t i o no ft h el i b r a r y . A c t i v i t i e so t h e rt h a nc o p y i n g ,d i s t r i b u t i o na n dm o d i f i c a t i o na r en o t c o v e r e db yt h i sL i c e n s e ;t h e ya r eo u t s i d ei t ss c o p e . T h ea c to f r u n n i n gap r o g r a mu s i n gt h eL i b r a r yi sn o tr e s t r i c t e d ,a n do u t p u tf r o m s u c hap r o g r a mi sc o v e r e do n l yi fi t sc o n t e n t sc o n s t i t u t eaw o r kb a s e d o nt h eL i b r a r y( i n d e p e n d e n to ft h eu s eo ft h eL i b r a r yi nat o o lf o r w r i t i n gi t ) . W h e t h e rt h a ti st r u ed e p e n d so nw h a tt h eL i b r a r yd o e s a n dw h a tt h ep r o g r a mt h a tu s e st h eL i b r a r yd o e s . 1 .Y o um a yc o p ya n dd i s t r i b u t ev e r b a t i mc o p i e so ft h eL i b r a r y ' s c o m p l e t es o u r c ec o d ea sy o ur e c e i v ei t ,i na n ym e d i u m ,p r o v i d e dt h a t y o uc o n s p i c u o u s l ya n da p p r o p r i a t e l yp u b l i s ho ne a c hc o p ya n a p p r o p r i a t ec o p y r i g h tn o t i c ea n dd i s c l a i m e ro fw a r r a n t y ;k e e pi n t a c t a l lt h en o t i c e st h a tr e f e rt ot h i sL i c e n s ea n dt ot h ea b s e n c eo fa n y w a r r a n t y ;a n dd i s t r i b u t eac o p yo ft h i sL i c e n s ea l o n gw i t ht h e L i b r a r y . Y o um a yc h a r g eaf e ef o rt h ep h y s i c a la c to ft r a n s f e r r i n gac o p y , a n dy o um a ya ty o u ro p t i o no f f e rw a r r a n t yp r o t e c t i o ni ne x c h a n g ef o ra f e e . 2 .Y o um a ym o d i f yy o u rc o p yo rc o p i e so ft h eL i b r a r yo ra n yp o r t i o n o fi t ,t h u sf o r m i n gaw o r kb a s e do nt h eL i b r a r y ,a n dc o p ya n d d i s t r i b u t es u c hm o d i f i c a t i o n so rw o r ku n d e rt h et e r m so fS e c t i o n1 a b o v e ,p r o v i d e dt h a ty o ua l s om e e ta l lo ft h e s ec o n d i t i o n s : a )T h em o d i f i e dw o r km u s ti t s e l fb eas o f t w a r el i b r a r y . b )Y o um u s tc a u s et h ef i l e sm o d i f i e dt oc a r r yp r o m i n e n tn o t i c e s s t a t i n gt h a ty o uc h a n g e dt h ef i l e sa n dt h ed a t eo fa n yc h a n g e . c )Y o um u s tc a u s et h ew h o l eo ft h ew o r kt ob el i c e n s e da tn o c h a r g et oa l lt h i r dp a r t i e su n d e rt h et e r m so ft h i sL i c e n s e . d )I faf a c i l i t yi nt h em o d i f i e dL i b r a r yr e f e r st oaf u n c t i o no ra t a b l eo fd a t at ob es u p p l i e db ya na p p l i c a t i o np r o g r a mt h a tu s e s

t h ef a c i l i t y ,o t h e rt h a na sa na r g u m e n tp a s s e dw h e nt h ef a c i l i t y i si n v o k e d ,t h e ny o um u s tm a k eag o o df a i t he f f o r tt oe n s u r et h a t , i nt h ee v e n ta na p p l i c a t i o nd o e sn o ts u p p l ys u c hf u n c t i o no r t a b l e ,t h ef a c i l i t ys t i l lo p e r a t e s ,a n dp e r f o r m sw h a t e v e rp a r to f i t sp u r p o s er e m a i n sm e a n i n g f u l . ( F o re x a m p l e ,af u n c t i o ni nal i b r a r yt oc o m p u t es q u a r er o o t sh a s ap u r p o s et h a ti se n t i r e l yw e l l d e f i n e di n d e p e n d e n to ft h e a p p l i c a t i o n . T h e r e f o r e ,S u b s e c t i o n2 dr e q u i r e st h a ta n y a p p l i c a t i o n s u p p l i e df u n c t i o no rt a b l eu s e db yt h i sf u n c t i o nm u s t b eo p t i o n a l :i ft h ea p p l i c a t i o nd o e sn o ts u p p l yi t ,t h es q u a r e r o o tf u n c t i o nm u s ts t i l lc o m p u t es q u a r er o o t s . ) T h e s er e q u i r e m e n t sa p p l yt ot h em o d i f i e dw o r ka saw h o l e . I f i d e n t i f i a b l es e c t i o n so ft h a tw o r ka r en o td e r i v e df r o mt h eL i b r a r y , a n dc a nb er e a s o n a b l yc o n s i d e r e di n d e p e n d e n ta n ds e p a r a t ew o r k si n t h e m s e l v e s ,t h e nt h i sL i c e n s e ,a n di t st e r m s ,d on o ta p p l yt ot h o s e s e c t i o n sw h e ny o ud i s t r i b u t et h e ma ss e p a r a t ew o r k s . B u tw h e ny o u d i s t r i b u t et h es a m es e c t i o n sa sp a r to faw h o l ew h i c hi saw o r kb a s e d o nt h eL i b r a r y ,t h ed i s t r i b u t i o no ft h ew h o l em u s tb eo nt h et e r m so f t h i sL i c e n s e ,w h o s ep e r m i s s i o n sf o ro t h e rl i c e n s e e se x t e n dt ot h e e n t i r ew h o l e ,a n dt h u st oe a c ha n de v e r yp a r tr e g a r d l e s so fw h ow r o t e i t . T h u s ,i ti sn o tt h ei n t e n to ft h i ss e c t i o nt oc l a i mr i g h t so rc o n t e s t y o u rr i g h t st ow o r kw r i t t e ne n t i r e l yb yy o u ;r a t h e r ,t h ei n t e n ti st o e x e r c i s et h er i g h tt oc o n t r o lt h ed i s t r i b u t i o no fd e r i v a t i v eo r c o l l e c t i v ew o r k sb a s e do nt h eL i b r a r y . I na d d i t i o n ,m e r ea g g r e g a t i o no fa n o t h e rw o r kn o tb a s e do nt h eL i b r a r y w i t ht h eL i b r a r y( o rw i t haw o r kb a s e do nt h eL i b r a r y )o nav o l u m eo f as t o r a g eo rd i s t r i b u t i o nm e d i u md o e sn o tb r i n gt h eo t h e rw o r ku n d e r t h es c o p eo ft h i sL i c e n s e . 3 .Y o um a yo p tt oa p p l yt h et e r m so ft h eo r d i n a r yG N UG e n e r a lP u b l i c L i c e n s ei n s t e a do ft h i sL i c e n s et oag i v e nc o p yo ft h eL i b r a r y . T od o t h i s ,y o um u s ta l t e ra l lt h en o t i c e st h a tr e f e rt ot h i sL i c e n s e ,s o t h a tt h e yr e f e rt ot h eo r d i n a r yG N UG e n e r a lP u b l i cL i c e n s e ,v e r s i o n2 , i n s t e a do ft ot h i sL i c e n s e . ( I fan e w e rv e r s i o nt h a nv e r s i o n2o ft h e o r d i n a r yG N UG e n e r a lP u b l i cL i c e n s eh a sa p p e a r e d ,t h e ny o uc a ns p e c i f y t h a tv e r s i o ni n s t e a di fy o uw i s h . ) D on o tm a k ea n yo t h e rc h a n g ei n t h e s en o t i c e s . O n c et h i sc h a n g ei sm a d ei nag i v e nc o p y ,i ti si r r e v e r s i b l ef o r t h a tc o p y ,s ot h eo r d i n a r yG N UG e n e r a lP u b l i cL i c e n s ea p p l i e st oa l l s u b s e q u e n tc o p i e sa n dd e r i v a t i v ew o r k sm a d ef r o mt h a tc o p y . T h i so p t i o ni su s e f u lw h e ny o uw i s ht oc o p yp a r to ft h ec o d eo f t h eL i b r a r yi n t oap r o g r a mt h a ti sn o tal i b r a r y . 4 .Y o um a yc o p ya n dd i s t r i b u t et h eL i b r a r y( o rap o r t i o no r d e r i v a t i v eo fi t ,u n d e rS e c t i o n2 )i no b j e c tc o d eo re x e c u t a b l ef o r m u n d e rt h et e r m so fS e c t i o n s1a n d2a b o v ep r o v i d e dt h a ty o ua c c o m p a n y i tw i t ht h ec o m p l e t ec o r r e s p o n d i n gm a c h i n e r e a d a b l es o u r c ec o d e ,w h i c h m u s tb ed i s t r i b u t e du n d e rt h et e r m so fS e c t i o n s1a n d2a b o v eo na m e d i u mc u s t o m a r i l yu s e df o rs o f t w a r ei n t e r c h a n g e . I fd i s t r i b u t i o no fo b j e c tc o d ei sm a d eb yo f f e r i n ga c c e s st oc o p y f r o mad e s i g n a t e dp l a c e ,t h e no f f e r i n ge q u i v a l e n ta c c e s st oc o p yt h e s o u r c ec o d ef r o mt h es a m ep l a c es a t i s f i e st h er e q u i r e m e n tt o d i s t r i b u t et h es o u r c ec o d e ,e v e nt h o u g ht h i r dp a r t i e sa r en o t c o m p e l l e dt oc o p yt h es o u r c ea l o n gw i t ht h eo b j e c tc o d e .

5 .Ap r o g r a mt h a tc o n t a i n sn od e r i v a t i v eo fa n yp o r t i o no ft h e L i b r a r y ,b u ti sd e s i g n e dt ow o r kw i t ht h eL i b r a r yb yb e i n gc o m p i l e do r l i n k e dw i t hi t ,i sc a l l e da" w o r kt h a tu s e st h eL i b r a r y " . S u c ha w o r k ,i ni s o l a t i o n ,i sn o tad e r i v a t i v ew o r ko ft h eL i b r a r y ,a n d t h e r e f o r ef a l l so u t s i d et h es c o p eo ft h i sL i c e n s e . H o w e v e r ,l i n k i n ga" w o r kt h a tu s e st h eL i b r a r y "w i t ht h eL i b r a r y c r e a t e sa ne x e c u t a b l et h a ti sad e r i v a t i v eo ft h eL i b r a r y( b e c a u s ei t c o n t a i n sp o r t i o n so ft h eL i b r a r y ) ,r a t h e rt h a na" w o r kt h a tu s e st h e l i b r a r y " . T h ee x e c u t a b l ei st h e r e f o r ec o v e r e db yt h i sL i c e n s e . S e c t i o n6s t a t e st e r m sf o rd i s t r i b u t i o no fs u c he x e c u t a b l e s . W h e na" w o r kt h a tu s e st h eL i b r a r y "u s e sm a t e r i a lf r o mah e a d e rf i l e t h a ti sp a r to ft h eL i b r a r y ,t h eo b j e c tc o d ef o rt h ew o r km a yb ea d e r i v a t i v ew o r ko ft h eL i b r a r ye v e nt h o u g ht h es o u r c ec o d ei sn o t . W h e t h e rt h i si st r u ei se s p e c i a l l ys i g n i f i c a n ti ft h ew o r kc a nb e l i n k e dw i t h o u tt h eL i b r a r y ,o ri ft h ew o r ki si t s e l fal i b r a r y . T h e t h r e s h o l df o rt h i st ob et r u ei sn o tp r e c i s e l yd e f i n e db yl a w . I fs u c ha no b j e c tf i l eu s e so n l yn u m e r i c a lp a r a m e t e r s ,d a t a s t r u c t u r el a y o u t sa n da c c e s s o r s ,a n ds m a l lm a c r o sa n ds m a l li n l i n e f u n c t i o n s( t e nl i n e so rl e s si nl e n g t h ) ,t h e nt h eu s eo ft h eo b j e c t f i l ei su n r e s t r i c t e d ,r e g a r d l e s so fw h e t h e ri ti sl e g a l l yad e r i v a t i v e w o r k . ( E x e c u t a b l e sc o n t a i n i n gt h i so b j e c tc o d ep l u sp o r t i o n so ft h e L i b r a r yw i l ls t i l lf a l lu n d e rS e c t i o n6 . ) O t h e r w i s e ,i ft h ew o r ki sad e r i v a t i v eo ft h eL i b r a r y ,y o um a y d i s t r i b u t et h eo b j e c tc o d ef o rt h ew o r ku n d e rt h et e r m so fS e c t i o n6 . A n ye x e c u t a b l e sc o n t a i n i n gt h a tw o r ka l s of a l lu n d e rS e c t i o n6 , w h e t h e ro rn o tt h e ya r el i n k e dd i r e c t l yw i t ht h eL i b r a r yi t s e l f . 6 .A sa ne x c e p t i o nt ot h eS e c t i o n sa b o v e ,y o um a ya l s oc o m b i n eo r l i n ka" w o r kt h a tu s e st h eL i b r a r y "w i t ht h eL i b r a r yt op r o d u c ea w o r kc o n t a i n i n gp o r t i o n so ft h eL i b r a r y ,a n dd i s t r i b u t et h a tw o r k u n d e rt e r m so fy o u rc h o i c e ,p r o v i d e dt h a tt h et e r m sp e r m i t m o d i f i c a t i o no ft h ew o r kf o rt h ec u s t o m e r ' so w nu s ea n dr e v e r s e e n g i n e e r i n gf o rd e b u g g i n gs u c hm o d i f i c a t i o n s . Y o um u s tg i v ep r o m i n e n tn o t i c ew i t he a c hc o p yo ft h ew o r kt h a tt h e L i b r a r yi su s e di ni ta n dt h a tt h eL i b r a r ya n di t su s ea r ec o v e r e db y t h i sL i c e n s e . Y o um u s ts u p p l yac o p yo ft h i sL i c e n s e . I ft h ew o r k d u r i n ge x e c u t i o nd i s p l a y sc o p y r i g h tn o t i c e s ,y o um u s ti n c l u d et h e c o p y r i g h tn o t i c ef o rt h eL i b r a r ya m o n gt h e m ,a sw e l la sar e f e r e n c e d i r e c t i n gt h eu s e rt ot h ec o p yo ft h i sL i c e n s e . A l s o ,y o um u s td oo n e o ft h e s et h i n g s : a )A c c o m p a n yt h ew o r kw i t ht h ec o m p l e t ec o r r e s p o n d i n g m a c h i n e r e a d a b l es o u r c ec o d ef o rt h eL i b r a r yi n c l u d i n gw h a t e v e r c h a n g e sw e r eu s e di nt h ew o r k( w h i c hm u s tb ed i s t r i b u t e du n d e r S e c t i o n s1a n d2a b o v e ) ;a n d ,i ft h ew o r ki sa ne x e c u t a b l el i n k e d w i t ht h eL i b r a r y ,w i t ht h ec o m p l e t em a c h i n e r e a d a b l e" w o r kt h a t u s e st h eL i b r a r y " ,a so b j e c tc o d ea n d / o rs o u r c ec o d e ,s ot h a tt h e u s e rc a nm o d i f yt h eL i b r a r ya n dt h e nr e l i n kt op r o d u c eam o d i f i e d e x e c u t a b l ec o n t a i n i n gt h em o d i f i e dL i b r a r y . ( I ti su n d e r s t o o d t h a tt h eu s e rw h oc h a n g e st h ec o n t e n t so fd e f i n i t i o n sf i l e si nt h e L i b r a r yw i l ln o tn e c e s s a r i l yb ea b l et or e c o m p i l et h ea p p l i c a t i o n t ou s et h em o d i f i e dd e f i n i t i o n s . ) b )U s eas u i t a b l es h a r e dl i b r a r ym e c h a n i s mf o rl i n k i n gw i t ht h e L i b r a r y . As u i t a b l em e c h a n i s mi so n et h a t( 1 )u s e sa tr u nt i m ea c o p yo ft h el i b r a r ya l r e a d yp r e s e n to nt h eu s e r ' sc o m p u t e rs y s t e m , r a t h e rt h a nc o p y i n gl i b r a r yf u n c t i o n si n t ot h ee x e c u t a b l e ,a n d( 2 ) w i l lo p e r a t ep r o p e r l yw i t ham o d i f i e dv e r s i o no ft h el i b r a r y ,i f

t h eu s e ri n s t a l l so n e ,a sl o n ga st h em o d i f i e dv e r s i o ni s i n t e r f a c e c o m p a t i b l ew i t ht h ev e r s i o nt h a tt h ew o r kw a sm a d ew i t h . c )A c c o m p a n yt h ew o r kw i t haw r i t t e no f f e r ,v a l i df o ra tl e a s t t h r e ey e a r s ,t og i v et h es a m eu s e rt h em a t e r i a l ss p e c i f i e di n S u b s e c t i o n6 a ,a b o v e ,f o rac h a r g en om o r et h a nt h ec o s to f p e r f o r m i n gt h i sd i s t r i b u t i o n . d )I fd i s t r i b u t i o no ft h ew o r ki sm a d eb yo f f e r i n ga c c e s st oc o p y f r o mad e s i g n a t e dp l a c e ,o f f e re q u i v a l e n ta c c e s st oc o p yt h ea b o v e s p e c i f i e dm a t e r i a l sf r o mt h es a m ep l a c e . e )V e r i f yt h a tt h eu s e rh a sa l r e a d yr e c e i v e dac o p yo ft h e s e m a t e r i a l so rt h a ty o uh a v ea l r e a d ys e n tt h i su s e rac o p y . F o ra ne x e c u t a b l e ,t h er e q u i r e df o r mo ft h e" w o r kt h a tu s e st h e L i b r a r y "m u s ti n c l u d ea n yd a t aa n du t i l i t yp r o g r a m sn e e d e df o r r e p r o d u c i n gt h ee x e c u t a b l ef r o mi t . H o w e v e r ,a sas p e c i a le x c e p t i o n , t h em a t e r i a l st ob ed i s t r i b u t e dn e e dn o ti n c l u d ea n y t h i n gt h a ti s n o r m a l l yd i s t r i b u t e d( i ne i t h e rs o u r c eo rb i n a r yf o r m )w i t ht h em a j o r c o m p o n e n t s( c o m p i l e r ,k e r n e l ,a n ds oo n )o ft h eo p e r a t i n gs y s t e mo n w h i c ht h ee x e c u t a b l er u n s ,u n l e s st h a tc o m p o n e n ti t s e l fa c c o m p a n i e s t h ee x e c u t a b l e . I tm a yh a p p e nt h a tt h i sr e q u i r e m e n tc o n t r a d i c t st h el i c e n s e r e s t r i c t i o n so fo t h e rp r o p r i e t a r yl i b r a r i e st h a td on o tn o r m a l l y a c c o m p a n yt h eo p e r a t i n gs y s t e m . S u c hac o n t r a d i c t i o nm e a n sy o uc a n n o t u s eb o t ht h e ma n dt h eL i b r a r yt o g e t h e ri na ne x e c u t a b l et h a ty o u d i s t r i b u t e . 7 .Y o um a yp l a c el i b r a r yf a c i l i t i e st h a ta r eaw o r kb a s e do nt h e L i b r a r ys i d e b y s i d ei nas i n g l el i b r a r yt o g e t h e rw i t ho t h e rl i b r a r y f a c i l i t i e sn o tc o v e r e db yt h i sL i c e n s e ,a n dd i s t r i b u t es u c hac o m b i n e d l i b r a r y ,p r o v i d e dt h a tt h es e p a r a t ed i s t r i b u t i o no ft h ew o r kb a s e do n t h eL i b r a r ya n do ft h eo t h e rl i b r a r yf a c i l i t i e si so t h e r w i s e p e r m i t t e d ,a n dp r o v i d e dt h a ty o ud ot h e s et w ot h i n g s : a )A c c o m p a n yt h ec o m b i n e dl i b r a r yw i t hac o p yo ft h es a m ew o r k b a s e do nt h eL i b r a r y ,u n c o m b i n e dw i t ha n yo t h e rl i b r a r y f a c i l i t i e s . T h i sm u s tb ed i s t r i b u t e du n d e rt h et e r m so ft h e S e c t i o n sa b o v e . b )G i v ep r o m i n e n tn o t i c ew i t ht h ec o m b i n e dl i b r a r yo ft h ef a c t t h a tp a r to fi ti saw o r kb a s e do nt h eL i b r a r y ,a n de x p l a i n i n g w h e r et of i n dt h ea c c o m p a n y i n gu n c o m b i n e df o r mo ft h es a m ew o r k . 8 .Y o um a yn o tc o p y ,m o d i f y ,s u b l i c e n s e ,l i n kw i t h ,o rd i s t r i b u t e t h eL i b r a r ye x c e p ta se x p r e s s l yp r o v i d e du n d e rt h i sL i c e n s e . A n y a t t e m p to t h e r w i s et oc o p y ,m o d i f y ,s u b l i c e n s e ,l i n kw i t h ,o r d i s t r i b u t et h eL i b r a r yi sv o i d ,a n dw i l la u t o m a t i c a l l yt e r m i n a t ey o u r r i g h t su n d e rt h i sL i c e n s e . H o w e v e r ,p a r t i e sw h oh a v er e c e i v e dc o p i e s , o rr i g h t s ,f r o my o uu n d e rt h i sL i c e n s ew i l ln o th a v et h e i rl i c e n s e s t e r m i n a t e ds ol o n ga ss u c hp a r t i e sr e m a i ni nf u l lc o m p l i a n c e . 9 .Y o ua r en o tr e q u i r e dt oa c c e p tt h i sL i c e n s e ,s i n c ey o uh a v en o t s i g n e di t . H o w e v e r ,n o t h i n ge l s eg r a n t sy o up e r m i s s i o nt om o d i f yo r d i s t r i b u t et h eL i b r a r yo ri t sd e r i v a t i v ew o r k s . T h e s ea c t i o n sa r e p r o h i b i t e db yl a wi fy o ud on o ta c c e p tt h i sL i c e n s e . T h e r e f o r e ,b y m o d i f y i n go rd i s t r i b u t i n gt h eL i b r a r y( o ra n yw o r kb a s e do nt h e L i b r a r y ) ,y o ui n d i c a t ey o u ra c c e p t a n c eo ft h i sL i c e n s et od os o ,a n d a l li t st e r m sa n dc o n d i t i o n sf o rc o p y i n g ,d i s t r i b u t i n go rm o d i f y i n g t h eL i b r a r yo rw o r k sb a s e do ni t .

1 0 .E a c ht i m ey o ur e d i s t r i b u t et h eL i b r a r y( o ra n yw o r kb a s e do nt h e L i b r a r y ) ,t h er e c i p i e n ta u t o m a t i c a l l yr e c e i v e sal i c e n s ef r o mt h e o r i g i n a ll i c e n s o rt oc o p y ,d i s t r i b u t e ,l i n kw i t ho rm o d i f yt h eL i b r a r y s u b j e c tt ot h e s et e r m sa n dc o n d i t i o n s . Y o um a yn o ti m p o s ea n yf u r t h e r r e s t r i c t i o n so nt h er e c i p i e n t s 'e x e r c i s eo ft h er i g h t sg r a n t e dh e r e i n . Y o ua r en o tr e s p o n s i b l ef o re n f o r c i n gc o m p l i a n c eb yt h i r dp a r t i e sw i t h t h i sL i c e n s e . 1 1 .I f ,a sac o n s e q u e n c eo fac o u r tj u d g m e n to ra l l e g a t i o no fp a t e n t i n f r i n g e m e n to rf o ra n yo t h e rr e a s o n( n o tl i m i t e dt op a t e n ti s s u e s ) , c o n d i t i o n sa r ei m p o s e do ny o u( w h e t h e rb yc o u r to r d e r ,a g r e e m e n to r o t h e r w i s e )t h a tc o n t r a d i c tt h ec o n d i t i o n so ft h i sL i c e n s e ,t h e yd on o t e x c u s ey o uf r o mt h ec o n d i t i o n so ft h i sL i c e n s e . I fy o uc a n n o t d i s t r i b u t es oa st os a t i s f ys i m u l t a n e o u s l yy o u ro b l i g a t i o n su n d e rt h i s L i c e n s ea n da n yo t h e rp e r t i n e n to b l i g a t i o n s ,t h e na sac o n s e q u e n c ey o u m a yn o td i s t r i b u t et h eL i b r a r ya ta l l . F o re x a m p l e ,i fap a t e n t l i c e n s ew o u l dn o tp e r m i tr o y a l t y f r e er e d i s t r i b u t i o no ft h eL i b r a r yb y a l lt h o s ew h or e c e i v ec o p i e sd i r e c t l yo ri n d i r e c t l yt h r o u g hy o u ,t h e n t h eo n l yw a yy o uc o u l ds a t i s f yb o t hi ta n dt h i sL i c e n s ew o u l db et o r e f r a i ne n t i r e l yf r o md i s t r i b u t i o no ft h eL i b r a r y . I fa n yp o r t i o no ft h i ss e c t i o ni sh e l di n v a l i do ru n e n f o r c e a b l eu n d e r a n yp a r t i c u l a rc i r c u m s t a n c e ,t h eb a l a n c eo ft h es e c t i o ni si n t e n d e dt o a p p l y ,a n dt h es e c t i o na saw h o l ei si n t e n d e dt oa p p l yi no t h e r c i r c u m s t a n c e s . I ti sn o tt h ep u r p o s eo ft h i ss e c t i o nt oi n d u c ey o ut oi n f r i n g ea n y p a t e n t so ro t h e rp r o p e r t yr i g h tc l a i m so rt oc o n t e s tv a l i d i t yo fa n y s u c hc l a i m s ;t h i ss e c t i o nh a st h es o l ep u r p o s eo fp r o t e c t i n gt h e i n t e g r i t yo ft h ef r e es o f t w a r ed i s t r i b u t i o ns y s t e mw h i c hi s i m p l e m e n t e db yp u b l i cl i c e n s ep r a c t i c e s . M a n yp e o p l eh a v em a d e g e n e r o u sc o n t r i b u t i o n st ot h ew i d er a n g eo fs o f t w a r ed i s t r i b u t e d t h r o u g ht h a ts y s t e mi nr e l i a n c eo nc o n s i s t e n ta p p l i c a t i o no ft h a t s y s t e m ;i ti su pt ot h ea u t h o r / d o n o rt od e c i d ei fh eo rs h ei sw i l l i n g t od i s t r i b u t es o f t w a r et h r o u g ha n yo t h e rs y s t e ma n dal i c e n s e ec a n n o t i m p o s et h a tc h o i c e . T h i ss e c t i o ni si n t e n d e dt om a k et h o r o u g h l yc l e a rw h a ti sb e l i e v e dt o b eac o n s e q u e n c eo ft h er e s to ft h i sL i c e n s e . 1 2 .I ft h ed i s t r i b u t i o na n d / o ru s eo ft h eL i b r a r yi sr e s t r i c t e di n c e r t a i nc o u n t r i e se i t h e rb yp a t e n t so rb yc o p y r i g h t e di n t e r f a c e s ,t h e o r i g i n a lc o p y r i g h th o l d e rw h op l a c e st h eL i b r a r yu n d e rt h i sL i c e n s e m a ya d da ne x p l i c i tg e o g r a p h i c a ld i s t r i b u t i o nl i m i t a t i o ne x c l u d i n gt h o s e c o u n t r i e s ,s ot h a td i s t r i b u t i o ni sp e r m i t t e do n l yi no ra m o n g c o u n t r i e sn o tt h u se x c l u d e d . I ns u c hc a s e ,t h i sL i c e n s ei n c o r p o r a t e s t h el i m i t a t i o na si fw r i t t e ni nt h eb o d yo ft h i sL i c e n s e . 1 3 .T h eF r e eS o f t w a r eF o u n d a t i o nm a yp u b l i s hr e v i s e da n d / o rn e w v e r s i o n so ft h eL e s s e rG e n e r a lP u b l i cL i c e n s ef r o mt i m et ot i m e . S u c hn e wv e r s i o n sw i l lb es i m i l a ri ns p i r i tt ot h ep r e s e n tv e r s i o n , b u tm a yd i f f e ri nd e t a i lt oa d d r e s sn e wp r o b l e m so rc o n c e r n s . E a c hv e r s i o ni sg i v e nad i s t i n g u i s h i n gv e r s i o nn u m b e r . I ft h eL i b r a r y s p e c i f i e sav e r s i o nn u m b e ro ft h i sL i c e n s ew h i c ha p p l i e st oi ta n d " a n yl a t e rv e r s i o n " ,y o uh a v et h eo p t i o no ff o l l o w i n gt h et e r m sa n d c o n d i t i o n se i t h e ro ft h a tv e r s i o no ro fa n yl a t e rv e r s i o np u b l i s h e db y t h eF r e eS o f t w a r eF o u n d a t i o n . I ft h eL i b r a r yd o e sn o ts p e c i f ya l i c e n s ev e r s i o nn u m b e r ,y o um a yc h o o s ea n yv e r s i o ne v e rp u b l i s h e db y t h eF r e eS o f t w a r eF o u n d a t i o n . 1 4 .I fy o uw i s ht oi n c o r p o r a t ep a r t so ft h eL i b r a r yi n t oo t h e rf r e e p r o g r a m sw h o s ed i s t r i b u t i o nc o n d i t i o n sa r ei n c o m p a t i b l ew i t ht h e s e ,

w r i t et ot h ea u t h o rt oa s kf o rp e r m i s s i o n . F o rs o f t w a r ew h i c hi s c o p y r i g h t e db yt h eF r e eS o f t w a r eF o u n d a t i o n ,w r i t et ot h eF r e e S o f t w a r eF o u n d a t i o n ;w es o m e t i m e sm a k ee x c e p t i o n sf o rt h i s . O u r d e c i s i o nw i l lb eg u i d e db yt h et w og o a l so fp r e s e r v i n gt h ef r e es t a t u s o fa l ld e r i v a t i v e so fo u rf r e es o f t w a r ea n do fp r o m o t i n gt h es h a r i n g a n dr e u s eo fs o f t w a r eg e n e r a l l y . N OW A R R A N T Y 1 5 .B E C A U S ET H EL I B R A R YI SL I C E N S E DF R E EO FC H A R G E ,T H E R EI SN O W A R R A N T YF O RT H EL I B R A R Y ,T OT H EE X T E N TP E R M I T T E DB YA P P L I C A B L EL A W . E X C E P TW H E NO T H E R W I S ES T A T E DI NW R I T I N GT H EC O P Y R I G H TH O L D E R SA N D / O R O T H E RP A R T I E SP R O V I D ET H EL I B R A R Y" A SI S "W I T H O U TW A R R A N T YO FA N Y K I N D ,E I T H E RE X P R E S S E DO RI M P L I E D ,I N C L U D I N G ,B U TN O TL I M I T E DT O ,T H E I M P L I E DW A R R A N T I E SO FM E R C H A N T A B I L I T YA N DF I T N E S SF O RAP A R T I C U L A R P U R P O S E . T H EE N T I R ER I S KA ST OT H EQ U A L I T YA N DP E R F O R M A N C EO FT H E L I B R A R YI SW I T HY O U . S H O U L DT H EL I B R A R YP R O V ED E F E C T I V E ,Y O UA S S U M E T H EC O S TO FA L LN E C E S S A R YS E R V I C I N G ,R E P A I RO RC O R R E C T I O N . 1 6 .I NN OE V E N TU N L E S SR E Q U I R E DB YA P P L I C A B L EL A WO RA G R E E DT OI N W R I T I N GW I L LA N YC O P Y R I G H TH O L D E R ,O RA N YO T H E RP A R T YW H OM A YM O D I F Y A N D / O RR E D I S T R I B U T ET H EL I B R A R YA SP E R M I T T E DA B O V E ,B EL I A B L ET OY O U F O RD A M A G E S ,I N C L U D I N GA N YG E N E R A L ,S P E C I A L ,I N C I D E N T A LO R C O N S E Q U E N T I A LD A M A G E SA R I S I N GO U TO FT H EU S EO RI N A B I L I T YT OU S ET H E L I B R A R Y( I N C L U D I N GB U TN O TL I M I T E DT OL O S SO FD A T AO RD A T AB E I N G R E N D E R E DI N A C C U R A T EO RL O S S E SS U S T A I N E DB YY O UO RT H I R DP A R T I E SO RA F A I L U R EO FT H EL I B R A R YT OO P E R A T EW I T HA N YO T H E RS O F T W A R E ) ,E V E NI F S U C HH O L D E RO RO T H E RP A R T YH A SB E E NA D V I S E DO FT H EP O S S I B I L I T YO FS U C H D A M A G E S . E N DO FT E R M SA N DC O N D I T I O N S H o wt oA p p l yT h e s eT e r m st oY o u rN e wL i b r a r i e s I fy o ud e v e l o pan e wl i b r a r y ,a n dy o uw a n ti tt ob eo ft h eg r e a t e s t p o s s i b l eu s et ot h ep u b l i c ,w er e c o m m e n dm a k i n gi tf r e es o f t w a r et h a t e v e r y o n ec a nr e d i s t r i b u t ea n dc h a n g e . Y o uc a nd os ob yp e r m i t t i n g r e d i s t r i b u t i o nu n d e rt h e s et e r m s( o r ,a l t e r n a t i v e l y ,u n d e rt h et e r m s o ft h eo r d i n a r yG e n e r a lP u b l i cL i c e n s e ) . T oa p p l yt h e s et e r m s ,a t t a c ht h ef o l l o w i n gn o t i c e st ot h el i b r a r y . I ti ss a f e s tt oa t t a c ht h e mt ot h es t a r to fe a c hs o u r c ef i l et om o s t e f f e c t i v e l yc o n v e yt h ee x c l u s i o no fw a r r a n t y ;a n de a c hf i l es h o u l d h a v ea tl e a s tt h e" c o p y r i g h t "l i n ea n dap o i n t e rt ow h e r et h ef u l l n o t i c ei sf o u n d . < o n el i n et og i v et h el i b r a r y ' sn a m ea n dab r i e fi d e ao fw h a ti td o e s . > C o p y r i g h t( C )< y e a r > < n a m eo fa u t h o r > T h i sl i b r a r yi sf r e es o f t w a r e ;y o uc a nr e d i s t r i b u t ei ta n d / o r m o d i f yi tu n d e rt h et e r m so ft h eG N UL e s s e rG e n e r a lP u b l i c L i c e n s ea sp u b l i s h e db yt h eF r e eS o f t w a r eF o u n d a t i o n ;e i t h e r v e r s i o n2 . 1o ft h eL i c e n s e ,o r( a ty o u ro p t i o n )a n yl a t e rv e r s i o n . T h i sl i b r a r yi sd i s t r i b u t e di nt h eh o p et h a ti tw i l lb eu s e f u l , b u tW I T H O U TA N YW A R R A N T Y ;w i t h o u te v e nt h ei m p l i e dw a r r a n t yo f M E R C H A N T A B I L I T Yo rF I T N E S SF O RAP A R T I C U L A RP U R P O S E . S e et h eG N U L e s s e rG e n e r a lP u b l i cL i c e n s ef o rm o r ed e t a i l s . Y o us h o u l dh a v er e c e i v e dac o p yo ft h eG N UL e s s e rG e n e r a lP u b l i c L i c e n s ea l o n gw i t ht h i sl i b r a r y ;i fn o t ,w r i t et ot h eF r e eS o f t w a r e F o u n d a t i o n ,I n c . ,5 1F r a n k l i nS t ,F i f t hF l o o r ,B o s t o n ,M A 0 2 1 1 0 1 3 0 1 U S A

A l s oa d di n f o r m a t i o no nh o wt oc o n t a c ty o ub ye l e c t r o n i ca n dp a p e rm a i l . Y o us h o u l da l s og e ty o u re m p l o y e r( i fy o uw o r ka sap r o g r a m m e r )o r y o u rs c h o o l ,i fa n y ,t os i g na" c o p y r i g h td i s c l a i m e r "f o rt h el i b r a r y , i fn e c e s s a r y . H e r ei sas a m p l e ;a l t e rt h en a m e s : Y o y o d y n e ,I n c . ,h e r e b yd i s c l a i m sa l lc o p y r i g h ti n t e r e s ti nt h e l i b r a r y` F r o b '( al i b r a r yf o rt w e a k i n gk n o b s )w r i t t e nb yJ a m e s R a n d o mH a c k e r . < s i g n a t u r eo fT yC o o n > ,1A p r i l1 9 9 0 T yC o o n ,P r e s i d e n to fV i c e T h a t ' sa l lt h e r ei st oi t !

Python License
1 .T h i sL I C E N S EA G R E E M E N Ti sb e t w e e nt h eP y t h o nS o f t w a r eF o u n d a t i o n ( " P S F " ) ,a n dt h eI n d i v i d u a lo rO r g a n i z a t i o n( " L i c e n s e e " )a c c e s s i n ga n d o t h e r w i s eu s i n gP y t h o n2 . 3s o f t w a r ei ns o u r c eo rb i n a r yf o r ma n di t s a s s o c i a t e dd o c u m e n t a t i o n . 2 .S u b j e c tt ot h et e r m sa n dc o n d i t i o n so ft h i sL i c e n s eA g r e e m e n t ,P S F h e r e b yg r a n t sL i c e n s e ean o n e x c l u s i v e ,r o y a l t y f r e e ,w o r l d w i d e l i c e n s et or e p r o d u c e ,a n a l y z e ,t e s t ,p e r f o r ma n d / o rd i s p l a yp u b l i c l y , p r e p a r ed e r i v a t i v ew o r k s ,d i s t r i b u t e ,a n do t h e r w i s eu s eP y t h o n2 . 3 a l o n eo ri na n yd e r i v a t i v ev e r s i o n ,p r o v i d e d ,h o w e v e r ,t h a tP S F ' s L i c e n s eA g r e e m e n ta n dP S F ' sn o t i c eo fc o p y r i g h t ,i . e . ," C o p y r i g h t( c ) 2 0 0 1 ,2 0 0 2P y t h o nS o f t w a r eF o u n d a t i o n ;A l lR i g h t sR e s e r v e d "a r e r e t a i n e di nP y t h o n2 . 3a l o n eo ri na n yd e r i v a t i v ev e r s i o np r e p a r e db y L i c e n s e e . 3 .I nt h ee v e n tL i c e n s e ep r e p a r e sad e r i v a t i v ew o r kt h a ti sb a s e do n o ri n c o r p o r a t e sP y t h o n2 . 3o ra n yp a r tt h e r e o f ,a n dw a n t st om a k e t h ed e r i v a t i v ew o r ka v a i l a b l et oo t h e r sa sp r o v i d e dh e r e i n ,t h e n L i c e n s e eh e r e b ya g r e e st oi n c l u d ei na n ys u c hw o r kab r i e fs u m m a r yo f t h ec h a n g e sm a d et oP y t h o n2 . 3 . 4 .P S Fi sm a k i n gP y t h o n2 . 3a v a i l a b l et oL i c e n s e eo na n" A SI S " b a s i s . P S FM A K E SN OR E P R E S E N T A T I O N SO RW A R R A N T I E S ,E X P R E S SO R I M P L I E D . B YW A YO FE X A M P L E ,B U TN O TL I M I T A T I O N ,P S FM A K E SN OA N D D I S C L A I M SA N YR E P R E S E N T A T I O NO RW A R R A N T YO FM E R C H A N T A B I L I T YO RF I T N E S S F O RA N YP A R T I C U L A RP U R P O S EO RT H A TT H EU S EO FP Y T H O N2 . 3W I L LN O T I N F R I N G EA N YT H I R DP A R T YR I G H T S . 5 .P S FS H A L LN O TB EL I A B L ET OL I C E N S E EO RA N YO T H E RU S E R SO FP Y T H O N 2 . 3F O RA N YI N C I D E N T A L ,S P E C I A L ,O RC O N S E Q U E N T I A LD A M A G E SO RL O S SA S AR E S U L TO FM O D I F Y I N G ,D I S T R I B U T I N G ,O RO T H E R W I S EU S I N GP Y T H O N2 . 3 , O RA N YD E R I V A T I V ET H E R E O F ,E V E NI FA D V I S E DO FT H EP O S S I B I L I T YT H E R E O F . 6 .T h i sL i c e n s eA g r e e m e n tw i l la u t o m a t i c a l l yt e r m i n a t eu p o nam a t e r i a l b r e a c ho fi t st e r m sa n dc o n d i t i o n s . 7 .N o t h i n gi nt h i sL i c e n s eA g r e e m e n ts h a l lb ed e e m e dt oc r e a t ea n y r e l a t i o n s h i po fa g e n c y ,p a r t n e r s h i p ,o rj o i n tv e n t u r eb e t w e e nP S Fa n d L i c e n s e e . T h i sL i c e n s eA g r e e m e n td o e sn o tg r a n tp e r m i s s i o nt ou s eP S F t r a d e m a r k so rt r a d en a m ei nat r a d e m a r ks e n s et oe n d o r s eo rp r o m o t e p r o d u c t so rs e r v i c e so fL i c e n s e e ,o ra n yt h i r dp a r t y . 8 .B yc o p y i n g ,i n s t a l l i n go ro t h e r w i s eu s i n gP y t h o n2 . 3 ,L i c e n s e e

a g r e e st ob eb o u n db yt h et e r m sa n dc o n d i t i o n so ft h i sL i c e n s e A g r e e m e n t .

Jpeg License
I np l a i nE n g l i s h : 1 .W ed o n ' tp r o m i s et h a tt h i ss o f t w a r ew o r k s . ( B u ti fy o uf i n da n yb u g s , p l e a s el e tu sk n o w ! ) 2 .Y o uc a nu s et h i ss o f t w a r ef o rw h a t e v e ry o uw a n t . Y o ud o n ' th a v et op a yu s . 3 .Y o um a yn o tp r e t e n dt h a ty o uw r o t et h i ss o f t w a r e . I fy o uu s ei ti na p r o g r a m ,y o um u s ta c k n o w l e d g es o m e w h e r ei ny o u rd o c u m e n t a t i o nt h a t y o u ' v eu s e dt h eI J Gc o d e . I nl e g a l e s e : T h ea u t h o r sm a k eN OW A R R A N T Yo rr e p r e s e n t a t i o n ,e i t h e re x p r e s so ri m p l i e d , w i t hr e s p e c tt ot h i ss o f t w a r e ,i t sq u a l i t y ,a c c u r a c y ,m e r c h a n t a b i l i t y ,o r f i t n e s sf o rap a r t i c u l a rp u r p o s e . T h i ss o f t w a r ei sp r o v i d e d" A SI S " ,a n dy o u , i t su s e r ,a s s u m et h ee n t i r er i s ka st oi t sq u a l i t ya n da c c u r a c y . T h i ss o f t w a r ei sc o p y r i g h t( C )1 9 9 1 1 9 9 8 ,T h o m a sG .L a n e . A l lR i g h t sR e s e r v e de x c e p ta ss p e c i f i e db e l o w . P e r m i s s i o ni sh e r e b yg r a n t e dt ou s e ,c o p y ,m o d i f y ,a n dd i s t r i b u t et h i s s o f t w a r e( o rp o r t i o n st h e r e o f )f o ra n yp u r p o s e ,w i t h o u tf e e ,s u b j e c tt ot h e s e c o n d i t i o n s : ( 1 )I fa n yp a r to ft h es o u r c ec o d ef o rt h i ss o f t w a r ei sd i s t r i b u t e d ,t h e nt h i s R E A D M Ef i l em u s tb ei n c l u d e d ,w i t ht h i sc o p y r i g h ta n dn o w a r r a n t yn o t i c e u n a l t e r e d ;a n da n ya d d i t i o n s ,d e l e t i o n s ,o rc h a n g e st ot h eo r i g i n a lf i l e s m u s tb ec l e a r l yi n d i c a t e di na c c o m p a n y i n gd o c u m e n t a t i o n . ( 2 )I fo n l ye x e c u t a b l ec o d ei sd i s t r i b u t e d ,t h e nt h ea c c o m p a n y i n g d o c u m e n t a t i o nm u s ts t a t et h a t" t h i ss o f t w a r ei sb a s e di np a r to nt h ew o r ko f t h eI n d e p e n d e n tJ P E GG r o u p " . ( 3 )P e r m i s s i o nf o ru s eo ft h i ss o f t w a r ei sg r a n t e do n l yi ft h eu s e ra c c e p t s f u l lr e s p o n s i b i l i t yf o ra n yu n d e s i r a b l ec o n s e q u e n c e s ;t h ea u t h o r sa c c e p t N OL I A B I L I T Yf o rd a m a g e so fa n yk i n d . T h e s ec o n d i t i o n sa p p l yt oa n ys o f t w a r ed e r i v e df r o mo rb a s e do nt h eI J Gc o d e , n o tj u s tt ot h eu n m o d i f i e dl i b r a r y . I fy o uu s eo u rw o r k ,y o uo u g h tt o a c k n o w l e d g eu s . P e r m i s s i o ni sN O Tg r a n t e df o rt h eu s eo fa n yI J Ga u t h o r ' sn a m eo rc o m p a n yn a m e i na d v e r t i s i n go rp u b l i c i t yr e l a t i n gt ot h i ss o f t w a r eo rp r o d u c t sd e r i v e df r o m i t . T h i ss o f t w a r em a yb er e f e r r e dt oo n l ya s" t h eI n d e p e n d e n tJ P E GG r o u p ' s s o f t w a r e " . W es p e c i f i c a l l yp e r m i ta n de n c o u r a g et h eu s eo ft h i ss o f t w a r ea st h eb a s i so f c o m m e r c i a lp r o d u c t s ,p r o v i d e dt h a ta l lw a r r a n t yo rl i a b i l i t yc l a i m sa r e a s s u m e db yt h ep r o d u c tv e n d o r .

PNG License
T h eP N GR e f e r e n c eL i b r a r yi ss u p p l i e d" A SI S " . T h eC o n t r i b u t i n gA u t h o r s a n dG r o u p4 2 ,I n c .d i s c l a i ma l lw a r r a n t i e s ,e x p r e s s e do ri m p l i e d , i n c l u d i n g ,w i t h o u tl i m i t a t i o n ,t h ew a r r a n t i e so fm e r c h a n t a b i l i t ya n do f f i t n e s sf o ra n yp u r p o s e . T h eC o n t r i b u t i n gA u t h o r sa n dG r o u p4 2 ,I n c . a s s u m en ol i a b i l i t yf o rd i r e c t ,i n d i r e c t ,i n c i d e n t a l ,s p e c i a l ,e x e m p l a r y , o rc o n s e q u e n t i a ld a m a g e s ,w h i c hm a yr e s u l tf r o mt h eu s eo ft h eP N G R e f e r e n c eL i b r a r y ,e v e ni fa d v i s e do ft h ep o s s i b i l i t yo fs u c hd a m a g e .

P e r m i s s i o ni sh e r e b yg r a n t e dt ou s e ,c o p y ,m o d i f y ,a n dd i s t r i b u t et h i s s o u r c ec o d e ,o rp o r t i o n sh e r e o f ,f o ra n yp u r p o s e ,w i t h o u tf e e ,s u b j e c t t ot h ef o l l o w i n gr e s t r i c t i o n s : 1 .T h eo r i g i no ft h i ss o u r c ec o d em u s tn o tb em i s r e p r e s e n t e d . 2 .A l t e r e dv e r s i o n sm u s tb ep l a i n l ym a r k e da ss u c ha n dm u s tn o t b em i s r e p r e s e n t e da sb e i n gt h eo r i g i n a ls o u r c e . 3 .T h i sC o p y r i g h tn o t i c em a yn o tb er e m o v e do ra l t e r e df r o ma n y s o u r c eo ra l t e r e ds o u r c ed i s t r i b u t i o n . T h eC o n t r i b u t i n gA u t h o r sa n dG r o u p4 2 ,I n c .s p e c i f i c a l l yp e r m i t ,w i t h o u t f e e ,a n de n c o u r a g et h eu s eo ft h i ss o u r c ec o d ea sac o m p o n e n tt o s u p p o r t i n gt h eP N Gf i l ef o r m a ti nc o m m e r c i a lp r o d u c t s . I fy o uu s et h i s s o u r c ec o d ei nap r o d u c t ,a c k n o w l e d g m e n ti sn o tr e q u i r e db u tw o u l db e a p p r e c i a t e d .

Zlib License
T h i ss o f t w a r ei sp r o v i d e d' a s i s ' ,w i t h o u ta n ye x p r e s so ri m p l i e d w a r r a n t y . I nn oe v e n tw i l lt h ea u t h o r sb eh e l dl i a b l ef o ra n yd a m a g e s a r i s i n gf r o mt h eu s eo ft h i ss o f t w a r e . P e r m i s s i o ni sg r a n t e dt oa n y o n et ou s et h i ss o f t w a r ef o ra n yp u r p o s e , i n c l u d i n gc o m m e r c i a la p p l i c a t i o n s ,a n dt oa l t e ri ta n dr e d i s t r i b u t ei t f r e e l y ,s u b j e c tt ot h ef o l l o w i n gr e s t r i c t i o n s : 1 .T h eo r i g i no ft h i ss o f t w a r em u s tn o tb em i s r e p r e s e n t e d ;y o um u s tn o t c l a i mt h a ty o uw r o t et h eo r i g i n a ls o f t w a r e .I fy o uu s et h i ss o f t w a r e i nap r o d u c t ,a na c k n o w l e d g m e n ti nt h ep r o d u c td o c u m e n t a t i o nw o u l db e a p p r e c i a t e db u ti sn o tr e q u i r e d . 2 .A l t e r e ds o u r c ev e r s i o n sm u s tb ep l a i n l ym a r k e da ss u c h ,a n dm u s tn o tb e m i s r e p r e s e n t e da sb e i n gt h eo r i g i n a ls o f t w a r e . 3 .T h i sn o t i c em a yn o tb er e m o v e do ra l t e r e df r o ma n ys o u r c ed i s t r i b u t i o n .

Bzip2 License
T h i sp r o g r a m ," b z i p 2 " ,t h ea s s o c i a t e dl i b r a r y" l i b b z i p 2 " ,a n da l l d o c u m e n t a t i o n ,a r ec o p y r i g h t( C )1 9 9 6 2 0 0 5J u l i a nRS e w a r d . A l l r i g h t sr e s e r v e d . R e d i s t r i b u t i o na n du s ei ns o u r c ea n db i n a r yf o r m s ,w i t ho rw i t h o u t m o d i f i c a t i o n ,a r ep e r m i t t e dp r o v i d e dt h a tt h ef o l l o w i n gc o n d i t i o n s a r em e t : 1 .R e d i s t r i b u t i o n so fs o u r c ec o d em u s tr e t a i nt h ea b o v ec o p y r i g h t n o t i c e ,t h i sl i s to fc o n d i t i o n sa n dt h ef o l l o w i n gd i s c l a i m e r . 2 .T h eo r i g i no ft h i ss o f t w a r em u s tn o tb em i s r e p r e s e n t e d ;y o um u s t n o tc l a i mt h a ty o uw r o t et h eo r i g i n a ls o f t w a r e . I fy o uu s et h i s s o f t w a r ei nap r o d u c t ,a na c k n o w l e d g m e n ti nt h ep r o d u c t d o c u m e n t a t i o nw o u l db ea p p r e c i a t e db u ti sn o tr e q u i r e d . 3 .A l t e r e ds o u r c ev e r s i o n sm u s tb ep l a i n l ym a r k e da ss u c h ,a n dm u s t n o tb em i s r e p r e s e n t e da sb e i n gt h eo r i g i n a ls o f t w a r e . 4 .T h en a m eo ft h ea u t h o rm a yn o tb eu s e dt oe n d o r s eo rp r o m o t e p r o d u c t sd e r i v e df r o mt h i ss o f t w a r ew i t h o u ts p e c i f i cp r i o rw r i t t e n p e r m i s s i o n .

p e r m i s s i o n . T H I SS O F T W A R EI SP R O V I D E DB YT H EA U T H O R' ' A SI S ' 'A N DA N YE X P R E S S O RI M P L I E DW A R R A N T I E S ,I N C L U D I N G ,B U TN O TL I M I T E DT O ,T H EI M P L I E D W A R R A N T I E SO FM E R C H A N T A B I L I T YA N DF I T N E S SF O RAP A R T I C U L A RP U R P O S E A R ED I S C L A I M E D . I NN OE V E N TS H A L LT H EA U T H O RB EL I A B L EF O RA N Y D I R E C T ,I N D I R E C T ,I N C I D E N T A L ,S P E C I A L ,E X E M P L A R Y ,O RC O N S E Q U E N T I A L D A M A G E S( I N C L U D I N G ,B U TN O TL I M I T E DT O ,P R O C U R E M E N TO FS U B S T I T U T E G O O D SO RS E R V I C E S ;L O S SO FU S E ,D A T A ,O RP R O F I T S ;O RB U S I N E S S I N T E R R U P T I O N )H O W E V E RC A U S E DA N DO NA N YT H E O R YO FL I A B I L I T Y , W H E T H E RI NC O N T R A C T ,S T R I C TL I A B I L I T Y ,O RT O R T( I N C L U D I N G N E G L I G E N C EO RO T H E R W I S E )A R I S I N GI NA N YW A YO U TO FT H EU S EO FT H I S S O F T W A R E ,E V E NI FA D V I S E DO FT H EP O S S I B I L I T YO FS U C HD A M A G E .

Modified BSD License

R e d i s t r i b u t i o na n du s ei ns o u r c ea n db i n a r yf o r m s ,w i t ho rw i t h o u t m o d i f i c a t i o n ,a r ep e r m i t t e dp r o v i d e dt h a tt h ef o l l o w i n gc o n d i t i o n sa r em e t : *R e d i s t r i b u t i o n so fs o u r c ec o d em u s tr e t a i nt h ea b o v ec o p y r i g h tn o t i c e , t h i sl i s to fc o n d i t i o n sa n dt h ef o l l o w i n gd i s c l a i m e r . *R e d i s t r i b u t i o n si nb i n a r yf o r mm u s tr e p r o d u c et h ea b o v ec o p y r i g h tn o t i c e , t h i sl i s to fc o n d i t i o n sa n dt h ef o l l o w i n gd i s c l a i m e ri nt h ed o c u m e n t a t i o n a n d / o ro t h e rm a t e r i a l sp r o v i d e dw i t ht h ed i s t r i b u t i o n . *T h en a m eo ft h ea u t h o rm a yb eu s e dt oe n d o r s eo rp r o m o t ep r o d u c t s d e r i v e df r o mt h i ss o f t w a r ew i t h o u ts p e c i f i cp r i o rw r i t t e np e r m i s s i o n . T H I SS O F T W A R EI SP R O V I D E DB YT H EC O P Y R I G H TH O L D E R SA N DC O N T R I B U T O R S" A SI S " A N DA N YE X P R E S SO RI M P L I E DW A R R A N T I E S ,I N C L U D I N G ,B U TN O TL I M I T E DT O ,T H E I M P L I E DW A R R A N T I E SO FM E R C H A N T A B I L I T YA N DF I T N E S SF O RAP A R T I C U L A RP U R P O S E A R ED I S C L A I M E D .I NN OE V E N TS H A L LT H EC O P Y R I G H TO W N E RO RC O N T R I B U T O R SB E L I A B L EF O RA N YD I R E C T ,I N D I R E C T ,I N C I D E N T A L ,S P E C I A L ,E X E M P L A R Y ,O R C O N S E Q U E N T I A LD A M A G E S( I N C L U D I N G ,B U TN O TL I M I T E DT O ,P R O C U R E M E N TO F S U B S T I T U T EG O O D SO RS E R V I C E S ;L O S SO FU S E ,D A T A ,O RP R O F I T S ;O RB U S I N E S S I N T E R R U P T I O N )H O W E V E RC A U S E DA N DO NA N YT H E O R YO FL I A B I L I T Y ,W H E T H E RI N C O N T R A C T ,S T R I C TL I A B I L I T Y ,O RT O R T( I N C L U D I N GN E G L I G E N C EO RO T H E R W I S E ) A R I S I N GI NA N YW A YO U TO FT H EU S EO FT H I SS O F T W A R E ,E V E NI FA D V I S E DO F T H EP O S S I B I L I T YO FS U C HD A M A G E .

Artistic License
T h eA r t i s t i cL i c e n s e V e r s i o n2 . 0 b e t a 4 ,O c t o b e r2 0 0 0 C o p y r i g h t( C )2 0 0 0 ,L a r r yW a l l . E v e r y o n ei sp e r m i t t e dt oc o p ya n dd i s t r i b u t ev e r b a t i mc o p i e s o ft h i sl i c e n s ed o c u m e n t ,b u tc h a n g i n gi ti sn o ta l l o w e d . P r e a m b l e T h i sc o p y r i g h tl i c e n s es t a t e st h et e r m su n d e rw h i c hag i v e nf r e e s o f t w a r eP a c k a g em a yb ec o p i e d ,m o d i f i e da n d / o rr e d i s t r i b u t e d ,w h i l et h e O r i g i n a t o r ( s )m a i n t a i ns o m ea r t i s t i cc o n t r o lo v e rt h ef u t u r ed e v e l o p m e n t o ft h a tP a c k a g e( a tl e a s ta sm u c ha r t i s t i cc o n t r o la sc a nb eg i v e nu n d e r c o p y r i g h tl a ww h i l es t i l lm a k i n gt h eP a c k a g eo p e ns o u r c ea n df r e es o f t w a r e ) . T h i sl i c e n s ei sb o u n db yc o p y r i g h tl a w ,a n dt h u si tl e g a l l ya p p l i e so n l y t ow o r k sw h i c ht h ec o p y r i g h th o l d e rh a sp e r m i t t e dc o p y i n g ,d i s t r i b u t i o n o rm o d i f i c a t i o nu n d e rt h et e r m so ft h eA r t i s t i cL i c e n s e ,V e r s i o n2 . 0 . Y o ua r er e m i n d e dt h a tY o ua r ea l w a y sp e r m i t t e dt om a k ea r r a n g e m e n t s

Y o ua r er e m i n d e dt h a tY o ua r ea l w a y sp e r m i t t e dt om a k ea r r a n g e m e n t s w h o l l yo u t s i d eo fag i v e nc o p y r i g h tl i c e n s ed i r e c t l yw i t ht h ec o p y r i g h t h o l d e r ( s )o fag i v e nP a c k a g e .I ft h et e r m so ft h i sl i c e n s ei m p e d ey o u r a b i l i t yt om a k ef u l lu s eo ft h eP a c k a g e ,Y o ua r ee n c o u r a g e dt oc o n t a c t t h ec o p y r i g h th o l d e r ( s )a n ds e e kad i f f e r e n tl i c e n s i n ga r r a n g e m e n t . D e f i n i t i o n s " P a c k a g e "r e f e r st ot h ec o l l e c t i o no ff i l e sd i s t r i b u t e db yt h e O r i g i n a t o r ( s ) ,a n dd e r i v a t i v e so ft h a tc o l l e c t i o no ff i l e sc r e a t e d t h r o u g ht e x t u a lm o d i f i c a t i o n . " S t a n d a r dV e r s i o n "r e f e r st ot h eP a c k a g ei fi th a sn o tb e e nm o d i f i e d ,o r h a sb e e nm o d i f i e do n l yi nw a y ss u g g e s t e db yt h eO r i g i n a t o r ( s ) . " M o d i f i e dV e r s i o n "r e f e r st ot h eP a c k a g e ,i fi th a sb e e nc h a n g e db yY o u v i at e x t u a lm o d i f i c a t i o no ft h es o u r c ec o d e ,a n ds u c hc h a n g e sw e r en o t s u g g e s t e db yt h eO r i g i n a t o r ( s ) . " O r i g i n a t o r "r e f e r st ot h ea u t h o r ( s )a n d / o rc o p y r i g h th o l d e r ( s )o ft h e S t a n d a r dV e r s i o no ft h eP a c k a g e . " Y o u "a n d" Y o u r "r e f e r st oa n yp e r s o nw h ow o u l dl i k et oc o p y , d i s t r i b u t e ,o rm o d i f yt h eP a c k a g e . " D i s t r i b u t i o nF e e "i sa n yf e et h a tY o uc h a r g ef o rp r o v i d i n gac o p yo f t h i sP a c k a g et oa n o t h e rp a r t y .I td o e sn o tr e f e rt ol i c e n s i n gf e e s . " F r e e l yA v a i l a b l e "m e a n st h a t : ( a )n of e ei sc h a r g e df o rt h er i g h tt ou s et h ei t e m( t h o u g ha D i s t r i b u t i o nF e em a yb ec h a r g e d ) . ( b )r e c i p i e n t so ft h ei t e mm a yr e d i s t r i b u t ei tu n d e rt h es a m e c o n d i t i o n st h e yr e c e i v e di t . ( c )I ft h ei t e mi sab i n a r y ,o b j e c tc o d e ,b y t e c o d e ,t h ec o m p l e t e c o r r e s p o n d i n gm a c h i n e r e a d a b l es o u r c ec o d ei si n c l u d e dw i t ht h e i t e m . P e r m i s s i o nf o rU s ea n dM o d i f i c a t i o nW i t h o u tR e d i s t r i b u t i o n ( 1 )Y o ua r ep e r m i t t e dt ou s et h eS t a n d a r dV e r s i o na n dc r e a t ea n du s e M o d i f i e dV e r s i o n sf o ra n yp u r p o s ew i t h o u tr e s t r i c t i o n ,p r o v i d e dt h a t y o ud on o tr e d i s t r i b u t et h eM o d i f i e dV e r s i o nt oo t h e r so u t s i d eo fy o u r c o m p a n yo ro r g a n i z a t i o n . P e r m i s s i o n sf o rR e d i s t r i b u t i o no ft h eS t a n d a r dV e r s i o n ( 2 )Y o um a ym a k ea v a i l a b l ev e r b a t i mc o p i e so ft h es o u r c ec o d eo ft h e S t a n d a r dV e r s i o no ft h i sP a c k a g ei na n ym e d i u mw i t h o u tr e s t r i c t i o n , e i t h e rg r a t i so rf o raD i s t r i b u t i o nF e e ,p r o v i d e dt h a ty o ud u p l i c a t e a l lo ft h eo r i g i n a lc o p y r i g h tn o t i c e sa n da s s o c i a t e dd i s c l a i m e r s . A t Y o u rd i s c r e t i o n ,s u c hv e r b a t i mc o p i e sm a yo rm a yn o ti n c l u d ec o m p i l e d b y t e c o d e ,o b j e c tc o d eo rb i n a r yv e r s i o n so ft h ec o r r e s p o n d i n gs o u r c e c o d ei nt h es a m em e d i u m . ( 3 )Y o um a ya p p l ya n yb u gf i x e s ,p o r t a b i l i t yc h a n g e s ,a n do t h e r m o d i f i c a t i o n sm a d ea v a i l a b l ef r o ma n yo ft h eO r i g i n a t o r ( s ) . T h e r e s u l t i n gm o d i f i e dP a c k a g ew i l ls t i l lb ec o n s i d e r e dt h eS t a n d a r d V e r s i o n ,a n dm a yb ec o p i e d ,m o d i f i e da n dr e d i s t r i b u t e du n d e rt h et e r m s

o ft h eo r i g i n a ll i c e n s eo ft h eS t a n d a r dV e r s i o na si fi tw e r et h e S t a n d a r dV e r s i o n . P e r m i s s i o n sf o rR e d i s t r i b u t i o no fM o d i f i e dV e r s i o n so ft h eP a c k a g ea sS o u r c e ( 4 )Y o um a ym o d i f yy o u rc o p yo ft h es o u r c ec o d eo ft h i sP a c k a g ei na n yw a y a n dd i s t r i b u t et h a tM o d i f i e dV e r s i o n( e i t h e rg r a t i so rf o ra D i s t r i b u t i o nF e e ,a n dw i t ho rw i t h o u tac o r r e s p o n d i n gb i n a r y ,b y t e c o d e o ro b j e c tc o d ev e r s i o no ft h eM o d i f i e dV e r s i o n )p r o v i d e dt h a tY o u c l e a r l yi n d i c a t ew h a tc h a n g e sY o um a d et ot h eP a c k a g e ,a n dp r o v i d e d t h a tY o ud oa tl e a s tO N Eo ft h ef o l l o w i n g : ( a )m a k et h eM o d i f i e dV e r s i o na v a i l a b l et ot h eO r i g i n a t o r ( s )o ft h e S t a n d a r dV e r s i o n ,u n d e rt h ee x a c tl i c e n s eo ft h eS t a n d a r d V e r s i o n ,s ot h a tt h eO r i g i n a t o r ( s )m a yi n c l u d ey o u rm o d i f i c a t i o n s i n t ot h eS t a n d a r dV e r s i o n( a tt h e i rd i s c r e t i o n ) . ( b )m o d i f ya n yi n s t a l l a t i o ns c r i p t sa n dp r o c e d u r e ss ot h a t i n s t a l l a t i o no ft h eM o d i f i e dV e r s i o nw i l ln e v e rc o n f l i c tw i t ha n i n s t a l l a t i o no ft h eS t a n d a r dV e r s i o n ,i n c l u d ef o re a c hp r o g r a m i n s t a l l e db yt h eM o d i f i e dV e r s i o nc l e a rd o c u m e n t a t i o nd e s c r i b i n g h o wi td i f f e r sf r o mt h eS t a n d a r dV e r s i o n ,a n dr e n a m ey o u r M o d i f i e dV e r s i o ns ot h a tt h en a m ei ss u b s t a n t i a l l yd i f f e r e n tf r o m t h eS t a n d a r dV e r s i o n . ( c )p e r m i ta n de n c o u r a g ea n y o n ew h or e c e i v e sac o p yo ft h eM o d i f i e d V e r s i o np e r m i s s i o nt om a k ey o u rm o d i f i c a t i o n sF r e e l yA v a i l a b l ei n s o m es p e c i f i cw a y . I fY o u rM o d i f i e dV e r s i o ni si nt u r nd e r i v e df r o maM o d i f i e dV e r s i o n m a d eb yat h i r dp a r t y ,t h e nY o ua r es t i l lr e q u i r e dt oe n s u r et h a tY o u r M o d i f i e dV e r s i o nc o m p l i e sw i t ht h er e q u i r e m e n t so ft h i sl i c e n s e . P e r m i s s i o n sf o rR e d i s t r i b u t i o no fN o n S o u r c eV e r s i o n so fP a c k a g e ( 5 )Y o um a yd i s t r i b u t eb i n a r y ,o b j e c tc o d e ,b y t e c o d eo ro t h e rn o n s o u r c e v e r s i o n so ft h eS t a n d a r dV e r s i o no ft h eP a c k a g e ,p r o v i d e dt h a ty o u i n c l u d ec o m p l e t ei n s t r u c t i o n so nw h e r et og e tt h es o u r c ec o d eo ft h e S t a n d a r dV e r s i o n . S u c hi n s t r u c t i o n sm u s tb ev a l i da tt h et i m eo fY o u r d i s t r i b u t i o n . I ft h e s ei n s t r u c t i o n s ,a ta n yt i m ew h i l eY o ua r e c a r r y i n go u rs u c hd i s t r i b u t i o n ,b e c o m ei n v a l i d ,y o um u s tp r o v i d en e w i n s t r u c t i o n so nd e m a n do rc e a s ef u r t h e rd i s t r i b u t i o n . I fY o uc e a s e d i s t r i b u t i o nw i t h i nt h i r t yd a y sa f t e rY o ub e c o m ea w a r et h a tt h e i n s t r u c t i o n sa r ei n v a l i d ,t h e nY o ud on o tf o r f e i ta n yo fY o u rr i g h t s u n d e rt h i sl i c e n s e . ( 6 )Y o um a yd i s t r i b u t eb i n a r y ,o b j e c tc o d e ,b y t e c o d eo ro t h e rn o n s o u r c e v e r s i o n so faM o d i f i e dV e r s i o np r o v i d e dt h a tY o ud oa tl e a s tO N Eo f t h ef o l l o w i n g : ( a )i n c l u d eac o p yo ft h ec o r r e s p o n d i n gs o u r c ec o d ef o rt h eM o d i f i e d V e r s i o nu n d e rt h et e r m si n d i c a t e di n( 4 ) . ( b )e n s u r et h a tt h ei n s t a l l a t i o no fY o u rn o n s o u r c eM o d i f i e dV e r s i o n d o e sn o tc o n f l i c ti na n yw a yw i t ha ni n s t a l l a t i o no ft h eS t a n d a r d V e r s i o n ,i n c l u d ef o re a c hp r o g r a mi n s t a l l e db yt h eM o d i f i e d V e r s i o nc l e a rd o c u m e n t a t i o nd e s c r i b i n gh o wi td i f f e r sf r o mt h e S t a n d a r dV e r s i o n ,a n dr e n a m ey o u rM o d i f i e dV e r s i o ns ot h a tt h e n a m ei ss u b s t a n t i a l l yd i f f e r e n tf r o mt h eS t a n d a r dV e r s i o n . ( c )e n s u r et h a tt h eM o d i f i e dV e r s i o ni n c l u d e sn o t i f i c a t i o no ft h e

c h a n g e sm a d ef r o mt h eS t a n d a r dV e r s i o n ,a n do f f e rt op r o v i d e m a c h i n e r e a d a b l es o u r c ec o d e( u n d e ral i c e n s et h a tp e r m i t sm a k i n g t h a ts o u r c ec o d eF r e e l yA v a i l a b l e )o ft h eM o d i f i e dV e r s i o nv i a m a i lo r d e r . P e r m i s s i o n sf o rI n c l u s i o no ft h eP a c k a g ei nA g g r e g a t eW o r k s ( 7 )Y o um a ya g g r e g a t et h i sP a c k a g e( e i t h e rt h eS t a n d a r dV e r s i o no r M o d i f i e dV e r s i o n )w i t ho t h e rp a c k a g e sa n dd i s t r i b u t et h er e s u l t i n g a g g r e g a t i o np r o v i d e dt h a tY o ud on o tc h a r g eal i c e n s i n gf e ef o rt h e P a c k a g e . D i s t r i b u t i o nF e e sa r ep e r m i t t e d ,a n dl i c e n s i n gf e e sf o r o t h e rp a c k a g e si nt h ea g g r e g a t i o na r ep e r m i t t e d . Y o u rp e r m i s s i o nt o d i s t r i b u t eS t a n d a r do rM o d i f i e dV e r s i o n so ft h eP a c k a g ei ss t i l l s u b j e c tt ot h eo t h e rt e r m ss e tf o r t hi no t h e rs e c t i o n so ft h i s l i c e n s e . ( 8 )I na d d i t i o nt ot h ep e r m i s s i o n sg i v e ne l s e w h e r eb yt h i sl i c e n s e ,Y o u a r ea l s op e r m i t t e dt ol i n kM o d i f i e da n dS t a n d a r dV e r s i o n so ft h i s P a c k a g ew i t ho t h e rw o r k sa n dd i s t r i b u t et h er e s u l tw i t h o u t r e s t r i c t i o n ,p r o v i d e dY o uh a v ep r o d u c e db i n a r yp r o g r a m ( s )t h a td on o t o v e r t l ye x p o s et h ei n t e r f a c e so ft h eP a c k a g e . T h i si n c l u d e s p e r m i s s i o nt oe m b e dt h eP a c k a g ei nal a r g e rw o r ko fy o u ro w nw i t h o u t e x p o s i n gad i r e c ti n t e r f a c et ot h eP a c k a g e . T h i sa l s oi n c l u d e s p e r m i s s i o nt ob u i l ds t a n d a l o n eb i n a r yo rb y t e c o d ev e r s i o n so fy o u r s c r i p t st h a tr e q u i r et h eP a c k a g e ,b u td on o to t h e r w i s eg i v et h ec a s u a l u s e rd i r e c ta c c e s st ot h eP a c k a g ei t s e l f . I t e m sT h a ta r eN e v e rC o n s i d e r e dP a r to faM o d i f i e dV e r s i o nP a c k a g e ( 9 )W o r k s( i n c l u d i n g ,b u tn o tl i m i t e dt o ,s u b r o u t i n e sa n ds c r i p t s )t h a t y o uh a v el i n k e do ra g g r e g a t e dw i t ht h eP a c k a g et h a tm e r e l ye x t e n do r m a k eu s eo ft h eP a c k a g e ,b u ta r en o ti n t e n d e dt oc a u s et h eP a c k a g et o o p e r a t ed i f f e r e n t l yf r o mt h eS t a n d a r dV e r s i o n ,d on o t ,b yt h e m s e l v e s , c a u s et h eP a c k a g et ob eaM o d i f i e dV e r s i o n . I na d d i t i o n ,s u c hw o r k s a r en o tc o n s i d e r e dp a r t so ft h eP a c k a g ei t s e l f ,a n da r en o tb o u n db y t h et e r m so ft h eP a c k a g e ' sl i c e n s e . A c c e p t a n c eo fL i c e n s ea n dD i s c l a i m e ro fW a r r a n t y ( 1 0 )Y o ua r en o tr e q u i r e dt oa c c e p tt h i sL i c e n s e ,s i n c ey o uh a v en o ts i g n e d i t . H o w e v e r ,n o t h i n ge l s eg r a n t sy o up e r m i s s i o nt oc o p y ,m o d i f yo r d i s t r i b u t et h eS t a n d a r do rM o d i f i e dV e r s i o n so ft h eP a c k a g e . T h e s e a c t i o n sa r ep r o h i b i t e db yc o p y r i g h tl a wi fy o ud on o ta c c e p tt h i s L i c e n s e . T h e r e f o r e ,b yc o p y i n g ,m o d i f y i n go rd i s t r i b u t i n gS t a n d a r d a n dM o d i f i e dV e r s i o n so ft h eP a c k a g e ,y o ui n d i c a t ey o u ra c c e p t a n c eo f t h el i c e n s eo ft h eP a c k a g e . ( 1 1 )D i s c l a i m e ro fW a r r a n t y : T H I SS O F T W A R EI SP R O V I D E DB YT H EC O P Y R I G H TH O L D E R SA N DC O N T R I B U T O R S " A SI S "A N DA N YE X P R E S SO RI M P L I E DW A R R A N T I E S ,I N C L U D I N G ,B U TN O T L I M I T E DT O ,T H EI M P L I E DW A R R A N T I E SO FM E R C H A N T A B I L I T YA N DF I T N E S SF O R AP A R T I C U L A RP U R P O S EA R ED I S C L A I M E D . I NN OE V E N TU N L E S SR E Q U I R E DB Y L A WO RA G R E E DT OI NW R I T I N GW I L LA N YC O P Y R I G H TH O L D E RO RC O N T R I B U T O R B EL I A B L EF O RA N YD I R E C T ,I N D I R E C T ,I N C I D E N T A L ,S P E C I A L ,E X E M P L A R Y , O RC O N S E Q U E N T I A LD A M A G E S( I N C L U D I N G ,B U TN O TL I M I T E DT O ,P R O C U R E M E N T O FS U B S T I T U T EG O O D SO RS E R V I C E S ;L O S SO FU S E ,D A T A ,P R O F I T S ;O R B U S I N E S SI N T E R R U P T I O N )H O W E V E RC A U S E DA N DO NA N YT H E O R YO FL I A B I L I T Y , W H E T H E RI NC O N T R A C T ,S T R I C TL I A B I L I T Y ,O RT O R T( I N C L U D I N GN E G L I G E N C E

O RO T H E R W I S E )A R I S I N GI NA N YW A YO U TO FT H EU S EO FT H I SS O F T W A R E , E V E NI FA D V I S E DO FT H EP O S S I B I L I T YO FS U C HD A M A G E .

Indices
Style Property Index Transform Property Index Variable and Definition Index Function and Class Index General Index