994 lines
65 KiB
HTML
994 lines
65 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>Layered Images — 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="3D Stage" href="3dstage.html" />
|
||
<link rel="prev" title="Matrixcolor" href="matrixcolor.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>
|
||
<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"><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 class="current">
|
||
<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 current"><a class="current reference internal" href="#">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="#">Layered Images</a><ul>
|
||
<li><a class="reference internal" href="#defining-layered-images">Defining Layered Images</a></li>
|
||
<li><a class="reference internal" href="#using-an-layered-image">Using an Layered Image</a></li>
|
||
<li><a class="reference internal" href="#automatic-attributes">Automatic Attributes</a></li>
|
||
<li><a class="reference internal" href="#statement-reference">Statement Reference</a><ul>
|
||
<li><a class="reference internal" href="#layeredimage">Layeredimage</a></li>
|
||
<li><a class="reference internal" href="#attribute">Attribute</a></li>
|
||
<li><a class="reference internal" href="#group">Group</a></li>
|
||
<li><a class="reference internal" href="#always">Always</a></li>
|
||
<li><a class="reference internal" href="#if">If</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#poses">Poses</a></li>
|
||
<li><a class="reference internal" href="#advice">Advice</a></li>
|
||
<li><a class="reference internal" href="#python">Python</a></li>
|
||
<li><a class="reference internal" href="#proxying-layered-images">Proxying Layered Images</a></li>
|
||
<li><a class="reference internal" href="#selecting-attributes-to-display">Selecting attributes to display</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="col-md-9 content">
|
||
|
||
<div class="section" id="layered-images">
|
||
<h1>Layered Images<a class="headerlink" href="#layered-images" title="Permalink to this headline"> link</a></h1>
|
||
<p>When a sprite-set gets to a certain level of complexity, defining every
|
||
possible combination may become unwieldy. For example, a sprite with
|
||
4 outfits, 4 hairstyles, and 6 emotions already has 96 possible
|
||
combinations. Creating static images for each possible combination would
|
||
consume a lot of disk space and programmer time.</p>
|
||
<p>To address this use case, Ren'Py has a way of defining an image consisting
|
||
of multiple layers. (For the purpose of this, consider layers to be the layers
|
||
in a paint program like Photoshop or the GIMP, and not the layers used elsewhere
|
||
in Ren'Py.) Layers can be shown unconditionally, or can be selected
|
||
by attributes provided to the image or conditions that are evaluated at
|
||
runtime.</p>
|
||
<p>To make defining layered images easier, Ren'Py has the <code class="docutils literal notranslate"><span class="pre">layeredimage</span></code> statement,
|
||
which introduces a domain-specific language that lets you define a layered
|
||
image. There's also the <a class="reference internal" href="#LayeredImage" title="LayeredImage"><code class="xref py py-func docutils literal notranslate"><span class="pre">LayeredImage()</span></code></a> object, which isn't an image
|
||
but can be assigned to an image statement and used like one.</p>
|
||
<div class="section" id="defining-layered-images">
|
||
<h2>Defining Layered Images<a class="headerlink" href="#defining-layered-images" title="Permalink to this headline"> link</a></h2>
|
||
<p>The layered image domain-specific language consists of only a few statements,
|
||
one of which is also a script language statement to introduce the image,
|
||
followed by statements to introduce the layers and groups of layers.</p>
|
||
<p>To introduce the language, here's a layered image that uses the
|
||
available features, with things that could be implied instead
|
||
explicitly given.</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">layeredimage</span> <span class="n">augustina</span><span class="p">:</span>
|
||
|
||
<span class="k">always</span><span class="p">:</span>
|
||
<span class="s2">"augustina_base"</span>
|
||
|
||
<span class="k">group</span> <span class="n">outfit</span><span class="p">:</span>
|
||
|
||
<span class="k">attribute</span> <span class="n">dress</span><span class="p">:</span>
|
||
<span class="s2">"augustina_outfit_dress"</span>
|
||
|
||
<span class="k">attribute</span> <span class="n">jeans</span><span class="p">:</span>
|
||
<span class="s2">"augustina_outfit_jeans"</span>
|
||
|
||
<span class="k">group</span> <span class="n">eyes</span><span class="p">:</span>
|
||
|
||
<span class="k">attribute</span> <span class="nb">open</span> <span class="k">default</span><span class="p">:</span>
|
||
<span class="s2">"augustina_eyes_open"</span>
|
||
<span class="k">default</span> <span class="kc">True</span>
|
||
|
||
<span class="k">attribute</span> <span class="n">wink</span><span class="p">:</span>
|
||
<span class="s2">"augustina_eyes_wink"</span>
|
||
|
||
<span class="k">group</span> <span class="n">eyebrows</span><span class="p">:</span>
|
||
|
||
<span class="k">attribute</span> <span class="n">normal</span> <span class="k">default</span><span class="p">:</span>
|
||
<span class="s2">"augustina_eyebrows_normal"</span>
|
||
|
||
<span class="k">attribute</span> <span class="n">oneup</span><span class="p">:</span>
|
||
<span class="s2">"augustina_eyebrows_oneup"</span>
|
||
|
||
<span class="k">group</span> <span class="n">mouth</span><span class="p">:</span>
|
||
|
||
<span class="na">pos</span> <span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="mi">100</span><span class="p">)</span>
|
||
|
||
<span class="k">attribute</span> <span class="n">smile</span> <span class="k">default</span><span class="p">:</span>
|
||
<span class="s2">"augustina_mouth_smile"</span>
|
||
|
||
<span class="k">attribute</span> <span class="n">happy</span><span class="p">:</span>
|
||
<span class="s2">"augustina_mouth_happy"</span>
|
||
|
||
<span class="k">if</span> <span class="n">evil</span><span class="p">:</span>
|
||
<span class="s2">"augustina_glasses_evil"</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="s2">"augustina_glasses"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>That is a large amount of script, but it's very regular, and below
|
||
we'll show how to simplify it.</p>
|
||
<p>First off, the <code class="docutils literal notranslate"><span class="pre">layeredimage</span></code> statement introduces a layered image
|
||
with the name of the sprite. This statement is part of the Ren'Py
|
||
script language, and runs at init time.</p>
|
||
<p>The block of a layered image can contain always, group, and if
|
||
statements. A <code class="docutils literal notranslate"><span class="pre">group</span></code> statement can take attributes. The <code class="docutils literal notranslate"><span class="pre">always</span></code> and <code class="docutils literal notranslate"><span class="pre">if</span></code>
|
||
statements must be supplied displayables, while the attribute statement
|
||
can optionally be supplied one. All statements can be supplied properties.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">always</span></code> statement declares a layer that is always displayed, like the
|
||
background of a sprite.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">group</span></code> statement introduces a group of attributes, where only one of
|
||
the attributes can be displayed at a time. So this layered image can only
|
||
have one outfit, and one post for each of the eyes, eyebrows, and mouth.
|
||
Properties given to the group are passed on to the attributes, and a group
|
||
can automatically declare attributes.</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">attribute</span></code> statement introduces a layer that is displayed if an attribute
|
||
is supplied to the image. For example, "augustina_outfit_dress" is only
|
||
displayed if if the "dress" attribute is supplied. If given the <code class="docutils literal notranslate"><span class="pre">default</span></code>
|
||
keyword, the attribute is displayed if no conflicting attributes are
|
||
provided; in this example, "augustina_eyes_open" is displayed unless the
|
||
unless the "wink" attribute is given.</p>
|
||
<p>Finally, the <code class="docutils literal notranslate"><span class="pre">if</span></code> statement adds a layer that selects between displayables
|
||
using a Python statement. This is evaluated constantly, and the first
|
||
condition that evaluates to true is the one that's displayed.</p>
|
||
<p>Properties consist of a property name and a simple expression, and
|
||
can be given to each layer. Some properties change the functioning of
|
||
a statement. If one or more <a class="reference internal" href="atl.html#transform-properties"><span class="std std-ref">transform properties</span></a> are
|
||
given, a <a class="reference internal" href="trans_trans_python.html#Transform" title="Transform"><code class="xref py py-func docutils literal notranslate"><span class="pre">Transform()</span></code></a> is created that wraps the display. The at property
|
||
can be given a transform or list of transforms that also wrap the displayable.
|
||
For example, the pos property here creates a transform that moves the top-left
|
||
corner of each mouth image.</p>
|
||
<p>The resulting image is the size of the bounding box of all the layers, so
|
||
it probably makes sense to have one layer the full size of the image, which
|
||
no other layer goes outside of. The first layer is in the back of the image,
|
||
while the last is in front – in this example, the glasses will be on top of
|
||
the other layers. It's recommended to avoid properties that assume the size
|
||
of the containing image, like <a class="reference internal" href="style_properties.html#style-property-xcenter"><code class="xref std std-propref docutils literal notranslate"><span class="pre">xcenter</span></code></a> and <a class="reference internal" href="style_properties.html#style-property-xalign"><code class="xref std std-propref docutils literal notranslate"><span class="pre">xalign</span></code></a>, as
|
||
these properties do not work well the when the image size is not known.</p>
|
||
<p>Groups and attributes may appear more than once in a layered image, with
|
||
all of the layers with an attribute being displayed.</p>
|
||
<p>With the exception of the condition in an <code class="docutils literal notranslate"><span class="pre">if</span></code> statement, all Python
|
||
expressions are evaluated at init time.</p>
|
||
</div>
|
||
<div class="section" id="using-an-layered-image">
|
||
<h2>Using an Layered Image<a class="headerlink" href="#using-an-layered-image" title="Permalink to this headline"> link</a></h2>
|
||
<p>To use this (but not other) layered images, the evil variable must be given
|
||
a value, for example with:</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">default</span> <span class="n">evil</span> <span class="o">=</span> <span class="kc">True</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Then the layered image can be shown like any other image. Almost certainly,
|
||
one of the outfits should be given – while Ren'Py doesn't enforce this,
|
||
this image requires one:</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">show</span> <span class="n">augustina</span> <span class="n">jeans</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>While a sprite is being shown, additional attributes will be added to
|
||
those already showing provided they do not conflict. (This is the case
|
||
in all of Ren'Py when an image being shown does not match one that's
|
||
already defined, something that is never the case with a layered image.) So,</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">show</span> <span class="n">augustina</span> <span class="n">wink</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Will activate the layers associated with the wink attribute. We could stop
|
||
winking with:</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">show</span> <span class="n">augustina</span> <span class="nb">open</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>As the open eyes conflict with the winking eyes. Or we could simply remove
|
||
the wink attribute using:</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">show</span> <span class="n">augustina</span> <span class="o">-</span><span class="n">wink</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Which would display the layer with the open attribute, as it is the
|
||
default.</p>
|
||
<p>Layered images can also be used with the scene statement.</p>
|
||
</div>
|
||
<div class="section" id="automatic-attributes">
|
||
<h2>Automatic Attributes<a class="headerlink" href="#automatic-attributes" title="Permalink to this headline"> link</a></h2>
|
||
<p>There's a lot of repetition our first example, when it comes to the
|
||
attribute names and the displayables that define the attribute. To
|
||
save you from having to do a lot of redundant typing, Ren'Py can
|
||
automatically determine a displayable name from the image name, group name,
|
||
and attribute name. This is done by combining the names with underscores.</p>
|
||
<p>When doing this, you can also take advantage of another feature of
|
||
attributes – it's possible to add any properties to the first line and
|
||
omit the block entirely.</p>
|
||
<p>Here's our example of having done that:</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">layeredimage</span> <span class="n">augustina</span><span class="p">:</span>
|
||
|
||
<span class="k">always</span><span class="p">:</span>
|
||
<span class="s2">"augustina_base"</span>
|
||
|
||
<span class="k">group</span> <span class="n">outfit</span><span class="p">:</span>
|
||
<span class="k">attribute</span> <span class="n">dress</span>
|
||
<span class="k">attribute</span> <span class="n">jeans</span>
|
||
|
||
<span class="k">group</span> <span class="n">eyes</span><span class="p">:</span>
|
||
<span class="k">attribute</span> <span class="nb">open</span> <span class="k">default</span>
|
||
<span class="k">attribute</span> <span class="n">wink</span>
|
||
|
||
<span class="k">group</span> <span class="n">eyebrows</span><span class="p">:</span>
|
||
<span class="k">attribute</span> <span class="n">normal</span> <span class="k">default</span>
|
||
<span class="k">attribute</span> <span class="n">oneup</span>
|
||
|
||
<span class="k">group</span> <span class="n">mouth</span><span class="p">:</span>
|
||
<span class="na">pos</span> <span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="mi">100</span><span class="p">)</span>
|
||
<span class="k">attribute</span> <span class="n">smile</span> <span class="k">default</span>
|
||
<span class="k">attribute</span> <span class="n">happy</span>
|
||
|
||
<span class="k">if</span> <span class="n">evil</span><span class="p">:</span>
|
||
<span class="s2">"augustina_glasses_evil"</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="s2">"augustina_glasses"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This example is equivalent to the first one (as we gave the same names for
|
||
the displayables in the first example). For example, the dress attribute in
|
||
the outfit group uses "augustina_outfit_dress" for the displayable, a
|
||
displayable that references the image with that name.</p>
|
||
<p>It's possible to go even further than this, by automatically defining the
|
||
attributes in a group. This is done by giving a group the <cite>auto</cite> keyword,
|
||
which causes the group to search for defined
|
||
images that would match the pattern, then define the attribute if it does
|
||
not already exist.</p>
|
||
<p>As with <code class="docutils literal notranslate"><span class="pre">attribute</span></code>, properties can be placed on the first line of the
|
||
group and the block omitted. The displayable and properties of the
|
||
always statement can be put on the first line the same way.</p>
|
||
<p>Here's an example of the final form:</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">layeredimage</span> <span class="n">augustina</span><span class="p">:</span>
|
||
|
||
<span class="k">always</span> <span class="s2">"augustina_base"</span>
|
||
|
||
<span class="k">group</span> <span class="n">outfit</span> <span class="k">auto</span>
|
||
|
||
<span class="k">group</span> <span class="n">eyes</span> <span class="k">auto</span><span class="p">:</span>
|
||
<span class="k">attribute</span> <span class="nb">open</span> <span class="k">default</span>
|
||
|
||
<span class="k">group</span> <span class="n">eyebrows</span> <span class="k">auto</span><span class="p">:</span>
|
||
<span class="k">attribute</span> <span class="n">normal</span> <span class="k">default</span>
|
||
|
||
<span class="k">group</span> <span class="n">mouth</span> <span class="k">auto</span><span class="p">:</span>
|
||
<span class="na">pos</span> <span class="p">(</span><span class="mi">100</span><span class="p">,</span> <span class="mi">100</span><span class="p">)</span>
|
||
<span class="k">attribute</span> <span class="n">smile</span> <span class="k">default</span>
|
||
|
||
<span class="k">if</span> <span class="n">evil</span><span class="p">:</span>
|
||
<span class="s2">"augustina_glasses_evil"</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="s2">"augustina_glasses"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This is about as simply as we can define that image, without changing
|
||
what we define. The savings with auto-definition increases as we have
|
||
more attributes per group. We could also save lines if we didn't need
|
||
default attributes. In that case, all of the groups could be written on
|
||
single lines.</p>
|
||
<p>There's no way to omit the displayables from the <code class="docutils literal notranslate"><span class="pre">always</span></code> or <code class="docutils literal notranslate"><span class="pre">if</span></code> statements,
|
||
so this is as short as it gets – but with a few more images with proper
|
||
names, it's possible to use this to define thousands or even millions
|
||
of combinations of layers.</p>
|
||
</div>
|
||
<div class="section" id="statement-reference">
|
||
<h2>Statement Reference<a class="headerlink" href="#statement-reference" title="Permalink to this headline"> link</a></h2>
|
||
<p>Note that with the exception of the conditions in the <code class="docutils literal notranslate"><span class="pre">if</span></code> statement, all expressions are
|
||
evaluated at init time, when the layered image is first defined.</p>
|
||
<div class="section" id="layeredimage">
|
||
<span id="layeredimage-statement"></span><h3>Layeredimage<a class="headerlink" href="#layeredimage" title="Permalink to this headline"> link</a></h3>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">layeredimage</span></code> statement is a statement in the Ren'Py script language
|
||
that introduces a layered image. It starts with an image name, and takes
|
||
a block that can contain attribute, group, and if statements.</p>
|
||
<p>Layeredimage takes the following properties:</p>
|
||
<dl class="docutils">
|
||
<dt><cite>image_format</cite></dt>
|
||
<dd>When a given image is a string, and this is supplied, the image name
|
||
is interpolated into <cite>image_format</cite> to make an image file. For example,
|
||
"sprites/eileen/{image}.png" will look for the image in a subdirectory
|
||
of sprites. (This is not used by auto groups, which look for images and
|
||
not image files.)</dd>
|
||
<dt><cite>format_function</cite></dt>
|
||
<dd>A function that is used instead of <cite>layeredimage.format_function</cite> to format
|
||
the image information into a displayable.</dd>
|
||
<dt><a class="reference internal" href="atl.html#transform-properties"><span class="std std-ref">transform properties</span></a></dt>
|
||
<dd>If present, these are used to construct a <a class="reference internal" href="trans_trans_python.html#Transform" title="Transform"><code class="xref py py-func docutils literal notranslate"><span class="pre">Transform()</span></code></a> that is applied
|
||
to the displayable.</dd>
|
||
<dt><cite>at</cite></dt>
|
||
<dd>A transform or list of transforms that are applied to the layered image.</dd>
|
||
<dt><cite>offer_screen</cite></dt>
|
||
<dd><p class="first">If this is True, the layeredimage will place its children, and size its
|
||
children with variable size, like it was given an area matching the whole
|
||
screen of the game. If it is False, the said behaviors will be done while
|
||
taking into account the available area, which for example will be smaller
|
||
in an hbox containing other elements, and the display of the layeredimage
|
||
will not be consistent every time it is shown.</p>
|
||
<p class="last">If None, the default, falls back to <a class="reference internal" href="config.html#var-config.layeredimage_offer_screen"><code class="xref std std-var docutils literal notranslate"><span class="pre">config.layeredimage_offer_screen</span></code></a>,
|
||
which defaults to True.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="attribute">
|
||
<h3>Attribute<a class="headerlink" href="#attribute" title="Permalink to this headline"> link</a></h3>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">attribute</span></code> statement adds a layer that is displayed when the given
|
||
attribute is used to display the image. The same attribute can be used with
|
||
multiple layers, with all layers corresponding to the attribute being shown
|
||
(the <cite>if_all</cite>, <cite>if_any</cite>, and <cite>if_not</cite> properties can change this).</p>
|
||
<p>An attribute takes an attribute name. It can also take two keywords.
|
||
The <code class="docutils literal notranslate"><span class="pre">default</span></code> keyword indicates that the attribute should be present
|
||
by default if no attribute in its group conflicts. The <code class="docutils literal notranslate"><span class="pre">null</span></code> keyword
|
||
prevents Ren'Py from automatically searching for a displayable corresponding
|
||
to this attribute, which is useful to have an attribute that is intended solely
|
||
for use with <cite>if_all</cite>, <cite>if_any</cite>, or <cite>if_not</cite>.</p>
|
||
<p>If the displayable is not present, it will be computed from the name of the
|
||
layer, group, group variant, and attribute, by replacing all spaces with
|
||
underscores and using underscores to combine everything together. So
|
||
if we have an image named "augustina", the group "eyes" and the attribute "closed",
|
||
the image "augustina_eyes_closed" will be used. (The layered image's
|
||
format function is used to do this, defaulting to <a class="reference internal" href="#layeredimage.format_function" title="layeredimage.format_function"><code class="xref py py-func docutils literal notranslate"><span class="pre">layeredimage.format_function()</span></code></a>.)</p>
|
||
<p>If an attribute is not inside a group, it's placed in a group with the
|
||
same name, but that group is not used to compute the displayable name.
|
||
(So it would look for "image_attribute", not "image_attribute_attribute").</p>
|
||
<p>The attribute statement takes the following properties:</p>
|
||
<dl class="docutils">
|
||
<dt><cite>if_all</cite></dt>
|
||
<dd>A string or list of strings giving the names of attributes. If this is
|
||
present, this layer is only displayed if all of the named attributes
|
||
are present.</dd>
|
||
<dt><cite>if_any</cite></dt>
|
||
<dd>A string or list of strings giving the names of attributes. If this is
|
||
present, this layer is only displayed if any of the named attributes
|
||
are present.</dd>
|
||
<dt><cite>if_not</cite></dt>
|
||
<dd>A string or list of strings giving the names of attributes. If this is
|
||
present, this layer is only displayed if none of the named attributes are
|
||
present.</dd>
|
||
<dt><a class="reference internal" href="atl.html#transform-properties"><span class="std std-ref">transform properties</span></a></dt>
|
||
<dd>If present, these are used to construct a transform that is applied
|
||
to the layer.</dd>
|
||
<dt><cite>at</cite></dt>
|
||
<dd>A transform or list of transforms that are applied to the layer.</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="group">
|
||
<h3>Group<a class="headerlink" href="#group" title="Permalink to this headline"> link</a></h3>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">group</span></code> statement groups together alternative layers. When an attribute is
|
||
inside a group, and unless the group is <code class="docutils literal notranslate"><span class="pre">multiple</span></code>, it is an error to include any
|
||
of the other attributes in that group. (But it's fine for several attributes
|
||
to have same name, even within the same group.)</p>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">group</span></code> statement takes a name. The name isn't used for very much, but is
|
||
used to generate the default names of attributes inside the group. That is not the
|
||
case for <code class="docutils literal notranslate"><span class="pre">multiple</span></code> groups for which the name doesn't have any use or impact.</p>
|
||
<p>The name may be followed by the <code class="docutils literal notranslate"><span class="pre">auto</span></code> keyword. If it's present, after any
|
||
attributes in the group have been declared, Ren'Py will scan its list of images
|
||
for those that match the group's pattern (see below). Any images that are found
|
||
that do not correspond to declared attributes are then added to the group as if
|
||
declared with the attribute statement.</p>
|
||
<p>This can be followed by the <code class="docutils literal notranslate"><span class="pre">multiple</span></code> keyword. If present, more than one
|
||
member of the group can be selected at the same time. This is useful to have
|
||
a group auto-define multiple attributes that are not exclusive, or to apply the
|
||
same properties to a set of attributes at once.
|
||
This conflicts with the <code class="docutils literal notranslate"><span class="pre">default</span></code> keyword being given to one of the attributes.</p>
|
||
<p>Properties can then be declared on the first line of the group, and it can
|
||
take a block that contains properties and attributes.</p>
|
||
<p>There are two properties that are specific to groups.</p>
|
||
<dl class="docutils">
|
||
<dt><cite>variant</cite></dt>
|
||
<dd>If given, this should be a string. If present, it adds an element that becomes
|
||
part of automatically-generated image names, and of the pattern used to search
|
||
for images when automatically defining attributes in <code class="docutils literal notranslate"><span class="pre">auto</span></code> groups.</dd>
|
||
<dt><cite>prefix</cite></dt>
|
||
<dd>If given, this is a prefix that is concatenated using an underscore with
|
||
the manually or automatically defined attribute names. So if prefix is
|
||
"leftarm", and the attribute name "hip" is encountered, the attribute
|
||
"leftarm_hip" is defined instead.</dd>
|
||
</dl>
|
||
<p>The group statement also takes the same properties <code class="docutils literal notranslate"><span class="pre">attribute</span></code> does. Properties
|
||
supplied to the group are passed to the attributes inside the group, unless
|
||
overridden by the same property of the attribute itself.</p>
|
||
<p>Several <code class="docutils literal notranslate"><span class="pre">group</span></code> blocks with the same name being defined in the same layeredimage
|
||
are considered to be different parts of a single group. For example:</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">layeredimage</span> <span class="n">eileen</span> <span class="n">sitting</span><span class="p">:</span>
|
||
<span class="k">attribute</span> <span class="n">base</span> <span class="k">default</span>
|
||
<span class="k">group</span> <span class="n">arms</span> <span class="na">variant</span> <span class="s2">"behind"</span><span class="p">:</span>
|
||
<span class="k">attribute</span> <span class="n">on_hips</span>
|
||
<span class="k">attribute</span> <span class="n">on_knees</span>
|
||
<span class="k">attribute</span> <span class="n">mixed</span>
|
||
<span class="k">attribute</span> <span class="n">table</span> <span class="k">default</span>
|
||
<span class="k">group</span> <span class="n">arms</span> <span class="na">variant</span> <span class="s2">"infront"</span><span class="p">:</span>
|
||
<span class="k">attribute</span> <span class="n">on_table</span> <span class="k">default</span>
|
||
<span class="k">attribute</span> <span class="n">holding_margarita</span>
|
||
<span class="k">attribute</span> <span class="n">mixed</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In our example, the <code class="docutils literal notranslate"><span class="pre">eileen_sitting_arms_behind_mixed.png</span></code> will contain her left
|
||
arm behind the table, and <code class="docutils literal notranslate"><span class="pre">eileen_sitting_arms_infront_mixed.png</span></code> will contain
|
||
her right arm on the table. When calling <code class="docutils literal notranslate"><span class="pre">show</span> <span class="pre">eileen</span> <span class="pre">sitting</span> <span class="pre">mixed</span></code>, the two
|
||
images will be shown at the same time, respectively behind and in front of the table.</p>
|
||
<p><strong>Pattern.</strong> The image pattern used consists of:</p>
|
||
<ul class="simple">
|
||
<li>The name of the image, with spaces replaced with underscores.</li>
|
||
<li>The name of the group, if the group is not <code class="docutils literal notranslate"><span class="pre">multiple</span></code>.</li>
|
||
<li>The name of the variant, if there is one.</li>
|
||
<li>The name of the attribute.</li>
|
||
</ul>
|
||
<p>all combined with underscores. For example, if we have a layered image with
|
||
the name "augustina work", and the group "eyes", this will match images
|
||
that match the pattern augustina_work_eyes_<cite>attribute</cite>. With a <cite>variant</cite>
|
||
of <cite>blue</cite>, it would match the pattern augustina_work_eyes_blue_<cite>attribute</cite>.</p>
|
||
</div>
|
||
<div class="section" id="always">
|
||
<h3>Always<a class="headerlink" href="#always" title="Permalink to this headline"> link</a></h3>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">always</span></code> statement declares a layer that is always shown. It
|
||
must be supplied a displayable, and can take properties also. Both can
|
||
be placed on the same line or inside a block.</p>
|
||
<p>The always statement takes the following properties:</p>
|
||
<dl class="docutils">
|
||
<dt><cite>if_all</cite></dt>
|
||
<dd>A string or list of strings giving the names of attributes. If this is
|
||
present, this layer is only displayed if all of the named attributes
|
||
are present.</dd>
|
||
<dt><cite>if_any</cite></dt>
|
||
<dd>A string or list of strings giving the names of attributes. If this is
|
||
present, this layer is only displayed if any of the named attributes
|
||
are present.</dd>
|
||
<dt><cite>if_not</cite></dt>
|
||
<dd>A string or list of strings giving the names of attributes. If this is
|
||
present, this layer is only displayed if none of the named attributes are
|
||
present.</dd>
|
||
<dt><a class="reference internal" href="atl.html#transform-properties"><span class="std std-ref">transform properties</span></a></dt>
|
||
<dd>If present, these are used to construct a transform that is applied
|
||
to the layer.</dd>
|
||
<dt><cite>at</cite></dt>
|
||
<dd>A transform or list of transforms that are applied to the layer.</dd>
|
||
</dl>
|
||
</div>
|
||
<div class="section" id="if">
|
||
<h3>If<a class="headerlink" href="#if" title="Permalink to this headline"> link</a></h3>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">if</span></code> statement (or more fully the if-elif-else statement) allows you
|
||
to supply one or more conditions that are evaluated at runtime. Each
|
||
condition is associated with a layer, with the first true condition
|
||
being the one that is shown. If no condition is true, the <code class="docutils literal notranslate"><span class="pre">else</span></code> layer
|
||
is shown if present.</p>
|
||
<p>A more complete example of an <code class="docutils literal notranslate"><span class="pre">if</span></code> statement might look like:</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="n">glasses</span> <span class="o">==</span> <span class="s2">"evil"</span><span class="p">:</span>
|
||
<span class="s2">"augustina_glasses_evil"</span>
|
||
<span class="k">elif</span> <span class="n">glasses</span> <span class="o">==</span> <span class="s2">"normal"</span><span class="p">:</span>
|
||
<span class="s2">"augustina_glasses"</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<span class="s2">"augustina_nose_mark"</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Each layer must have a displayable given. It can also be given these properties:</p>
|
||
<dl class="docutils">
|
||
<dt><cite>if_all</cite></dt>
|
||
<dd>A string or list of strings giving the names of attributes. If this is
|
||
present, this condition is only considered if all of the named attributes
|
||
are present.</dd>
|
||
<dt><cite>if_any</cite></dt>
|
||
<dd>A string or list of strings giving the names of attributes. If this is
|
||
present, this condition is only considered if any of the named attributes
|
||
are present.</dd>
|
||
<dt><cite>if_not</cite></dt>
|
||
<dd>A string or list of strings giving the names of attributes. If this is
|
||
present, this condition is only considered if none of the named attributes are
|
||
present.</dd>
|
||
<dt><a class="reference internal" href="atl.html#transform-properties"><span class="std std-ref">transform properties</span></a></dt>
|
||
<dd>If present, these are used to construct a transform that is applied
|
||
to the layer.</dd>
|
||
<dt><cite>at</cite></dt>
|
||
<dd>A transform or list of transforms that are applied to the layer.</dd>
|
||
</dl>
|
||
<p>The <code class="docutils literal notranslate"><span class="pre">if</span></code> statement is transformed to a <a class="reference internal" href="displayables.html#ConditionSwitch" title="ConditionSwitch"><code class="xref py py-func docutils literal notranslate"><span class="pre">ConditionSwitch()</span></code></a> when the
|
||
<code class="docutils literal notranslate"><span class="pre">layeredimage</span></code> statement runs.</p>
|
||
<p>When <code class="docutils literal notranslate"><span class="pre">predict_all</span></code> is not true, changing the condition of the if statement
|
||
should be avoided while the layered image is shown or about to be shown,
|
||
as it would lead to an unpredicted image load. It's intended for use for
|
||
character customization options that change rarely.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="poses">
|
||
<h2>Poses<a class="headerlink" href="#poses" title="Permalink to this headline"> link</a></h2>
|
||
<p>It's possible to have a character that has sprites in multiple poses,
|
||
where everything – or at least everything of interest – is different.
|
||
For example, if a character has standing and sitting poses, all the image
|
||
parts will be in different places.</p>
|
||
<p>In that case, it makes sense to define multiple layered images for the same
|
||
image tag. The <code class="docutils literal notranslate"><span class="pre">layeredimage</span></code> statement makes this possible by allowing
|
||
you to include attributes as part of the image name. So we can have:</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">layeredimage</span> <span class="n">augustina</span> <span class="n">sitting</span><span class="p">:</span>
|
||
<span class="o">...</span>
|
||
|
||
<span class="k">layeredimage</span> <span class="n">augustina</span> <span class="n">standing</span><span class="p">:</span>
|
||
<span class="o">...</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This is especially useful when using a layered image to compose a side
|
||
image, where the side images of different characters will have nothing
|
||
to do with each other.</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">layeredimage</span> <span class="k">side</span> <span class="n">eileen</span><span class="p">:</span>
|
||
<span class="o">...</span>
|
||
|
||
<span class="k">layeredimage</span> <span class="k">side</span> <span class="n">lucy</span><span class="p">:</span>
|
||
<span class="o">...</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="advice">
|
||
<h2>Advice<a class="headerlink" href="#advice" title="Permalink to this headline"> link</a></h2>
|
||
<p><strong>Use underscores in image names.</strong>
|
||
By default, Ren'Py's layered images use underscores to separate sections
|
||
of image names. It might be tempting to use images with spaces between
|
||
sections, but that could lead to problems later on.</p>
|
||
<p>Ren'Py has a rule that if you show an image with the exact name as one
|
||
that's being shown, it's shown instead. This can bypass the layered image
|
||
you defined and show the layer directly, which can lead to weird problems
|
||
like a pair of eyes floating in space.</p>
|
||
<p>By having each layer have a different tag from the main image, this is no
|
||
longer a problem.</p>
|
||
<p><strong>Cropping layers isn't necessary.</strong>
|
||
Ren'Py optimizes images by cropping them to the bounding box of the
|
||
non-transparent pixels before loading them into RAM. As a result, assuming
|
||
the images are being predicted properly, it generally won't improve
|
||
performance or image size much to crop the images yourself.</p>
|
||
<p><strong>Layered images shouldn't use data that changes at runtime.</strong>
|
||
With the exception of the condition inside an if statement, all of the
|
||
expressions in a layered images are run at init time. The layered image
|
||
will not pick up changes in variables that occur after the game starts.
|
||
(However, expressions in ATL transforms will be run each time the image
|
||
is show, as with other ATL transforms.)</p>
|
||
</div>
|
||
<div class="section" id="python">
|
||
<h2>Python<a class="headerlink" href="#python" title="Permalink to this headline"> link</a></h2>
|
||
<p>Of course, the <code class="docutils literal notranslate"><span class="pre">layeredimage</span></code> statements have a Python equivalents. The
|
||
group statement does not – the group is supplied to <code class="docutils literal notranslate"><span class="pre">attribute</span></code>, and the
|
||
auto functionality can be implemented using <a class="reference internal" href="displaying_images.html#renpy.list_images" title="renpy.list_images"><code class="xref py py-func docutils literal notranslate"><span class="pre">renpy.list_images()</span></code></a>.</p>
|
||
<dl class="function">
|
||
<dt id="Attribute">
|
||
<code class="descname">Attribute</code><span class="sig-paren">(</span><em>group</em>, <em>attribute</em>, <em>image=None</em>, <em>default=False</em>, <em>group_args={}</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#Attribute" title="Permalink to this definition"> link</a></dt>
|
||
<dd><p>This is used to represent a layer of an LayeredImage that is
|
||
controlled by an attribute. A single attribute can control
|
||
multiple layers, in which case all layers corresponding to
|
||
that attribute will be displayed.</p>
|
||
<dl class="docutils">
|
||
<dt><cite>group</cite></dt>
|
||
<dd>A string giving the group the attribute is part of. This
|
||
may be None, in which case a group with the same name as
|
||
the attribute is created.</dd>
|
||
<dt><cite>attribute</cite></dt>
|
||
<dd>A string giving the name of the attribute.</dd>
|
||
<dt><cite>image</cite></dt>
|
||
<dd>If not None, this should be a displayable that is displayed when
|
||
this attribute is shown.</dd>
|
||
<dt><cite>default</cite></dt>
|
||
<dd>If True, and no other attribute for the group is selected,
|
||
this attribute is.</dd>
|
||
</dl>
|
||
<p>The following keyword arguments are also known:</p>
|
||
<dl class="docutils">
|
||
<dt><cite>at</cite></dt>
|
||
<dd>A transform or list of transforms that are applied to the
|
||
image.</dd>
|
||
<dt><cite>if_all</cite></dt>
|
||
<dd>An attribute or list of attributes. The displayable is only shown
|
||
if all of these are showing.</dd>
|
||
<dt><cite>if_any</cite></dt>
|
||
<dd>An attribute or list of attributes. if not empty, the displayable is only shown
|
||
if any of these are showing.</dd>
|
||
<dt><cite>if_not</cite></dt>
|
||
<dd>An attribute or list of attributes. The displayable is only shown
|
||
if none of these are showing.</dd>
|
||
</dl>
|
||
<p>Other keyword arguments are interpreted as transform properties. If
|
||
any are present, a transform is created that wraps the image. (For
|
||
example, pos=(100, 200) can be used to offset the image by 100 pixels
|
||
horizontally and 200 vertically.)</p>
|
||
<p>If the <cite>image</cite> parameter is omitted or None, and the LayeredImage
|
||
has been given the <cite>image_format</cite> parameter, the image_format is used
|
||
to generate an image filename.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="Condition">
|
||
<code class="descname">Condition</code><span class="sig-paren">(</span><em>condition</em>, <em>image</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#Condition" title="Permalink to this definition"> link</a></dt>
|
||
<dd><p>This is used to represent a layer of an LayeredImage that
|
||
is controlled by a condition. When the condition is true,
|
||
the layer is displayed. Otherwise, nothing is displayed.</p>
|
||
<dl class="docutils">
|
||
<dt><cite>condition</cite></dt>
|
||
<dd>This should be a string giving a Python condition that determines
|
||
if the layer is displayed.</dd>
|
||
<dt><cite>image</cite></dt>
|
||
<dd>If not None, this should be a displayable that is displayed when
|
||
the condition is true.</dd>
|
||
<dt><cite>if_all</cite></dt>
|
||
<dd>An attribute or list of attributes. The condition is only evaluated
|
||
if all of these are showing.</dd>
|
||
<dt><cite>if_any</cite></dt>
|
||
<dd>An attribute or list of attributes. If not empty, the condition is only evaluated
|
||
if any of these are showing.</dd>
|
||
<dt><cite>if_not</cite></dt>
|
||
<dd>An attribute or list of attributes. The condition is only evaluated
|
||
if none of these are showing.</dd>
|
||
<dt><cite>at</cite></dt>
|
||
<dd>A transform or list of transforms that are applied to the
|
||
image.</dd>
|
||
</dl>
|
||
<p>Other keyword arguments are interpreted as transform properties. If
|
||
any are present, a transform is created that wraps the image. (For
|
||
example, pos=(100, 200) can be used to offset the image by 100 pixels
|
||
horizontally and 200 vertically.)</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="LayeredImage">
|
||
<code class="descname">LayeredImage</code><span class="sig-paren">(</span><em>attributes</em>, <em>at=[]</em>, <em>name=None</em>, <em>image_format=None</em>, <em>format_function=None</em>, <em>attribute_function=None</em>, <em>offer_screen=None</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#LayeredImage" title="Permalink to this definition"> link</a></dt>
|
||
<dd><p>This is an image-like object that, when shown with the proper set of
|
||
attributes, shows a displayable created by compositing together the
|
||
displayables associated with those attribute.</p>
|
||
<dl class="docutils">
|
||
<dt><cite>attributes</cite></dt>
|
||
<dd>This must be a list of Attribute objects. Each Attribute object
|
||
reflects a displayable that may or may not be displayed as part
|
||
of the image. The items in this list are in back-to-front order,
|
||
with the first item further from the viewer and the last
|
||
closest.</dd>
|
||
<dt><cite>at</cite></dt>
|
||
<dd>A transform or list of transforms that are applied to the displayable
|
||
after it is parameterized.</dd>
|
||
<dt><cite>name</cite></dt>
|
||
<dd>The name of the layeredimage. This is used as part of the names
|
||
of image components.</dd>
|
||
<dt><cite>image_format</cite></dt>
|
||
<dd>When a given image is a string, and this is supplied, the image name
|
||
is interpolated into <cite>image_format</cite> to make an image file. For example,
|
||
"sprites/eileen/{image}.png" will look for the image in a subdirectory
|
||
of sprites. (This is not used by auto groups, which look for images and
|
||
not image files.)</dd>
|
||
<dt><cite>format_function</cite></dt>
|
||
<dd>A function that is used instead of <cite>layeredimage.format_function</cite> to format
|
||
the image information into a displayable.</dd>
|
||
<dt><cite>attribute_function</cite></dt>
|
||
<dd>If not None, a function that's called with a set of attributes supplied to
|
||
the image, and returns the set of attributes used to select layers. This is
|
||
called when determining the layers to display, after the attribute themselves
|
||
have been chosen. It can be used to express complex dependencies between attributes
|
||
or select attributes at random.</dd>
|
||
<dt><cite>offer_screen</cite></dt>
|
||
<dd>Sets whether or not the available area is taken into account as for how children
|
||
are placed and how they are sized (when they have variable size). If False, the
|
||
available area is considered, and if True it is not. If None, defaults to
|
||
<a class="reference internal" href="config.html#var-config.layeredimage_offer_screen"><code class="xref std std-var docutils literal notranslate"><span class="pre">config.layeredimage_offer_screen</span></code></a>.</dd>
|
||
</dl>
|
||
<p>Additional keyword arguments may contain transform properties. If
|
||
any are present, a transform is created that wraps the result image.
|
||
Remaining keyword arguments are passed to a Fixed that is created to hold
|
||
the layer. Unless explicitly overridden, xfit and yfit are set to true on
|
||
the Fixed, which means it will shrink to the smallest size that fits all
|
||
of the layer images it is showing.</p>
|
||
<p>A LayeredImage is not a displayable, and can't be used in all the
|
||
places a displayable can be used. This is because it requires an image
|
||
name (generally including image attributes) to be provided. As such,
|
||
it should either be displayed through a scene or show statement, or by
|
||
an image name string used as a displayable.</p>
|
||
</dd></dl>
|
||
|
||
<p><a class="reference internal" href="#layeredimage.format_function" title="layeredimage.format_function"><code class="xref py py-func docutils literal notranslate"><span class="pre">layeredimage.format_function()</span></code></a> is a function that is used to format attributes
|
||
and displayables into image files. It's supplied so you can see how it's
|
||
documented, and the arguments it takes if you want to supply your own
|
||
<cite>format_function</cite> to replace it.</p>
|
||
<dl class="function">
|
||
<dt id="layeredimage.format_function">
|
||
<code class="descclassname">layeredimage.</code><code class="descname">format_function</code><span class="sig-paren">(</span><em>what</em>, <em>name</em>, <em>group</em>, <em>variant</em>, <em>attribute</em>, <em>image</em>, <em>image_format</em>, <em>**kwargs</em><span class="sig-paren">)</span><a class="headerlink" href="#layeredimage.format_function" title="Permalink to this definition"> link</a></dt>
|
||
<dd><p>This is called to format the information about an attribute
|
||
or condition into a displayable. This can be replaced by a
|
||
creator, but the new function should ignore unknown kwargs.</p>
|
||
<dl class="docutils">
|
||
<dt><cite>what</cite></dt>
|
||
<dd>A string giving a description of the thing being formatted,
|
||
which is used to create better error messages.</dd>
|
||
<dt><cite>name</cite></dt>
|
||
<dd>The name of the layeredimage.</dd>
|
||
<dt><cite>group</cite></dt>
|
||
<dd>The group of an attribute, None if not supplied or if it's
|
||
part of a condition.</dd>
|
||
<dt><cite>variant</cite></dt>
|
||
<dd>The variant argument to the group, or None if it is not
|
||
supplied.</dd>
|
||
<dt><cite>attribute</cite></dt>
|
||
<dd>The attribute itself.</dd>
|
||
<dt><cite>image</cite></dt>
|
||
<dd>Either a displayable or string.</dd>
|
||
<dt><cite>image_format</cite></dt>
|
||
<dd>The image_format argument of the LayeredImage.</dd>
|
||
</dl>
|
||
<p>If <cite>image</cite> is None, then <cite>name</cite>, <cite>group</cite> (if not None), <cite>variant</cite> (if not None),
|
||
and <cite>attribute</cite> are combined with underscores to create <cite>image</cite>, which
|
||
will then be a string.</p>
|
||
<p>If <cite>images</cite> is a string, and <cite>image_format</cite> is not None, <cite>image</cite> is formatted
|
||
into the string to get the final displayable.</p>
|
||
<p>So if <cite>name</cite> is "eileen", <cite>group</cite> is "expression", and
|
||
<cite>attribute</cite> is "happy", <cite>image</cite> would be set to "eileen_expression_happy".
|
||
If <cite>image_format</cite> is "images/{image}.png",
|
||
the final image Ren'Py finds is "images/eileen_expression_happy.png".
|
||
But note that it would have found the same image without the format
|
||
argument.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="proxying-layered-images">
|
||
<h2>Proxying Layered Images<a class="headerlink" href="#proxying-layered-images" title="Permalink to this headline"> link</a></h2>
|
||
<p>Sometimes, it's necessary to proxy a layered image, to use the same
|
||
layered image in multiple places. One reason for this would be to have
|
||
the same sprite at multiple sizes, while another would be to use it as
|
||
a side image.</p>
|
||
<p>The <a class="reference internal" href="#LayeredImageProxy" title="LayeredImageProxy"><code class="xref py py-func docutils literal notranslate"><span class="pre">LayeredImageProxy()</span></code></a> object does this, taking one layered image and
|
||
duplicating it somewhere else.</p>
|
||
<p>For example:</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">image</span> <span class="n">dupe</span> <span class="o">=</span> <span class="n">LayeredImageProxy</span><span class="p">(</span><span class="s2">"augustina"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>creates a duplicate of the image that can be displayed independently. This
|
||
also takes a transform argument that makes it useful to position a side
|
||
image, like this:</p>
|
||
<div class="highlight-renpy notranslate"><div class="highlight"><pre><span></span><span class="k">image</span> <span class="k">side</span> <span class="n">augustina</span> <span class="o">=</span> <span class="n">LayeredImageProxy</span><span class="p">(</span><span class="s2">"augustina"</span><span class="p">,</span> <span class="n">Transform</span><span class="p">(</span><span class="na">crop</span><span class="o">=</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">362</span><span class="p">,</span> <span class="mi">362</span><span class="p">),</span> <span class="na">xoffset</span><span class="o">=-</span><span class="mi">80</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<dl class="function">
|
||
<dt id="LayeredImageProxy">
|
||
<code class="descname">LayeredImageProxy</code><span class="sig-paren">(</span><em>name</em>, <em>transform=None</em><span class="sig-paren">)</span><a class="headerlink" href="#LayeredImageProxy" title="Permalink to this definition"> link</a></dt>
|
||
<dd><p>This is an image-like object that proxies attributes passed to it to
|
||
another layered image.</p>
|
||
<dl class="docutils">
|
||
<dt><cite>name</cite></dt>
|
||
<dd>A string giving the name of the layered image to proxy to.</dd>
|
||
<dt><cite>transform</cite></dt>
|
||
<dd>If given, a transform or list of transforms that are applied to the
|
||
image after it has been proxied.</dd>
|
||
</dl>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="selecting-attributes-to-display">
|
||
<h2>Selecting attributes to display<a class="headerlink" href="#selecting-attributes-to-display" title="Permalink to this headline"> link</a></h2>
|
||
<p>Several factors influence what gets displayed following a given <code class="docutils literal notranslate"><span class="pre">show</span></code> instruction.
|
||
To provide more clarity as to what happens in which order, this section showcases
|
||
the life of a set of attributes, from the show instruction to the on-screen display.</p>
|
||
<ul class="simple">
|
||
<li>The <code class="docutils literal notranslate"><span class="pre">show</span></code> statement provides the initial set of attributes, following the
|
||
image tag.</li>
|
||
<li>If a <a class="reference internal" href="config.html#var-config.adjust_attributes"><code class="xref std std-var docutils literal notranslate"><span class="pre">config.adjust_attributes</span></code></a> function exists to match
|
||
the image tag, it is called, and returns a potentially different set of
|
||
attributes. If so, it replaces the former set, which is forgotten.</li>
|
||
<li>If a <a class="reference internal" href="config.html#var-config.default_attribute_callbacks"><code class="xref std std-var docutils literal notranslate"><span class="pre">config.default_attribute_callbacks</span></code></a> function exists and if its trigger
|
||
conditions are met, it is called and potentially adds attributes to the set.</li>
|
||
<li>The two previous stages are not specific to layeredimages, because it is only
|
||
after this stage that renpy determines which image or layeredimage
|
||
will be called to display. For that reason, the given set of attributes must
|
||
lead to one, and only one, defined image (or layeredimage, Live2D...), using
|
||
the behavior described in the <a class="reference internal" href="displaying_images.html#show-statement"><span class="std std-ref">show statement section</span></a>.</li>
|
||
<li>Then, the provided attributes are combined with the attributes defined in the
|
||
layeredimage, discarding some previously shown attributes and conserving others.
|
||
This is also the point where unrecognized attributes are detected and related
|
||
errors are raised. If no such error is raised, the new attributes, along with
|
||
those which were not discarded, will be recognized by renpy as the set of
|
||
attributes associated with that image tag. This computing takes some of the
|
||
incompatibility constraints into account, but not all. For instance
|
||
incompatibilities due to attributes being in the same non-multiple group will
|
||
trigger at this point in time, but the if_any/if_all/if_not clauses will not.
|
||
That's why an attribute called but negated by such a clause will be considered
|
||
active by renpy, and will for example become visible without having to be called
|
||
again if at some point the condition of the if_x clause is no longer fulfilled.</li>
|
||
<li>If an attribute_function has been provided to the layeredimage, it is called
|
||
with the set of remaining attributes. It returns a potentially different set of
|
||
attributes.</li>
|
||
<li>This set is once again confronted with the incompatibility constraints of the
|
||
layeredimage, this time in full. That is the final stage, and remaining attributes
|
||
are called into display.</li>
|
||
</ul>
|
||
</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> |