<pclass="last">You are reading an old version of the Evennia documentation. <ahref="https://www.evennia.com/docs/latest/index.html">The latest version is here</a></p>.
<h1>Wilderness system<aclass="headerlink"href="#wilderness-system"title="Permalink to this headline">¶</a></h1>
<p>Contribution by titeuf87, 2017</p>
<p>This contrib provides a wilderness map without actually creating a large number
of rooms - as you move, you instead end up back in the same room but its description
changes. This means you can make huge areas with little database use as
long as the rooms are relatively similar (e.g. only the names/descs changing).</p>
<sectionid="installation">
<h2>Installation<aclass="headerlink"href="#installation"title="Permalink to this headline">¶</a></h2>
<p>This contrib does not provide any new commands. Instead the default <codeclass="docutils literal notranslate"><spanclass="pre">py</span></code> command
is used to call functions/classes in this contrib directly.</p>
</section>
<sectionid="usage">
<h2>Usage<aclass="headerlink"href="#usage"title="Permalink to this headline">¶</a></h2>
<p>A wilderness map needs to created first. There can be different maps, all
with their own name. If no name is provided, then a default one is used. Internally,
the wilderness is stored as a Script with the name you specify. If you don’t
specify the name, a script named “default” will be created and used.</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>py from evennia.contrib.grid import wilderness; wilderness.create_wilderness()
</pre></div>
</div>
<p>Once created, it is possible to move into that wilderness map:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>py from evennia.contrib.grid import wilderness; wilderness.enter_wilderness(me)
</pre></div>
</div>
<p>All coordinates used by the wilderness map are in the format of <codeclass="docutils literal notranslate"><spanclass="pre">(x,</span><spanclass="pre">y)</span></code>
tuples. x goes from left to right and y goes from bottom to top. So <codeclass="docutils literal notranslate"><spanclass="pre">(0,</span><spanclass="pre">0)</span></code>
is the bottom left corner of the map.</p>
<blockquote>
<div><p>You can also add a wilderness by defining a WildernessScript in your GLOBAL_SCRIPT
settings. If you do, make sure define the map provider.</p>
</div></blockquote>
</section>
<sectionid="customisation">
<h2>Customisation<aclass="headerlink"href="#customisation"title="Permalink to this headline">¶</a></h2>
<p>The defaults, while useable, are meant to be customised. When creating a
new wilderness map it is possible to give a “map provider”: this is a
python object that is smart enough to create the map.</p>
<p>The default provider, <codeclass="docutils literal notranslate"><spanclass="pre">WildernessMapProvider</span></code>, just creates a grid area that
is unlimited in size.</p>
<p><codeclass="docutils literal notranslate"><spanclass="pre">WildernessMapProvider</span></code> can be subclassed to create more interesting
maps and also to customize the room/exit typeclass used.</p>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">WildernessScript</span></code> also has an optional <codeclass="docutils literal notranslate"><spanclass="pre">preserve_items</span></code> property, which
when set to <codeclass="docutils literal notranslate"><spanclass="pre">True</span></code> will not recycle rooms that contain any objects. By default,
a wilderness room is recycled whenever there are no players left in it.</p>
<p>There is also no command that allows players to enter the wilderness. This
still needs to be added: it can be a command or an exit, depending on your
needs.</p>
</section>
<sectionid="example">
<h2>Example<aclass="headerlink"href="#example"title="Permalink to this headline">¶</a></h2>
<p>To give an example of how to customize, we will create a very simple (and
small) wilderness map that is shaped like a pyramid. The map will be
provided as a string: a “.” symbol is a location we can walk on.</p>
<p>Let’s create a file <codeclass="docutils literal notranslate"><spanclass="pre">world/pyramid.py</span></code>:</p>
<p>Note that the currently active description is stored as <codeclass="docutils literal notranslate"><spanclass="pre">.ndb.active_desc</span></code>. When
looking at the room, this is what will be pulled and shown.</p>
<blockquote>
<div><p>Exits on a room are always present, but locks hide those not used for a
location. So make sure to <codeclass="docutils literal notranslate"><spanclass="pre">quell</span></code> if you are a superuser (since the superuser ignores
locks, those exits will otherwise not be hidden)</p>
</div></blockquote>
<p>Now we can use our new pyramid-shaped wilderness map. From inside Evennia we
create a new wilderness (with the name “default”) but using our new map provider:</p>
<divclass="highlight-none notranslate"><divclass="highlight"><pre><span></span>py from world import pyramid as p; p.wilderness.create_wilderness(mapprovider=p.PyramidMapProvider())
py from evennia.contrib.grid import wilderness; wilderness.enter_wilderness(me, coordinates=(4, 1))
</pre></div>
</div>
</section>
<sectionid="implementation-details">
<h2>Implementation details<aclass="headerlink"href="#implementation-details"title="Permalink to this headline">¶</a></h2>
<p>When a character moves into the wilderness, they get their own room. If
they move, instead of moving the character, the room changes to match the
new coordinates.</p>
<p>If a character meets another character in the wilderness, then their room
merges. When one of the character leaves again, they each get their own
separate rooms.</p>
<p>Rooms are created as needed. Unneeded rooms are stored away to avoid the
overhead cost of creating new rooms again in the future.</p>
<hrclass="docutils"/>
<p><small>This document page is generated from <codeclass="docutils literal notranslate"><spanclass="pre">evennia/contrib/grid/wilderness/README.md</span></code>. Changes to this
file will be overwritten, so edit that file rather than this one.</small></p>
<pclass="last">You are reading an old version of the Evennia documentation. <ahref="https://www.evennia.com/docs/latest/index.html">The latest version is here</a></p>.
</div>
<divclass="footer"role="contentinfo">
© Copyright 2023, The Evennia developer community.
Created using <ahref="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
