503 lines
32 KiB
HTML
503 lines
32 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>Labels & Control Flow — 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="Dialogue and Narration" href="dialogue.html" />
|
||
|
<link rel="prev" title="Language Basics" href="language_basics.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 current"><a class="current reference internal" href="#">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="#">Labels & Control Flow</a><ul>
|
||
|
<li><a class="reference internal" href="#label-statement">Label Statement</a></li>
|
||
|
<li><a class="reference internal" href="#jump-statement">Jump Statement</a></li>
|
||
|
<li><a class="reference internal" href="#call-statement">Call Statement</a></li>
|
||
|
<li><a class="reference internal" href="#return-statement">Return Statement</a></li>
|
||
|
<li><a class="reference internal" href="#special-labels">Special Labels</a></li>
|
||
|
<li><a class="reference internal" href="#labels-control-flow-functions">Labels & Control Flow Functions</a></li>
|
||
|
</ul>
|
||
|
</li>
|
||
|
</ul>
|
||
|
|
||
|
</div>
|
||
|
</div>
|
||
|
<div class="col-md-9 content">
|
||
|
|
||
|
<div class="section" id="labels-control-flow">
|
||
|
<span id="id1"></span><h1>Labels & Control Flow<a class="headerlink" href="#labels-control-flow" title="Permalink to this headline"> link</a></h1>
|
||
|
<div class="section" id="label-statement">
|
||
|
<span id="id2"></span><h2>Label Statement<a class="headerlink" href="#label-statement" title="Permalink to this headline"> link</a></h2>
|
||
|
<p>Label statements allow the given name to be assigned to a program point. They
|
||
|
exist solely to be called or jumped to, either from Ren'Py script, Python
|
||
|
functions, or from screens.</p>
|
||
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">label</span> <span class="n">sample1</span><span class="p">:</span>
|
||
|
<span class="s2">"Here is 'sample1' label."</span>
|
||
|
|
||
|
<span class="k">label</span> <span class="n">sample2</span><span class="p">(</span><span class="n">a</span><span class="o">=</span><span class="s2">"default"</span><span class="p">):</span>
|
||
|
<span class="s2">"Here is 'sample2' label."</span>
|
||
|
<span class="s2">"a = [a]"</span>
|
||
|
</pre></div>
|
||
|
</div>
|
||
|
<p>A label statement may have a block associated with it. In that case, control
|
||
|
enters the block whenever the label statement is reached, and proceeds with the
|
||
|
statement after the label statement whenever the end of the block is reached.</p>
|
||
|
<p>There are two kinds of labels: <em>global</em> and <em>local</em> labels. Global labels live
|
||
|
in one global scope shared across all project files and thus should have unique
|
||
|
names per game. Local labels logically reside inside the scope of the global label
|
||
|
they are declared in. To declare a local label, prefix its name with a period <code class="docutils literal notranslate"><span class="pre">.</span></code>.
|
||
|
For example:</p>
|
||
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">label</span> <span class="n">global_label</span><span class="p">:</span>
|
||
|
<span class="s2">"Inside a global label.."</span>
|
||
|
<span class="k">label</span> <span class="o">.</span><span class="n">local_name</span><span class="p">:</span>
|
||
|
<span class="s2">"..resides a local one."</span>
|
||
|
<span class="k">jump</span> <span class="o">.</span><span class="n">local_name</span>
|
||
|
</pre></div>
|
||
|
</div>
|
||
|
<p>Local labels can be referenced directly inside the same global label they are
|
||
|
declared in or by their full name, consisting of global and local name parts:</p>
|
||
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">label</span> <span class="n">another_global</span><span class="p">:</span>
|
||
|
<span class="s2">"Now lets jump inside local label located somewhere else."</span>
|
||
|
<span class="k">jump</span> <span class="n">global_label</span><span class="o">.</span><span class="n">local_name</span>
|
||
|
</pre></div>
|
||
|
</div>
|
||
|
<p>The label statement may take an optional list of parameters. These parameters
|
||
|
are processed as described in <span class="target" id="index-0"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0570"><strong>PEP 570</strong></a>, with two exceptions:</p>
|
||
|
<ul class="simple">
|
||
|
<li>The values of default parameters are evaluated at call time.</li>
|
||
|
<li>The variables are dynamically, rather than lexically, scoped.</li>
|
||
|
</ul>
|
||
|
<p>When a variable is dynamically scoped, its value lasts until a return
|
||
|
statement following the label. It doesn't generally make sense to
|
||
|
have a label with parameters that is reached by a jump or a previous
|
||
|
statement. For an example of labels with parameters, see the
|
||
|
<a class="reference internal" href="#call-statement"><span class="std std-ref">call statement</span></a>.</p>
|
||
|
</div>
|
||
|
<div class="section" id="jump-statement">
|
||
|
<span id="id3"></span><h2>Jump Statement<a class="headerlink" href="#jump-statement" title="Permalink to this headline"> link</a></h2>
|
||
|
<p>The jump statement is used to transfer control to the given label.</p>
|
||
|
<p>If the <code class="docutils literal notranslate"><span class="pre">expression</span></code> keyword is present, the expression following it is
|
||
|
evaluated, and the string so computed is used as the label name of the
|
||
|
statement to jump to. If the <code class="docutils literal notranslate"><span class="pre">expression</span></code> keyword is not present, the label
|
||
|
name of the statement to jump to must be explicitly given.</p>
|
||
|
<p>Unlike call, jump does not push the next statement onto a stack. As a
|
||
|
result, there's no way to return to where you've jumped from.</p>
|
||
|
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">label</span> <span class="n">loop_start</span><span class="p">:</span>
|
||
|
|
||
|
<span class="n">e</span> <span class="s2">"Oh no! It looks like we're trapped in an infinite loop."</span>
|
||
|
|
||
|
<span class="k">jump</span> <span class="n">loop_start</span>
|
||
|
</pre></div>
|
||
|
</div>
|
||
|
</div>
|
||
|
<div class="section" id="call-statement">
|
||
|
<span id="id4"></span><h2>Call Statement<a class="headerlink" href="#call-statement" title="Permalink to this headline"> link</a></h2>
|
||
|
<p>The call statement is used to transfer control to the given label. It
|
||
|
also pushes the next statement onto the call stack, allowing the return statement
|
||
|
to return control to the statement following the call.</p>
|
||
|
<p>If the <code class="docutils literal notranslate"><span class="pre">expression</span></code> keyword is present, the expression following it is evaluated, and the
|
||
|
string so computed is used as the name of the label to call. If the
|
||
|
<code class="docutils literal notranslate"><span class="pre">expression</span></code> keyword is not present, the name of the statement to call must be
|
||
|
explicitly given.</p>
|
||
|
<p>If the optional <code class="docutils literal notranslate"><span class="pre">from</span></code> clause is present, it has the effect of including a label
|
||
|
statement with the given name as the statement immediately following the call
|
||
|
statement. An explicit label helps to ensure that saved games with return
|
||
|
stacks can return to the proper place when loaded on a changed script.</p>
|
||
|
<p>The call statement may take arguments, which are processed as described in <span class="target" id="index-1"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0448"><strong>PEP 448</strong></a>.</p>
|
||
|
<p>When using a call expression with an arguments list, the <code class="docutils literal notranslate"><span class="pre">pass</span></code> keyword must
|
||
|
be inserted between the expression and the arguments list. Otherwise, the
|
||
|
arguments list will be parsed as part of the expression, not as part of the
|
||
|
call.</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="n">e</span> <span class="s2">"First, we will call a subroutine."</span>
|
||
|
|
||
|
<span class="k">call</span> <span class="n">subroutine</span>
|
||
|
|
||
|
<span class="k">call</span> <span class="n">subroutine</span><span class="p">(</span><span class="mi">2</span><span class="p">)</span>
|
||
|
|
||
|
<span class="k">call</span> <span class="k">expression</span> <span class="s2">"sub"</span> <span class="o">+</span> <span class="s2">"routine"</span> <span class="k">pass</span> <span class="p">(</span><span class="n">count</span><span class="o">=</span><span class="mi">3</span><span class="p">)</span>
|
||
|
|
||
|
<span class="k">return</span>
|
||
|
|
||
|
<span class="c1"># ...</span>
|
||
|
|
||
|
<span class="k">label</span> <span class="n">subroutine</span><span class="p">(</span><span class="n">count</span><span class="o">=</span><span class="mi">1</span><span class="p">):</span>
|
||
|
|
||
|
<span class="n">e</span> <span class="s2">"I came here [count] time(s)."</span>
|
||
|
<span class="n">e</span> <span class="s2">"Next, we will return from the subroutine."</span>
|
||
|
|
||
|
<span class="k">return</span>
|
||
|
</pre></div>
|
||
|
</div>
|
||
|
<div class="admonition warning">
|
||
|
<p class="first admonition-title">Warning</p>
|
||
|
<p>Publishing a game without <code class="docutils literal notranslate"><span class="pre">from</span></code> clauses for each <code class="docutils literal notranslate"><span class="pre">call</span></code> statement
|
||
|
is dangerous, if you intend to publish updates of the game later on.
|
||
|
If no such clauses are added, and if you edit the file containing the
|
||
|
<code class="docutils literal notranslate"><span class="pre">call</span></code> instruction, there is a potential risk for saves made inside
|
||
|
the called label to become broken.</p>
|
||
|
<p class="last">Using the "Add from clauses to calls" option when building a game's
|
||
|
distribution can solve that issue.</p>
|
||
|
</div>
|
||
|
</div>
|
||
|
<div class="section" id="return-statement">
|
||
|
<span id="id5"></span><h2>Return Statement<a class="headerlink" href="#return-statement" title="Permalink to this headline"> link</a></h2>
|
||
|
<p>The <code class="docutils literal notranslate"><span class="pre">return</span></code> statement pops the top statement off of the call stack, and transfers
|
||
|
control to it. If the call stack is empty, the return statement restarts
|
||
|
Ren'Py, returning control to the main menu.</p>
|
||
|
<p>If the optional expression is given to return, it is evaluated, and it's result
|
||
|
is stored in the <code class="docutils literal notranslate"><span class="pre">_return</span></code> variable. This variable is dynamically scoped to each
|
||
|
context.</p>
|
||
|
</div>
|
||
|
<div class="section" id="special-labels">
|
||
|
<h2>Special Labels<a class="headerlink" href="#special-labels" title="Permalink to this headline"> link</a></h2>
|
||
|
<p>The following labels are used by Ren'Py:</p>
|
||
|
<dl class="docutils">
|
||
|
<dt><code class="docutils literal notranslate"><span class="pre">start</span></code></dt>
|
||
|
<dd>By default, Ren'Py jumps to this label when the game starts.</dd>
|
||
|
<dt><code class="docutils literal notranslate"><span class="pre">quit</span></code></dt>
|
||
|
<dd>If it exists, this label is called in a new context when the user
|
||
|
quits the game.</dd>
|
||
|
<dt><code class="docutils literal notranslate"><span class="pre">after_load</span></code></dt>
|
||
|
<dd>If it exists, this label is called when a game is loaded. It can be
|
||
|
use to fix data when the game is updated. If data is changed by this
|
||
|
label, <a class="reference internal" href="save_load_rollback.html#renpy.block_rollback" title="renpy.block_rollback"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.block_rollback()</span></code></a> should be called to prevent those
|
||
|
changes from being reverted inf the player rolls back past the load
|
||
|
point.</dd>
|
||
|
<dt><code class="docutils literal notranslate"><span class="pre">splashscreen</span></code></dt>
|
||
|
<dd>If it exists, this label is called when the game is first run, before
|
||
|
showing the main menu. Please see <a class="reference internal" href="splashscreen_presplash.html#adding-a-splashscreen"><span class="std std-ref">Adding a Splashscreen</span></a>.</dd>
|
||
|
<dt><code class="docutils literal notranslate"><span class="pre">before_main_menu</span></code></dt>
|
||
|
<dd>If it exists, this label is called before the main menu. It is used in
|
||
|
rare cases to set up the main menu, for example by starting a movie
|
||
|
playing in the background.</dd>
|
||
|
<dt><code class="docutils literal notranslate"><span class="pre">main_menu</span></code></dt>
|
||
|
<dd><p class="first">If it exists, this label is called instead of the main menu. If it returns,
|
||
|
Ren'Py will start the game at the <code class="docutils literal notranslate"><span class="pre">start</span></code> label. For example, the
|
||
|
following will immediately start the game without displaying the
|
||
|
main menu.</p>
|
||
|
<div class="last highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">label</span> <span class="n">main_menu</span><span class="p">:</span>
|
||
|
<span class="k">return</span>
|
||
|
</pre></div>
|
||
|
</div>
|
||
|
</dd>
|
||
|
<dt><code class="docutils literal notranslate"><span class="pre">after_warp</span></code></dt>
|
||
|
<dd>If it is existed, this label is called after a warp but before the warped-to
|
||
|
statement executes. Please see <a class="reference internal" href="developer_tools.html#warping-to-a-line"><span class="std std-ref">Warping to a line</span></a>.</dd>
|
||
|
<dt><code class="docutils literal notranslate"><span class="pre">hide_windows</span></code></dt>
|
||
|
<dd>If it exists, this label is called when the player hides the windows with
|
||
|
the right mouse button or the H key. If this returns true, the hide is
|
||
|
cancelled (it's assumed the hide has occurred). Otherwise, the hide
|
||
|
continues.</dd>
|
||
|
</dl>
|
||
|
</div>
|
||
|
<div class="section" id="labels-control-flow-functions">
|
||
|
<h2>Labels & Control Flow Functions<a class="headerlink" href="#labels-control-flow-functions" title="Permalink to this headline"> link</a></h2>
|
||
|
<dl class="function">
|
||
|
<dt id="renpy.call_in_new_context">
|
||
|
<code class="descclassname">renpy.</code><code class="descname">call_in_new_context</code><span class="sig-paren">(</span><em>label</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.call_in_new_context" title="Permalink to this definition"> link</a></dt>
|
||
|
<dd><p>This creates a new context, and then starts executing Ren'Py script
|
||
|
from the given label in that context. Rollback is disabled in the
|
||
|
new context, and saving/loading will occur in the top level
|
||
|
context.</p>
|
||
|
<p>Use this to begin a second interaction with the user while
|
||
|
inside an interaction.</p>
|
||
|
</dd></dl>
|
||
|
|
||
|
<dl class="function">
|
||
|
<dt id="renpy.get_all_labels">
|
||
|
<code class="descclassname">renpy.</code><code class="descname">get_all_labels</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#renpy.get_all_labels" title="Permalink to this definition"> link</a></dt>
|
||
|
<dd><p>Returns the set of all labels defined in the program, including labels
|
||
|
defined for internal use in the libraries.</p>
|
||
|
</dd></dl>
|
||
|
|
||
|
<dl class="function">
|
||
|
<dt id="renpy.get_return_stack">
|
||
|
<code class="descclassname">renpy.</code><code class="descname">get_return_stack</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#renpy.get_return_stack" title="Permalink to this definition"> link</a></dt>
|
||
|
<dd><p>Returns a list giving the current return stack. The return stack is a
|
||
|
list of statement names.</p>
|
||
|
<p>The statement names will be strings (for labels), or opaque tuples (for
|
||
|
non-label statements).</p>
|
||
|
</dd></dl>
|
||
|
|
||
|
<dl class="function">
|
||
|
<dt id="renpy.has_label">
|
||
|
<code class="descclassname">renpy.</code><code class="descname">has_label</code><span class="sig-paren">(</span><em>name</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.has_label" title="Permalink to this definition"> link</a></dt>
|
||
|
<dd><p>Returns true if <cite>name</cite> is a valid label the program, or false otherwise.</p>
|
||
|
<dl class="docutils">
|
||
|
<dt><cite>name</cite></dt>
|
||
|
<dd>Should be a string to check for the existence of a label. It can
|
||
|
also be an opaque tuple giving the name of a non-label statement.</dd>
|
||
|
</dl>
|
||
|
</dd></dl>
|
||
|
|
||
|
<dl class="function">
|
||
|
<dt id="renpy.invoke_in_new_context">
|
||
|
<code class="descclassname">renpy.</code><code class="descname">invoke_in_new_context</code><span class="sig-paren">(</span><em>callable</em>, <em>*args</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.invoke_in_new_context" title="Permalink to this definition"> link</a></dt>
|
||
|
<dd><p>This function creates a new context, and invokes the given Python
|
||
|
callable (function) in that context. When the function returns
|
||
|
or raises an exception, control returns to the the original context.
|
||
|
It's generally used to call a Python function that needs to display
|
||
|
information to the player (like a confirmation prompt) from inside
|
||
|
an event handler.</p>
|
||
|
<p>A context maintains the state of the display (including what screens
|
||
|
and images are being shown) and the audio system. Both are restored
|
||
|
when the context returns.</p>
|
||
|
<p>Additional arguments and keyword arguments are passed to the
|
||
|
callable.</p>
|
||
|
<p>A context created with this function cannot execute Ren'Py script.
|
||
|
Functions that would change the flow of Ren'Py script, like
|
||
|
<a class="reference internal" href="statement_equivalents.html#renpy.jump" title="renpy.jump"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.jump()</span></code></a>, are handled by the outer context. If you want
|
||
|
to call Ren'Py script rather than a Python function, use
|
||
|
<a class="reference internal" href="#renpy.call_in_new_context" title="renpy.call_in_new_context"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.call_in_new_context()</span></code></a> instead.</p>
|
||
|
</dd></dl>
|
||
|
|
||
|
<dl class="function">
|
||
|
<dt id="renpy.jump_out_of_context">
|
||
|
<code class="descclassname">renpy.</code><code class="descname">jump_out_of_context</code><span class="sig-paren">(</span><em>label</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.jump_out_of_context" title="Permalink to this definition"> link</a></dt>
|
||
|
<dd><p>Causes control to leave the current context, and then to be
|
||
|
transferred in the parent context to the given label.</p>
|
||
|
</dd></dl>
|
||
|
|
||
|
<dl class="function">
|
||
|
<dt id="renpy.mark_label_seen">
|
||
|
<code class="descclassname">renpy.</code><code class="descname">mark_label_seen</code><span class="sig-paren">(</span><em>label</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.mark_label_seen" title="Permalink to this definition"> link</a></dt>
|
||
|
<dd><p>Marks the named label as if it has been already executed on the current user's
|
||
|
system.</p>
|
||
|
</dd></dl>
|
||
|
|
||
|
<dl class="function">
|
||
|
<dt id="renpy.mark_label_unseen">
|
||
|
<code class="descclassname">renpy.</code><code class="descname">mark_label_unseen</code><span class="sig-paren">(</span><em>label</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.mark_label_unseen" title="Permalink to this definition"> link</a></dt>
|
||
|
<dd><p>Marks the named label as if it has not been executed on the current user's
|
||
|
system yet.</p>
|
||
|
</dd></dl>
|
||
|
|
||
|
<dl class="function">
|
||
|
<dt id="renpy.seen_label">
|
||
|
<code class="descclassname">renpy.</code><code class="descname">seen_label</code><span class="sig-paren">(</span><em>label</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.seen_label" title="Permalink to this definition"> link</a></dt>
|
||
|
<dd><p>Returns true if the named label has executed at least once on the current user's
|
||
|
system, and false otherwise. This can be used to unlock scene galleries, for
|
||
|
example.</p>
|
||
|
</dd></dl>
|
||
|
|
||
|
<dl class="function">
|
||
|
<dt id="renpy.set_return_stack">
|
||
|
<code class="descclassname">renpy.</code><code class="descname">set_return_stack</code><span class="sig-paren">(</span><em>stack</em><span class="sig-paren">)</span><a class="headerlink" href="#renpy.set_return_stack" title="Permalink to this definition"> link</a></dt>
|
||
|
<dd><p>Sets the current return stack. The return stack is a list of statement
|
||
|
names.</p>
|
||
|
<p>Statement names may be strings (for labels) or opaque tuples (for
|
||
|
non-label statements).</p>
|
||
|
</dd></dl>
|
||
|
|
||
|
</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>
|