546 lines
38 KiB
HTML
546 lines
38 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>Python Statements — 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="Conditional Statements" href="conditional.html" />
|
|||
|
|
<link rel="prev" title="In-Game Menus" href="menus.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"><a class="reference internal" href="language_basics.html">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 current"><a class="current reference internal" href="#">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="#">Python Statements</a><ul>
|
|||
|
|
<li><a class="reference internal" href="#python-statement">Python</a></li>
|
|||
|
|
<li><a class="reference internal" href="#one-line-python-statement">One-line Python Statement</a></li>
|
|||
|
|
<li><a class="reference internal" href="#init-python-statement">Init Python Statement</a></li>
|
|||
|
|
<li><a class="reference internal" href="#define-statement">Define Statement</a></li>
|
|||
|
|
<li><a class="reference internal" href="#default-statement">Default Statement</a></li>
|
|||
|
|
<li><a class="reference internal" href="#init-offset-statement">Init Offset Statement</a></li>
|
|||
|
|
<li><a class="reference internal" href="#names-in-the-store">Names in the Store</a></li>
|
|||
|
|
<li><a class="reference internal" href="#other-named-stores">Other Named Stores</a></li>
|
|||
|
|
<li><a class="reference internal" href="#first-and-third-party-python-modules-and-packages">First and Third-Party Python Modules and Packages</a></li>
|
|||
|
|
</ul>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="col-md-9 content">
|
|||
|
|
|
|||
|
|
<div class="section" id="python-statements">
|
|||
|
|
<span id="python"></span><h1>Python Statements<a class="headerlink" href="#python-statements" title="Permalink to this headline"> link</a></h1>
|
|||
|
|
<p>Ren'Py is written in the Python programming language, and includes
|
|||
|
|
support for including Python inside Ren'Py scripts. Python
|
|||
|
|
support can be used for many things, from setting a flag to creating
|
|||
|
|
new displayables. This chapter covers ways in which Ren'Py scripts can
|
|||
|
|
directly invoke Python, through the various Python statements.</p>
|
|||
|
|
<p>Ren'Py 7 supports Python 2.7. Ren'Py 8 supports Python 3.9.</p>
|
|||
|
|
<div class="admonition note">
|
|||
|
|
<p class="first admonition-title">Note</p>
|
|||
|
|
<p>If you know Python, you'll be able to take advantage of that. However,
|
|||
|
|
not everything you know about Python will apply directly. For example.
|
|||
|
|
Python packages that don't ship with Ren'Py may not work inside Ren'Py.</p>
|
|||
|
|
<p>There are also some Python constructs that work, but may lead to problems
|
|||
|
|
in saving. Please read the <a class="reference internal" href="save_load_rollback.html"><span class="doc">save, load, and rollback</span></a> page
|
|||
|
|
for more details, especially the section on <a class="reference internal" href="save_load_rollback.html#cant-save"><span class="std std-ref">what can't be saved</span></a>.
|
|||
|
|
(You need to be careful with files, sockets, iterators, task, futures, and
|
|||
|
|
generators.)</p>
|
|||
|
|
<p class="last">Finally, while many statements have Python equivalents, those equivalents
|
|||
|
|
can be inferior. For example, Ren'Py can predict the <code class="docutils literal notranslate"><span class="pre">show</span></code> statement,
|
|||
|
|
and load images early, but it can't predict the <a class="reference internal" href="statement_equivalents.html#renpy.show" title="renpy.show"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.show()</span></code></a> function.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="python-statement">
|
|||
|
|
<span id="id1"></span><h2>Python<a class="headerlink" href="#python-statement" title="Permalink to this headline"> link</a></h2>
|
|||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">python</span></code> statement takes a block of Python, and runs the block
|
|||
|
|
when control reaches the statement. A basic Python statement can be
|
|||
|
|
very simple:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">python</span><span class="p">:</span>
|
|||
|
|
<span class="n">flag</span> <span class="o">=</span> <span class="kc">True</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>Python statements can get more complex, when necessary:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">python</span><span class="p">:</span>
|
|||
|
|
<span class="n">player_health</span> <span class="o">=</span> <span class="nb">max</span><span class="p">(</span><span class="n">player_health</span> <span class="o">-</span> <span class="n">damage</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span>
|
|||
|
|
<span class="k">if</span> <span class="n">enemy_vampire</span><span class="p">:</span>
|
|||
|
|
<span class="n">enemy_health</span> <span class="o">=</span> <span class="nb">min</span><span class="p">(</span><span class="n">enemy_health</span> <span class="o">+</span> <span class="n">damage</span><span class="p">,</span> <span class="n">enemy_max_health</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>There are two modifiers to the Python statement that change its
|
|||
|
|
behavior:</p>
|
|||
|
|
<dl class="docutils">
|
|||
|
|
<dt><code class="docutils literal notranslate"><span class="pre">hide</span></code></dt>
|
|||
|
|
<dd><p class="first">If given the hide modifier, the Python statement will run the
|
|||
|
|
block of Python in an anonymous scope. The scope will be lost when the
|
|||
|
|
Python block terminates.</p>
|
|||
|
|
<p class="last">This allows Python to use temporary variables that can't be
|
|||
|
|
saved – but it means that the store needs to be accessed as fields
|
|||
|
|
on the store object, rather than directly.</p>
|
|||
|
|
</dd>
|
|||
|
|
<dt><code class="docutils literal notranslate"><span class="pre">in</span></code></dt>
|
|||
|
|
<dd>The <code class="docutils literal notranslate"><span class="pre">in</span></code> modifier takes a name. Instead of executing in the
|
|||
|
|
default store, the Python will execute in the store with that
|
|||
|
|
name.</dd>
|
|||
|
|
</dl>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="one-line-python-statement">
|
|||
|
|
<h2>One-line Python Statement<a class="headerlink" href="#one-line-python-statement" title="Permalink to this headline"> link</a></h2>
|
|||
|
|
<p>A common case is to have a single line of Python that runs in the
|
|||
|
|
default store. For example, a Python one-liner can be used to
|
|||
|
|
initialize or update a flag. To make writing Python one-liners
|
|||
|
|
more convenient, there is the one-line Python statement.</p>
|
|||
|
|
<p>The one-line Python statement begins with the dollar-sign <code class="docutils literal notranslate"><span class="pre">$</span></code>
|
|||
|
|
character, and contains everything else on that line. Here
|
|||
|
|
are some example of Python one-liners:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="c1"># Set a flag.</span>
|
|||
|
|
<span class="k">$</span> <span class="n">flag</span> <span class="o">=</span> <span class="kc">True</span>
|
|||
|
|
|
|||
|
|
<span class="c1"># Initialize a variable.</span>
|
|||
|
|
<span class="k">$</span> <span class="n">romance_points</span> <span class="o">=</span> <span class="mi">0</span>
|
|||
|
|
|
|||
|
|
<span class="c1"># Increment a variable.</span>
|
|||
|
|
<span class="k">$</span> <span class="n">romance_points</span> <span class="o">+=</span> <span class="mi">1</span>
|
|||
|
|
|
|||
|
|
<span class="c1"># Call a function that exposes Ren'Py functionality.</span>
|
|||
|
|
<span class="k">$</span> <span class="n">renpy</span><span class="o">.</span><span class="n">movie_cutscene</span><span class="p">(</span><span class="s2">"opening.ogv"</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>Python one-liners always run in the default store.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="init-python-statement">
|
|||
|
|
<span id="id2"></span><h2>Init Python Statement<a class="headerlink" href="#init-python-statement" title="Permalink to this headline"> link</a></h2>
|
|||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">init</span> <span class="pre">python</span></code> statement runs Python at initialization time,
|
|||
|
|
before the game loads. Among other things, this can be used to define
|
|||
|
|
classes and functions, or to initialize styles, config variables, or
|
|||
|
|
persistent data.</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">init</span> <span class="k">python</span><span class="p">:</span>
|
|||
|
|
|
|||
|
|
<span class="k">def</span> <span class="nf">auto_voice_function</span><span class="p">(</span><span class="n">ident</span><span class="p">):</span>
|
|||
|
|
<span class="k">return</span> <span class="s2">"voice/"</span> <span class="o">+</span> <span class="n">ident</span> <span class="o">+</span> <span class="s2">".ogg"</span>
|
|||
|
|
|
|||
|
|
<span class="n">config</span><span class="o">.</span><span class="n">auto_voice</span> <span class="o">=</span> <span class="n">auto_voice_function</span>
|
|||
|
|
|
|||
|
|
<span class="k">if</span> <span class="n">persistent</span><span class="o">.</span><span class="n">endings</span> <span class="k">is</span> <span class="kc">None</span><span class="p">:</span>
|
|||
|
|
<span class="n">persistent</span><span class="o">.</span><span class="n">endings</span> <span class="o">=</span> <span class="nb">set</span><span class="p">()</span>
|
|||
|
|
|
|||
|
|
<span class="k">init</span> <span class="mi">1</span> <span class="k">python</span><span class="p">:</span>
|
|||
|
|
|
|||
|
|
<span class="c1"># The bad ending is always unlocked.</span>
|
|||
|
|
<span class="n">persistent</span><span class="o">.</span><span class="n">endings</span><span class="o">.</span><span class="k">add</span><span class="p">(</span><span class="s2">"bad_ending"</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>A priority number can be placed between <code class="docutils literal notranslate"><span class="pre">init</span></code> and <code class="docutils literal notranslate"><span class="pre">python</span></code>. When
|
|||
|
|
a priority is not given, 0 is used. Init statements are run in priority
|
|||
|
|
order, from lowest to highest. Init statements of the same priority are run in
|
|||
|
|
Unicode order by filepath, and then from top to bottom within a file.</p>
|
|||
|
|
<p>To avoid conflict with Ren'Py, creators should use priorities in the
|
|||
|
|
range -999 to 999. Priorities of less than 0 are generally used for
|
|||
|
|
libraries and to set up themes. Normal init statements should have a priority
|
|||
|
|
of 0 or higher.</p>
|
|||
|
|
<p>Init python statements also take the <code class="docutils literal notranslate"><span class="pre">hide</span></code> or <code class="docutils literal notranslate"><span class="pre">in</span></code> clauses.</p>
|
|||
|
|
<p>Variables that have their value set in an init python block are not
|
|||
|
|
saved, loaded, and do not participate in rollback. Therefore, these
|
|||
|
|
variables should not be changed after init is over.</p>
|
|||
|
|
<div class="admonition warning">
|
|||
|
|
<p class="first admonition-title">Warning</p>
|
|||
|
|
<p>Classes created within Ren'py and inheriting nothing or explicitly
|
|||
|
|
inheriting <code class="docutils literal notranslate"><span class="pre">object</span></code>, and subclasses of these classes, do not support
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">__slots__</span></code>. Trying to do so will misbehave with rollback in older
|
|||
|
|
versions of renpy, and will raise errors in newer versions.</p>
|
|||
|
|
<p class="last">In order to have slotted classes, creators should explicitly subclass
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">python_object</span></code>, which doesn't support rollback.</p>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="define-statement">
|
|||
|
|
<span id="id3"></span><h2>Define Statement<a class="headerlink" href="#define-statement" title="Permalink to this headline"> link</a></h2>
|
|||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">define</span></code> statement sets a single variable to a value at init time.
|
|||
|
|
For example:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="n">e</span> <span class="o">=</span> <span class="n">Character</span><span class="p">(</span><span class="s2">"Eileen"</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>is equivalent (except for some advantages, see below) to:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">init</span> <span class="k">python</span><span class="p">:</span>
|
|||
|
|
<span class="n">e</span> <span class="o">=</span> <span class="n">Character</span><span class="p">(</span><span class="s2">"Eileen"</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>The define statement can take an optional named store (see below), by
|
|||
|
|
prepending it to the variable name with a dot. The store is created
|
|||
|
|
if it doesn't already exist. For example:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="n">character</span><span class="o">.</span><span class="n">e</span> <span class="o">=</span> <span class="n">Character</span><span class="p">(</span><span class="s2">"Eileen"</span><span class="p">)</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>The define statement can take an optional index, making it possible
|
|||
|
|
to add entries to a dictionary:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="n">config</span><span class="o">.</span><span class="n">tag_layer</span><span class="p">[</span><span class="s2">"eileen"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"master"</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>In addition to <code class="docutils literal notranslate"><span class="pre">=</span></code>, define can take two more operators. The <code class="docutils literal notranslate"><span class="pre">+=</span></code>
|
|||
|
|
operator adds, and is generally used for list concatenaton. The <code class="docutils literal notranslate"><span class="pre">|=</span></code>
|
|||
|
|
or operator is generally used to concatenate sets. For example:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="n">config</span><span class="o">.</span><span class="n">keymap</span><span class="p">[</span><span class="s2">"dismiss"</span><span class="p">]</span> <span class="o">+=</span> <span class="p">[</span> <span class="s2">"K_KP_PLUS"</span> <span class="p">]</span>
|
|||
|
|
<span class="k">define</span> <span class="n">endings</span> <span class="o">|=</span> <span class="p">{</span> <span class="s2">"best_ending }</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>One advantage of using the define statement is that it records the
|
|||
|
|
filename and line number at which the assignment occurred, and
|
|||
|
|
makes that available to the navigation feature of the launcher.
|
|||
|
|
Another advantage is that <a class="reference internal" href="developer_tools.html#lint"><span class="std std-ref">Lint</span></a> will be able to check defined
|
|||
|
|
values, for example by detecting whether the same variable is defined
|
|||
|
|
twice, potentially with different values.</p>
|
|||
|
|
<p>Variables that are defined using the define statement are treated
|
|||
|
|
as constant, are not saved or loaded, and should not be changed. This
|
|||
|
|
constant-nature extends to objects reachable through these variables
|
|||
|
|
through field access and subscripting. (Ren'Py does not enforce this,
|
|||
|
|
but will produce undefined behavior when this is not the case.)</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="default-statement">
|
|||
|
|
<span id="id4"></span><h2>Default Statement<a class="headerlink" href="#default-statement" title="Permalink to this headline"> link</a></h2>
|
|||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">default</span></code> statement sets a single variable to a value if that variable
|
|||
|
|
is not defined when the game starts, or after a new game is loaded. For
|
|||
|
|
example:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">default</span> <span class="n">points</span> <span class="o">=</span> <span class="mi">0</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>When the variable <code class="docutils literal notranslate"><span class="pre">points</span></code> is not defined at game start, this statement is
|
|||
|
|
equivalent to:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">label</span> <span class="n">start</span><span class="p">:</span>
|
|||
|
|
<span class="k">$</span> <span class="n">points</span> <span class="o">=</span> <span class="mi">0</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>When the variable <code class="docutils literal notranslate"><span class="pre">points</span></code> is not defined at game load, it's equivalent to:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">label</span> <span class="n">after_load</span><span class="p">:</span>
|
|||
|
|
<span class="k">$</span> <span class="n">points</span> <span class="o">=</span> <span class="mi">0</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>The default statement can take an optional named store (see below), by
|
|||
|
|
prepending it to the variable name with a dot. The store is created
|
|||
|
|
if it doesn't already exist. For example:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">default</span> <span class="n">schedule</span><span class="o">.</span><span class="n">day</span> <span class="o">=</span> <span class="mi">0</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>As for the <code class="docutils literal notranslate"><span class="pre">define</span></code> statement, <a class="reference internal" href="developer_tools.html#lint"><span class="std std-ref">Lint</span></a> offers checks and optimizations
|
|||
|
|
related to the <code class="docutils literal notranslate"><span class="pre">default</span></code> statement.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="init-offset-statement">
|
|||
|
|
<span id="id5"></span><h2>Init Offset Statement<a class="headerlink" href="#init-offset-statement" title="Permalink to this headline"> link</a></h2>
|
|||
|
|
<p>The <code class="docutils literal notranslate"><span class="pre">init</span> <span class="pre">offset</span></code> statement sets a priority offset for all statements
|
|||
|
|
that run at init time (init, init python, define, default, screen,
|
|||
|
|
transform, style, and more). The offset applies to all following
|
|||
|
|
statements in the current block and child blocks, up to the next
|
|||
|
|
init priority statement. The statement:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">init</span> <span class="k">offset</span> <span class="o">=</span> <span class="mi">42</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>sets the priority offset to 42. In:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">init</span> <span class="k">offset</span> <span class="o">=</span> <span class="mi">2</span>
|
|||
|
|
<span class="k">define</span> <span class="n">foo</span> <span class="o">=</span> <span class="mi">2</span>
|
|||
|
|
|
|||
|
|
<span class="k">init</span> <span class="k">offset</span> <span class="o">=</span> <span class="mi">1</span>
|
|||
|
|
<span class="k">define</span> <span class="n">foo</span> <span class="o">=</span> <span class="mi">1</span>
|
|||
|
|
|
|||
|
|
<span class="k">init</span> <span class="k">offset</span> <span class="o">=</span> <span class="mi">0</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>The first define statement is run at priority 2, which means it runs
|
|||
|
|
after the second define statement, and hence <code class="docutils literal notranslate"><span class="pre">foo</span></code> winds up with
|
|||
|
|
a value of 2.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="names-in-the-store">
|
|||
|
|
<h2>Names in the Store<a class="headerlink" href="#names-in-the-store" title="Permalink to this headline"> link</a></h2>
|
|||
|
|
<p>The default place that Ren'Py stores Python variables is called the
|
|||
|
|
store. It's important to make sure that the names you use in the
|
|||
|
|
store do not conflict.</p>
|
|||
|
|
<p>The define statement assigns a value to a variable, even when it's
|
|||
|
|
used to define a character. This means that it's not possible to
|
|||
|
|
use the same name for a character and a flag.</p>
|
|||
|
|
<p>The following faulty script:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="n">e</span> <span class="o">=</span> <span class="n">Character</span><span class="p">(</span><span class="s2">"Eileen"</span><span class="p">)</span>
|
|||
|
|
|
|||
|
|
<span class="k">label</span> <span class="n">start</span><span class="p">:</span>
|
|||
|
|
|
|||
|
|
<span class="k">$</span> <span class="n">e</span> <span class="o">=</span> <span class="mi">0</span>
|
|||
|
|
|
|||
|
|
<span class="n">e</span> <span class="s2">"Hello, world."</span>
|
|||
|
|
|
|||
|
|
<span class="k">$</span> <span class="n">e</span> <span class="o">+=</span> <span class="mi">1</span>
|
|||
|
|
<span class="n">e</span> <span class="s2">"You scored a point!"</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>will not work, because the variable <code class="docutils literal notranslate"><span class="pre">e</span></code> is being used as both a
|
|||
|
|
character and a flag. Other things that are usually placed into
|
|||
|
|
the store are transitions and transforms.</p>
|
|||
|
|
<p>Names beginning with underscore <code class="docutils literal notranslate"><span class="pre">_</span></code> are reserved for Ren'Py's
|
|||
|
|
internal use. In addition, there is an <a class="reference internal" href="reserved.html"><span class="doc">Index of Reserved Names</span></a>.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="other-named-stores">
|
|||
|
|
<h2>Other Named Stores<a class="headerlink" href="#other-named-stores" title="Permalink to this headline"> link</a></h2>
|
|||
|
|
<p>Named stores provide a way of organizing Python functions and variables
|
|||
|
|
into modules. By placing Python in modules, you can minimize the chance of name
|
|||
|
|
conflicts.</p>
|
|||
|
|
<p>Named stores can be accessed by supplying the <code class="docutils literal notranslate"><span class="pre">in</span></code> clause to
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">python</span></code> or <code class="docutils literal notranslate"><span class="pre">init</span> <span class="pre">python</span></code>, all of which run Python in a named
|
|||
|
|
store. Each store corresponds to a Python module. The default store is
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">store</span></code>, while a named store is accessed as <code class="docutils literal notranslate"><span class="pre">store.name</span></code>. Names in
|
|||
|
|
the modules can be imported using the Python <code class="docutils literal notranslate"><span class="pre">from</span></code> statement.
|
|||
|
|
Named stores can be created using <code class="docutils literal notranslate"><span class="pre">init</span> <span class="pre">python</span> <span class="pre">in</span></code> blocks, or using
|
|||
|
|
default or define statements.</p>
|
|||
|
|
<p>For example:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">init</span> <span class="k">python</span> <span class="k">in</span> <span class="n">mystore</span><span class="p">:</span>
|
|||
|
|
|
|||
|
|
<span class="n">serial_number</span> <span class="o">=</span> <span class="mi">0</span>
|
|||
|
|
|
|||
|
|
<span class="k">def</span> <span class="nf">serial</span><span class="p">():</span>
|
|||
|
|
|
|||
|
|
<span class="k">global</span> <span class="n">serial_number</span>
|
|||
|
|
<span class="n">serial_number</span> <span class="o">+=</span> <span class="mi">1</span>
|
|||
|
|
<span class="k">return</span> <span class="n">serial_number</span>
|
|||
|
|
|
|||
|
|
<span class="k">default</span> <span class="n">character_stats</span><span class="o">.</span><span class="n">chloe_substore</span><span class="o">.</span><span class="n">friends</span> <span class="o">=</span> <span class="p">{</span><span class="s2">"Eileen"</span><span class="p">,}</span>
|
|||
|
|
|
|||
|
|
<span class="k">label</span> <span class="n">start</span><span class="p">:</span>
|
|||
|
|
<span class="k">$</span> <span class="n">serial</span> <span class="o">=</span> <span class="n">mystore</span><span class="o">.</span><span class="n">serial</span><span class="p">()</span>
|
|||
|
|
|
|||
|
|
<span class="k">if</span> <span class="s2">"Lucy"</span> <span class="k">in</span> <span class="n">character_stats</span><span class="o">.</span><span class="n">chloe_substore</span><span class="o">.</span><span class="n">friends</span><span class="p">:</span>
|
|||
|
|
<span class="n">chloe</span> <span class="s2">"Lucy is my friend !"</span>
|
|||
|
|
<span class="k">elif</span> <span class="n">character_stats</span><span class="o">.</span><span class="n">chloe_substore</span><span class="o">.</span><span class="n">friends</span><span class="p">:</span>
|
|||
|
|
<span class="n">chloe</span> <span class="s2">"I have friends, but Lucy is not one of them."</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>Named stores participate in save, load, and rollback in the same way
|
|||
|
|
that the default store does. Special namespaces such as <code class="docutils literal notranslate"><span class="pre">persistent</span></code>,
|
|||
|
|
<code class="docutils literal notranslate"><span class="pre">config</span></code>, <code class="docutils literal notranslate"><span class="pre">renpy</span></code>... do not and never have supported substore creation
|
|||
|
|
within them.</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="section" id="first-and-third-party-python-modules-and-packages">
|
|||
|
|
<span id="python-modules"></span><h2>First and Third-Party Python Modules and Packages<a class="headerlink" href="#first-and-third-party-python-modules-and-packages" title="Permalink to this headline"> link</a></h2>
|
|||
|
|
<p>Ren'Py can import pure-Python modules and packages. First-party modules
|
|||
|
|
and packages – ones written for the game – can be placed directly
|
|||
|
|
into the game directory. Third party packages can be placed into the
|
|||
|
|
game/python-packages directory.</p>
|
|||
|
|
<p>For example, to install the requests package, one can change into the
|
|||
|
|
game's base directory, and run the command:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">target</span> <span class="n">game</span><span class="o">/</span><span class="k">python</span><span class="o">-</span><span class="n">packages</span> <span class="n">requests</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<p>In either case, the module or package can be imported from an init python
|
|||
|
|
block:</p>
|
|||
|
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">init</span> <span class="k">python</span><span class="p">:</span>
|
|||
|
|
<span class="kn">import</span> <span class="nn">requests</span>
|
|||
|
|
</pre></div>
|
|||
|
|
</div>
|
|||
|
|
<div class="admonition warning">
|
|||
|
|
<p class="first admonition-title">Warning</p>
|
|||
|
|
<p class="last">Python defined in .rpy files is transformed to allow rollback
|
|||
|
|
to work. Python imported from .py files is not. As a result,
|
|||
|
|
objects created in Python will not work with rollback, and
|
|||
|
|
probably should not be changed after creation.</p>
|
|||
|
|
</div>
|
|||
|
|
</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>
|