Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-19 14:26:30 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions
evennia/docs/1.0-dev/Howto/Starting/Part1/Searching-Things.html
Griatch edf9ca4c4b Updated HTML docs
2020-10-15 01:31:30 +02:00

384 lines
No EOL
35 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>11. Searching for things &#8212; Evennia 1.0-dev documentation</title>
<link rel="stylesheet" href="../../../_static/nature.css" type="text/css" />
<link rel="stylesheet" href="../../../_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="../../../" src="../../../_static/documentation_options.js"></script>
<script src="../../../_static/jquery.js"></script>
<script src="../../../_static/underscore.js"></script>
<script src="../../../_static/doctools.js"></script>
<script src="../../../_static/language_data.js"></script>
<link rel="shortcut icon" href="../../../_static/favicon.ico"/>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<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="../../../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../../../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href=""><span class="section-number">11. </span>Searching for things</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="searching-for-things">
<h1><span class="section-number">11. </span>Searching for things<a class="headerlink" href="#searching-for-things" title="Permalink to this headline"></a></h1>
<p><a class="reference internal" href="Creating-Things.html"><span class="doc">prev lesson</span></a> | <a class="reference internal" href="Django-queries.html"><span class="doc">next lesson</span></a></p>
<p>We have gone through how to create the various entities in Evennia. But creating something is of little use
if we cannot find and use it afterwards.</p>
<div class="section" id="main-search-functions">
<h2><span class="section-number">11.1. </span>Main search functions<a class="headerlink" href="#main-search-functions" title="Permalink to this headline"></a></h2>
<p>The base tools are the <code class="docutils literal notranslate"><span class="pre">evennia.search_*</span></code> functions, such as <code class="docutils literal notranslate"><span class="pre">evennia.search_object</span></code>.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span> <span class="n">rose</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_object</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="s2">&quot;rose&quot;</span><span class="p">)</span>
<span class="n">acct</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_account</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="s2">&quot;MyAccountName&quot;</span><span class="p">,</span> <span class="n">email</span><span class="o">=</span><span class="s2">&quot;foo@bar.com&quot;</span><span class="p">)</span>
</pre></div>
</div>
<div class="sidebar">
<p class="sidebar-title">Querysets</p>
<p>What is returned from the main search functions is actually a <cite>queryset</cite>. They can be
treated like lists except that they can’t modified in-place. We’ll discuss querysets in
the <cite>next lesson</cite> &lt;Django-queries&gt;`_.</p>
</div>
<p>Strings are always case-insensitive, so searching for <code class="docutils literal notranslate"><span class="pre">&quot;rose&quot;</span></code>, <code class="docutils literal notranslate"><span class="pre">&quot;Rose&quot;</span></code> or <code class="docutils literal notranslate"><span class="pre">&quot;rOsE&quot;</span></code> give the same results.
It’s important to remember that what is returned from these search methods is a <em>listing</em> of 0, one or more
elements - all the matches to your search. To get the first match:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rose</span> <span class="o">=</span> <span class="n">rose</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
</pre></div>
</div>
<p>Often you really want all matches to the search parameters you specify. In other situations, having zero or
more than one match is a sign of a problem and you need to handle this case yourself.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">the_one_ring</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_object</span><span class="p">(</span><span class="n">key</span><span class="o">=</span><span class="s2">&quot;The one Ring&quot;</span><span class="p">)</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">the_one_ring</span><span class="p">:</span>
<span class="c1"># handle not finding the ring at all</span>
<span class="k">elif</span> <span class="nb">len</span><span class="p">(</span><span class="n">the_one_ring</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">1</span><span class="p">:</span>
<span class="c1"># handle finding more than one ring</span>
<span class="k">else</span><span class="p">:</span>
<span class="c1"># ok - exactly one ring found</span>
<span class="n">the_one_ring</span> <span class="o">=</span> <span class="n">the_one_ring</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span>
</pre></div>
</div>
<p>There are equivalent search functions for all the main resources. You can find a listing of them
<a class="reference internal" href="../../../Evennia-API.html"><span class="doc">in the Search functions section</span></a> of the API frontpage.</p>
</div>
<div class="section" id="searching-using-object-search">
<h2><span class="section-number">11.2. </span>Searching using Object.search<a class="headerlink" href="#searching-using-object-search" title="Permalink to this headline"></a></h2>
<p>On the <code class="docutils literal notranslate"><span class="pre">DefaultObject</span></code> is a <code class="docutils literal notranslate"><span class="pre">.search</span></code> method which we have already tried out when we made Commands. For
this to be used you must already have an object available:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rose</span> <span class="o">=</span> <span class="n">obj</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s2">&quot;rose&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>The <code class="docutils literal notranslate"><span class="pre">.search</span></code> method wraps <code class="docutils literal notranslate"><span class="pre">evennia.search_object</span></code> and handles its output in various ways.</p>
<ul class="simple">
<li><p>By default it will always search for objects among those in <code class="docutils literal notranslate"><span class="pre">obj.location.contents</span></code> and <code class="docutils literal notranslate"><span class="pre">obj.contents</span></code> (that is,
things in obj’s inventory or in the same room).</p></li>
<li><p>It will always return exactly one match. If it found zero or more than one match, the return is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>
<li><p>On a no-match or multimatch, <code class="docutils literal notranslate"><span class="pre">.search</span></code> will automatically send an error message to <code class="docutils literal notranslate"><span class="pre">obj</span></code>.</p></li>
</ul>
<p>So this method handles error messaging for you. A very common way to use it is in commands:</p>
<div class="highlight-python notranslate"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre> 1
2
3
4
5
6
7
8
9
10
11</pre></div></td><td class="code"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">evennia</span> <span class="kn">import</span> <span class="n">Command</span>
<span class="k">class</span> <span class="nc">MyCommand</span><span class="p">(</span><span class="n">Command</span><span class="p">):</span>
<span class="n">key</span> <span class="o">=</span> <span class="s2">&quot;findfoo&quot;</span>
<span class="k">def</span> <span class="nf">func</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">foo</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s2">&quot;foo&quot;</span><span class="p">)</span>
<span class="k">if</span> <span class="ow">not</span> <span class="n">foo</span><span class="p">:</span>
<span class="k">return</span>
</pre></div>
</td></tr></table></div>
<p>Remember, <code class="docutils literal notranslate"><span class="pre">self.caller</span></code> is the one calling the command. This is usually a Character, which
inherits from <code class="docutils literal notranslate"><span class="pre">DefaultObject</span></code>! This (rather stupid) Command searches for an object named “foo” in
the same location. If it can’t find it, <code class="docutils literal notranslate"><span class="pre">foo</span></code> will be <code class="docutils literal notranslate"><span class="pre">None</span></code>. The error has already been reported
to <code class="docutils literal notranslate"><span class="pre">self.caller</span></code> so we just abort with <code class="docutils literal notranslate"><span class="pre">return</span></code>.</p>
<p>You can use <code class="docutils literal notranslate"><span class="pre">.search</span></code> to find anything, not just stuff in the same room:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">volcano</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s2">&quot;Volcano&quot;</span><span class="p">,</span> <span class="k">global</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>If you only want to search for a specific list of things, you can do so too:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">stone</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s2">&quot;MyStone&quot;</span><span class="p">,</span> <span class="n">candidates</span><span class="o">=</span><span class="p">[</span><span class="n">obj1</span><span class="p">,</span> <span class="n">obj2</span><span class="p">,</span> <span class="n">obj3</span><span class="p">,</span> <span class="n">obj4</span><span class="p">])</span>
</pre></div>
</div>
<p>This will only return a match if MyStone is one of the four provided candidate objects. This is quite powerful,
here’s how you’d find something only in your inventory:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">potion</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s2">&quot;Healing potion&quot;</span><span class="p">,</span> <span class="n">candidates</span><span class="o">=</span><span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">contents</span><span class="p">)</span>
</pre></div>
</div>
<p>You can also turn off the automatic error handling:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">swords</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s2">&quot;Sword&quot;</span><span class="p">,</span> <span class="n">quiet</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>With <code class="docutils literal notranslate"><span class="pre">quiet=True</span></code> the user will not be notified on zero or multi-match errors. Instead you are expected to handle this
yourself and what you get back is now a list of zero, one or more matches!</p>
</div>
<div class="section" id="what-can-be-searched-for">
<h2><span class="section-number">11.3. </span>What can be searched for<a class="headerlink" href="#what-can-be-searched-for" title="Permalink to this headline"></a></h2>
<p>These are the main database entities one can search for:</p>
<ul class="simple">
<li><p><a class="reference internal" href="../../../Components/Objects.html"><span class="doc">Objects</span></a></p></li>
<li><p><a class="reference internal" href="../../../Components/Accounts.html"><span class="doc">Accounts</span></a></p></li>
<li><p><a class="reference internal" href="../../../Components/Scripts.html"><span class="doc">Scripts</span></a>,</p></li>
<li><p><a class="reference external" href="Components/Communications.html#channels">Channels</a>,</p></li>
<li><p><a class="reference external" href="Howto/Starting/Part1/Communication#Msg">Messages</a></p></li>
<li><p><a class="reference internal" href="../../../Components/Help-System.html"><span class="doc">Help Entries</span></a>.</p></li>
</ul>
<p>Most of the time you’ll likely spend your time searching for Objects and the occasional Accounts.</p>
<p>So to find an entity, what can be searched for?</p>
<div class="section" id="search-by-key">
<h3><span class="section-number">11.3.1. </span>Search by key<a class="headerlink" href="#search-by-key" title="Permalink to this headline"></a></h3>
<p>The <code class="docutils literal notranslate"><span class="pre">key</span></code> is the name of the entity. Searching for this is always case-insensitive.</p>
</div>
<div class="section" id="search-by-aliases">
<h3><span class="section-number">11.3.2. </span>Search by aliases<a class="headerlink" href="#search-by-aliases" title="Permalink to this headline"></a></h3>
<p>Objects and Accounts can have any number of aliases. When searching for <code class="docutils literal notranslate"><span class="pre">key</span></code> these will searched too,
you can’t easily search only for aliases.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rose</span><span class="o">.</span><span class="n">aliases</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;flower&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>If the above <code class="docutils literal notranslate"><span class="pre">rose</span></code> has a <code class="docutils literal notranslate"><span class="pre">key</span></code> <code class="docutils literal notranslate"><span class="pre">&quot;Rose&quot;</span></code>, it can now also be found by searching for <code class="docutils literal notranslate"><span class="pre">flower</span></code>. In-game
you can assign new aliases to things with the <code class="docutils literal notranslate"><span class="pre">alias</span></code> command.</p>
</div>
<div class="section" id="search-by-location">
<h3><span class="section-number">11.3.3. </span>Search by location<a class="headerlink" href="#search-by-location" title="Permalink to this headline"></a></h3>
<p>Only Objects (things inheriting from <code class="docutils literal notranslate"><span class="pre">evennia.DefaultObject</span></code>) has a location. This is usually a room.
The <code class="docutils literal notranslate"><span class="pre">Object.search</span></code> method will automatically limit it search by location, but it also works for the
general search function. If we assume <code class="docutils literal notranslate"><span class="pre">room</span></code> is a particular Room instance,</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">chest</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_object</span><span class="p">(</span><span class="s2">&quot;Treasure chest&quot;</span><span class="p">,</span> <span class="n">location</span><span class="o">=</span><span class="n">room</span><span class="p">)</span>
</pre></div>
</div>
</div>
<div class="section" id="search-by-tags">
<h3><span class="section-number">11.3.4. </span>Search by Tags<a class="headerlink" href="#search-by-tags" title="Permalink to this headline"></a></h3>
<p>Think of a <a class="reference internal" href="../../../Components/Tags.html"><span class="doc">Tag</span></a> as the label the airport puts on your luggage when flying.
Everyone going on the same plane gets a tag grouping them together so the airport can know what should
go to which plane. Entities in Evennia can be grouped in the same way. Any number of tags can be attached
to each object.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rose</span><span class="o">.</span><span class="n">tags</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;flowers&quot;</span><span class="p">)</span>
<span class="n">daffodil</span><span class="o">.</span><span class="n">tags</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;flowers&quot;</span><span class="p">)</span>
<span class="n">tulip</span><span class="o">.</span><span class="n">tags</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;flowers&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>You can now find all flowers using the <code class="docutils literal notranslate"><span class="pre">search_tag</span></code> function:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">all_flowers</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_tag</span><span class="p">(</span><span class="s2">&quot;flowers&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>Tags can also have categories. By default this category is <code class="docutils literal notranslate"><span class="pre">None</span></code> which is also considered a category.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">silmarillion</span><span class="o">.</span><span class="n">tags</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;fantasy&quot;</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">&quot;books&quot;</span><span class="p">)</span>
<span class="n">ice_and_fire</span><span class="o">.</span><span class="n">tags</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;fantasy&quot;</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">&quot;books&quot;</span><span class="p">)</span>
<span class="n">mona_lisa_overdrive</span><span class="o">.</span><span class="n">tags</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="s2">&quot;cyberpunk&quot;</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">&quot;books&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>Note that if you specify the tag you <em>must</em> also include its category, otherwise that category
will be <code class="docutils literal notranslate"><span class="pre">None</span></code> and find no matches.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">all_fantasy_books</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_tag</span><span class="p">(</span><span class="s2">&quot;fantasy&quot;</span><span class="p">)</span> <span class="c1"># no matches! </span>
<span class="n">all_fantasy_books</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_tag</span><span class="p">(</span><span class="s2">&quot;fantasy&quot;</span><span class="p">,</span> <span class="n">category</span><span class="o">=</span><span class="s2">&quot;books&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>Only the second line above returns the two fantasy books. If we specify a category however,
we can get all tagged entities within that category:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">all_books</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_tag</span><span class="p">(</span><span class="n">category</span><span class="o">=</span><span class="s2">&quot;books&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>This gets all three books.</p>
</div>
<div class="section" id="search-by-attribute">
<h3><span class="section-number">11.3.5. </span>Search by Attribute<a class="headerlink" href="#search-by-attribute" title="Permalink to this headline"></a></h3>
<p>We can also search by the <a class="reference internal" href="../../../Components/Attributes.html"><span class="doc">Attributes</span></a> associated with entities.</p>
<p>For example, let’s give our rose thorns:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">rose</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">has_thorns</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">wines</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">has_thorns</span> <span class="o">=</span> <span class="kc">True</span>
<span class="n">daffodil</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">has_thorns</span> <span class="o">=</span> <span class="kc">False</span>
</pre></div>
</div>
<p>Now we can find things attribute and the value we want it to have:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">is_ouch</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_object_attribute</span><span class="p">(</span><span class="s2">&quot;has_thorns&quot;</span><span class="p">,</span> <span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<p>This returns the rose and the wines.</p>
<blockquote>
<div><p>Searching by Attribute can be very practical. But if you plan to do a search very often, searching
by-tag is generally faster.</p>
</div></blockquote>
</div>
<div class="section" id="search-by-typeclass">
<h3><span class="section-number">11.3.6. </span>Search by Typeclass<a class="headerlink" href="#search-by-typeclass" title="Permalink to this headline"></a></h3>
<p>Sometimes it’s useful to find all objects of a specific Typeclass. All of Evennia’s search tools support this.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">all_roses</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_object</span><span class="p">(</span><span class="n">typeclass</span><span class="o">=</span><span class="s2">&quot;typeclasses.flowers.Rose&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>If you have the <code class="docutils literal notranslate"><span class="pre">Rose</span></code> class already imported you can also pass it directly:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">all_roses</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_object</span><span class="p">(</span><span class="n">typeclass</span><span class="o">=</span><span class="n">Rose</span><span class="p">)</span>
</pre></div>
</div>
<p>You can also search using the typeclass itself:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">all_roses</span> <span class="o">=</span> <span class="n">Rose</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">all</span><span class="p">()</span>
</pre></div>
</div>
<p>This last way of searching is a simple form of a Django <em>query</em>. This is a way to express SQL queries using
Python. We’ll cover this some more as an <a class="reference external" href="#Extra-Credits">Extra-credits</a> section at the end of this lesson.</p>
</div>
<div class="section" id="search-by-dbref">
<h3><span class="section-number">11.3.7. </span>Search by dbref<a class="headerlink" href="#search-by-dbref" title="Permalink to this headline"></a></h3>
<p>The database id or <code class="docutils literal notranslate"><span class="pre">#dbref</span></code> is unique and never-reused within each database table. In search methods you can
replace the search for <code class="docutils literal notranslate"><span class="pre">key</span></code> with the dbref to search for. This must be written as a string <code class="docutils literal notranslate"><span class="pre">#dbref</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">the_answer</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">caller</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s2">&quot;#42&quot;</span><span class="p">)</span>
<span class="n">eightball</span> <span class="o">=</span> <span class="n">evennia</span><span class="o">.</span><span class="n">search_object</span><span class="p">(</span><span class="s2">&quot;#8&quot;</span><span class="p">)</span>
</pre></div>
</div>
<p>Since <code class="docutils literal notranslate"><span class="pre">#dbref</span></code> is always unique, this search is always global.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Relying on #dbrefs</p>
<p>You may be used to using #dbrefs a lot from other codebases. It is however considered
<cite>bad practice</cite> in Evennia to rely on hard-coded #dbrefs. It makes your code hard to maintain
and tied to the exact layout of the database. In 99% of cases you should pass the actual objects
around and search by key/tags/attribute instead.</p>
</div>
</div>
</div>
<div class="section" id="finding-objects-relative-each-other">
<h2><span class="section-number">11.4. </span>Finding objects relative each other<a class="headerlink" href="#finding-objects-relative-each-other" title="Permalink to this headline"></a></h2>
<p>Let’s consider a <code class="docutils literal notranslate"><span class="pre">chest</span></code> with a <code class="docutils literal notranslate"><span class="pre">coin</span></code> inside it. The chests stand in a room <code class="docutils literal notranslate"><span class="pre">dungeon</span></code>. In the dungeon is also
a <code class="docutils literal notranslate"><span class="pre">door</span></code>. This is an exit leading outside.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">coin.location</span></code> is <code class="docutils literal notranslate"><span class="pre">chest</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">chest.location</span></code> is <code class="docutils literal notranslate"><span class="pre">dungeon</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">door.location</span></code> is <code class="docutils literal notranslate"><span class="pre">dungeon</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">room.location</span></code> is <code class="docutils literal notranslate"><span class="pre">None</span></code> since it’s not inside something else.</p></li>
</ul>
<p>One can use this to find what is inside what. For example, <code class="docutils literal notranslate"><span class="pre">coin.location.location</span></code> is the <code class="docutils literal notranslate"><span class="pre">room</span></code>.
We can also find what is inside each object. This is a list of things.</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">room.contents</span></code> is <code class="docutils literal notranslate"><span class="pre">[chest,</span> <span class="pre">door]</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">chest.contents</span></code> is <code class="docutils literal notranslate"><span class="pre">[coin]</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">coin.contents</span></code> is <code class="docutils literal notranslate"><span class="pre">[]</span></code>, the empty list since there’s nothing ‘inside’ the coin.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">door.contents</span></code> is <code class="docutils literal notranslate"><span class="pre">[]</span></code> too.</p></li>
</ul>
<p>A convenient helper is <code class="docutils literal notranslate"><span class="pre">.contents_get</span></code> - this allows to restrict what is returned:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">room.contents_get(exclude=chest)</span></code> - this returns everything in the room except the chest (maybe it’s hidden?)</p></li>
</ul>
<p>There is a special property for finding exits:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">room.exits</span></code> is <code class="docutils literal notranslate"><span class="pre">[door]</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">coin.exits</span></code> is <code class="docutils literal notranslate"><span class="pre">[]</span></code> (same for all the other objects)</p></li>
</ul>
<p>There is a property <code class="docutils literal notranslate"><span class="pre">.destination</span></code> which is only used by exits:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">door.destination</span></code> is <code class="docutils literal notranslate"><span class="pre">outside</span></code> (or wherever the door leads)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">room.destination</span></code> is <code class="docutils literal notranslate"><span class="pre">None</span></code> (same for all the other non-exit objects)</p></li>
</ul>
</div>
<div class="section" id="summary">
<h2><span class="section-number">11.5. </span>Summary<a class="headerlink" href="#summary" title="Permalink to this headline"></a></h2>
<p>Knowing how to find things is important and the tools from this section will serve you well. For most of your needs
these tools will be all you need …</p>
<p>… but not always. In the next lesson we will dive further into more complex searching when we look at
Django queries and querysets in earnest.</p>
<p><a class="reference internal" href="Creating-Things.html"><span class="doc">prev lesson</span></a> | <a class="reference internal" href="Django-queries.html"><span class="doc">next lesson</span></a></p>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../../../index.html">
<img class="logo" src="../../../_static/evennia_logo.png" alt="Logo"/>
</a></p>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../../../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
<p><h3><a href="../../../index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">11. Searching for things</a><ul>
<li><a class="reference internal" href="#main-search-functions">11.1. Main search functions</a></li>
<li><a class="reference internal" href="#searching-using-object-search">11.2. Searching using Object.search</a></li>
<li><a class="reference internal" href="#what-can-be-searched-for">11.3. What can be searched for</a><ul>
<li><a class="reference internal" href="#search-by-key">11.3.1. Search by key</a></li>
<li><a class="reference internal" href="#search-by-aliases">11.3.2. Search by aliases</a></li>
<li><a class="reference internal" href="#search-by-location">11.3.3. Search by location</a></li>
<li><a class="reference internal" href="#search-by-tags">11.3.4. Search by Tags</a></li>
<li><a class="reference internal" href="#search-by-attribute">11.3.5. Search by Attribute</a></li>
<li><a class="reference internal" href="#search-by-typeclass">11.3.6. Search by Typeclass</a></li>
<li><a class="reference internal" href="#search-by-dbref">11.3.7. Search by dbref</a></li>
</ul>
</li>
<li><a class="reference internal" href="#finding-objects-relative-each-other">11.4. Finding objects relative each other</a></li>
<li><a class="reference internal" href="#summary">11.5. Summary</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<!--h3>This Page</h3-->
<ul class="this-page-menu">
<li><a href="../../../_sources/Howto/Starting/Part1/Searching-Things.md.txt"
rel="nofollow">Show Page Source</a></li>
</ul>
</div>
<h3>Versions</h3>
<ul>
<li><a href="Searching-Things.html">1.0-dev (develop branch)</a></li>
<li><a href="../../../../0.9.5/index.html">0.9.5 (master branch)</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<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="../../../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="nav-item nav-item-0"><a href="../../../index.html">Evennia 1.0-dev</a> &#187;</li>
<li class="nav-item nav-item-this"><a href=""><span class="section-number">11. </span>Searching for things</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
&#169; Copyright 2020, The Evennia developer community.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>
Reference in a new issue View git blame Copy permalink