/usr/share/doc/renpy/html/persistent.html is in renpy-doc 6.17.6-1.1.
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 | <!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Persistent Data — 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.18.0',
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="Transforms and Transitions in Python" href="trans_trans_python.html" />
<link rel="prev" title="Saving, Loading, and Rollback" href="save_load_rollback.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="trans_trans_python.html" title="Transforms and Transitions in Python"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="save_load_rollback.html" title="Saving, Loading, and Rollback"
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="#">Persistent Data</a><ul>
<li><a class="reference internal" href="#merging-persistent-data">Merging Persistent Data</a></li>
<li><a class="reference internal" href="#persistent-functions">Persistent Functions</a></li>
<li><a class="reference internal" href="#multi-game-persistence">Multi-Game Persistence</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="save_load_rollback.html"
title="previous chapter">Saving, Loading, and Rollback</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="trans_trans_python.html"
title="next chapter">Transforms and Transitions in Python</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="persistent-data">
<h1>Persistent Data<a class="headerlink" href="#persistent-data" title="Permalink to this headline">¶</a></h1>
<p>Ren'Py supports persistent data, saved data that is not
associated with a particular point in a game. Persistent data is
accessed through fields of the persistent object, which is bound to the
variable <tt class="docutils literal"><span class="pre">persistent</span></tt>.</p>
<p>All data reachable through fields on <tt class="docutils literal"><span class="pre">persistent</span></tt> is saved when
Ren'Py terminates, or when <a class="reference internal" href="#renpy.save_persistent" title="renpy.save_persistent"><tt class="xref py py-func docutils literal"><span class="pre">renpy.save_persistent()</span></tt></a> is called.
Persistent data is loaded when Ren'Py starts, and when Ren'Py detects
that the persistent data has been updated on disk.</p>
<p>The persistent object is special in that an access to an undefined field will
have a None value, rather than causing an exception.</p>
<p>An example use of persistent is the creation of an unlockable image gallery.
This is done by storing a flag in persistent that determines if the gallery has
been unlocked, as in</p>
<div class="highlight-renpy"><div class="highlight"><pre><span class="k">label</span> <span class="n">gallery</span><span class="p">:</span>
<span class="k">if</span> <span class="k">not</span> <span class="n">persistent</span><span class="o">.</span><span class="n">gallery_unlocked</span><span class="p">:</span>
<span class="k">show</span> <span class="na">background</span>
<span class="n">centered</span> <span class="s">"You haven't unlocked this gallery yet."</span>
<span class="k">$</span> <span class="n">renpy</span><span class="o">.</span><span class="n">full_restart</span><span class="p">()</span>
<span class="c"># Actually show the gallery here.</span>
</pre></div>
</div>
<p>When the user gets an ending that causes the gallery to be unlocked, the flag
must be set to True.</p>
<div class="highlight-renpy"><div class="highlight"><pre><span class="k">$</span> <span class="n">persistent</span><span class="o">.</span><span class="n">gallery_unlocked</span> <span class="o">=</span> <span class="bp">True</span>
</pre></div>
</div>
<p>As persistent data is loaded before the init code is run, persistent data
should only contain types that are native to python or Ren'Py. Alternatively,
classes that are defined in <tt class="docutils literal"><span class="pre">python</span> <span class="pre">early</span></tt> blocks can be used, provided
those classes can be pickled and implement equality.</p>
<div class="section" id="merging-persistent-data">
<h2>Merging Persistent Data<a class="headerlink" href="#merging-persistent-data" title="Permalink to this headline">¶</a></h2>
<p>There are cases where Ren'Py has to merge persistent data from two
sources. For example, Ren'Py may need to merge persistent data stored
on a USB drive with persistent data from the local machine.</p>
<p>Ren'Py does this merging on a field-by-field basis, taking the value
of the field that was updated more recently. In some cases, this is
not the desired behavior. In that case, the <a class="reference internal" href="#renpy.register_persistent" title="renpy.register_persistent"><tt class="xref py py-func docutils literal"><span class="pre">renpy.register_persistent()</span></tt></a>
function can be used.</p>
<p>For example, if we have a set of seen endings, we'd like to take the
union of that set when merging data.</p>
<div class="highlight-renpy"><div class="highlight"><pre><span class="k">init</span> <span class="k">python</span><span class="p">:</span>
<span class="k">if</span> <span class="n">persistent</span><span class="o">.</span><span class="n">endings</span> <span class="k">is</span> <span class="bp">None</span><span class="p">:</span>
<span class="n">persistent</span><span class="o">.</span><span class="n">endings</span> <span class="o">=</span> <span class="nb">set</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">merge_endings</span><span class="p">(</span><span class="n">old</span><span class="p">,</span> <span class="n">new</span><span class="p">,</span> <span class="n">current</span><span class="p">):</span>
<span class="n">current</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">old</span><span class="p">)</span>
<span class="n">current</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">new</span><span class="p">)</span>
<span class="n">renpy</span><span class="o">.</span><span class="n">register_persistent</span><span class="p">(</span><span class="s">'endings'</span><span class="p">,</span> <span class="n">merge_endings</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="persistent-functions">
<h2>Persistent Functions<a class="headerlink" href="#persistent-functions" title="Permalink to this headline">¶</a></h2>
<dl class="function">
<dt id="renpy.register_persistent">
<tt class="descclassname">renpy.</tt><tt class="descname">register_persistent</tt><big>(</big><em>field</em>, <em>func</em><big>)</big><a class="headerlink" href="#renpy.register_persistent" title="Permalink to this definition">¶</a></dt>
<dd><p>Registers a function that is used to merge values of a persistent field
loaded from disk with values of current persistent object.</p>
<dl class="docutils">
<dt><cite>field</cite></dt>
<dd>The name of a field on the persistent object.</dd>
<dt><cite>function</cite></dt>
<dd><p class="first">A function that is called with three parameters, <cite>old</cite>, <cite>new</cite>, and
<cite>current</cite>:</p>
<dl class="docutils">
<dt><cite>old</cite></dt>
<dd>The value of the field in the older object.</dd>
<dt><cite>new</cite></dt>
<dd>The value of the field in the newer object.</dd>
<dt><cite>current</cite></dt>
<dd>The value of the field in the current persistent object. This is
provided for cases where the identity of the object referred to
by the field can't change.</dd>
</dl>
<p class="last">The function is expected to return the new value of the field in the
persistent object.</p>
</dd>
</dl>
</dd></dl>
<dl class="function">
<dt id="renpy.save_persistent">
<tt class="descclassname">renpy.</tt><tt class="descname">save_persistent</tt><big>(</big><big>)</big><a class="headerlink" href="#renpy.save_persistent" title="Permalink to this definition">¶</a></dt>
<dd><p>Saves the persistent data to disk.</p>
</dd></dl>
</div>
<div class="section" id="multi-game-persistence">
<h2>Multi-Game Persistence<a class="headerlink" href="#multi-game-persistence" title="Permalink to this headline">¶</a></h2>
<p>Multi-Game persistence is a feature that lets you share information between
Ren'Py games. This may be useful if you plan to make a series of games, and
want to have them share information.</p>
<p>To use multipersistent data, a MultiPersistent object must be created inside
an init block. The user can then update this object, and save it to disk by
calling its save method. Undefined fields default to None. To ensure the
object can be loaded again, we suggest not assigning the object instances
of user-defined types.</p>
<dl class="class">
<dt id="MultiPersistent">
<em class="property">class </em><tt class="descname">MultiPersistent</tt><big>(</big><em>key</em><big>)</big><a class="headerlink" href="#MultiPersistent" title="Permalink to this definition">¶</a></dt>
<dd><p>Creates a new MultiPersistent object. This should only be called inside an
init block, and it returns a new MultiPersistent with the given key.</p>
<dl class="docutils">
<dt><cite>key</cite></dt>
<dd>The key used to to access the multipersistent data. Games using the
same key will access the same multipersistent data.</dd>
</dl>
<dl class="method">
<dt id="MultiPersistent.save">
<tt class="descname">save</tt><big>(</big><big>)</big><a class="headerlink" href="#MultiPersistent.save" title="Permalink to this definition">¶</a></dt>
<dd><p>Saves the multipersistent data to disk. This must be called after
the data is modified.</p>
</dd></dl>
</dd></dl>
<p>As an example, take the first part of a two-part game:</p>
<div class="highlight-renpy"><div class="highlight"><pre><span class="k">init</span> <span class="k">python</span><span class="p">:</span>
<span class="n">mp</span> <span class="o">=</span> <span class="n">MultiPersistent</span><span class="p">(</span><span class="s">"demo.renpy.org"</span><span class="p">)</span>
<span class="k">label</span> <span class="n">start</span><span class="p">:</span>
<span class="c"># ...</span>
<span class="c"># Record the fact that the user beat part 1.</span>
<span class="k">$</span> <span class="n">mp</span><span class="o">.</span><span class="n">beat_part_1</span> <span class="o">=</span> <span class="bp">True</span>
<span class="k">$</span> <span class="n">mp</span><span class="o">.</span><span class="n">save</span><span class="p">()</span>
<span class="n">e</span> <span class="s">"You beat part 1. See you in part 2!"</span>
</pre></div>
</div>
<p>And the second part:</p>
<div class="highlight-renpy"><div class="highlight"><pre><span class="k">init</span> <span class="k">python</span><span class="p">:</span>
<span class="n">mp</span> <span class="o">=</span> <span class="n">MultiPersistent</span><span class="p">(</span><span class="s">"demo.renpy.org"</span><span class="p">)</span>
<span class="k">label</span> <span class="n">start</span><span class="p">:</span>
<span class="k">if</span> <span class="n">mp</span><span class="o">.</span><span class="n">beat_part_1</span><span class="p">:</span>
<span class="n">e</span> <span class="s">"I see you've beaten part 1, so welcome back!"</span>
<span class="k">else</span><span class="p">:</span>
<span class="n">e</span> <span class="s">"Hmm, you haven't played part 1, why not try it first?"</span>
</pre></div>
</div>
</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="trans_trans_python.html" title="Transforms and Transitions in Python"
>next</a> |</li>
<li class="right" >
<a href="save_load_rollback.html" title="Saving, Loading, and Rollback"
>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>
</body>
</html>
|