/usr/share/doc/renpy/html/dialogue.html is in renpy-doc 6.15.7-1ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 | <!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Dialogue and Narration — Ren'Py Documentation</title>
<link rel="stylesheet" href="_static/screen.css" type="text/css" media="screen, projection"/>
<link rel="stylesheet" href="_static/renpydoc.css" type="text/css" media="print" />
<!--[if lt IE 8]>
<link rel="stylesheet" href="_static/renpydoc.css" type="text/css" media="screen, projection"/>
<![endif]-->
<link rel="stylesheet" href="_static/renpydoc.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '',
VERSION: '6.15.6',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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>
<link rel="top" title="Ren'Py Documentation" href="index.html" />
<link rel="next" title="Displaying Images" href="displaying_images.html" />
<link rel="prev" title="Language Basics" href="language_basics.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="displaying_images.html" title="Displaying Images"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="language_basics.html" title="Language Basics"
accesskey="P">previous</a> |</li>
<li> <img src="_static/logo.png" width=19 height=21 align=center>
<li> <a href="http://www.renpy.org/">Ren'Py Home</a> |
<li><a href="index.html">Ren'Py Documentation</a></li>
</ul>
</div>
<div class="container">
<div class="span4">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Dialogue and Narration</a><ul>
<li><a class="reference internal" href="#say-statement">Say Statement</a></li>
<li><a class="reference internal" href="#defining-character-objects">Defining Character Objects</a></li>
<li><a class="reference internal" href="#say-with-image-attributes">Say with Image Attributes</a></li>
<li><a class="reference internal" href="#example-characters">Example Characters</a></li>
<li><a class="reference internal" href="#special-characters">Special Characters</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="language_basics.html"
title="previous chapter">Language Basics</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="displaying_images.html"
title="next chapter">Displaying Images</a></p>
<h4>Search</h4>
<div id="cse-search-form" style="width: 100%;"></div>
<div class="copydata">
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
<br>
</div>
</div>
</div>
</div>
<div class="document span20 last">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="dialogue-and-narration">
<h1>Dialogue and Narration<a class="headerlink" href="#dialogue-and-narration" title="Permalink to this headline">¶</a></h1>
<p>Text is fundamental to visual novels, and generally quite important to
storytelling-based games. This text may consist of dialogue labeled
with the character that is saying it, and narration, which does not
have a speaker. (For convenience, we will lump both dialogue and
narration together as dialogue, except where the differences are
important.) It's also important that the user be able to customize the
look of dialogue to suit their game.</p>
<p>In Ren'Py, most dialogue is written using say statements. The look of
dialogue may be customized on a per-character basis by using Character
objects.</p>
<div class="section" id="say-statement">
<span id="id1"></span><h2>Say Statement<a class="headerlink" href="#say-statement" title="Permalink to this headline">¶</a></h2>
<p>The say statement is used for dialogue and narration. Since it's
almost always the most frequently used statement in Ren'Py scripts,
the say statement has a syntax that minimizes the overhead in
writing it. Some example say statements are:</p>
<div class="highlight-renpy"><div class="highlight"><pre>
<span class="s">"This is narration."</span>
<span class="s">"Eileen"</span> <span class="s">"This is dialogue, with an explicit character name."</span>
<span class="n">e</span> <span class="s">"This is dialogue, using a character object instead."</span>
</pre></div>
</div>
<p>The first form of the say statement consists of a string by
itself. This form is used for narration, with the narration being the
contents of the string.</p>
<p>The second form consists of two strings. The first string is the name
of the character who is speaking, and the second is the dialogue being
spoken.</p>
<p>The final form is consists of a simple expression followed by a
string. The simple expression should evaluate to either a string
giving a character name, or a Character object. In the latter case,
the character object is used to control how the dialogue is shown.</p>
<p>Although the precise details of what a say statement does is
controlled by the character object used, the usual effect of a say
statement is to display dialogue on the screen until the user clicks
to dismiss it, then to remove that dialogue on the screen.</p>
<p>Certain characters have special meaning to Ren'Py, and so can't be
used in dialogue strings. The <tt class="docutils literal"><span class="pre">{</span></tt> character begins a text tag, and
the <tt class="docutils literal"><span class="pre">[</span></tt> character begins a substitution. To use them in dialogue,
double them. It may also be necessary to precede a quote with a
backslash to prevent it from closing the string. For example:</p>
<div class="highlight-renpy"><div class="highlight"><pre>
<span class="s">"I walked past a sign saying, </span><span class="se">\"</span><span class="s">Let's give it 100%!</span><span class="se">\"</span><span class="s">"</span>
</pre></div>
</div>
</div>
<div class="section" id="defining-character-objects">
<h2>Defining Character Objects<a class="headerlink" href="#defining-character-objects" title="Permalink to this headline">¶</a></h2>
<p>By creating a Character object and using it in a say statement, you
can customize the look (and to some extent, the behavior) of
dialogue. Characters are created by using the define statement to
assign a Character to a variable. For example:</p>
<div class="highlight-renpy"><div class="highlight"><pre><span class="k">define</span> <span class="n">e</span> <span class="o">=</span> <span class="n">Character</span><span class="p">(</span><span class="s">"Eileen"</span><span class="p">,</span>
<span class="n">who_color</span><span class="o">=</span><span class="s">"#c8ffc8"</span><span class="p">)</span>
</pre></div>
</div>
<p>Once this is done, the character can be used in a say statement:</p>
<div class="highlight-renpy"><div class="highlight"><pre>
<span class="n">e</span> <span class="s">"Hello, world."</span>
</pre></div>
</div>
<p>Character is a python function, that takes a large number of keyword
arguments. These keyword arguments control the behavior of the
character.</p>
<dl class="function">
<dt id="Character">
<tt class="descname">Character</tt><big>(</big><em>name</em>, <em>kind=adv</em>, <em>**args</em><big>)</big><a class="headerlink" href="#Character" title="Permalink to this definition">¶</a></dt>
<dd><p>Creates and returns a Character object, which controls the look
and feel of dialogue and narration.</p>
<dl class="docutils">
<dt><cite>name</cite></dt>
<dd>If a string, the name of the character for dialogue. When
<cite>name</cite> is <tt class="docutils literal"><span class="pre">None</span></tt>, display of the name is omitted, as for
narration.</dd>
<dt><cite>kind</cite></dt>
<dd>The Character to base this Character off of. When used, the
default value of any argument not supplied to this Character
is the value of that argument supplied to <cite>kind</cite>. This can
be used to define a template character, and then copy that
character with changes.</dd>
</dl>
<p><strong>Linked Image</strong>
An image tag may be associated with a Character. This allows a
say statement involving this character to display an image with
the tag, and also allows Ren'Py to automatically select a side
image to show when this character speaks.</p>
<dl class="docutils">
<dt><cite>image</cite></dt>
<dd>A string giving the image tag that is linked with this
character.</dd>
</dl>
<p><strong>Voice Tag</strong>
If a voice tag is assign to a Character, the voice files that are
associated with it, can be muted or played in the preference
screen.</p>
<dl class="docutils">
<dt><cite>voice_tag</cite></dt>
<dd>A String that enables the voice file assosiated with the
Character to be muted or played in the 'voice' channel.</dd>
</dl>
<p><strong>Prefixes and Suffixes.</strong>
These allow a prefix and suffix to be applied to the name of the
character, and to the text being shown. This can be used, for
example, to add quotes before and after each line of dialogue.</p>
<dl class="docutils">
<dt><cite>what_prefix</cite></dt>
<dd>A string that is prepended to the dialogue being spoken before
it is shown.</dd>
<dt><cite>what_suffix</cite></dt>
<dd>A string that is appended to the dialogue being spoken before
it is shown.</dd>
<dt><cite>who_prefix</cite></dt>
<dd>A string that is prepended to the name of the character before
it is shown.</dd>
<dt><cite>who_suffix</cite></dt>
<dd>A string that is appended to the name of the character before
it is shown.</dd>
</dl>
<p><strong>Changing Name Display.</strong>
These options help to control the display of the name.</p>
<dl class="docutils">
<dt><cite>dynamic</cite></dt>
<dd>If true, then <cite>name</cite> should be a string containing a python
expression. That string will be evaluated before each line
of dialogue, and the result used as the name of the character.</dd>
</dl>
<p><strong>Controlling Interactions.</strong>
These options control if the dialogue is displayed, if an
interaction occurs, and the mode that is entered upon display.</p>
<dl class="docutils">
<dt><cite>condition</cite></dt>
<dd>If given, this should be a string containing a python
expression. If the expression is false, the dialogue
does not occur, as if the say statement did not happen.</dd>
<dt><cite>interact</cite></dt>
<dd>If true, the default, an interaction occurs whenever the
dialogue is shown. If false, an interaction will not occur,
and additional elements can be added to the screen.</dd>
<dt><cite>mode</cite></dt>
<dd>A string giving the mode to enter when this character
speaks. See the section on <a class="reference internal" href="modes.html#modes"><em>modes</em></a> for more details.</dd>
<dt><cite>callback</cite></dt>
<dd>A function that is called when events occur while the
character is speaking. See the section on
<em class="xref std std-ref">character callbacks</em> fore more information.</dd>
</dl>
<p><strong>Click-to-continue.</strong>
A click-to-continue indicator is displayed once all the text has
finished displaying, to prompt the user to advance.</p>
<dl class="docutils">
<dt><cite>ctc</cite></dt>
<dd>A Displayable to use as the click-to-continue indicator, unless
a more specific indicator is used.</dd>
<dt><cite>ctc_pause</cite></dt>
<dd>A Displayable to use a the click-to-continue indicator when the
display of text is paused by the {p} or {w} text tags.</dd>
<dt><cite>ctc_timedpause</cite></dt>
<dd>A Displayable to use a the click-to-continue indicator when the
display of text is paused by the {p=} or {w=} text tags. When
None, this takes its default from ctc_pause, use <tt class="docutils literal"><span class="pre">Null()</span></tt>
when you want a ctc_pause but no ctc_timedpause.</dd>
<dt><cite>ctc_position</cite></dt>
<dd>Controls the location of the click-to-continue indicator. If
<tt class="docutils literal"><span class="pre">"nestled"</span></tt>, the indicator is displayed as part of the text
being shown, immediately after the last character. If <tt class="docutils literal"><span class="pre">"fixed"</span></tt>,
the indicator is added to the screen, and its position is
controlled by the position style properties.</dd>
</dl>
<p><strong>Screens.</strong>
The display of dialogue uses a <a class="reference internal" href="screens.html#screens"><em>screen</em></a>. These arguments
allow you to select that screen, and to provide arguments to it.</p>
<dl class="docutils">
<dt><cite>screen</cite></dt>
<dd>The name of the screen that is used to display the dialogue.</dd>
</dl>
<p>Keyword arguments beginning with <tt class="docutils literal"><span class="pre">show_</span></tt> have the prefix
stripped off, and are passed to the screen as arguments. For
example, the value of <tt class="docutils literal"><span class="pre">show_side_image</span></tt> will become the
value of the <tt class="docutils literal"><span class="pre">side_image</span></tt> variable in the screen.</p>
<p>Some useful <tt class="docutils literal"><span class="pre">show_</span></tt> variables implemented by the default screens are:</p>
<dl class="docutils">
<dt><cite>show_side_image</cite></dt>
<dd>When given a Displayable, shows that displayable when the
dialogue is shown. The position of that displayable is
controlled by its position properties. This is often used
to show an image of the speaking character to the side
of the dialogue.</dd>
<dt><cite>show_two_window</cite></dt>
<dd>If true, restructures the layout so that the name of the
character is placed in one window, and the dialogue text in a
second window.</dd>
</dl>
<p><strong>Styling Text and Windows.</strong>
Keyword arguments beginning with <tt class="docutils literal"><span class="pre">who_</span></tt>, <tt class="docutils literal"><span class="pre">what_</span></tt>, and
<cite>window_`</cite> have their prefix stripped, and are used to <a class="reference internal" href="style.html#styles"><em>style</em></a> the character name, the spoken text, and the window
containing both, respectively.</p>
<p>For example, if a character is given the keyword argument
<tt class="docutils literal"><span class="pre">who_color="#c8ffc8"</span></tt>, the color of the character's name is
changed, in this case to green. <tt class="docutils literal"><span class="pre">window_background="frame.png"</span></tt>
sets the background of the window containing this character's
dialogue.</p>
<p>The style applied to the character name, spoken text, and window
can also be set this way, using the <cite>who_style</cite>, <cite>what_style</cite>, and
<cite>window_style</cite> arguments, respectively.</p>
</dd></dl>
</div>
<div class="section" id="say-with-image-attributes">
<h2>Say with Image Attributes<a class="headerlink" href="#say-with-image-attributes" title="Permalink to this headline">¶</a></h2>
<p>When a character is defined with an associated image tag, say
statement involving that character may have image attributes
placed between the character name and the second string.</p>
<p>In this form, if an image with the given tag is showing, Ren'Py will
issue a show command involving the character tag and the
attributes. If the image is not shown, Ren'Py will store the
attributes for use by side images, but will not show an image.</p>
<p>For example, the code:</p>
<div class="highlight-renpy"><div class="highlight"><pre><span class="k">define</span> <span class="n">e</span> <span class="o">=</span> <span class="n">Character</span><span class="p">(</span><span class="s">"Eileen"</span><span class="p">,</span> <span class="k">image</span><span class="o">=</span><span class="s">"eileen"</span><span class="p">)</span>
<span class="k">label</span> <span class="n">start</span><span class="p">:</span>
<span class="k">show</span> <span class="n">eileen</span> <span class="n">mad</span>
<span class="n">e</span> <span class="s">"I'm a little upset at you."</span>
<span class="n">e</span> <span class="n">happy</span> <span class="s">"But it's just a passing thing."</span>
</pre></div>
</div>
<p>is equivalent to:</p>
<div class="highlight-renpy"><div class="highlight"><pre><span class="k">define</span> <span class="n">e</span> <span class="o">=</span> <span class="n">Character</span><span class="p">(</span><span class="s">"Eileen"</span><span class="p">)</span>
<span class="k">label</span> <span class="n">start</span><span class="p">:</span>
<span class="k">show</span> <span class="n">eileen</span> <span class="n">mad</span>
<span class="n">e</span> <span class="s">"I'm a little upset at you."</span>
<span class="k">show</span> <span class="n">eileen</span> <span class="n">happy</span>
<span class="n">e</span> <span class="s">"But it's just a passing thing."</span>
</pre></div>
</div>
<p>To cause a transition to occur whenever the images are changed in this way, set
<a class="reference internal" href="config.html#var-config.say_attribute_transition"><tt class="xref std std-var docutils literal"><span class="pre">config.say_attribute_transition</span></tt></a> to a transition.</p>
</div>
<div class="section" id="example-characters">
<h2>Example Characters<a class="headerlink" href="#example-characters" title="Permalink to this headline">¶</a></h2>
<p>Here are a few example characters:</p>
<div class="highlight-renpy"><div class="highlight"><pre><span class="c"># A character that has its dialogue enclosed in parenthesis.</span>
<span class="k">define</span> <span class="n">e</span> <span class="o">=</span> <span class="n">Character</span><span class="p">(</span><span class="s">"Eileen"</span><span class="p">,</span> <span class="n">what_prefix</span><span class="o">=</span><span class="s">'"'</span><span class="p">,</span> <span class="n">what_suffix</span><span class="o">=</span><span class="s">'"'</span><span class="p">)</span>
<span class="c"># A character that pulls its name from a variable.</span>
<span class="k">define</span> <span class="n">p</span> <span class="o">=</span> <span class="n">Character</span><span class="p">(</span><span class="s">"player_name"</span><span class="p">,</span> <span class="n">dynamic</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="special-characters">
<h2>Special Characters<a class="headerlink" href="#special-characters" title="Permalink to this headline">¶</a></h2>
<p>A few character names are defined by default, and are used
automatically in certain situations. Intentionally redefining these
characters can change the behavior of Ren'Py, but accidentally using
them can be a problem.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">adv</span></tt></dt>
<dd>The default kind of character used by Character. This sets up a
character such that one line is displayed on the screen at a
time.</dd>
<dt><tt class="docutils literal"><span class="pre">nvl</span></tt></dt>
<dd>A kind of Character that causes dialogue to be displayed in
<a class="reference internal" href="nvl_mode.html#nvl-mode"><em>NVL-Mode Tutorial</em></a>, with multiple lines of text on the screen
at once.</dd>
<dt><tt class="docutils literal"><span class="pre">narrator</span></tt></dt>
<dd>The character that's used to display narration, by say statements
without a character name.</dd>
<dt><tt class="docutils literal"><span class="pre">name_only</span></tt></dt>
<dd>A character that is used to display dialogue in which the
character name is given as a string. This character is copied to a
new character with the given name, and then that new character is
used to display the dialogue.</dd>
</dl>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="displaying_images.html" title="Displaying Images"
>next</a> |</li>
<li class="right" >
<a href="language_basics.html" title="Language Basics"
>previous</a> |</li>
<li> <img src="_static/logo.png" width=19 height=21 align=center>
<li> <a href="http://www.renpy.org/">Ren'Py Home</a> |
<li><a href="index.html">Ren'Py Documentation</a></li>
</ul>
</div>
<script src="http://www.google.com/jsapi" type="text/javascript"></script>
<script type="text/javascript">
google.load('search', '1', {language : 'en' });
google.setOnLoadCallback(function() {
var customSearchControl = new google.search.CustomSearchControl('012476843541036121001:gx3sqkoaxkm');
customSearchControl.setResultSetSize(google.search.Search.FILTERED_CSE_RESULTSET);
var options = new google.search.DrawOptions();
options.enableSearchboxOnly("http://www.google.com/cse?cx=012476843541036121001:gx3sqkoaxkm");
customSearchControl.draw('cse-search-form', options);
}, true);
</script>
</body>
</html>
|