587 lines
35 KiB
HTML
587 lines
35 KiB
HTML
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
|
||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
<title>Language Basics — Ren'Py Documentation</title>
|
||
<link rel="stylesheet" href="_static/renpydoc.css" type="text/css" />
|
||
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
|
||
<link rel="stylesheet" type="text/css" href="_static/bootstrap-3.3.6/css/bootstrap.min.css" />
|
||
<link rel="stylesheet" type="text/css" href="_static/bootstrap-3.3.6/css/bootstrap-theme.min.css" />
|
||
<link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css" />
|
||
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
|
||
<script type="text/javascript" src="_static/jquery.js"></script>
|
||
<script type="text/javascript" src="_static/underscore.js"></script>
|
||
<script type="text/javascript" src="_static/doctools.js"></script>
|
||
<script type="text/javascript" src="_static/language_data.js"></script>
|
||
<script type="text/javascript" src="_static/js/jquery-1.11.0.min.js"></script>
|
||
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
|
||
<script type="text/javascript" src="_static/bootstrap-3.3.6/js/bootstrap.min.js"></script>
|
||
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>
|
||
<link rel="index" title="Index" href="genindex.html" />
|
||
<link rel="search" title="Search" href="search.html" />
|
||
<link rel="next" title="Labels & Control Flow" href="label.html" />
|
||
<link rel="prev" title="GUI Customization Guide" href="gui.html" />
|
||
<meta charset='utf-8'>
|
||
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
|
||
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
|
||
<meta name="apple-mobile-web-app-capable" content="yes">
|
||
|
||
</head><body>
|
||
|
||
<div id="navbar" class="navbar navbar-default navbar-fixed-top">
|
||
<div class="container">
|
||
<div class="navbar-header">
|
||
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
|
||
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
|
||
<span class="icon-bar"></span>
|
||
<span class="icon-bar"></span>
|
||
<span class="icon-bar"></span>
|
||
</button>
|
||
<a class="navbar-brand" href="index.html">
|
||
Ren'Py Documentation</a>
|
||
<span class="navbar-text navbar-version pull-left"><b>7.5.3</b></span>
|
||
</div>
|
||
|
||
<div class="collapse navbar-collapse nav-collapse">
|
||
<ul class="nav navbar-nav">
|
||
|
||
<li><a href="https://www.renpy.org">Home Page</a></li>
|
||
<li><a href="https://www.renpy.org/doc/html/">Online Documentation</a></li>
|
||
|
||
|
||
<li class="dropdown globaltoc-container">
|
||
<a role="button"
|
||
id="dLabelGlobalToc"
|
||
data-toggle="dropdown"
|
||
data-target="#"
|
||
href="index.html">Site <b class="caret"></b></a>
|
||
<ul class="dropdown-menu globaltoc"
|
||
role="menu"
|
||
aria-labelledby="dLabelGlobalToc"><ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="quickstart.html">Quickstart</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="gui.html">GUI Customization Guide</a></li>
|
||
</ul>
|
||
<ul class="current">
|
||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Language Basics</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="label.html">Labels & Control Flow</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="dialogue.html">Dialogue and Narration</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="displaying_images.html">Displaying Images</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="menus.html">In-Game Menus</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="python.html">Python Statements</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="conditional.html">Conditional Statements</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="audio.html">Audio</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="movie.html">Movie</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="voice.html">Voice</a></li>
|
||
</ul>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="text.html">Text</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="translation.html">Translation</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="displayables.html">Displayables</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="transforms.html">Transforms</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="transitions.html">Transitions</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="atl.html">Animation and Transformation Language</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="matrixcolor.html">Matrixcolor</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="layeredimage.html">Layered Images</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="3dstage.html">3D Stage</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="live2d.html">Live2D Cubism</a></li>
|
||
</ul>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="style.html">Styles</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="style_properties.html">Style Properties</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="screens.html">Screens and Screen Language</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="screen_actions.html">Screen Actions, Values, and Functions</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="screen_special.html">Special Screen Names</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="screen_optimization.html">Screen Language Optimization</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="config.html">Configuration Variables</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="preferences.html">Preference Variables</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="store_variables.html">Store Variables</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="mouse.html">Custom Mouse Cursors</a></li>
|
||
</ul>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="launcher.html">Launcher</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="developer_tools.html">Developer Tools</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="director.html">Interactive Director</a></li>
|
||
</ul>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="nvl_mode.html">NVL-Mode Tutorial</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="input.html">Text Input</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="side_image.html">Side Images</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="rooms.html">Image Gallery, Music Room, and Replay Actions</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="drag_drop.html">Drag and Drop</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="sprites.html">Sprites</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="keymap.html">Customizing the Keymap</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="achievement.html">Achievements</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="history.html">Dialogue History</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="multiple.html">Multiple Character Dialogue</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="splashscreen_presplash.html">Splashscreen and Presplash</a></li>
|
||
</ul>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="statement_equivalents.html">Statement Equivalents</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="save_load_rollback.html">Saving, Loading, and Rollback</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="persistent.html">Persistent Data</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="trans_trans_python.html">Transforms and Transitions in Python</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="gui_advanced.html">Advanced GUI</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="screen_python.html">Screens and Python</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="modes.html">Modes</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="cdd.html">Creator-Defined Displayables</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="cds.html">Creator-Defined Statements</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="custom_text_tags.html">Custom Text Tags</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="character_callbacks.html">Character Callbacks</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="file_python.html">File Access</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="color_class.html">Color Class</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="matrix.html">Matrix</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="model.html">Model-Based Rendering</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="other.html">Other Functions and Variables</a></li>
|
||
</ul>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="build.html">Building Distributions</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="updater.html">Web Updater</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="android.html">Android</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="chromeos.html">Chrome OS/Chromebook</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="ios.html">iOS</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="iap.html">In-App Purchasing</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="gesture.html">Gestures</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="raspi.html">Raspberry Pi</a></li>
|
||
</ul>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="security.html">Security</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="problems.html">Dealing with Problems</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="environment_variables.html">Environment Variables</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="self_voicing.html">Self-Voicing</a></li>
|
||
</ul>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="editor.html">Text Editor Integration</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="skins.html">Skins</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="translating_renpy.html">Translating Ren'Py</a></li>
|
||
</ul>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog (Ren'Py 7.x-)</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="changelog6.html">Changelog (Ren'Py 6.11 - 6.99)</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="incompatible.html">Incompatible Changes</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="distributor.html">Distributor Notes</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="credits.html">Credits</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="sponsors.html">Ren'Py Development Sponsors</a></li>
|
||
</ul>
|
||
<ul>
|
||
<li class="toctree-l1"><a class="reference internal" href="thequestion.html">Script of The Question</a></li>
|
||
<li class="toctree-l1"><a class="reference internal" href="thequestion_nvl.html">NVL-mode script for The Question</a></li>
|
||
</ul>
|
||
</ul>
|
||
</li>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
</ul>
|
||
|
||
|
||
|
||
<form class="navbar-form navbar-right" action="search.html" method="get">
|
||
<div class="form-group">
|
||
<input type="text" name="q" class="form-control" placeholder="Search" />
|
||
</div>
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="container">
|
||
<div class="row">
|
||
<div class="col-md-3">
|
||
<div id="sidebar" class="bs-sidenav" role="complementary"><ul>
|
||
<li><a class="reference internal" href="#">Language Basics</a><ul>
|
||
<li><a class="reference internal" href="#files">Files</a><ul>
|
||
<li><a class="reference internal" href="#base-directory">Base Directory</a></li>
|
||
<li><a class="reference internal" href="#game-directory">Game Directory</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#comments">Comments</a></li>
|
||
<li><a class="reference internal" href="#logical-lines">Logical Lines</a></li>
|
||
<li><a class="reference internal" href="#indentation-and-blocks">Indentation and Blocks</a></li>
|
||
<li><a class="reference internal" href="#elements-of-statements">Elements of Statements</a></li>
|
||
<li><a class="reference internal" href="#common-statement-syntax">Common Statement Syntax</a></li>
|
||
<li><a class="reference internal" href="#python-expression-syntax">Python Expression Syntax</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="col-md-9 content">
|
||
|
||
<div class="section" id="language-basics">
|
||
<h1>Language Basics<a class="headerlink" href="#language-basics" title="Permalink to this headline"> link</a></h1>
|
||
<p>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.</p>
|
||
<div class="section" id="files">
|
||
<h2>Files<a class="headerlink" href="#files" title="Permalink to this headline"> link</a></h2>
|
||
<p>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 the Unicode order of their paths),
|
||
and will use the contents of the files as the script.</p>
|
||
<p>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.</p>
|
||
<p>To speed up loading time, Ren'Py will compile the .rpy files into
|
||
.rpyc files when it starts up. When a .rpy file is changed, the .rpyc
|
||
file will be updated when Ren'Py starts up. However, if a .rpyc file
|
||
exists without a corresponding .rpy file, the .rpyc file will be
|
||
used. This can lead to problems if a .rpy file is deleted without
|
||
deleting the .rpyc file.</p>
|
||
<p>Filenames must being with a letter or number, and may not begin with
|
||
"00", as Ren'Py uses such files for its own purposes.</p>
|
||
<div class="section" id="base-directory">
|
||
<h3>Base Directory<a class="headerlink" href="#base-directory" title="Permalink to this headline"> link</a></h3>
|
||
<p>The base directory is the directory that contains all files that are
|
||
distributed with the game. (It may also contain some files that are not
|
||
distributed with the game.) Things like README files should be placed in the
|
||
base directory, from where they will be distributed.</p>
|
||
<p>The base directory is created underneath the Ren'Py directory, and has the name
|
||
of your game. For example, if your Ren'Py directory is named renpy-6.11.2, and
|
||
your game is named "HelloWorld", your base directory will be
|
||
renpy-6.11.2/HelloWorld.</p>
|
||
</div>
|
||
<div class="section" id="game-directory">
|
||
<h3>Game Directory<a class="headerlink" href="#game-directory" title="Permalink to this headline"> link</a></h3>
|
||
<p>The game directory is almost always a directory named "game" underneath the
|
||
base directory. For example, if your base directory is renpy-6.11.2/HelloWorld,
|
||
your game directory will be renpy-6.11.2/HelloWorld/game.</p>
|
||
<p>However, Ren'Py searches directories in the following order:</p>
|
||
<ul class="simple">
|
||
<li>The name of the executable, without the suffix. For example,
|
||
if the executable is named moonlight.exe, it will look for
|
||
a directory named moonlight under the base directory.</li>
|
||
<li>The name of the executable, without the suffix, and with
|
||
a prefix ending with _ removed. For example, if the executable
|
||
is moonlight_en.exe, Ren'Py will look for a directory named en.</li>
|
||
<li>The directories "game", "data", and "launcher", in that order.</li>
|
||
</ul>
|
||
<p>The launcher will only properly recognize the "game" and "data" directories,
|
||
however.</p>
|
||
<p>The game directory contains all the files used by the game. It, including all
|
||
subdirectories, is scanned for .rpy and .rpyc files, and those are combined to
|
||
form the game script. It is scanned for .rpa archive files, and those are
|
||
automatically used by the game. Finally, when the game gives a path to a file
|
||
to load, it is loaded relative to the game directory. (But note that
|
||
config.searchpath can change this.)</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="comments">
|
||
<h2>Comments<a class="headerlink" href="#comments" title="Permalink to this headline"> link</a></h2>
|
||
<p>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.</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="c1"># This is a comment.</span>
|
||
<span class="k">show</span> <span class="n">black</span> <span class="c1"># this is also a comment.</span>
|
||
|
||
<span class="s2">"# This isn't a comment, since it's part of a string."</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Ren'Py ignores comments, so the script is treated like the comment
|
||
wasn't there.</p>
|
||
</div>
|
||
<div class="section" id="logical-lines">
|
||
<h2>Logical Lines<a class="headerlink" href="#logical-lines" title="Permalink to this headline"> link</a></h2>
|
||
<p>A script file is broken up into <em class="dfn">logical lines</em>. 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:</p>
|
||
<ul class="simple">
|
||
<li>The last character on the line is a backslash ('\').</li>
|
||
<li>The line contains an open parenthesis character ('(', '{', or '['),
|
||
that hasn't been matched by the cooresponding close parenthesis
|
||
character (')', '}', or ']', respectively).</li>
|
||
<li>The end of the line occurs during a string.</li>
|
||
</ul>
|
||
<p>Once a logical line ends, the next logical line begins at the start of
|
||
the next line.</p>
|
||
<p>Most statements in the Ren'Py language consist of a single logical
|
||
line, while some statements consist of multiple lines.</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="s2">"This is one logical line"</span>
|
||
|
||
<span class="s2">"Since this line contains a string, it continues</span>
|
||
<span class="n">even</span> <span class="n">when</span> <span class="n">the</span> <span class="n">line</span> <span class="n">ends</span><span class="o">.</span><span class="s2">"</span>
|
||
|
||
<span class="k">$</span> <span class="n">a</span> <span class="o">=</span> <span class="p">[</span> <span class="s2">"Because of parenthesis, this line also"</span><span class="p">,</span>
|
||
<span class="s2">"spans more than one line."</span> <span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Empty logical lines are ignored.</p>
|
||
</div>
|
||
<div class="section" id="indentation-and-blocks">
|
||
<h2>Indentation and Blocks<a class="headerlink" href="#indentation-and-blocks" title="Permalink to this headline"> link</a></h2>
|
||
<p><em class="dfn">Indentation</em> 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.</p>
|
||
<p>Indentation is used to group statements into <em class="dfn">blocks</em>. A block is
|
||
a group of lines, and often a group of statements. The rules for
|
||
dividing a file into blocks are:</p>
|
||
<ul class="simple">
|
||
<li>A block is open at the start of a file.</li>
|
||
<li>A new block is started whenever a logical line is indented past the
|
||
previous logical line.</li>
|
||
<li>All logical lines inside a block must have the same indentation.</li>
|
||
<li>A block ends when a logical line is encountered with less
|
||
indentation than the lines in the block.</li>
|
||
</ul>
|
||
<p>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.</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="s2">"This statement, and the if statement that follows, is part of a block."</span>
|
||
|
||
<span class="k">if</span> <span class="kc">True</span><span class="p">:</span>
|
||
|
||
<span class="s2">"But this statement is part of a new block."</span>
|
||
|
||
<span class="s2">"This is also part of that new block."</span>
|
||
|
||
<span class="s2">"This is part of the first block, again."</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="elements-of-statements">
|
||
<h2>Elements of Statements<a class="headerlink" href="#elements-of-statements" title="Permalink to this headline"> link</a></h2>
|
||
<p>Ren'Py statements are made of a few basic parts.</p>
|
||
<dl class="docutils">
|
||
<dt><em class="dfn">Keyword</em></dt>
|
||
<dd><p class="first">A keyword is a word that must literally appear in the script of the game.
|
||
Keywords are used to introduce statements and properties.</p>
|
||
<p class="last">Names beginning 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-specific version of that name.</p>
|
||
</dd>
|
||
<dt><em class="dfn">Name</em></dt>
|
||
<dd>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.</dd>
|
||
<dt><em class="dfn">Image Name</em></dt>
|
||
<dd><p class="first">An <em class="dfn">image name</em> consists of one or more components, separated by
|
||
spaces. The first component of the image name is called the
|
||
<em class="dfn">image tag</em>. The second and later components of the name are
|
||
the <em class="dfn">image attributes</em>. An image component consists of a
|
||
string of letters, numbers, and underscores.</p>
|
||
<p class="last">For example, take the image name <code class="docutils literal notranslate"><span class="pre">mary</span> <span class="pre">beach</span> <span class="pre">night</span> <span class="pre">happy</span></code>. The
|
||
image tag is <code class="docutils literal notranslate"><span class="pre">mary</span></code>, while the image attributes are,
|
||
<code class="docutils literal notranslate"><span class="pre">beach</span></code>, <code class="docutils literal notranslate"><span class="pre">night</span></code>, and <code class="docutils literal notranslate"><span class="pre">happy</span></code>.</p>
|
||
</dd>
|
||
<dt><em class="dfn">String</em></dt>
|
||
<dd><p class="first">A string begins with a quote character (one of ", ', or `),
|
||
contains some sequence of characters, and ends with the same quote
|
||
character.</p>
|
||
<p>The backslash character (\) is used to escape quotes, special
|
||
characters such as % (written as \%), [ (written as \[), and
|
||
{ (written as \{). It's also used to include newlines, using the \n
|
||
sequence.</p>
|
||
<p>Inside a Ren'Py string, consecutive whitespace is compressed into
|
||
a single whitespace character, unless a space is preceded by a
|
||
backslash.</p>
|
||
<div class="last highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="s1">'Strings can</span><span class="se">\'</span><span class="s1">t contain their delimiter, unless you escape it.'</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
<dt><em class="dfn">Simple Expression</em></dt>
|
||
<dd><p class="first">A simple expression is a Python expression, used to include Python
|
||
in some parts of the Ren'Py script. A simple expression begins
|
||
with:</p>
|
||
<ul class="simple">
|
||
<li>A name.</li>
|
||
<li>A string.</li>
|
||
<li>A number.</li>
|
||
<li>Any Python expression, in parenthesis.</li>
|
||
</ul>
|
||
<p>This can be followed by any number of:</p>
|
||
<ul class="simple">
|
||
<li>A dot followed by a name.</li>
|
||
<li>A parenthesised Python expression.</li>
|
||
</ul>
|
||
<p class="last">As an example, <code class="docutils literal notranslate"><span class="pre">3</span></code>, <code class="docutils literal notranslate"><span class="pre">(3</span> <span class="pre">+</span> <span class="pre">4)</span></code>, <code class="docutils literal notranslate"><span class="pre">foo.bar</span></code>, and <code class="docutils literal notranslate"><span class="pre">foo(42)</span></code>
|
||
are all simple expressions. But <code class="docutils literal notranslate"><span class="pre">3</span> <span class="pre">+</span> <span class="pre">4</span></code> is not, as the
|
||
expression ends at the end of a string.</p>
|
||
</dd>
|
||
<dt><em class="dfn">At List</em></dt>
|
||
<dd>An at list is a list of simple expressions, separated by commas.</dd>
|
||
<dt><em class="dfn">Python Expression</em></dt>
|
||
<dd>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.</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="common-statement-syntax">
|
||
<h2>Common Statement Syntax<a class="headerlink" href="#common-statement-syntax" title="Permalink to this headline"> link</a></h2>
|
||
<p>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.</p>
|
||
<p>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.</p>
|
||
<p>If the statement takes a block, the line ends with a colon
|
||
(:). Otherwise, the line just ends.</p>
|
||
</div>
|
||
<div class="section" id="python-expression-syntax">
|
||
<span id="python-basics"></span><h2>Python Expression Syntax<a class="headerlink" href="#python-expression-syntax" title="Permalink to this headline"> link</a></h2>
|
||
<div class="admonition note">
|
||
<p class="first admonition-title">Note</p>
|
||
<p class="last">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.</p>
|
||
</div>
|
||
<p>Many portions of Ren'Py take Python expressions. For example, defining
|
||
a new Character involves a call to the <a class="reference internal" href="dialogue.html#Character" title="Character"><code class="xref py py-func docutils literal notranslate"><span class="pre">Character()</span></code></a> function. While
|
||
Python expressions are very powerful, only a fraction of that power is
|
||
necessary to write a basic Ren'Py game.</p>
|
||
<p>Here's a synopsis of Python expressions.</p>
|
||
<dl class="docutils">
|
||
<dt><em class="dfn">Integer</em></dt>
|
||
<dd>An integer is a number without a decimal point. <code class="docutils literal notranslate"><span class="pre">3</span></code> and <code class="docutils literal notranslate"><span class="pre">42</span></code>
|
||
are integers.</dd>
|
||
<dt><em class="dfn">Float</em></dt>
|
||
<dd>A float (short for floating-point number) is a number with a
|
||
decimal point. <code class="docutils literal notranslate"><span class="pre">.5</span></code>, <code class="docutils literal notranslate"><span class="pre">7.</span></code>, and <code class="docutils literal notranslate"><span class="pre">9.0</span></code> are all floats.</dd>
|
||
<dt><em class="dfn">String</em></dt>
|
||
<dd>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.</dd>
|
||
<dt><em class="dfn">True, False, None</em></dt>
|
||
<dd>There are three special values. <code class="docutils literal notranslate"><span class="pre">True</span></code> is a true value, <code class="docutils literal notranslate"><span class="pre">False</span></code> is
|
||
a false value. <code class="docutils literal notranslate"><span class="pre">None</span></code> represents the absence of a value.</dd>
|
||
<dt><em class="dfn">Tuple</em></dt>
|
||
<dd><p class="first">Tuples are used to represent containers where the number of items
|
||
is important. For example, one might use a 2-tuple (also called a
|
||
pair) to represent width and height, or a 4-tuple (x, y, width,
|
||
height) to represent a rectangle.</p>
|
||
<p>Tuples begin with a left-parenthesis <code class="docutils literal notranslate"><span class="pre">(</span></code>, consist of zero or
|
||
more comma-separated Python expressions, and end with a
|
||
right-parenthesis <code class="docutils literal notranslate"><span class="pre">)</span></code>. As a special case, the one-item tuple
|
||
must have a comma following the item. For example:</p>
|
||
<div class="last highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="p">()</span>
|
||
<span class="p">(</span><span class="mi">1</span><span class="p">,)</span>
|
||
<span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="s2">"#555"</span><span class="p">)</span>
|
||
<span class="p">(</span><span class="mi">32</span><span class="p">,</span> <span class="mi">24</span><span class="p">,</span> <span class="mi">200</span><span class="p">,</span> <span class="mi">100</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
<dt><em class="dfn">List</em></dt>
|
||
<dd><p class="first">Lists are used to represent containers where the number of items
|
||
may vary. A list begins with a <code class="docutils literal notranslate"><span class="pre">[</span></code>, contains a comma-separated
|
||
list of expressions, and ends with <code class="docutils literal notranslate"><span class="pre">]</span></code>. For example:</p>
|
||
<div class="last highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="p">[</span> <span class="p">]</span>
|
||
<span class="p">[</span> <span class="mi">1</span> <span class="p">]</span>
|
||
<span class="p">[</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span> <span class="p">]</span>
|
||
<span class="p">[</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span> <span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd>
|
||
<dt><em class="dfn">Variable</em></dt>
|
||
<dd><p class="first">Python expressions can use variables, that store values defined
|
||
using the <code class="docutils literal notranslate"><span class="pre">define</span></code> statement or Python statements. A variable begins
|
||
with a letter or underscore, and then has zero or more letters,
|
||
numbers, or underscores. For example:</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="n">name</span>
|
||
<span class="n">love_love_points</span>
|
||
<span class="n">trebuchet2_range</span>
|
||
</pre></div>
|
||
</div>
|
||
<p class="last">Variables beginning with _ are reserved for Ren'Py's use, and
|
||
shouldn't be used by creators.</p>
|
||
</dd>
|
||
<dt><em class="dfn">Field Access</em></dt>
|
||
<dd><p class="first">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:</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="n">config</span><span class="o">.</span><span class="n">screen_width</span>
|
||
</pre></div>
|
||
</div>
|
||
<p class="last">Consists of a variable (config) followed by a field access
|
||
(screen_width).</p>
|
||
</dd>
|
||
<dt><em class="dfn">Call</em></dt>
|
||
<dd><p class="first">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:</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="n">Character</span><span class="p">(</span><span class="s2">"Eileen"</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="n">adv</span><span class="p">,</span> <span class="na">color</span><span class="o">=</span><span class="s2">"#0f0"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>we call the Character function. It's given one positional
|
||
argument, the string "Eileen". It's given two keyword argument:
|
||
<code class="docutils literal notranslate"><span class="pre">type</span></code> with the value of the <code class="docutils literal notranslate"><span class="pre">adv</span></code> variable, and <code class="docutils literal notranslate"><span class="pre">color</span></code>
|
||
with a string value of "#0f0".</p>
|
||
<p class="last">Constructors are a type of function which returns a new object,
|
||
and are called the same way.</p>
|
||
</dd>
|
||
</dl>
|
||
<p>When reading this documentation, you might see a function signature
|
||
like:</p>
|
||
<dl class="function">
|
||
<dt id="Sample">
|
||
<code class="descname">Sample</code><span class="sig-paren">(</span><em>name</em>, <em>delay</em>, <em>position=(0</em>, <em>0)</em>, <em>**properties</em><span class="sig-paren">)</span><a class="headerlink" href="#Sample" title="Permalink to this definition"> link</a></dt>
|
||
<dd><p>A sample function that doesn't actually exist in Ren'Py, but
|
||
is used only in documentation.</p>
|
||
</dd></dl>
|
||
|
||
<p>This function:</p>
|
||
<ul class="simple">
|
||
<li>Has the name "Sample"</li>
|
||
<li>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.</li>
|
||
<li>Has one keyword argument, position, which has a default value
|
||
of (0, 0).</li>
|
||
</ul>
|
||
<p>Since the functions ends with **properties, it means that it can
|
||
take <a class="reference internal" href="style_properties.html"><span class="doc">style properties</span></a> as additional keyword
|
||
arguments. Other special entries are *args, which means that it takes
|
||
an arbitrary number of positional parameters, and **kwargs, which means
|
||
that the keyword arguments are described in the documentation.</p>
|
||
<p>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
|
||
<a class="reference external" href="http://docs.python.org/release/2.7/tutorial/index.html">python.org</a>.
|
||
While we don't think a deep knowledge of Python is necessary to work
|
||
with Ren'Py, the basics of Python statements and expressions is
|
||
often helpful.</p>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
|
||
</div>
|
||
</div>
|
||
<footer class="footer">
|
||
<div class="container">
|
||
<p class="pull-right">
|
||
<a href="#">Back to top</a>
|
||
|
||
</p>
|
||
<p>
|
||
© Copyright 2012-2022, Tom Rothamel.<br/>
|
||
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.6.<br/>
|
||
</p>
|
||
</div>
|
||
</footer>
|
||
</body>
|
||
</html> |